Workspace and project

One workshop holds many projects and many shared folders. Only the workshop is bound; projects are registered.

What it is#

Three different things, easy to confuse because they are all folders.

	What it is	How it comes to exist	How many
Workspace (workshop)	The folder holding `orch.yaml` and `.orch/`. Everything orch governs sits under it.	`orch setup`	One per bound folder; a machine can have several
Project	A git repo orch knows about, by path and short name	`orch project add <path>`	Many — the plan sets `orch.projects.max`
Shared folder	A folder registered under a language bucket, where the lock and symbol law applies	`orch shared add <path> --lang go`	Many, grouped by language

Registering never creates a folder. Both orch project add and orch shared add say so in their own help: does not create folders.

my-workshop/                 <- workspace: orch.yaml + .orch/
├── orch.yaml                   registered projects and shared buckets
├── .orch/                      runtime: orch.db, agents/, worktrees
├── .workflow/                  BOARD.md, RESUME.md
├── shared/go/                  <- shared folder (locks + orch:export apply)
├── products/billing/           <- project (its own git repo)
└── products/portal/            <- project (its own git repo)

Why it exists#

Because the unit of governance and the unit of work are not the same size. Locks, the symbol registry, the bus and the runtime database are workshop-wide — they have to be, or two agents in two repos could not see each other. But a Chair is elected per git project, and a worker's worktree is a branch in one repo. N repos means N orch project add entries and up to N Chairs working at once.

Binding is deliberate and file-based but not file-only: a cloned repo can ship an orch.yaml and a .orch/ of its own, so the files alone never bind a workspace to your machine.

How it relates to the rest#

Outside a bound workspace orch runs in loose mode. The gateway and the local optimizations work; locks, the bus and project control do not, and the shared-protocol tools answer with a skip message instead of an error.
orch workspace prints the resolved binding for the current folder — binary location, workspace root, config file and runtime directory. orch workspace <path> initializes another folder as a workshop.
orch home shows the other half: the machine home, shared by every workspace on the machine, where identity and provider keys live.
Registering a shared folder also seeds and indexes it: orch shared add reports seeded tags=… files=… scanned=… skipped_no_ast=… indexed=… because the symbol registry has to know about the folder before the shared code law can mean anything.

Nothing to run here#

This page describes a layout, not a procedure. The commands that create it are in the Quickstart; the law that applies inside a shared folder is in Shared code law.