Workspaces and areas

A workspace is where your team's work lives: its missions, intents and documents, and every repository that belongs to them. An area is one repository inside it, or one product or domain if you split your work that way. Missions, intents and documents belong to the workspace as a whole, because one intent often spans several repositories. Tasks are placed in the area where the work happens.

On your machine, a workspace is a folder and its areas are folders too. This page shows how orbitmap init records that mapping, and how your agent uses it.

The workspace root

The folder where you run init becomes the workspace root. init writes one file there, .orbitmap/config.json, which records:

which workspace this folder belongs to,
which agent profile the CLI should use (the agent's name, not its API key),
which subfolder is which area.

For a folder that holds two repositories, api and web, the file looks like this:

{
  "schema_version": 1,
  "mode": "cloud",
  "agent": "my-ai-agent",
  "workspace_id": "9b1c6f0e-…",
  "workspace": "acme",
  "areas": {
    "api": "api",
    "web": "web"
  }
}

Each entry under areas maps a folder, relative to the root, to an area. When you run init inside a single repository, the root is itself the area, and the map has one entry: ".": "<area>".

The file holds no secret. The API key stays in ~/.orbitmap/credentials.json on your machine, stored under the agent's name that the config points to. That is why you can, and should, commit .orbitmap/config.json.

One folder holds one workspace. If init finds another workspace's root above or below the folder you run it in, it names that workspace and asks before going on.

One area per repository

Each area's folder gets a small marker of its own, <area>/.orbitmap/config.json, that names its area:

{
  "area": "api"
}

The root does not need a marker when it is itself the area; its areas map already says so.

init matches folders to areas by the folder's name and by its git remote, compared with the repository address stored on the area. On a new account it creates the areas: one per repository it finds, named after the folder, with the repository's remote attached. When a folder matches no area, init asks for a path or lets you skip it.

A typical layout after init:

acme/                       workspace root
├── .orbitmap/
│   └── config.json         workspace, agent, areas map (committed)
├── .gitignore              .orbitmap/docs/ and .orbitmap/link.json added
├── api/                    area "api"
│   └── .orbitmap/
│       └── config.json     marker: {"area": "api"}
└── web/                    area "web"
    └── .orbitmap/
        └── config.json     marker: {"area": "web"}

Working from inside an area

Every orbitmap command looks for these files by walking up from the folder it runs in. That is how your agent knows where it is without being told:

Inside an area's folder, or any folder below it, commands work in that area. The marker is found first, and the workspace comes from the root config above it.
At the workspace root of a multi-repository folder, commands see the whole workspace. A command that needs one area tells you so and lists the workspace's areas: pass --area <slug>, or cd into the area's folder.

So start your agent where the work is. Start it in the root when the work spans repositories, as most intents do, and inside an area's folder when you work on that repository only.

To check what the CLI resolves in the current folder, run:

orbitmap context

It shows your agent's name and current area at the top, followed by the workspace's missions, intents, areas and documents.

Areas outside the tree

Sometimes a repository of the workspace lives somewhere else on your disk, not under the workspace root. When you give init such a path, it cannot put it in .orbitmap/config.json: an absolute path only makes sense on your machine, and that file is shared. So init records it in .orbitmap/link.json next to the config instead. That file maps the area to its absolute path and stays out of git, through the line init added to .gitignore.

The outside folder gets two files of its own:

a marker .orbitmap/config.json that names both its area and its workspace, because walking up from there never reaches the root,
a .orbitmap/link.json pointing back to the workspace root, so the area shares the root's documents instead of keeping a second copy.

Teammates and other machines

Because .orbitmap/config.json and the area markers are committed, everyone who clones the repositories gets the same map of workspace and areas. Each person brings their own agent and API key:

Clone the repositories in the same layout.
Run npx orbitmap init in the workspace root, and paste the API key of your own agent.
init finds the existing config, merges into it, and keeps the areas already mapped. Your key goes into your own ~/.orbitmap/, never into the repository.

The same steps connect a second machine of yours.

.orbitmap/link.json is not shared, because its paths belong to one machine. On each new machine, map areas that live outside the tree again: run init in the workspace root, choose A parent directory, and give their paths when init asks about the areas it could not place.

Cloned a repository of the workspace later? Run init inside it. It joins the workspace config above it instead of starting a new one.

Install and init: every question init asks and every file it writes.
Missions: the focus that the work in your workspace belongs to.