@open-agent-toolkit/cli 0.2.59 → 0.2.63

package/assets/docs/reference/cli-reference.md

@@ -56,8 +56,14 @@ The first practical expansion path is to keep improving the existing owners: [Do
 
 Notable commands introduced in the current CLI surface:
 
-- `oat project new <slug> --scope shared|local|synced [--force]` - create a
-  project in an explicit scope. Without `--scope`, creation uses
+- `oat project new <slug> [--mode spec-driven|quick|import|lite] --scope shared|local|synced [--force]` - create a
+  project in an explicit scope. `--mode` selects the workflow mode and therefore
+  which artifacts are scaffolded; it defaults to `spec-driven`. Use `quick` for a
+  bounded feature with clear requirements, `import` to normalize an externally
+  authored plan, and `lite` for a single-sitting change that scaffolds only
+  `plan.md`, `state.md`, and `implementation.md`. See
+  [Lifecycle](../workflows/projects/lifecycle.md) for the per-lane flow. Without
+  `--scope`, creation uses
   `projects.defaultScope`, which defaults to `synced`. Project slugs are
   unique across all scopes by default, including recorded or remotely
   published synced projects. `--force` deliberately permits a duplicate; use
@@ -133,16 +139,17 @@ Notable commands introduced in the current CLI surface:
 - `oat project status --field <path>` - print one arbitrary dot-path field from the same status payload, e.g. `project.workflowMode` or `project.timestamps.stateUpdated`. Missing/null fields print `null`; object and array fields print compact JSON.
 - `oat project status --project-path <path>` - read from a repo-relative or absolute project path instead of `.oat/config.local.json`'s active project pointer. Combine it with `--field` or `--shell` when a skill has already resolved the target project path.
 - `oat project status --shell NAME=path ...` - print shell-safe assignments for one or more fields from one status read, e.g. `WORKFLOW_MODE='quick'`. This is the preferred multi-field read API for skills. See [Writing Skills → Reading project state](../contributing/skills.md#reading-project-state) for examples and the `npx`-backed `oat` shim contract.
+- `oat project promote <project-path> --to quick [--json]` - promote an authored lite project to quick mode. The command derives `discovery.md` from the lite plan's Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria; carries Product Behavior into Success Criteria and Technical Design into a carried-forward discovery section when those adaptive sections are present; preserves the original as `references/lite-plan.md`; and scaffolds a fresh quick `plan.md`. It refuses unsupported targets, non-lite or unreadable projects, an existing lite-plan reference, invalid authored sections, unresolved scope, unavailable templates, failed writes, or failed persistence. JSON output is `{ status: "promoted" | "refused", reason, files }`; `reason` is the stable categorical contract and refused results exit non-zero.
 - `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`, with `null` values when no review exists. Archived project reviews remain discoverable as history but return `actionable: false`.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
 - `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit]` - archive a tracked project through the same local move, summary export, and configured S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. For synced projects, a configured S3 upload must succeed before terminal cleanup. Successful closeout makes `refs/oat/completed/<project>` authoritative, deletes the tracked JSON record and nested checkout, and leaves archive metadata sufficient for an idempotent recordless retry. Legacy complete records receive a cleanup diagnosis rather than pull/open guidance. With `--json`, the terminal receipt reports `completedRef`, `verifiedSourceSha`, whether `activeAliasDisposition` was `retained` or `removed`, whether `recordRetired` completed, and the parent `lifecycleCommit`. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately leaves `lifecycleCommit` null. Never pass it through `oat-project-complete`, which requires that receipt.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
 - `oat project dispatch record --event-file <json-file-or-dash> [--project <project-path>]` - validate one generic dispatch record plus its namespaced OAT evidence event, and persist it into the project's append-only `dispatch/` journal. Omit `--project` to validate without persisting. Revision 1 is `dispatch/<request-id>.json` and every later revision is `dispatch/<request-id>@<NNNN>.json`; superseded revisions are never replaced or removed. The command validates and records evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never persisted, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/projects/evidence-layers.md).
-- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
+- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a `manual:` instruction. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
-- `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_missing` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. `artifact_missing` means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For `targeting_correlation_failed`, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../cli-utilities/workflow-gates.md).
+- `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_missing` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. `artifact_missing` means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For `targeting_correlation_failed`, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. When post-selection work fails after the reviewer already committed a run-correlated artifact, the gate re-validates that selected snapshot through the same eligibility path rather than re-parsing whatever the path now holds, never re-dispatching, and returns the ordinary `ok` or `blocked` envelope with additive `postSelectionRecovery: true`; the artifact must still be present and unchanged for re-validation to succeed. When nothing recovers, `review_failed` names the failing sub-step in `postSelection.step` and its cause in `postSelection.code`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../cli-utilities/workflow-gates.md).
 - `oat gate route --expect-runtime <runtime> --expect-model <model> --can-await <true|false> --json` - return the headless child route (`inline`, `delegate-sync`, or `refuse`) from provider-marker and model evidence. Ambiguous or contradictory evidence never routes inline.
 - `oat gate exec <prompt...>` / `oat gate cross-provider-exec <prompt...>` - run a generic target prompt. `--timeout-ms` uses the same validated CLI override; untyped runs otherwise retain the legacy default path.
 - `oat gate target set <id> --invocation-model <model|provider-default> --invocation-reasoning-effort <effort|provider-default>` - persist optional configured invocation metadata alongside an exec target without inferring it from the target command.
@@ -152,15 +159,25 @@ Notable commands introduced in the current CLI surface:
 
 ## `oat config` surface flags
 
-`oat config set` supports mutually exclusive surface flags that control which config file receives the write:
+`oat config set` and `oat config unset` support the same mutually exclusive surface flags, which control the config file the write or removal lands in:
 
-- `--shared` — write to `.oat/config.json` (committed team repo settings)
-- `--local` — write to `.oat/config.local.json` (per-developer repo state, gitignored)
-- `--user` — write to `~/.oat/config.json` (user-level fallback, applies across all repos)
+- `--shared` — write to or remove from `.oat/config.json` (committed team repo settings)
+- `--local` — write to or remove from `.oat/config.local.json` (per-developer repo state, gitignored)
+- `--user` — write to or remove from `~/.oat/config.json` (user-level fallback, applies across all repos)
 
 When no flag is passed, the CLI picks a sensible default per key type: structural keys (`projects.root`, `documentation.*`, etc.) go to shared, state keys (`activeProject`, etc.) go to local, workflow preferences (`workflow.*`) go to local. Pass at most one flag — the command rejects multiple surface flags.
 
-Per-key restrictions apply: structural keys can only be written at shared scope, most state keys can only be written at local scope (`activeIdea` is the exception — it accepts both local and user), and workflow preference keys accept any non-auto surface. Legacy `autoReviewAtCheckpoints` remains shared-only; prefer `workflow.autoReviewAtHillCheckpoints`.
+Per-key restrictions apply identically to `set` and `unset`: structural keys can only be written at shared scope, most state keys can only be written at local scope (`activeIdea` is the exception — it accepts both local and user), and workflow preference keys accept any non-auto surface. Legacy `autoReviewAtCheckpoints` remains shared-only; prefer `workflow.autoReviewAtHillCheckpoints`.
+
+`oat config unset <key>` removes the key from the selected surface and prunes any parent object it empties, so the resolved value falls back through the remaining surfaces to the built-in default. Removing a key the surface does not hold is not an error: it reports an already-unset outcome and exits 0. With `--json` the envelope adds a `removed` boolean, which is the machine-readable way to tell a real removal from an already-unset no-op, since both exit 0. A stored value that fails validation is still removed, matching `oat config set`, which repairs the same file.
+
+`unset` refuses five classes of key, each with exit code 1:
+
+- **Unknown keys**, including keys OAT reads but does not expose in the `oat config` catalog (`documentation.index`). These are not removable by any `oat config` command.
+- **Lifecycle state** (`activeProject`, `lastPausedProject`) — cleared with `oat config set <key> ''` instead.
+- **Pack intent** (`tools.*`) — removed with `oat tools remove --pack <pack> --scope project`, which also removes the installed pack files. Clearing the intent alone would leave them behind.
+- **Aggregate read views** (`workflow.dispatchCeiling`, `workflow.dispatchCeiling.providers`) — these are assembled for `get` from the leaf keys and are not stored as such. Unset `workflow.dispatchCeiling.preset` or `workflow.dispatchCeiling.providers.<provider>` instead.
+- **Environment-shadowed keys with nothing stored on the target surface** — when `OAT_PROJECTS_ROOT`, `OAT_PROJECTS_DEFAULT_SCOPE`, or `OAT_WORKTREES_ROOT` supplies the effective value and the surface holds nothing to remove, clear the environment variable in your shell. When the surface _does_ hold a stored value, `unset` removes it (as `set` would rewrite it) and warns that the override still supplies the effective value.
 
 ## `workflow.*` preference keys
 

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

@@ -110,37 +110,38 @@ Legacy `.oat/active-project` / `.oat/projects-root` / `.oat/active-idea` files m
 
 Current schema keys:
 
-| Key                                                        | Type                       | Default                  | Description                                                                                                                                                                                                                                                                                             |
-| ---------------------------------------------------------- | -------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `version`                                                  | `number`                   | `1`                      | Schema version                                                                                                                                                                                                                                                                                          |
-| `worktrees.root`                                           | `string`                   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                                                                                                                                            |
-| `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.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.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`.                                                                                                                                      |
-| `workflow.autoReviewAtHillCheckpoints`                     | `boolean`                  | unset                    | When `true`, completing a HiLL checkpoint automatically runs the extra lifecycle review. Does not control Tier 1 per-phase `oat-reviewer` gates. Can be overridden per-project via `oat_auto_review_at_hill_checkpoints` in `plan.md` frontmatter. Legacy `autoReviewAtCheckpoints` remains a fallback. |
-| `workflow.dispatchPolicy.mode`                             | `string`                   | unset                    | Dispatch policy mode: `managed` lets OAT select model/effort controls; `inherit` leaves controls to the host/provider defaults.                                                                                                                                                                         |
-| `workflow.dispatchPolicy.policy`                           | `string`                   | unset                    | Managed dispatch policy: `economy`, `balanced`, `high`, `frontier`, or `uncapped`. Capped policies compile to provider targets; `uncapped` keeps OAT-managed preferred selection without provider caps. `inherit` mode is separate and leaves controls to the host/provider.                            |
-| `workflow.dispatchCeiling.preset`                          | `string`                   | unset                    | Legacy compatibility preset for capped managed policy setup (`balanced`, `maximum`, `cost-conscious`). `maximum` maps to `high`; `cost-conscious` maps to `economy`.                                                                                                                                    |
-| `workflow.dispatchCeiling.providers.<provider>`            | `object` or legacy scalar  | unset                    | Reusable provider candidate ladder. The canonical shape maps `economy`, `balanced`, `high`, and `frontier` to ordered candidate cells; project and phase state record only a named maximum over that ladder.                                                                                            |
-| `workflow.dispatchCeiling.providers.<provider>.<tier>`     | `{ candidates: [...] }`    | unset                    | One ordered candidate cell. Codex entries carry exact `model` plus `effort` and resolve to materialized roles; Claude entries carry a model; Cursor strings remain opaque and pass to Cursor byte-for-byte. The final candidate defines that tier's reviewer ceiling.                                   |
-| `workflow.dispatchCeiling.providers.{codex,claude,cursor}` | `string`, route, or target | unset                    | Legacy compatibility input normalized to a one-candidate ladder. New configuration should use tiered candidate cells. The flat keys `workflow.dispatchCeiling.codex` and `workflow.dispatchCeiling.claude` were removed without migration.                                                              |
-| `workflow.gates.skills`                                    | `object`                   | unset                    | Per-skill final gate config keyed by skill name. Managed with `oat gate set/unset`; gate-aware skills declare `oat_gateable: true`.                                                                                                                                                                     |
-| `workflow.gates.execTargets`                               | `object`                   | built-ins                | Cross-runtime exec target registry keyed by opaque target id. Managed with `oat gate target set/unset`; built-ins cover Codex, Claude, and Cursor defaults.                                                                                                                                             |
-| `archive.s3Uri`                                            | `string`                   | -                        | Base S3 URI for repo-scoped archived project sync, for example `s3://bucket/oat-archive`                                                                                                                                                                                                                |
-| `archive.s3SyncOnComplete`                                 | `boolean`                  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                                                                                                                              |
-| `archive.summaryExportPath`                                | `string`                   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                                                                                                                                       |
-| `archive.wrapUpExportPath`                                 | `string`                   | -                        | Repo-relative directory where `oat-wrap-up` writes dated reports like `20260413-wrap-up-past-week.md`; when unset, the skill falls back to `.oat/repo/reference/wrap-ups/`                                                                                                                              |
-| `archive.awsProfile`                                       | `string`                   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat repo archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                     |
-| `archive.awsRegion`                                        | `string`                   | -                        | Optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows. Overrides ambient shell `AWS_REGION` / `AWS_DEFAULT_REGION` when set.                                                                                                                                         |
-
-All `documentation.*` keys are managed via `oat config get/set` and are set automatically by `oat docs init`.
+| Key                                                        | Type                       | Default                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------------------------------------------------------- | -------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`                                                  | `number`                   | `1`                      | Schema version                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `worktrees.root`                                           | `string`                   | `".worktrees"`           | Root directory for git worktrees (repo-relative or absolute)                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `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.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.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.instructionPointerExcludes`                 | `string[]`                 | -                        | Repo-relative directories `oat instructions sync`/`validate` must not treat as pointer sites, additive to the documentation content root they skip by default. Normalized and de-duplicated; a malformed value (non-array, or an empty or non-string entry) is rejected with exit code `2`. Set as one comma-separated value with `oat config set`; absolute paths and paths escaping the repository are refused. See [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees). |
+| `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`.                                                                                                                                                                                                                                                                                                                                  |
+| `workflow.autoReviewAtHillCheckpoints`                     | `boolean`                  | unset                    | When `true`, completing a HiLL checkpoint automatically runs the extra lifecycle review. Does not control Tier 1 per-phase `oat-reviewer` gates. Can be overridden per-project via `oat_auto_review_at_hill_checkpoints` in `plan.md` frontmatter. Legacy `autoReviewAtCheckpoints` remains a fallback.                                                                                                                                                                                             |
+| `workflow.dispatchPolicy.mode`                             | `string`                   | unset                    | Dispatch policy mode: `managed` lets OAT select model/effort controls; `inherit` leaves controls to the host/provider defaults.                                                                                                                                                                                                                                                                                                                                                                     |
+| `workflow.dispatchPolicy.policy`                           | `string`                   | unset                    | Managed dispatch policy: `economy`, `balanced`, `high`, `frontier`, or `uncapped`. Capped policies compile to provider targets; `uncapped` keeps OAT-managed preferred selection without provider caps. `inherit` mode is separate and leaves controls to the host/provider.                                                                                                                                                                                                                        |
+| `workflow.dispatchCeiling.preset`                          | `string`                   | unset                    | Legacy compatibility preset for capped managed policy setup (`balanced`, `maximum`, `cost-conscious`). `maximum` maps to `high`; `cost-conscious` maps to `economy`.                                                                                                                                                                                                                                                                                                                                |
+| `workflow.dispatchCeiling.providers.<provider>`            | `object` or legacy scalar  | unset                    | Reusable provider candidate ladder. The canonical shape maps `economy`, `balanced`, `high`, and `frontier` to ordered candidate cells; project and phase state record only a named maximum over that ladder.                                                                                                                                                                                                                                                                                        |
+| `workflow.dispatchCeiling.providers.<provider>.<tier>`     | `{ candidates: [...] }`    | unset                    | One ordered candidate cell. Codex entries carry exact `model` plus `effort` and resolve to materialized roles; Claude entries carry a model; Cursor strings remain opaque and pass to Cursor byte-for-byte. The final candidate defines that tier's reviewer ceiling.                                                                                                                                                                                                                               |
+| `workflow.dispatchCeiling.providers.{codex,claude,cursor}` | `string`, route, or target | unset                    | Legacy compatibility input normalized to a one-candidate ladder. New configuration should use tiered candidate cells. The flat keys `workflow.dispatchCeiling.codex` and `workflow.dispatchCeiling.claude` were removed without migration.                                                                                                                                                                                                                                                          |
+| `workflow.gates.skills`                                    | `object`                   | unset                    | Per-skill final gate config keyed by skill name. Managed with `oat gate set/unset`; gate-aware skills declare `oat_gateable: true`.                                                                                                                                                                                                                                                                                                                                                                 |
+| `workflow.gates.execTargets`                               | `object`                   | built-ins                | Cross-runtime exec target registry keyed by opaque target id. Managed with `oat gate target set/unset`; built-ins cover Codex, Claude, and Cursor defaults.                                                                                                                                                                                                                                                                                                                                         |
+| `archive.s3Uri`                                            | `string`                   | -                        | Base S3 URI for repo-scoped archived project sync, for example `s3://bucket/oat-archive`                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `archive.s3SyncOnComplete`                                 | `boolean`                  | `false`                  | When `true`, `oat-project-complete` uploads the archived project to the configured S3 archive after local archive succeeds                                                                                                                                                                                                                                                                                                                                                                          |
+| `archive.summaryExportPath`                                | `string`                   | -                        | Repo-relative directory where completion exports `summary.md` as a dated snapshot like `20260401-<project-name>.md` for durable tracked reference                                                                                                                                                                                                                                                                                                                                                   |
+| `archive.wrapUpExportPath`                                 | `string`                   | -                        | Repo-relative directory where `oat-wrap-up` writes dated reports like `20260413-wrap-up-past-week.md`; when unset, the skill falls back to `.oat/repo/reference/wrap-ups/`                                                                                                                                                                                                                                                                                                                          |
+| `archive.awsProfile`                                       | `string`                   | -                        | Optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows (`oat-project-complete` S3 sync, `oat repo archive sync`). Overrides ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` when set.                                                                                                                                                                                                                                                                 |
+| `archive.awsRegion`                                        | `string`                   | -                        | Optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows. Overrides ambient shell `AWS_REGION` / `AWS_DEFAULT_REGION` when set.                                                                                                                                                                                                                                                                                                                                     |
+
+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).
@@ -305,6 +306,7 @@ Not all workflow modes require every artifact:
 - `spec-driven`: discovery + spec + design + plan + implementation
 - `quick`: discovery + plan + implementation (spec/design optional)
 - `import`: imported plan + implementation (spec/design optional)
+- `lite`: single-phase plan + implementation (summary/documentation optional at closeout)
 
 ## `.oat/repo/` structure
 

package/assets/docs/workflows/ideas/index.md

@@ -37,4 +37,4 @@ If the thought is still pre-shape — you don't know whether it should land as a
 
 ## Promotion Path
 
-When an idea becomes concrete, summarize it and then start a tracked OAT project in quick or spec-driven mode depending on design risk.
+When an idea becomes concrete, summarize it and then start a tracked OAT project in lite, quick, or spec-driven mode depending on scope and design risk. Lite suits a single-sitting change and seeds `plan.md` directly; quick and spec-driven seed `discovery.md` instead.

package/assets/docs/workflows/index.md

@@ -44,6 +44,7 @@ Stay with direct CLI usage when:
 ## Workflow Modes In Practice
 
 - CLI only: direct commands, no tracked project artifacts
+- Lite mode: a batched interview and one approval produce a single-phase `plan.md` for a single-sitting change
 - Quick mode: tracked work with a lighter upfront planning path
 - Spec-driven mode: explicit discovery, requirements, design, and plan artifacts
 - Import mode: an externally-authored plan imported into OAT for tracked execution

package/assets/docs/workflows/projects/artifacts.md

@@ -50,9 +50,30 @@ archive metadata own terminal reachability and retry identity.
 
 Mode-sensitive notes:
 
-- `state.md` includes workflow mode metadata (`spec-driven`, `quick`, `import`) for routing.
-- `spec.md` and `design.md` are required in spec-driven mode, optional in quick/import mode. Quick mode offers a lightweight `design.md` (architecture, components, testing strategy) at a post-discovery decision point.
-- `plan.md` remains canonical execution artifact across all modes.
+- `state.md` includes workflow mode metadata (`spec-driven`, `quick`, `import`, `lite`) for routing.
+- `plan.md` remains the canonical execution artifact across all modes.
+
+| Mode          | Core authored artifacts                                                                                                                | Optional artifacts                         |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `spec-driven` | `discovery.md`, `spec.md`, `design.md`, `plan.md`                                                                                      | -                                          |
+| `quick`       | `discovery.md`, `plan.md`                                                                                                              | Lightweight `design.md`, `spec.md`         |
+| `import`      | `references/imported-plan.md`, `plan.md`                                                                                               | `spec.md`, `design.md`                     |
+| `lite`        | Single-phase `plan.md` with Summary, Decisions, Assumptions, Out of Scope, Validation Criteria, and an explicit adaptive content shape | `summary.md` and documentation at closeout |
+
+Every Lite plan keeps Summary, Decisions, Assumptions, Out of Scope, and
+Validation Criteria. User-visible changes add numbered, testable Product
+Behavior. Changes that cross module boundaries, alter data or state formats,
+or change a contract consumed by another surface add Technical Design. That
+section covers current operation, proposed changes, and data flow when data or
+state crosses a boundary. The Decisions section records the selected shape and
+why it fits.
+
+Each Lite task also records an implementation and proof strategy: the risk it
+covers, why the evidence is proportionate, and the exact command or manual
+proof. Strategies may be test-first, characterization-first,
+implementation-then-regression, static/build, or manual/visual. Static or build
+checks alone fit only changes that cannot affect runtime behavior; every
+behavioral change needs evidence that fails without the change.
 
 ## Supporting artifacts
 

package/assets/docs/workflows/projects/hill-checkpoints.md

@@ -38,6 +38,27 @@ Semantics:
 - Empty list: checkpoint after every phase boundary, but only after implementation has confirmed the choice and written `oat_plan_hill_phases: []` into `plan.md`.
 - Explicit list: checkpoint only after completing the named phases (`p01`, `p04`, etc).
 
+### Lite checkpoint bypass
+
+Lite projects have no HiLL checkpoints. `oat-project-implement` resolves
+`oat_workflow_mode` from project state before any checkpoint field read, and
+when the mode is `lite` it resolves checkpoint state as `none` without reading
+or interpreting `oat_plan_hill_phases`. An empty list cannot represent lite's
+policy, because for every other mode an empty list means "checkpoint after every
+phase". `oat-project-implement`'s Lite checkpoint bypass writes:
+
+```yaml
+oat_auto_review_at_hill_checkpoints: false # lite: no checkpoints
+```
+
+The workflow preference prompt, the standard checkpoint prompt, and the
+auto-review preference prompt are all skipped in both interactive and autonomous
+runs. Only HiLL approval pauses are absent — the root-owned per-phase review and
+the final review remain required.
+
+The rest of this section applies to `spec-driven`, `quick`, and `import`
+projects.
+
 On the first implementation run, `oat-project-implement` must summarize every plan phase, state the total phase count and final phase ID, and then ask an explicit three-option checkpoint question:
 
 - Stop after each phase

package/assets/docs/workflows/projects/implementation-execution.md

@@ -426,6 +426,11 @@ For a plan-declared parallel group, the root:
 Containment, ownership, base, or fixture-readiness failure in smoke mode aborts
 the run. It never authorizes replacement or sequential degradation.
 
+Lite plans never take this path. A lite `plan.md` must contain exactly one phase
+and declare no parallel groups, so lite implementation is always sequential;
+`oat project validate-plan` enforces both rules. Work that needs more than one
+phase should promote to quick rather than declare a parallel group.
+
 ## Synced projects in worktrees
 
 A tracked `.oat/projects/synced/<project>.json` record lets every repository

package/assets/docs/workflows/projects/lifecycle.md

@@ -1,6 +1,6 @@
 ---
 title: Lifecycle
-description: 'End-to-end phase flow from discovery through completion: spec-driven, quick, and import paths.'
+description: 'End-to-end phase flow from discovery through completion: spec-driven, quick, lite, and import paths.'
 ---
 
 # Lifecycle
@@ -27,9 +27,9 @@ Full spec-driven design supports three interaction modes: collaborative, selecti
 
 ## Quick Look
 
-- What it does: explains the end-to-end lifecycle for tracked OAT projects, including alternate quick and import lanes.
+- What it does: explains the end-to-end lifecycle for tracked OAT projects, including alternate quick, lite, and import lanes.
 - When to use it: when you need the actual project execution model, not just a high-level overview of workflow mode.
-- Primary entry points: `oat-project-new`, `oat-project-quick-start`, `oat-project-import-plan`, `oat-project-implement`
+- Primary entry points: `oat-project-new`, `oat-project-quick-start`, `oat-project-lite`, `oat-project-import-plan`, `oat-project-implement`
 
 ## Lifecycle Map
 
@@ -42,6 +42,10 @@ flowchart LR
   DOC --> C["Complete"]
 ```
 
+This map shows the spec-driven default. The quick, lite, import, and capture
+lanes each skip part of it — see [Lane diagrams](#lane-diagrams) below. Lite in
+particular has no discovery, spec, or design step at all.
+
 ## Post-implementation flow
 
 Implementation closeout has one authoritative order:
@@ -73,6 +77,37 @@ After implementation closeout finishes:
    - After revision tasks complete, state returns to `pr_open`
 5. **Complete** (`oat-project-complete`) — accepts any phase status (`pr_open`, `complete`, `in_progress`), auto-refreshes `summary.md` before closeout when needed, and archives when selected by the workflow preference or completion prompt
 
+### Project-recap gate (non-lite)
+
+The final-closeout orchestrator owns one project-recap gate. It runs after the
+final code review has passed and after any configured pre-approval summary and
+documentation steps, but before final HiLL approval. It neither replaces nor
+repeats the final review, and the stored order of the other pre-approval steps
+is preserved.
+
+Recap intent resolves through `oat-explainer-kit`. A fresh `project-recap`
+manifest for the current completed implementation is reused rather than
+regenerated — fresh means it names recipe `project-recap`, belongs to this
+project, has a terminal outcome, and its recorded source hashes match the
+current approved inputs. A present-but-incomplete, wrong-recipe, or stale
+manifest does not qualify.
+
+Recap outcomes are reported, not blocking: `failed` and `built-not-durable` are
+recorded as warnings and never block final approval, completion reporting, or
+later PR steps. The selected or attempted outcome and run path are included in
+the implementation completion report, and `summary.md` carries a single
+`Explainer Outcome` section when it exists.
+
+**Lite skips this gate entirely.** Lite sets `PROJECT_RECAP_REACHABLE=false` and
+does not resolve recap intent, inspect recap runs, invoke `oat-explainer-kit`,
+or run the terminal-outcome guard. It proceeds from the required reviews through
+its stored optional steps to `pr` and sequence completion.
+
+Lite mode collapses the default pre-approval sequence to PR creation only.
+`oat-project-pr-final` builds the body directly from the lite plan and
+`implementation.md`; summary and documentation remain explicit lite opt-ins,
+and retro is not added to the lite closeout sequence.
+
 ### Completion archive behavior
 
 On completion, OAT treats archive handling as an explicit closeout choice:
@@ -106,6 +141,51 @@ On completion, OAT treats archive handling as an explicit closeout choice:
   ref. `oat project prune` is a separate destructive choice that removes
   terminal ref reachability but preserves local and S3 archive snapshots.
 
+### Absorbed-project retirement sweep
+
+Retiring a project that a later project absorbed is a semantic claim, not a
+filesystem operation. Deleting or archiving the old scaffold does not make the
+roadmap stop promising its work, so completion checks the claim against the
+prose that still makes it.
+
+When a quick project consolidates earlier scaffolds, quick-start records
+`absorbed_projects` and `absorbed_backlog_ids` in that project's `state.md`
+frontmatter. Those two fields are the only inputs the sweep takes.
+
+Recording them is a quick-mode step today. A lite project that consolidates
+earlier scaffolds records nothing, so the sweep finds no inputs and degrades to
+its recorded note rather than checking that project's surfaces.
+
+Inside the project-log completion gate — after the log status probe and before
+the roll-up and seal — completion searches the active planning surfaces for each
+absorbed slug and backlog ID, and for future-oriented ownership language tied to
+them:
+
+- `.oat/repo/pjm/roadmap.md` (the Now/Next/Later lanes and the sequencing map)
+- `.oat/repo/pjm/current-state.md`
+- the Curated Overview in `.oat/repo/pjm/backlog/index.md`
+- the scope-nested `state.md` of projects that are still active, under the
+  configured projects root, skipping the `archived` tree and any project already
+  recorded as complete
+
+The sweep is advisory. A raw match is never a hard block on closeout: each hit
+becomes a named finding carrying a recorded disposition: fixed in the same run,
+accepted as historical with a reason, or — in an autonomous run — recorded as
+`deferred advisory`. Prose that clearly describes
+past state is exempt, so a dated history entry, a retro, a decision record, or a
+changelog line reads as evidence rather than a stale claim.
+
+Placement is the point. Dispositions are appended to the project log before the
+roll-up, so the roll-up summarizes them and the completion seal remains the
+final entry — no project-log append ever follows the seal. Three variations
+change where and how the dispositions are recorded: an autonomous run records
+each finding as a `deferred advisory` warning and continues, a project with no log reports them in the
+final completion summary, and a resumed completion whose log already
+carries a seal runs report-only and appends nothing.
+
+Repositories that never adopted PJM skip the sweep with a one-line note. A
+missing planning surface degrades the sweep, never the closeout.
+
 ### Phase status: `pr_open`
 
 After `oat-project-pr-final` runs, `state.md` shows `oat_phase_status: pr_open`. This signals:
@@ -167,7 +247,9 @@ When `workflow.autoReviewAtHillCheckpoints` is enabled or `plan.md` frontmatter
 ### Phase-review setup during planning
 
 Spec-driven, quick, and import planning run one shared setup after stable phase
-IDs exist and before the plan artifact review. The target probe qualifies only
+IDs exist and before the plan artifact review. Lite omits this planning-time
+setup and prompt, while its built-in implementation phase and final reviews
+remain required. The target probe qualifies only
 an explicitly configured, enabled, and available review target, then offers all
 phases, selected phases, or disabled. Existing explicit
 `oat_phase_review_gate` values are preserved unchanged without re-prompting.
@@ -214,6 +296,13 @@ See [Implementation Execution](implementation-execution.md) for the full executi
 4. `oat-project-review-provide` / `oat-project-pr-final`
 5. Optional `oat-project-promote-spec-driven` to backfill spec-driven lifecycle artifacts in-place
 
+### Lite lane diagram
+
+1. `oat-project-lite` runs one batched interview, authors a single-phase `plan.md` with validation criteria, and pauses once for approval
+2. Implement: `oat-project-implement` runs the single phase without HiLL checkpoint prompts
+3. Pass the mandatory final review, then route directly to `oat-project-pr-final`
+4. Optional `oat project promote <project-path> --to quick` when the work no longer fits one sitting
+
 ### Import lane diagram
 
 1. `oat-project-import-plan` (checks inherited git state before import scaffolding so sync-generated or unrelated dirty files do not silently roll into project bookkeeping)
@@ -269,6 +358,75 @@ still read as compatibility capped-policy input, but new quick-start selections
 should use the dispatch-policy names, including explicit `Uncapped` and
 `Inherit Host Defaults`.
 
+### Lite lane
+
+```mermaid
+flowchart LR
+  L["Lite interview\n(one batched round)"] --> P["Single-phase plan\n(one approval)"]
+  P --> I["Implement (oat-project-implement)"]
+  I --> R["Final review"] --> PR["PR (default closeout)"]
+  P -->|Scope grows| Q["Promote to Quick"]
+```
+
+Lite keeps planning and validation in `plan.md`. The interview selects a
+`minimal`, `product`, `technical`, or `both` content shape and records the
+rationale. Product Behavior is required for user-visible changes; Technical
+Design is required for cross-module, data/state-format, or consumed-contract
+changes. It has no separate discovery, spec, or design artifact, skips
+implementation HiLL prompts, and routes a passed final review directly to PR
+creation. Summary and documentation run only when enabled through the
+lite-specific post-implementation sequence.
+
+Each task chooses evidence proportionate to its risk instead of requiring one
+test-first recipe. Behavioral changes need a proof that fails without the
+change; refactors default to characterization-first when existing coverage is
+insufficient; documentation-only work may use formatting, link, spelling, or
+build checks. UI changes require visual proof. In autonomous runs, available
+computer-use capability performs that proof; otherwise execution stops at an
+explicit proof boundary.
+
+### Promoting a lite project to quick
+
+When lite work outgrows one sitting, `oat project promote <project-path> --to quick`
+converts it in place. Each artifact has a different fate: the authored lite plan
+is **moved** to `references/lite-plan.md`, a new `discovery.md` is **derived**
+from its five core sections plus any adaptive Product Behavior and Technical
+Design, a **fresh** quick template takes over the `plan.md` path, and `state.md`
+is **rewritten** to quick mode.
+
+```mermaid
+flowchart LR
+  subgraph Before
+    LPLAN["plan.md\nfive core sections plus adaptive\nProduct Behavior / Technical Design"]
+    LSTATE["state.md\noat_workflow_mode: lite"]
+  end
+
+  CMD["oat project promote\n--to quick"]
+
+  subgraph After
+    DISC["discovery.md\nderived from the lite plan\noat_ready_for: oat-project-quick-start"]
+    REF["references/lite-plan.md\noriginal lite plan, preserved"]
+    QPLAN["plan.md\nfresh quick-start template"]
+    QSTATE["state.md\noat_workflow_mode: quick\noat_phase: discovery (complete)\noat_ready_for: oat-project-quick-start"]
+  end
+
+  LPLAN --> CMD
+  LSTATE --> CMD
+  CMD -->|derive| DISC
+  CMD -->|move| REF
+  CMD -->|scaffold| QPLAN
+  CMD -->|rewrite| QSTATE
+```
+
+The project slug, directory, and branch are untouched, so history and any open
+work continue uninterrupted. `oat_ready_for` is stamped on **both** `discovery.md`
+and `state.md`; the quick-start recommender reads artifact readiness, so
+consumers must preserve both. Promotion refuses rather than half-applying: a
+non-lite project, an existing `references/lite-plan.md`, invalid authored
+sections, an unresolved scope, or an unreadable template each return a stable
+categorical `reason` and exit non-zero. See
+[CLI Reference](../../reference/cli-reference.md) for the full refusal contract.
+
 ### Import lane
 
 ```mermaid
@@ -304,6 +462,10 @@ Quick lane progression:
 
 `discovery.md` -> [`design.md` (optional lightweight)] -> `plan.md` -> `implementation.md`
 
+Lite lane progression:
+
+`plan.md` -> `implementation.md` -> `pr/*.md` (`summary.md` and documentation are opt-in)
+
 Import lane progression:
 
 `references/imported-plan.md` -> `plan.md` -> `implementation.md` (`spec.md`/`design.md` optional)
@@ -360,15 +522,15 @@ actionable `oat pjm init` stop instead of scaffolding implicitly. See
 
 ### Seeding a new project from a brainstorm
 
-When the brainstorming destination is "promote to a new OAT project", the dispatcher confirms a project slug and a mode (`quick` vs `spec-driven`) with the user, runs `oat project new <slug> --mode <mode>` to scaffold the project, and writes the new project's `discovery.md` directly from the brainstorming payload — Initial Request, Solution Space with approaches considered, Chosen Direction, Key Decisions, Open Questions. It writes `discovery.md` only (never a partial `design.md`), so the design phase keeps its full collaborative cadence and consumes the brainstorm's architectural intent from discovery's Solution Space and Chosen Direction sections during approach reaffirmation. The dispatcher stops with a pointer to `oat-project-quick-start` or `oat-project-design` — it deliberately does not auto-chain into the next phase, so the user makes that transition consciously.
+When the brainstorming destination is "promote to a new OAT project", the dispatcher confirms a project slug and one of three modes: `lite`, `quick`, or `spec-driven`. For Quick and Spec-Driven projects, it runs `oat project new <slug> --mode <mode>` and writes `discovery.md` directly from the brainstorming payload — Initial Request, Solution Space with approaches considered, Chosen Direction, Key Decisions, and Open Questions. It writes only `discovery.md` (never a partial `design.md`), then points to `oat-project-quick-start` or `oat-project-design` without auto-chaining. For Lite projects, it instead seeds the five sections in `plan.md`, leaves `discovery.md` and `design.md` absent, and points to `oat-project-lite`.
 
-This is a parallel entry path into the Spec-Driven and Quick lanes, not a new lane: the resulting project follows the normal lane it was scaffolded into. The brainstorm-as-seed step is what changes — the user arrives at `oat-project-quick-start` (or `oat-project-design`) with discovery already populated rather than starting from a blank discovery template.
+This is a parallel entry path into all three lanes, not a new lane. Quick and Spec-Driven users arrive at `oat-project-quick-start` or `oat-project-design` with discovery already populated; Lite users arrive at `oat-project-lite` with the single-phase plan already seeded.
 
 ### Folding back into an active project
 
 When `oat-brainstorm` fires while a project is active, it offers a 3-way picker before any pack-filtered destination shows up:
 
-- **Related to the project** → fold the synthesized brainstorming content back into the most-specific upstream artifact (`design.md` if it exists, otherwise `discovery.md`), commit immediately, and print a handoff prompt for the right plan-authoring skill (`oat-project-plan` for spec-driven, `oat-project-quick-start` for quick, `oat-project-revise` when an open PR exists). The fold-back commit is safety-gated: a preflight `git status --porcelain -- "$ARTIFACT_PATH"` checks for dirty state, staging is exactly `git add -- "$ARTIFACT_PATH"` (never `-A`, never globs), and the handoff prompt only prints after the scoped commit succeeds.
+- **Related to the project** → for Lite, fold the synthesis into `plan.md` immediately above `## Phase 1` and hand off to `oat-project-lite`; for Quick and Spec-Driven, use the most-specific upstream artifact (`design.md` if it exists, otherwise `discovery.md`) and hand off to `oat-project-quick-start` or `oat-project-plan`. Any mode with an open PR hands off to `oat-project-revise`. The fold-back commit is safety-gated: a preflight `git status --porcelain -- "$ARTIFACT_PATH"` checks for dirty state, staging is exactly `git add -- "$ARTIFACT_PATH"` (never `-A`, never globs), and the handoff prompt only prints after the scoped commit succeeds.
 - **Independent of the project** → the active project is acknowledged but doesn't constrain the picker; brainstorm routes through its standard pack-filtered terminal-state options (new project, backlog item, idea, doc-to-path, inline).
 - **Related but supplementary** → write a brainstorming reference file at `.oat/projects/<scope>/<project>/brainstorming/YYYY-MM-DD-<topic>.md`, alongside `pr/` and `reviews/`. No lifecycle artifact is touched.
 

package/assets/docs/workflows/projects/picking-up-projects.md

@@ -36,6 +36,20 @@ its parent is reported and skipped rather than adopted.
 After adoption, set or open the project through the normal lifecycle command
 you are using. Arrival-aware project skills pull before reading its artifacts.
 
+An adopted quick-workflow project whose `plan.md` is not implementation-ready
+resumes through `oat-project-quick-start`, which continues it in place without
+re-scaffolding, rather than through `oat-project-implement`. `oat-project-plan`,
+`oat-project-progress`, and `oat-project-next` all route by the single **quick
+plan readiness** predicate that `oat-project-quick-start` defines; readiness is
+never inferred from the presence of tasks alone.
+
+`oat project status` and `oat project list` apply the same predicate. For a
+quick project at the `plan` phase they recommend `oat-project-quick-start`, with
+the unmet clause in the reason, until the plan carries ready frontmatter, a
+durable `## Reviews` disposition, and a substantive task; only then do they
+recommend `oat-project-implement`. Recommendations for lite, spec-driven, and
+import projects are unchanged, because the predicate is quick-workflow policy.
+
 ## What travels
 
 - The project ref carries the complete active artifact tree and its history.