@open-agent-toolkit/cli 0.3.12 → 0.3.14

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
+- `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/docs-index-contract.md

@@ -1,6 +1,6 @@
 ---
 title: Docs Index Contract
-description: 'Docs source contract: authored index.md maps, generated Fumadocs manifests and meta.json navigation, and MkDocs nav sync.'
+description: 'Docs source contract: authored Markdown context/maps, optional external inventories, Fumadocs manifests and meta.json navigation, and MkDocs nav sync.'
 ---
 
 # Docs Index Contract
@@ -9,7 +9,8 @@ OAT docs navigation starts from authored `docs/**/index.md` files. Each `## Cont
 
 ## Rules
 
-- Every documentation directory must contain an `index.md`.
+- Every non-excluded Markdown-bearing content directory must contain an authored `index.md`; asset-only directories are exempt.
+- Preserve useful audience/scope context, ownership guidance, and existing local instructions. Authored pages need nonempty title/description metadata.
 - Every `index.md` must include a `## Contents` section.
 - The `## Contents` section is the machine-readable local map for sibling pages and child directories.
 - Every `## Contents` link should use a `.md`-suffixed relative target, including child directory links such as `subdir/index.md`.
@@ -35,6 +36,20 @@ Notes:
 - Leaf pages should link to their `.md` filename.
 - Prose outside `## Contents` is ignored by nav generation and remains freeform; it can explain scope, reader paths, or migration status.
 
+## Plain Markdown Ownership
+
+Configured Markdown uses `documentation.root` literally, even with a child named
+`docs`. The configured `<root>/index.md` is authored context plus a Contents map;
+edit it directly. Bootstrap/adoption creates missing baseline files and root
+guidance, but content gaps remain analyze/apply work. No app package, site build,
+nav sync, default manifest, or docs-root AGENTS creation is required.
+
+Optional inventories need explicit output outside the full configured content
+tree, for example `oat docs generate-index --docs-dir docs --output .oat/docs-manifest.md`.
+Default generation is refused, as is output to the authored index or any part of
+the full root, even with narrowed source flags or symlink aliases. Generation
+never repoints the configured authored index.
+
 ## Fumadocs Generation
 
 For this Fumadocs app, rendered page routing comes from the Fumadocs file/source pipeline over `apps/oat-docs/docs`, and the sidebar order comes from the committed `meta.json` files that `oat docs nav sync` writes (see [Fumadocs Nav Sync](#fumadocs-nav-sync)). The generated root manifest, `apps/oat-docs/index.md`, is an inventory for agents and tooling; it is not the rendered sidebar/page-tree source.
@@ -84,7 +99,7 @@ MkDocs generated behavior:
 
 ## Generated-file boundaries
 
-- Edit authored files under `docs/`, especially the nearest `index.md` and `## Contents`.
+- Edit authored files under the resolved content root (`docs/` inside framework apps, or the literal configured Markdown root), especially the nearest `index.md` and `## Contents`.
 - Do not hand-edit a Fumadocs app-root generated `index.md`; regenerate it from the docs source tree.
 - Do not hand-maintain MkDocs `nav:` entries or Fumadocs `meta.json` `pages` lists when the local workflow uses `oat docs nav sync`.
 - If a Fumadocs generated manifest lists pages that are missing from authored `## Contents`, treat that as authored-source drift or intentional generator-inventory behavior to verify before relying on the generated file as navigation evidence.
@@ -94,7 +109,7 @@ MkDocs generated behavior:
 - Use `index.md` as the local discovery surface for humans and agents.
 - Add a short topic description next to each link so agents can choose the right file without opening every page.
 - Update `## Contents` whenever you add, remove, rename, or reorder docs files in a directory.
-- Regenerate the framework-specific artifacts after structural changes: `nav sync` for MkDocs `mkdocs.yml` and Fumadocs `meta.json` navigation, plus `generate-index` for Fumadocs root manifests.
+- Markdown checks authored files/links, regenerating optional external manifests only when declared. Frameworks regenerate their artifacts after structural changes: `nav sync` for MkDocs `mkdocs.yml` and Fumadocs `meta.json` navigation, plus `generate-index` for Fumadocs root manifests.
 - Refresh or freshness-check the generated artifact before committing structural docs changes.
 
 ## If You Are Trying To...

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,13 +168,16 @@ 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/`
 - `packages/cli/src/commands/cleanup/project/`
 - `packages/cli/src/commands/cleanup/artifacts/`
 - `packages/cli/src/commands/docs/` — `oat docs` command family
-- `packages/cli/src/commands/docs/init/` — scaffold a docs app (Fumadocs or MkDocs)
+- `packages/cli/src/commands/docs/init/` — bootstrap/adopt authored Markdown or scaffold a docs app (Fumadocs or MkDocs)
 - `packages/cli/src/commands/docs/migrate/` — convert MkDocs admonitions to GFM callouts
 - `packages/cli/src/commands/docs/index-generate/` — generate a docs index from markdown files
 - `packages/cli/src/commands/docs/nav/` — regenerate mkdocs.yml nav or Fumadocs meta.json from index.md sections
@@ -196,3 +199,5 @@ Archive sync surfaces:
 
 - `.oat/templates/docs-app-fuma/` — Fumadocs (Next.js) scaffold template
 - `.oat/templates/docs-app-mkdocs/` — MkDocs Material scaffold template
+
+- `.oat/templates/docs-markdown/` — authored `index.md` and `contributing.md` baseline templates; installed by the docs pack, with no app or docs-root AGENTS template

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

@@ -48,16 +48,16 @@ Project scope is used for project workflows and repo-local sync state. User scop
 
 ## Top-level entries
 
-| Path                     | Purpose                                             | Notes                                                                                                                                 |
-| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `.oat/config.json`       | Shared repo runtime config for non-sync settings    | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, `documentation.*`, `instructions.*`, and `pjm.remote.*` |
-| `.oat/config.local.json` | Local per-developer runtime state                   | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                                               |
-| `.oat/state.md`          | Generated repo state dashboard                      | Gitignored; rebuilt with `oat state refresh` from config, project artifacts, and knowledge metadata                                   |
-| `.oat/projects/`         | OAT project artifacts                               | `shared`, `synced`, `local`, and lifecycle `archived` locations                                                                       |
-| `.oat/ideas/`            | Project-level ideas store                           | Often gitignored                                                                                                                      |
-| `.oat/sync/`             | Interop sync state/config                           | See details below                                                                                                                     |
-| `.oat/templates/`        | Artifact templates used by OAT skills               | Source for scaffolding. Includes `docs-app-fuma/` (Fumadocs) and `docs-app-mkdocs/` (MkDocs) templates.                               |
-| `.oat/repo/`             | Repo-level PJM/knowledge/reference/review artifacts | Active PJM state under `pjm/`; durable references (including decisions) under `reference/`                                            |
+| Path                     | Purpose                                             | Notes                                                                                                                                                    |
+| ------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.oat/config.json`       | Shared repo runtime config for non-sync settings    | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, `documentation.*`, `instructions.*`, and `pjm.remote.*`                    |
+| `.oat/config.local.json` | Local per-developer runtime state                   | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                                                                  |
+| `.oat/state.md`          | Generated repo state dashboard                      | Gitignored; rebuilt with `oat state refresh` from config, project artifacts, and knowledge metadata                                                      |
+| `.oat/projects/`         | OAT project artifacts                               | `shared`, `synced`, `local`, and lifecycle `archived` locations                                                                                          |
+| `.oat/ideas/`            | Project-level ideas store                           | Often gitignored                                                                                                                                         |
+| `.oat/sync/`             | Interop sync state/config                           | See details below                                                                                                                                        |
+| `.oat/templates/`        | Artifact templates used by OAT skills               | Source for scaffolding. Includes `docs-markdown/` (authored index/contributing), `docs-app-fuma/` (Fumadocs), and `docs-app-mkdocs/` (MkDocs) templates. |
+| `.oat/repo/`             | Repo-level PJM/knowledge/reference/review artifacts | Active PJM state under `pjm/`; durable references (including decisions) under `reference/`                                                               |
 
 ## `.oat/sync/` details
 
@@ -120,10 +120,10 @@ Current schema keys:
 | `projects.root`                                            | `string`                   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `projects.defaultScope`                                    | `string`                   | `"synced"`               | Scope used by project creation when `--scope` is omitted: `shared`, `local`, or `synced`. Environment override: `OAT_PROJECTS_DEFAULT_SCOPE`.                                                                                                                                                                                                                                                                                                                                                       |
 | `localPaths`                                               | `string[]`                 | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                                                                                                                                                                                                                                                                                                                                         |
-| `documentation.root`                                       | `string`                   | -                        | Docs **app root** — the directory `oat docs init` scaffolds (e.g., `apps/docs`). Authored pages live under `<root>/docs`. See [Documentation path resolution](#documentation-path-resolution).                                                                                                                                                                                                                                                                                                      |
-| `documentation.tooling`                                    | `string`                   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `documentation.root`                                       | `string`                   | -                        | Literal authored content root for tooling `markdown` (default `docs`); otherwise docs **app root** (e.g., `apps/docs`) with authored pages normally under `<root>/docs`. See [Documentation path resolution](#documentation-path-resolution).                                                                                                                                                                                                                                                       |
+| `documentation.tooling`                                    | `string`                   | -                        | Documentation tooling identifier (`markdown`, `mkdocs`, or `fumadocs`); parsing remains permissive                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `documentation.config`                                     | `string`                   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `documentation.index`                                      | `string`                   | -                        | Path to the docs surface entry point: the generated app-root manifest `<root>/index.md` for Fumadocs, `mkdocs.yml` for MkDocs. Set by `oat docs init`. `oat docs generate-index` writes it only for the Fumadocs manifest transition and never for MkDocs.                                                                                                                                                                                                                                          |
+| `documentation.index`                                      | `string`                   | -                        | Path to the docs surface entry point: authored `<root>/index.md` for Markdown, the generated app-root manifest `<root>/index.md` for Fumadocs, `mkdocs.yml` for MkDocs. Set by `oat docs init`. `oat docs generate-index` writes it only for the Fumadocs manifest transition and never for Markdown or MkDocs.                                                                                                                                                                                     |
 | `documentation.excludes`                                   | `string[]`                 | -                        | Globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. See [Excluding pages from the generated index](#excluding-pages-from-the-generated-index).                                                                                                                                                                                                                                                                                                 |
 | `documentation.requireForProjectCompletion`                | `boolean`                  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `git.defaultBranch`                                        | `string`                   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                                                                                                                                                                                                                                                                                                                                  |
@@ -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:
 
@@ -174,24 +174,26 @@ Example:
 
 ### Documentation path resolution
 
-`documentation.root` canonically names the docs **app root** — exactly the directory `oat docs init` scaffolds. Authored Markdown lives under `<root>/docs`, and the generated Fumadocs manifest is written to `<root>/index.md`, outside the tree it indexes.
+With `documentation.tooling: "markdown"`, `documentation.root` is the dedicated literal content directory and `documentation.index` is authored `<root>/index.md`. A child named `docs` does not narrow it. Fresh setup/adoption creates missing baseline pages and managed root guidance, without app files, dependencies, site builds, or a docs-root AGENTS file; existing local instructions are preserved.
+
+Framework roots retain their app-root meaning. Authored content commonly lives under `<root>/docs`; the generated Fumadocs manifest lives at `<root>/index.md`, outside its source tree.
 
 `oat docs generate-index` resolves omitted options from this configuration:
 
-| Option       | Omitted                                                                                  | Supplied                            |
-| ------------ | ---------------------------------------------------------------------------------------- | ----------------------------------- |
-| `--docs-dir` | `<documentation.root>/docs` when that directory exists, otherwise `<documentation.root>` | Resolved from the current directory |
-| `--output`   | `<documentation.root>/index.md`                                                          | Resolved from the current directory |
+| Option       | Omitted                                                                                                 | Supplied                            |
+| ------------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `--docs-dir` | Markdown: literal `<documentation.root>`; other tooling: `<root>/docs` when present, otherwise `<root>` | Resolved from the current directory |
+| `--output`   | Markdown: explicit external output required; otherwise `<root>/index.md`                                | Resolved from the current directory |
 
 If an omitted option has no non-empty `documentation.root` to resolve against, or the configured root is not a directory, the command fails with exit code `2` before generating or writing anything.
 
-**Compatibility behavior.** Preferring `<root>/docs` exists for legacy configs whose `root` names a docs _source_ directory rather than an app root; it is not a second meaning of the key. Because the rule is a plain directory-existence test, a source root that happens to contain its own `docs` subdirectory is narrowed to it. The command prints the directory it derived in both human and JSON output (`docsDir`, `docsDirSource`), and `--docs-dir` is the escape hatch when the derivation is wrong.
+**Compatibility behavior.** Preferring `<root>/docs` exists for legacy configs whose `root` names a docs _source_ directory rather than an app root; it is not a second meaning of the key. For non-Markdown tooling the rule is a plain directory-existence test, so a source root that happens to contain its own `docs` subdirectory is narrowed to it. The command prints the directory it derived in both human and JSON output (`docsDir`, `docsDirSource`), and `--docs-dir` is the escape hatch when the derivation is wrong.
 
 A legacy source root with no `docs` child resolves `--docs-dir` and `--output` to the same tree, so a bare run is refused rather than allowed to overwrite an authored page. Pass an explicit `--output` outside the source tree, or repoint `documentation.root` at the app root.
 
-**Refused output targets.** Checked before generation for derived and explicit paths alike, the command refuses to write an output that is inside the docs directory it indexes, equals `documentation.config`, or ends in `.yml` / `.yaml`. A derived output whose existing file lacks the `AUTOGENERATED by oat docs generate-index` header is also refused; naming that same path with `--output` overwrites it explicitly.
+**Refused output targets.** Checked before generation for derived and explicit paths alike, the command refuses to write an output that is inside the docs directory it indexes, equals `documentation.config`, or ends in `.yml` / `.yaml`. A derived output whose existing file lacks the `AUTOGENERATED by oat docs generate-index` header is also refused; naming that same path with `--output` overwrites it explicitly only when no other guard applies. Configured Markdown additionally protects the full canonical configured content root and authored `documentation.index`, even with narrowed `--docs-dir` or symlink aliases. Default Markdown generation is refused; use explicit output outside the full content tree. The authored index remains configured.
 
-**Configuration writes.** The only configuration write generation performs is the Fumadocs manifest transition: when the written manifest lies inside `documentation.root` and `documentation.tooling` is `fumadocs`, the repo-relative output path is recorded in `documentation.index`. A config that declares neither `documentation.tooling` nor `documentation.config` is treated as the same Fumadocs-shaped case. Any other declared tooling — `mkdocs` included — is never written, and neither are `documentation.root` and `documentation.config`. The value is always repo-relative: when `documentation.root` points outside the repository, the manifest is still generated but the key is left untouched rather than recording a machine-specific path.
+**Configuration writes.** The only configuration write generation performs is the Fumadocs manifest transition: when the written manifest lies inside `documentation.root` and `documentation.tooling` is `fumadocs`, the repo-relative output path is recorded in `documentation.index`. A config that declares neither `documentation.tooling` nor `documentation.config` is treated as the same Fumadocs-shaped case. Any other declared tooling — `markdown` and `mkdocs` included — is never written, and neither are `documentation.root` and `documentation.config`. The value is always repo-relative: when `documentation.root` points outside the repository, the manifest is still generated but the key is left untouched rather than recording a machine-specific path.
 
 ### Excluding pages from the generated index