docs: add cross-doc links + explain repos (one project, several repos)

Author: corrm

docs/DESIGN.md

@@ -294,7 +294,7 @@ For the full cascade detail and all recognized label forms, see [`resolution.md`
 in v1 (no server, no webhook). On each tick it:
 
 1. Counts issues currently `In Progress` and `In Review` against the project's
-   capacity caps (`limits.inProgress`, `limits.inReview` in `config.json`).
+   capacity caps ([`limits.inProgress`, `limits.inReview`](config.md#projects) in `config.json`).
 2. If under cap, fetches `Todo` issues ordered by priority.
 3. Filters out issues that are quarantined (label `beflow:quarantined`), blocked
    by unfinished dependencies (`blockedBy`), or (when `scheduling.activeCycleOnly`
@@ -306,10 +306,10 @@ in v1 (no server, no webhook). On each tick it:
      continuation prompt (the review comment thread as context).
    - Issues in `In Review` with `needs-decision` → move to Needs Input with the
      open question surfaced as a comment.
-   - When `ci.autoReworkOnRed` is enabled, CI-failing PRs trigger a rework
+   - When [`ci.autoReworkOnRed`](config.md#projects) is enabled, CI-failing PRs trigger a rework
      dispatch with the failure details as continuation context. Loop-safe: never
      reworks the same head SHA twice; quarantines a perpetually red PR once the
-     attempt counter hits the dead-letter threshold.
+     attempt counter hits the [`deadLetter`](config.md#defaults) threshold.
    - Stale `In Progress` issues past the configured SLA window get a nudge comment.
 6. Sleeps for `--interval` seconds (default 30) and repeats.
 

docs/OPERATING-MODEL.md

@@ -32,7 +32,7 @@ narrow dispatch to the active cycle, but the core model does not require them.
 Instead of estimating how much work fits in a period, beflow enforces
 **work-in-progress limits** on the active lanes:
 
-- **In Progress** is capped (`limits.inProgress`, default 3) — beflow dispatches
+- **In Progress** is capped ([`limits.inProgress`](config.md#projects), default 3) — beflow dispatches
   from Todo only up to the remaining headroom under this cap.
 - **In Review** is capped (`limits.inReview`, default 5) — this is the lane that
   protects _you_. Pull requests pile up here waiting on human review, and the cap
@@ -95,7 +95,7 @@ code they govern. When standards change, you change them in one place — the re
 ## One project, several repos
 
 A project on the board can span several git repositories. A single work item maps
-to the repo (or repos) its code area lives in via `module_repo_map`: a **module**
+to the repo (or repos) its code area lives in via [`module_repo_map`](config.md#projects): a **module**
 names a code area, and the map resolves that module to the repository beflow
 should check out and open a PR against.
 

docs/acp-events.md

@@ -17,9 +17,9 @@ acpx --format json --json-strict --cwd <repo> <permission-flag> \
 - `--format json` emits the **raw ACP JSON-RPC** wire stream as NDJSON (one JSON
   object per line). `--json-strict` suppresses non-JSON noise on stderr — always
   pair them.
-- `<permission-flag>`: `--approve-all` in autonomous mode; `--approve-reads` in
+- `<permission-flag>`: `--approve-all` in [autonomous mode](resolution.md#run-mode); `--approve-reads` in
   supervised mode.
-- `--append-system-prompt` carries the jobKind contract when one is configured.
+- `--append-system-prompt` carries the [jobKind](resolution.md#job-kind) contract when one is configured.
 - `--timeout` asks acpx to cooperatively stop after that many seconds; beflow adds
   a hard-kill grace window on top.
 - `prompt -s <SESSION-KEY>` sends a prompt to a named, resumable session scoped by

docs/adapters.md

@@ -133,7 +133,7 @@ workspace-level toggle). When `opts.prune` is true, also delete orphan entities
 (those present in the tracker but absent from the template) and record them in
 `pruned`. When `opts.resolveModuleChanges` is provided, call it with the
 `ModuleChange` diff before pruning modules so the caller can rename instead of
-delete.
+delete. Called by [`beflow setup`](commands.md#setup-project--update-project).
 
 **`createProject(spec)`** — Create a new project from `ProjectCreateSpec`.
 Return `ProjectCreateResult`, which carries the tracker-internal project ID in
@@ -163,7 +163,7 @@ interface Issue {
 }
 ```
 
-`areas` drives repo resolution via `module_repo_map` in
+`areas` drives repo resolution via [`module_repo_map`](config.md#projects) in
 `config.json`'s `projects.<KEY>`.
 
 ### `StateGroup`
@@ -175,7 +175,7 @@ type StateGroup = "backlog" | "unstarted" | "started" | "completed" | "cancelled
 Map your tracker's statuses onto this five-value enum. beflow's default board
 uses: `Backlog` → `backlog`, `Todo` → `unstarted`, `In Progress` → `started`,
 `Needs Input` → `started`, `In Review` → `started`, `Done` → `completed`,
-`Cancelled` → `cancelled`.
+`Cancelled` → `cancelled`. See [lifecycle.md](lifecycle.md) for the full board state reference.
 
 ### `IssueMeta`
 

docs/config.md

@@ -112,6 +112,48 @@ or a Linear team) and the local repos its work lands in.
 Per-project `deadLetter`, `inputQuality`, `qualityGate`, `review`, `sla`, and
 `telemetry` mirror their [Defaults](#defaults) counterparts and override them.
 
+### Repos: one project, several repositories
+
+A beflow project is a single board, but the work on it often lands in **more
+than one git repository** — say a backend service, a marketing site, and a
+shared library. `repos` is the map from a short **repo key** to that
+repository's absolute path on disk; it is the set of repositories a run is
+allowed to touch. (`root` is just the common parent directory; `beflow doctor`
+checks that `root` and every `repos` path exist.)
+
+When beflow runs a work item it resolves **which** repo the agent works in, then
+runs the agent in a git worktree of that repo:
+
+1. `--repo <key>` on the command line wins, if given.
+2. otherwise `module_repo_map` routes by the item's module — the board module
+   maps to a repo key.
+3. otherwise `default_repo` is the fallback.
+
+See [resolution](resolution.md#repo) for the full cascade.
+
+```json
+"APP": {
+  "name": "My App",
+  "root": "/home/you/projects/app",
+  "default_repo": "api",
+  "repos": {
+    "api": "/home/you/projects/app/api",
+    "web": "/home/you/projects/app/web",
+    "shared": "/home/you/projects/app/shared"
+  },
+  "module_repo_map": {
+    "Backend": "api",
+    "Frontend": "web",
+    "Shared Library": "shared"
+  }
+}
+```
+
+With the above, a work item filed under the **Backend** module runs in `api`, a
+**Frontend** item in `web`, and a **Shared Library** item in `shared`. An item
+with no module (or one not in the map) falls back to `default_repo` (`api`).
+Override per run with `beflow run APP-42 --repo web`.
+
 ## Agents
 
 Each entry defines how to launch one coding-agent CLI.

docs/issue-templates.md

@@ -27,20 +27,20 @@ and write the issue for you.
 
 The frontmatter is a YAML object. Only `name` and `description` are required.
 
-| Field         | Type                                              | Meaning                                                                        |
-| ------------- | ------------------------------------------------- | ------------------------------------------------------------------------------ |
-| `name`        | string (**required**)                             | The template id — the file stem and the argument to `beflow new <KEY> <name>`. |
-| `description` | string (**required**)                             | One-line summary shown in the interactive template picker.                     |
-| `agent`       | string                                            | Pins the agent → emits an `agent:<name>` picker label on the new card.         |
-| `jobKind`     | `triage` \| `spec` \| `implement`                 | Pins the lifecycle job kind → emits a `jobkind:<jobKind>` picker label.        |
-| `runMode`     | `autonomous` \| `supervised`                      | Pins the run mode → emits a `run:<mode>` picker label.                         |
-| `type`        | string                                            | The work-item type (e.g. `Bug`, `Feature`, `Spike`).                           |
-| `priority`    | `urgent` \| `high` \| `medium` \| `low` \| `none` | The work-item priority.                                                        |
-| `state`       | string                                            | The state the issue is created into (defaults to `Backlog`).                   |
-| `labels`      | string[]                                          | Extra labels attached on creation, on top of the picker labels.                |
-| `enrich`      | bool (default `false`)                            | Run the agent read-only to author the body before the preview.                 |
-| `title`       | string                                            | A `{{key}}` pattern for the title (see [Title](#title)).                       |
-| `questions`   | question[] (default `[]`)                         | The typed inputs collected from the operator (see [Questions](#questions)).    |
+| Field         | Type                                              | Meaning                                                                                           |
+| ------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `name`        | string (**required**)                             | The template id — the file stem and the argument to `beflow new <KEY> <name>`.                    |
+| `description` | string (**required**)                             | One-line summary shown in the interactive template picker.                                        |
+| `agent`       | string                                            | Pins the agent → emits an `agent:<name>` picker label on the new card.                            |
+| `jobKind`     | `triage` \| `spec` \| `implement`                 | Pins the lifecycle [job kind](resolution.md#job-kind) → emits a `jobkind:<jobKind>` picker label. |
+| `runMode`     | `autonomous` \| `supervised`                      | Pins the [run mode](resolution.md#run-mode) → emits a `run:<mode>` picker label.                  |
+| `type`        | string                                            | The work-item type (e.g. `Bug`, `Feature`, `Spike`).                                              |
+| `priority`    | `urgent` \| `high` \| `medium` \| `low` \| `none` | The work-item priority.                                                                           |
+| `state`       | string                                            | The state the issue is created into (defaults to `Backlog`).                                      |
+| `labels`      | string[]                                          | Extra labels attached on creation, on top of the picker labels.                                   |
+| `enrich`      | bool (default `false`)                            | Run the agent read-only to author the body before the preview.                                    |
+| `title`       | string                                            | A `{{key}}` pattern for the title (see [Title](#title)).                                          |
+| `questions`   | question[] (default `[]`)                         | The typed inputs collected from the operator (see [Questions](#questions)).                       |
 
 ## Questions
 
@@ -99,7 +99,7 @@ by giving it a new name.
 
 A template's `agent`, `jobKind`, and `runMode` are translated to the board's **picker
 labels** on creation: `agent:<name>`, `jobkind:<jobKind>`, `run:<mode>`. The board
-provisions these labels through `beflow setup` / `beflow update` — the `jobkind:*`
+provisions these labels through [`beflow setup` / `beflow update`](commands.md#setup-project--update-project) — the `jobkind:*`
 labels (`jobkind:triage`, `jobkind:spec`, `jobkind:implement`) are seeded alongside the
 `run:*` pickers. After adding a template that pins a new `jobKind`, run
 `beflow update <KEY>` once so the label exists. `createIssue` resolves each picker

docs/mcp.md

@@ -1,7 +1,7 @@
 # MCP servers (per-run, via acpx)
 
 beflow can hand the coding agent a set of **MCP servers** on a per-run basis. When
-`mcp.enabled` is `true` in `config.json`, beflow reads a user `.mcp.json`, translates
+[`mcp.enabled`](config.md#top-level) is `true` in `config.json`, beflow reads a user `.mcp.json`, translates
 it to the ACP `McpServer` shape, and injects it as a managed `.acpxrc.json` into the
 agent's working directory. acpx merges `<cwd>/.acpxrc.json` and forwards its
 `mcpServers` to the ACP `session/new` request.

docs/prompts.md

@@ -32,7 +32,7 @@ issue fields.
 
 ### Issue-authoring template (`issue-enrich.md`)
 
-`issue-enrich.md` is a separate prompt used only by `beflow new --enrich`. It is
+`issue-enrich.md` is a separate prompt used only by [`beflow new`](commands.md#new-project-template) `--enrich`. It is
 **not** part of `PromptSet` and is loaded on demand by `loadEnrichPrompt`. It rides
 the same override cascade as the rest of the templates. For the `beflow new`
 issue-template system (the per-type Markdown frontmatter files), see
@@ -62,7 +62,7 @@ For each template, beflow resolves the first readable file in this order
 (highest priority first) and falls back to the compiled-in default if none exist:
 
 1. `<configDir>/prompts/<name>.md` — project-local, beside the `config.json` beflow loaded.
-2. `<prompts.dir>/<name>.md` — the directory named by the optional `prompts.dir`
+2. `<prompts.dir>/<name>.md` — the directory named by the optional [`prompts.dir`](config.md#top-level)
    config key (a leading `~` expands to your home directory).
 3. `~/.beflow/prompts/<name>.md` — your personal global override.
 4. The compiled-in default (embedded in the binary at build time).

docs/resolution.md

@@ -10,12 +10,12 @@ the first non-`undefined` value in a priority-ordered list wins. Empty string an
 
 Each field can be supplied from up to four sources, in priority order:
 
-| Source             | What it is                                                                |
-| ------------------ | ------------------------------------------------------------------------- |
-| `cli`              | Command-line flags passed to `beflow run` for this invocation.            |
-| `meta`             | Per-issue metadata parsed from the issue body and labels (see below).     |
-| `project.defaults` | The `defaults` object inside the matching project entry in `config.json`. |
-| `global.defaults`  | The top-level `defaults` object in `config.json` (`fileSchema.defaults`). |
+| Source             | What it is                                                                            |
+| ------------------ | ------------------------------------------------------------------------------------- |
+| `cli`              | Command-line flags passed to [`beflow run`](commands.md#run-key) for this invocation. |
+| `meta`             | Per-issue metadata parsed from the issue body and labels (see below).                 |
+| `project.defaults` | The `defaults` object inside the matching project entry in `config.json`.             |
+| `global.defaults`  | The top-level `defaults` object in `config.json` (`fileSchema.defaults`).             |
 
 ### Per-issue metadata (`meta`)
 
@@ -112,7 +112,7 @@ filesystem path).
 
 Area-derived uses only the **primary area** (first element of `issue.areas`):
 `project.module_repo_map[areas[0]]`. If the issue has no areas, or the primary
-area has no entry in `module_repo_map`, this slot is skipped.
+area has no entry in [`module_repo_map`](config.md#projects), this slot is skipped.
 
 If all four slots are `undefined`, beflow throws: