@open-agent-toolkit/cli 0.3.13 → 0.3.15

package/assets/docs/{cli-utilities → reference}/configuration.md

@@ -12,10 +12,10 @@ Use this guide when you need to answer two questions quickly:
 
 For the deep file-by-file reference, see:
 
-- [File Locations](../reference/file-locations.md)
-- [`.oat` Directory Structure](../reference/oat-directory-structure.md)
+- [File Locations](file-locations.md)
+- [`.oat` Directory Structure](oat-directory-structure.md)
 - [Sync Config (`.oat/sync/config.json`)](../provider-sync/config.md)
-- [Remote Project Management](remote-project-management.md)
+- [Remote Project Management](../workflows/backlog-and-planning/remote-project-management.md)
 
 ## The five config surfaces
 
@@ -44,15 +44,15 @@ oat config list
 oat config get projects.root
 oat config describe
 oat config describe archive.s3Uri
-oat config describe sync.providers.github.enabled
+oat config describe sync.providers.copilot.enabled
 ```
 
 What each command is for:
 
 - `oat config list` shows the currently resolved command-surface values for shared and repo-local keys.
 - `oat config get <key>` reads one supported key value.
-- `oat config set <key> <value>` updates supported shared or repo-local keys. Writes to the shared `.oat/config.json` keep the file's existing key order, and a write that would not change any value leaves the file byte-identical.
-- `oat config unset <key>` removes a supported key from one surface, using the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. The resolved value then falls back to the next surface down, or to the built-in default. A key the surface does not hold exits 0 as already-unset (`--json` adds a `removed` boolean to tell the two apart). Unknown keys, lifecycle state, `tools.*` pack intent, aggregate read views, read-only remote-policy structure, and environment-shadowed keys with nothing stored are refused with exit 1 — see [CLI Reference](../reference/cli-reference.md#oat-config-surface-flags).
+- `oat config set <key> <value>` updates supported shared, repo-local, or user keys according to per-key restrictions. Writes to the shared `.oat/config.json` keep the file's existing key order, and a write that would not change any value leaves the file byte-identical.
+- `oat config unset <key>` removes a supported key from one surface, using the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. The resolved value then falls back to the next surface down, or to the built-in default. A key the surface does not hold exits 0 as already-unset (`--json` adds a `removed` boolean to tell the two apart). Unknown keys, lifecycle state, `tools.*` pack intent, aggregate read views, read-only remote-policy structure, and environment-shadowed keys with nothing stored are refused with exit 1 — see [CLI Reference](cli-reference.md#oat-config-surface-flags).
 - `oat config describe` shows the supported config catalog across shared repo, repo-local, user, and sync/provider surfaces.
 - `oat config describe <key>` shows file, scope, default, mutability, owning command, and description for one key. A deprecated key also prints `Deprecated: prefer <successor>`, and `--json` carries the same fact as a `deprecated` object (`supersededBy`, plus `note` and `legacyValues` where they apply).
 
@@ -72,9 +72,9 @@ For a guided pass instead of individual commands, run the `/oat-doctor` skill (c
 
 These labels match what `oat config dump` emits, so tooling that consumes either command can rely on the same vocabulary.
 
-:::note Upgrade note
-Earlier CLI versions returned `config.json` / `config.local.json` / `env` / `default` as the `source` strings. External scripts that previously matched on `"source":"config.json"` or `"source":"config.local.json"` should update to match the new `shared` / `local` labels. This change was made to align the `oat config get` / `oat config list` output with `oat config dump` and to avoid confusing users about which file was consulted.
-:::
+> [!NOTE]
+> **Upgrade note.**
+> Earlier CLI versions returned `config.json` / `config.local.json` / `env` / `default` as the `source` strings. External scripts that previously matched on `"source":"config.json"` or `"source":"config.local.json"` should update to match the new `shared` / `local` labels. This change was made to align the `oat config get` / `oat config list` output with `oat config dump` and to avoid confusing users about which file was consulted.
 
 ## Shared repo config you will touch most often
 
@@ -93,7 +93,7 @@ Common keys in `.oat/config.json`:
   configured value for the current process.
 - `worktrees.root` — where OAT-managed worktrees live
 - `git.defaultBranch` — base branch fallback for PR workflows
-- `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership. With tooling `markdown`, root is the literal content directory (including nested `docs`) and `documentation.index` is authored `<root>/index.md`; Markdown adds no framework config. Framework roots retain app/source semantics. Use `oat docs init --framework markdown` or explicit `--adopt` for setup; optional manifests need external output and never change the authored index. See [Documentation path resolution](../reference/oat-directory-structure.md#documentation-path-resolution)
+- `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership. With tooling `markdown`, root is the literal content directory (including nested `docs`) and `documentation.index` is authored `<root>/index.md`; Markdown adds no framework config. Framework roots retain app/source semantics. Use `oat docs init --framework markdown` or explicit `--adopt` for setup; optional manifests need external output and never change the authored index. See [Documentation path resolution](oat-directory-structure.md#documentation-path-resolution)
 - `documentation.excludes` — a JSON array of globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. `oat config set` takes the list as one comma-separated value (`"a/**,b.md"`) and stores it as an array; repeated `--exclude` flags extend it, and an empty value clears the key
 - `documentation.requireForProjectCompletion` — whether docs sync is a completion gate
 - `instructions.claude.shims` — how `oat instructions sync` keeps a `CLAUDE.md` beside each `AGENTS.md`: `none` (the default: no shims; sync removes the ones OAT created and warns about any other `CLAUDE.md`, all or nothing: it removes none while any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` has content of its own; see [All or nothing](../provider-sync/instruction-sync.md#all-or-nothing)), `pointer`, `symlink`, or `copy`. The `--strategy` flag overrides it for one run. Set it with `oat config set instructions.claude.shims pointer` when contributors need `CLAUDE.md` (see [Claude Code and AGENTS.md](../provider-sync/instruction-sync.md#claude-code-and-agentsmd)); `oat config unset` returns to `none`. Any other value is rejected with exit code `2` rather than read as unset, and `oat config set` can still replace it
@@ -106,7 +106,8 @@ Common keys in `.oat/config.json`:
 - `archive.awsRegion` — optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows
 - `tools.<pack>` — project-scope intent for a bundled tool pack (`true` or absent)
 - `pjm.remote.storage.state` — `local` by default; `shared` requires an
-  explicit preview and fresh approval and is unavailable to local projects
+  explicit preview and fresh approval. The current production store does not
+  enforce the intended local-project exclusion; see the remote storage warning
 - `pjm.remote.policy.description` — `none`, `managed-section`, or `replace`;
   the default is `none`
 - `pjm.remote.policy.authority.*` — repository defaults and operation-specific
@@ -126,6 +127,10 @@ and purpose field grants intersect to narrow outbound fields. No configured
 layer bypasses hard approval floors or current caller-owned authority evidence;
 missing, stale, or mismatched evidence fails closed.
 
+Current CLI bindings use fixed intake/source or publish/planning purposes and
+empty per-binding restrictions. Those internal narrowing layers are not
+additional user-settable binding policy controls.
+
 The shared `pjm.remote` tree is closed. An unknown key, a non-object where an
 object is expected, or a wrong-typed leaf (for example `authority.default: 5`,
 a string `schemaVersion`, or a number, boolean, array, object, or `null` where a
@@ -189,7 +194,7 @@ oat pjm doctor --json
 verified. It is the authoritative repository adoption marker: PJM, backlog, and
 decision mutations fail closed without it, and `oat doctor` keys its `pjm:*`
 checks on adoption state rather than on `tools.project-management`. See
-[Install vs. initialize](tool-packs.md#install-vs-initialize) for the full state
+[Install vs. initialize](../getting-started/tool-packs.md#install-vs-initialize) for the full state
 table and template precedence.
 
 ### Explainer configuration
@@ -263,9 +268,8 @@ packaged `assets/` directory next to the installed CLI. Setting a non-empty
   `validateBundleStructure`. That is a narrower promise than the exit-2 list
   above: release validation does not check bundle metadata beyond its presence,
   so a malformed or version-mismatched `bundle-metadata.json` is not covered.
-  The regression evidence is the negative pack control in
-  `packages/cli/src/release/public-package-contract.test.ts`:
-  `fails release validation when a required bundle directory is empty in the tarball`.
+  OAT's own release tests include a check that release validation fails when a
+  required bundle directory is empty in the packed tarball.
 - Produce a matching bundle with `bash packages/cli/scripts/bundle-assets.sh`
   while `OAT_ASSETS_DIR` points at the target directory (the script already
   honors the variable as its destination).
@@ -273,12 +277,12 @@ packaged `assets/` directory next to the installed CLI. Setting a non-empty
 This is primarily a test-isolation and packaging seam; day-to-day use of the CLI
 does not need it.
 
-See [Explainer Kit](../workflows/skills/explainer-kit.md) for recipes, artifact
+See [Explainer Kit](../skills/explainer-kit.md) for recipes, artifact
 locations, lifecycle behavior, and archive/export behavior.
 
 Workflow gate objects are structured config and use their own command group
 instead of the scalar `oat config set` surface. See
-[Workflow Gates](workflow-gates.md) for the full command surface and examples.
+[Workflow Gates](../workflows/advanced/workflow-gates.md) for the full command surface and examples.
 
 Gate budgets resolve per run in this order: CLI `--timeout-ms`, selected
 target `timeoutMs`, `workflow.gateTimeouts` by review type,
@@ -377,7 +381,7 @@ configuration, never mutates any config layer, and is never written by a
 non-interactive run. Resolve it with
 `oat gate resolve <skill> --project <path-or-name> --json`; without `--project`
 the command keeps its original raw output. See
-[Workflow gates](./workflow-gates.md) for the full resolution envelope and the
+[Workflow gates](../workflows/advanced/workflow-gates.md) for the full resolution envelope and the
 phase-review and autonomous exclusions.
 
 In practice, you usually inspect these via:
@@ -398,14 +402,14 @@ Dispatch configuration has two layers:
 
 A named ceiling is a maximum constraint, not an exact model-family or effort
 preference. For the full model, see
-[Dispatch Policy](../workflows/projects/dispatch-ceiling.md).
+[Dispatch Policy](../workflows/advanced/dispatch-ceiling.md).
 
 ### Config keys
 
 | Key                                                    | Values                                                | Purpose                                                                              |
 | ------------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------ |
 | `workflow.dispatchPolicy.mode`                         | `managed`, `inherit`                                  | `managed` lets OAT select exact candidates; `inherit` leaves controls to the host    |
-| `workflow.dispatchPolicy.policy`                       | `economy`, `balanced`, `high`, `frontier`, `uncapped` | Default named maximum or explicit managed uncapped state                             |
+| `workflow.dispatchPolicy.policy`                       | `economy`, `balanced`, `high`, `frontier`, `uncapped` | Configured maximum overriding project state, or explicit managed uncapped state      |
 | `workflow.dispatchCeiling.providers.<provider>`        | tier map or legacy bare value                         | Reusable provider candidate column                                                   |
 | `workflow.dispatchCeiling.providers.<provider>.<tier>` | `candidates` cell, route, or legacy bare value        | One named tier in the provider ladder                                                |
 | `workflow.dispatchCeiling.recommendationVersion`       | string                                                | Bundle version last written by adoption; does not prove the effective ladder matches |
@@ -705,7 +709,7 @@ Workflow preferences let power users answer repetitive confirmation prompts once
 Workflow preference keys live under the `workflow.*` namespace:
 
 - `workflow.designMode` — `collaborative`, `selective`, or `draft`. Default design interaction mode. `selective` applies only to full `oat-project-design`; quick-start lightweight design treats it as collaborative because quick-start keeps the smaller collaborative/draft choice.
-- `workflow.hillCheckpointDefault` — `every` or `final`. Default HiLL checkpoint behavior in `oat-project-implement`: pause after every phase or only after the last phase. When unset, the skill prompts.
+- `workflow.hillCheckpointDefault` — `every` or `final`. Default HiLL checkpoint behavior in `oat-project-implement` (a HiLL, or human-in-the-loop, checkpoint is a stop for your review): pause after every phase or only after the last phase. When unset, the skill prompts. See [Choosing a checkpoint default](#choosing-a-checkpoint-default).
 - `workflow.archiveOnComplete` — boolean. Skip the "Archive after completion?" prompt in `oat-project-complete`. When unset, the skill prompts.
 - `workflow.createPrOnComplete` — boolean. Skip the "Open a PR?" prompt in `oat-project-complete`; when true, completion auto-triggers PR creation. When unset, the skill prompts.
 - `workflow.postImplementSequence` — legacy `wait`, `summary`, `pr`, or `docs-pr`, or `{ "preApproval": [...], "postApproval": [...] }`. Legacy values remain strings and keep their existing mappings. Structured arrays contain ordered, globally unique `summary`, `document`, `pr`, and `retro` steps. `retro` is post-approval only: a structured value containing it in `preApproval` is rejected. Pre-approval steps run after final review and before final HiLL approval; post-approval steps run only after that approval. Plain retrieval keeps legacy strings and prints structured values as compact JSON; `--json` returns the raw value.
@@ -735,6 +739,22 @@ Without those settings, non-interactive retro generation records proposals but
 does not apply or file them. Interactive runs still present the applicable
 promotion and filing choices before side effects.
 
+What leaves your repository through retro filing: `oat-project-retro-file`
+files the retro's "OAT Upstream Feedback" items (`UP-01`, `UP-02`, and so on;
+each is a title plus a problem, evidence summary, and suggested direction) as
+GitHub issues in the upstream repository. That repository is
+`workflow.retro.upstreamRepo` when set and `voxmedia/open-agent-toolkit` when
+it is not. Nothing is filed by default: the skill runs only when you ask for
+it, an interactive run asks you to confirm each destination and each item, and
+a non-interactive run files nothing for a lane whose filing key is unset or
+`none`. When the source repository is private and the destination is public,
+the skill removes private log excerpts, internal URLs, credential-shaped
+strings, and private identifiers before posting, and does not post an item it
+cannot sanitize safely. To stop non-interactive upstream filing, run
+`oat config set workflow.retro.filing.upstream none`; to send upstream items to
+a different repository, run
+`oat config set workflow.retro.upstreamRepo <owner/name>`.
+
 The two project-log keys use the standard workflow precedence:
 `local > shared > user > default`.
 
@@ -764,7 +784,7 @@ explicit final-default path and enables checkpoint auto-review; it preserves an
 existing valid empty or explicit list. Because autonomy itself is never
 persisted, a later interactive run pauses at the stored checkpoints normally.
 
-See [HiLL Checkpoints](../workflows/projects/hill-checkpoints.md) for timing and
+See [HiLL Checkpoints](../workflows/projects/planning/hill-checkpoints.md) for timing and
 approval behavior.
 
 ### Auto artifact-review preferences
@@ -792,23 +812,20 @@ Workflow preferences resolve through three config surfaces, with `local > shared
 
 ```bash
 # User-level: applies to all repos on this machine
+# Checkpoint default: choose every (pause after each phase) or final (pause once at the end)
 oat config set workflow.hillCheckpointDefault final --user
-oat config set workflow.archiveOnComplete true --user
-oat config set workflow.createPrOnComplete true --user
-oat config set workflow.postImplementSequence pr --user
 oat config set workflow.reviewExecutionModel subagent --user
 oat config set workflow.autoReviewAtHillCheckpoints true --user
 oat config set workflow.designMode selective --user
-oat config set workflow.dispatchCeiling.preset balanced --user
-oat config adopt dispatch-matrix --user
-oat config set workflow.autoArtifactReview.plan true --user
-oat config set workflow.autoArtifactReview.analysis true --user
+oat config set workflow.autoNarrowReReviewScope true --user
+oat config adopt dispatch-matrix --user  # your own model ladder; sets no policy
 
 # Shared repo: team decision for this repo
+oat config set workflow.archiveOnComplete true --shared
+oat config set workflow.postImplementSequence docs-pr --shared
 oat config set workflow.createPrOnComplete false --shared
 oat config set workflow.designMode collaborative --shared
-oat config set workflow.dispatchCeiling.preset balanced --shared
-oat config set workflow.dispatchCeiling.providers.cursor.high composer-2.5 --shared
+oat config set workflow.dispatchCeiling.providers.cursor.high composer-2.5 --shared  # one ladder cell
 oat config set workflow.autoArtifactReview.plan false --shared
 oat config set workflow.projectLog auto --shared
 oat config set workflow.projectLogLedgerPath .oat/repo/reference/project-observations.md --shared
@@ -816,10 +833,40 @@ oat config set workflow.projectLogLedgerPath .oat/repo/reference/project-observa
 # Repo-local: personal override for this repo (default when no flag)
 oat config set workflow.hillCheckpointDefault every
 oat config set workflow.designMode draft
-oat config set workflow.dispatchCeiling.providers.codex medium  # Advanced: per-provider override
 oat config set workflow.autoArtifactReview.analysis false
 ```
 
+The user-level workflow preference lines use only keys that this page lists as
+safe personal defaults in [Choosing the right surface](#choosing-the-right-surface-personal-vs-per-repo).
+The dispatch lines adopt a model ladder and set one ladder cell; neither sets
+a dispatch policy. The examples deliberately leave out the legacy
+`workflow.dispatchCeiling.preset` key and bare per-provider values such as
+`workflow.dispatchCeiling.providers.codex medium`: both still work, but they
+replace that scope's ladder columns with a single legacy ceiling, and a
+dispatch policy set in any config file overrides every project's own choice.
+Read the warning below and [Dispatch Policy](../workflows/advanced/dispatch-ceiling.md)
+before setting either.
+The completion and PR keys (`workflow.archiveOnComplete`,
+`workflow.createPrOnComplete`, and `workflow.postImplementSequence`) appear in
+the shared block instead. A value in `~/.oat/config.json` applies in every
+repository on your machine that does not set the same key in its own
+`.oat/config.json` or `.oat/config.local.json`, because OAT resolves each key
+as local, then shared, then user, then the built-in default. Whether those
+completion keys are safe depends on each repository's archive and
+documentation settings, so set them per repository. The
+`workflow.autoArtifactReview.*` keys already default to `true`; set them only
+in a repository that opts out, as the shared and repo-local examples show.
+
+The legacy preset and bare-provider examples above remain readable compatibility
+syntax, not recommended complete-ladder setup. They can replace candidate
+columns with bare legacy ceilings. Prefer named policy plus explicit ladder
+adoption for new configurations.
+
+> [!WARNING]
+> A dispatch policy set in any config file overrides the policy that every
+> project chose for itself in its `state.md`. Leave the policy keys unset when
+> each project should choose its own policy.
+
 Default (no flag) targets `.oat/config.local.json` for workflow keys. Pass at most one of `--user`, `--shared`, or `--local`. Structural keys (`projects.root`, `worktrees.root`, `git.*`, `documentation.*`, `instructions.*`, `archive.*`, `tools.*`) are still shared-only regardless of flag.
 
 ### Choosing the right surface (personal vs per-repo)
@@ -830,7 +877,7 @@ Not every workflow preference belongs at user level, even though "set once, appl
 
 Some preferences are **genuinely personal** — their correct value is the same for you regardless of which repo you're in. These are safe to set at `--user`:
 
-- `workflow.hillCheckpointDefault` — your personal tolerance for mid-implementation interruption
+- `workflow.hillCheckpointDefault` — how often you want implementation to pause for your review. It is a personal preference by default; see [Choosing a checkpoint default](#choosing-a-checkpoint-default) below for when a team should set it instead.
 - `workflow.designMode` — your preferred full-design interaction style. Set `selective` when you usually want low-risk sections drafted silently but high-risk sections reviewed live.
 - `workflow.reviewExecutionModel` — depends on your provider environment (Claude Code, Cursor, Codex), not the repo
 - `workflow.autoReviewAtHillCheckpoints` — your preference for automatic lifecycle review at HiLL checkpoints. Shared/local config can still override this when a repo should behave differently.
@@ -845,10 +892,12 @@ Other preferences **depend on per-repo configuration** to be safe. These should
 
 **Cross-repo foot-gun example:** If you set `workflow.createPrOnComplete: true --user`, it applies to every repo you work on. In a repo with `documentation.requireForProjectCompletion: true` and `postImplementSequence: pr` (no docs step), running `oat-project-complete` would try to auto-create a PR, then immediately hit the docs gate and block you — leaving you with an open PR and a stuck completion. Your user-level preference silently asserted something that only holds in a specific shared-config shape.
 
-**Recommended split for most users:**
+**Example split between personal and team settings:**
 
 ```bash
 # Personal preferences that differ from built-in defaults (apply everywhere)
+# Optional checkpoint default: every for more control, final for fewer interruptions;
+# leave unset to be asked on each project's first implementation run
 oat config set workflow.hillCheckpointDefault final --user
 oat config set workflow.reviewExecutionModel subagent --user
 oat config set workflow.autoReviewAtHillCheckpoints true --user
@@ -864,6 +913,29 @@ If you want to override a shared team decision for this specific checkout, use `
 oat config set workflow.archiveOnComplete false --local  # "I don't want to archive on this specific branch checkout"
 ```
 
+### Choosing a checkpoint default
+
+`workflow.hillCheckpointDefault` decides where `oat-project-implement` stops
+for your review. These stops are called HiLL checkpoints (HiLL stands for
+"human in the loop"). Neither value is right for everyone:
+
+- `every` pauses after each phase. You get more control over the work, at the
+  cost of more interruptions.
+- `final` pauses once, after the last phase. You are interrupted less, but you
+  see the work only at the end.
+
+When the key is unset, the first implementation run of each project asks you
+which to use. When it is set, that first run uses the configured value without
+asking, and the value replaces any checkpoint value already written in the
+project's `plan.md`. Later runs of the same project keep the value stored in
+`plan.md`.
+
+Treat the key as a personal preference by default, and set it at user level
+(`--user`) or for one checkout (`--local`). Set it at shared level (`--shared`)
+only when your team has agreed on a rule for where agents must pause. A shared
+value overrides each person's user-level value, but anyone can still override
+it for their own checkout with `--local`.
+
 ### Relationship to `autoReviewAtCheckpoints`
 
 `workflow.autoReviewAtHillCheckpoints` is the preferred key. It controls whether `oat-project-implement` runs the extra lifecycle review when a configured HiLL checkpoint is reached.
@@ -914,3 +986,48 @@ When you are unsure where a setting lives:
 3. Use the owning command shown there.
 
 That keeps config discovery centralized without forcing you to remember which settings belong to workflow state versus provider sync.
+
+## Choosing a config layer
+
+`oat config set` can write a setting to one of three files, called layers:
+
+- **shared** (`--shared`): `.oat/config.json`, committed with the repository so
+  it applies to the whole team;
+- **local** (`--local`): `.oat/config.local.json`, which applies only to this
+  checkout and is not committed;
+- **user** (`--user`): `~/.oat/config.json` in your home directory, which
+  applies to you in every repository.
+
+When the same key is set in more than one layer, local wins over shared, and
+shared wins over user. A team's shared value therefore overrides your personal
+user value unless you also set it locally.
+
+| Layer      | Choose it when                                              | What you give up                                                      |
+| ---------- | ----------------------------------------------------------- | --------------------------------------------------------------------- |
+| `--shared` | The team should behave the same way in this repository      | Personal flexibility: changes go through code review like other files |
+| `--local`  | You want to override something for yourself in one checkout | Nobody else, and none of your other checkouts, sees the value         |
+| `--user`   | The value is about how you work, whatever the repository    | Any repository that sets the key in shared or local config wins       |
+
+With no flag, workflow preferences, project state, and explainer defaults are
+written to local config, update notifications to user config, and structural
+settings (repository paths and policy, such as `projects.root` or
+`documentation.*`) to shared config. Some keys can live in only one layer:
+project state is local-only, update notifications are user-only, and remote
+project-management policy is shared-only. `oat tools install` records each pack
+in the scope you installed it to, but `oat config set tools.*` writes only to
+shared config.
+
+- If you are trying OAT on your own, set values with no flag and accept the
+  defaults.
+- If you are rolling OAT out to a team, set policy keys with `--shared` and
+  commit the change so it is reviewed.
+- If you want a preference to follow you into every repository, use `--user`,
+  but only for keys listed as personal in
+  [Choosing the right surface](#choosing-the-right-surface-personal-vs-per-repo).
+- If you need to differ from the team's setting in one checkout, use `--local`
+  rather than changing the policy for everyone.
+
+Environment variables override all three layers, but only for three keys:
+`projects.root`, `projects.defaultScope`, and `worktrees.root`. Some skills read
+their own environment variables, such as `OAT_DESIGN_MODE`; those are separate
+from config resolution.

package/assets/docs/reference/file-locations.md

@@ -111,7 +111,7 @@ When shared state is explicitly previewed and approved,
 `.oat/repo/pjm/remote/state/` or `<project>/remote/state/` replaces the local
 operational root. Shared state can contain remote planning content and is not
 available for local projects. See
-[Remote Project Management](../cli-utilities/remote-project-management.md).
+[Remote Project Management](../workflows/backlog-and-planning/remote-project-management.md).
 
 ## Project artifact trees
 
@@ -168,6 +168,9 @@ Archive sync surfaces:
 
 ## CLI code
 
+These paths are in the OAT source repository, not in a repository that uses
+OAT. They matter only if you are working on OAT itself.
+
 - `packages/control-plane/` - read-only control-plane library for project-state parsing and recommendation
 - `packages/cli/src/commands/`
 - `packages/cli/src/commands/cleanup/`

package/assets/docs/reference/index.md

@@ -11,11 +11,17 @@ Contributor how-to material now lives under `contributing/`, and user-facing rou
 
 ## Contents
 
+- [What OAT Writes](what-oat-writes.md) - Every file, link and Git ref OAT creates, what to commit, and how to remove it.
+- [Configuration](configuration.md) - OAT configuration guidance across shared, local, user, and provider-sync surfaces.
+- [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
 - [CLI Reference](cli-reference.md) - Shallow map of the OAT command surface with links to owning sections.
 - [File Locations](file-locations.md) - Where core OAT files, assets, and artifacts live.
 - [Docs Index Contract](docs-index-contract.md) - Authored `index.md` maps, `.md` links, generated Fumadocs manifests, and MkDocs and Fumadocs nav sync boundaries.
-- [OAT Directory Structure](oat-directory-structure.md) - Canonical `.oat/` tree map and the role of each major directory.
+- [`.oat` Directory Structure](oat-directory-structure.md) - Canonical `.oat/` tree map and the role of each major directory.
 - [Troubleshooting](troubleshooting.md) - Common issues, diagnostics, and remediation guidance.
+- [Project Artifacts](project-artifacts.md) - What lives in `state.md`, `discovery.md`, `plan.md`, `implementation.md`, and related files.
+- [State Machine](project-state-machine.md) - Lifecycle and review status transitions across a project.
+- [Repository PR Comment Analysis](repository-pr-comments.md) - Repo-wide PR comment collection and triage workflows.
 
 ## What Belongs Here
 
@@ -28,3 +34,9 @@ Contributor how-to material now lives under `contributing/`, and user-facing rou
 - [CLI Reference](cli-reference.md) for the command-surface map
 - [Docs Tooling](../docs-tooling/index.md) for docs app setup and workflow guidance
 - [Contributing](../contributing/index.md) for code, docs, and skill-authoring practices
+
+## General CLI Adoption Guidance
+
+Use OAT's general CLI for repository setup, tool-pack management, configuration and diagnostics independently of provider sync, docs tooling or tracked workflows.
+
+Start with [Getting Started](../getting-started/index.md) for bootstrap and tool packs. See [Configuration](configuration.md) for settings, [Config and Local State](config-and-local-state.md) for diagnostics, and [Advanced](../workflows/advanced/index.md) for workflow gates.

package/assets/docs/reference/meta.json

@@ -1,10 +1,16 @@
 {
   "title": "Reference",
   "pages": [
+    "what-oat-writes",
+    "configuration",
+    "config-and-local-state",
     "cli-reference",
     "file-locations",
     "docs-index-contract",
     "oat-directory-structure",
-    "troubleshooting"
+    "troubleshooting",
+    "project-artifacts",
+    "project-state-machine",
+    "repository-pr-comments"
   ]
 }

package/assets/docs/reference/oat-directory-structure.md

@@ -148,7 +148,7 @@ Current schema keys:
 Most `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`. One has no `oat config set` entry and is edited directly in `.oat/config.json`: `documentation.index`, which `oat docs init` still seeds for you.
 The `git.defaultBranch` key is auto-detected during `oat init` and can be overridden via `oat config set git.defaultBranch <branch>`.
 Archive settings are managed via `oat config get/set`, and `oat config describe archive.s3Uri` (or the other archive keys) shows the lifecycle and ownership details from the CLI.
-Workflow gate objects are structured config and are managed with `oat gate`, not the scalar `oat config set` surface. See [Workflow Gates](../cli-utilities/workflow-gates.md).
+Workflow gate objects are structured config and are managed with `oat gate`, not the scalar `oat config set` surface. See [Workflow Gates](../workflows/advanced/workflow-gates.md).
 
 Example:
 

package/assets/docs/{workflows/projects/artifacts.md → reference/project-artifacts.md}

@@ -86,7 +86,7 @@ behavioral change needs evidence that fails without the change.
   machine-scannable repo-improvement (`RP-NN`) and upstream-feedback (`UP-NN`)
   registers. Promotion and filing rollups let the retro skills resume approved
   applications and tracker filing without repeating settled work. See
-  [Project Retrospectives](retro.md).
+  [Project Retrospectives](../workflows/projects/closeout/retro.md).
 
 ### Explainer artifacts
 
@@ -197,7 +197,7 @@ Coordination parents do not contain executable phase files. `spec.md`, `design.m
 
 The parent still keeps `state.md`, `discovery.md`, and `references/split-plan.json`. Child projects are flat siblings and link back to the parent through state metadata. Each child starts from a distilled discovery seed and must revalidate inherited context before moving beyond discovery/design.
 
-See [Project Splitting](splitting.md) for the full parent/child model.
+See [Project Splitting](../workflows/projects/planning/splitting.md) for the full parent/child model.
 
 ### plan.md frontmatter
 
@@ -232,7 +232,7 @@ Each inner array is a group of phases that execute concurrently in their own wor
 
 **Validation:**
 
-Before dispatching, `oat-project-implement` invokes `oat project validate-plan --project-path "${PROJECT_PATH}"`. Non-zero exit blocks the run. See [CLI Reference](../../reference/cli-reference.md) and [Implementation Execution](implementation-execution.md) for details.
+Before dispatching, `oat-project-implement` invokes `oat project validate-plan --project-path "${PROJECT_PATH}"`. Non-zero exit blocks the run. See [CLI Reference](cli-reference.md) and [Implementation Execution](../workflows/projects/execution/implementation-execution.md) for details.
 
 #### oat_phase_review_gate
 
@@ -261,7 +261,7 @@ oat_phase_review_gate:
 - `review_type` → optional, defaults to `code`. Only `code` is supported for phase gates.
 - `exit_nonzero_on` → optional, defaults to `high`. One of `critical`, `high`, `medium`, `low`. This is the blocking threshold: findings at or above it stop the phase; sub-threshold findings are dispositioned by the judgment sweep rather than ignored.
 
-A malformed gate stops the run before task execution rather than being silently disabled. The gate is independent of HiLL checkpoints and reuses the existing `oat gate review` target config — it does not hardcode a `--target`. See [Reviews → Phase review gate](reviews.md#phase-review-gate) for the runtime behavior and disposition rules.
+A malformed gate stops the run before task execution rather than being silently disabled. The gate is independent of HiLL checkpoints and reuses the existing `oat gate review` target config — it does not hardcode a `--target`. See [Reviews → Phase review gate](../workflows/projects/reviews/index.md#phase-review-gate) for the runtime behavior and disposition rules.
 
 ## Reference artifacts
 

package/assets/docs/{workflows/projects/state-machine.md → reference/project-state-machine.md}

@@ -15,26 +15,33 @@ This page is the compact contract for how project lifecycle state and review sta
 
 ## State Transition Map
 
-```mermaid
-flowchart TD
-  D["Discovery in progress"] --> RS["Ready for spec"]
-  RS --> S["Spec in progress"] --> RD["Ready for design"]
-  RD --> G["Design in progress"] --> RP["Ready for plan"]
-  RP --> P["Plan in progress"] --> RI["Ready for implement"]
-  RI --> I["Implement in progress"] --> IC["Implement complete"]
-  IC --> PRO["PR open (pr_open)"]
-  PRO --> REV["Revise (in_progress)"]
-  REV --> PRO
-  PRO --> C["Complete"]
-
-  I --> RV["Review received"]
-  RV --> FA["Fixes added"]
-  FA --> FC["Fixes completed"]
-  FC --> PASSED["Review passed"]
-  PASSED --> I
-
-  LITE["Lite: batched interview\n(no discovery/spec/design)"] -. entry point .-> P
-```
+=== "Diagram"
+
+    ![Project state machine: discovery, spec, design, plan and implementation phases, then PR open and complete; a review loop returns to implementation, a revise loop runs from PR open and back, and lite enters at planning](/diagrams/project-state-machine-light.svg)
+    ![Project state machine: discovery, spec, design, plan and implementation phases, then PR open and complete; a review loop returns to implementation, a revise loop runs from PR open and back, and lite enters at planning](/diagrams/project-state-machine-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      D["Discovery in progress"] --> RS["Ready for spec"]
+      RS --> S["Spec in progress"] --> RD["Ready for design"]
+      RD --> G["Design in progress"] --> RP["Ready for plan"]
+      RP --> P["Plan in progress"] --> RI["Ready for implement"]
+      RI --> I["Implement in progress"] --> IC["Implement complete"]
+      IC --> PRO["PR open (pr_open)"]
+      PRO --> REV["Revise (in_progress)"]
+      REV --> PRO
+      PRO --> C["Complete"]
+
+      I --> RV["Review received"]
+      RV --> FA["Fixes added"]
+      FA --> FC["Fixes completed"]
+      FC --> PASSED["Review passed"]
+      PASSED --> I
+
+      LITE["Lite: batched interview\n(no discovery/spec/design)"] -. entry point .-> P
+    ```
 
 The solid chain is the spec-driven progression. Lite enters at **Plan in
 progress** and never sets `oat_phase` to `discovery`, `spec`, or `design`;
@@ -83,7 +90,7 @@ Lite progression:
 A lite project that outgrows one sitting can move to the quick chain with `oat
 project promote <project-path> --to quick`, which flips `oat_workflow_mode` to
 `quick` and sets `oat_phase: discovery` with `oat_phase_status: complete`. See
-[Lifecycle](lifecycle.md#promoting-a-lite-project-to-quick).
+[Lifecycle](../workflows/projects/lifecycle.md#promoting-a-lite-project-to-quick).
 
 ## Review progression
 

package/assets/docs/{workflows/projects/repo-analysis.md → reference/repository-pr-comments.md}

@@ -7,7 +7,7 @@ description: 'Repository-level PR comment analysis commands for collecting and t
 
 The `oat repo pr-comments` command group provides repository-level review analysis tools. These commands operate across merged pull requests rather than on individual PRs.
 
-This page covers the PR-comment analysis surface only. Other repository-level commands, such as `oat repo archive sync`, are covered in [Lifecycle](lifecycle.md#completion-archive-behavior) and [Configuration](../../cli-utilities/configuration.md#shared-repo-config-you-will-touch-most-often).
+This page covers the PR-comment analysis surface only. Other repository-level commands, such as `oat repo archive sync`, are covered in [Lifecycle](../workflows/projects/lifecycle.md#completion-archive-behavior) and [Configuration](configuration.md#shared-repo-config-you-will-touch-most-often).
 
 ## Quick Look
 
@@ -102,4 +102,4 @@ Both commands accept dependency injection for testability:
 
 - Source: `packages/cli/src/commands/repo/pr-comments/`
 - Types: `packages/cli/src/commands/repo/pr-comments/collect/pr-comments.types.ts`
-- Archive sync: [Lifecycle](lifecycle.md#completion-archive-behavior) and [Configuration](../../cli-utilities/configuration.md#shared-repo-config-you-will-touch-most-often)
+- Archive sync: [Lifecycle](../workflows/projects/lifecycle.md#completion-archive-behavior) and [Configuration](configuration.md#shared-repo-config-you-will-touch-most-often)