@open-agent-toolkit/cli 0.3.21 → 0.3.23

package/assets/docs/workflows/projects/execution/project-log.md

@@ -11,16 +11,20 @@ would otherwise remain in agent transcripts, then roll that evidence into
 tracked project and repository references before archiving the project.
 
 The command group is the only supported writer for the artifact. Do not edit
-entries or the synthesis section by hand.
+entries or the synthesis section by hand. A new log starts with a two-line
+header that links to this page; the entry contract lives here and in
+`oat project log append --help` rather than in every log.
 
 ## Configure project logs
 
-Two workflow keys control the feature:
+Four workflow keys control the feature:
 
-| Key                             | Values                   | Default                                       |
-| ------------------------------- | ------------------------ | --------------------------------------------- |
-| `workflow.projectLog`           | `auto`, `true`, `false`  | `auto`                                        |
-| `workflow.projectLogLedgerPath` | repository-relative path | `.oat/repo/reference/project-observations.md` |
+| Key                                    | Values                   | Default                                       |
+| -------------------------------------- | ------------------------ | --------------------------------------------- |
+| `workflow.projectLog`                  | `auto`, `true`, `false`  | `auto`                                        |
+| `workflow.projectLogLedgerPath`        | repository-relative path | `.oat/repo/reference/project-observations.md` |
+| `workflow.projectLogDigest.maxEntries` | positive integer         | `12`                                          |
+| `workflow.projectLogDigest.maxLines`   | positive integer         | `60`                                          |
 
 ```bash
 oat config set workflow.projectLog auto --shared
@@ -35,6 +39,12 @@ current config value.
 For one scaffold operation, `oat project new --with-project-log` forces
 creation and `--no-project-log` suppresses it.
 
+The two `workflow.projectLogDigest` keys bound the Workflow Observations digest
+that roll-up writes into `summary.md` (see
+[Promote and roll up observations](#promote-and-roll-up-observations)). They
+are siblings of `workflow.projectLog`, resolve independently of it, and accept
+only positive integers.
+
 ## Append entries
 
 Judgment entries capture evidence about the project or reusable workflow:
@@ -57,6 +67,48 @@ Judgment flags:
 - `--version-note <text>` — adds an `observed on` clause
 - `--project <path>` — optional when an active project resolves
 
+### Learning entries
+
+A judgment entry can carry a learning category and a stable source identity.
+Autonomous, cloud and goal runs record their learnings this way, so the log is
+the one place learnings live; summary and retro read these entries first and a
+legacy `oat-execution-learnings.md` second.
+
+```bash
+oat project log append \
+  --project .oat/projects/shared/example \
+  --type friction --scope project --area "cloud cache misses" \
+  --category environment-limited \
+  --source obs-2026-10-11-cache \
+  --origin oat-project-autonomous \
+  --idempotency-key obs-2026-10-11-cache \
+  --body "Observation: the runner cache missed on every run. Impact: builds doubled. Recommendation: warm the cache in setup."
+```
+
+- `--category <category>` — one of `gotcha`, `efficiency`,
+  `documentation-gap`, `candidate-skill-content`, `decision`, or
+  `environment-limited`, carried verbatim. Any other value is refused, and
+  `--category` without `--source` is refused.
+- `--source <id>` — the stable per-observation source id, one word. Pass the
+  same id as `--idempotency-key` and a retried write appends nothing; the key
+  is found in the `**Source:**` line, so the body need not repeat it.
+- `--origin <producer>` — the producer that recorded the learning.
+
+These flags write a body head above the body:
+
+```text
+**Category:** environment-limited
+**Source:** obs-2026-10-11-cache
+**Origin:** oat-project-autonomous
+**Recorded:** 2026-10-11T14:03:22Z
+```
+
+The heading grammar and the four judgment types are unchanged, and an entry
+written without these flags is stored exactly as before. The flags are refused
+on structural entries.
+
+### Structural entries
+
 Structural entries record lifecycle events without duplicating larger
 artifacts:
 
@@ -185,7 +237,10 @@ oat project log check --project .oat/projects/shared/example --json
 
 `check` reports whether the log is absent, ready, or still awaiting synthesis;
 entry counts by class, type, and scope; the last entry date; and invalid
-hand-written headings. It reads only `project-log.md`.
+hand-written headings. It reads `project-log.md` and checks only for the
+presence of the legacy learnings file: `learnings` is `legacy` when the project
+still has `oat-execution-learnings.md` (summary and retro read it after the
+log) and `none` otherwise, in every status including `absent`.
 
 It also reports whether the log carries a completion seal:
 
@@ -253,16 +308,50 @@ oat project log rollup \
   --json
 ```
 
-`rollup` writes or updates `## Workflow Observations` in `summary.md` and
-appends `general` judgments to `workflow.projectLogLedgerPath`. Ledger entries
+`rollup` writes a bounded observations digest into `summary.md` and appends
+`general` judgments to `workflow.projectLogLedgerPath`. Ledger entries
 deduplicate by date and area. The command is idempotent.
 
+The digest is a projection, not a copy:
+
+- Only judgment entries qualify. Structural entries are provenance and stay in
+  the log; they are counted, never rendered.
+- Entries are ordered newest first, then `decision` and `gotcha` categories
+  ahead of the rest, then by heading text, and taken while both bounds hold:
+  at most `workflow.projectLogDigest.maxEntries` items and at most
+  `workflow.projectLogDigest.maxLines` lines for the whole section. Entries
+  beyond the bound are counted in a one-line trailer, never copied.
+- Each item is concise: a line with date, type, area, scope, category and the
+  entry's source locator, then the first observation sentence and any
+  limitation or uncertainty line. A recommendation is rendered only for an
+  uncategorized entry; a categorized learning's recommendation belongs to the
+  summary's Autonomous Execution Learnings section, and the digest adds a
+  one-line cross-reference to it.
+- The locator is a plain token, never a link:
+  `oat-project:<slug>#<entry-id>`, where the entry id is
+  `<date>-<type>-<area slug>-<n>` and `n` counts entries sharing that date,
+  type and area slug in log order. Archive export finalizes the token to the
+  archive identity.
+- Live `.oat/projects/<scope>/<slug>/…` paths in rendered text are replaced by
+  a `(project file …)` label that keeps the project-relative remainder.
+- When no judgment entry qualifies, the section is omitted: an existing
+  Workflow Observations section is removed and none is created.
+
+The digest never feeds the ledger. Ledger graduation reads the complete
+judgment set, so a `general` lesson the digest bound left out still graduates.
+
 The structured result contains:
 
 - `status`: `ok`, `failed`, or `ambiguous`
-- `summarySection`: `written` or `updated`
+- `summarySection`: `written`, `updated`, or `omitted`
 - `ledgerOutcome`: `appended`, `deduplicated`, `skipped_permitted`, or `failed`
-- `entriesRolledUp`: number of log entries written to the summary section
+- `entriesRolledUp`: number of log entries read, structural and judgment
+- `digest`: the bounds used (`maxEntries`, `maxLines`), the `rendered` count,
+  `omitted` counts (`overBound`, `structural`, and `malformed` for a heading
+  that matches neither grammar and was skipped individually),
+  `omittedEntries` (the locator tokens of over-bound entries, no bodies), and
+  `byProducer` rendered/omitted counts keyed by a judgment's `**Origin:**` (or
+  `unattributed`) or a structural entry's producer
 
 An `ambiguous` result carries only `status` and an `ambiguity` reason, and exits
 1: the log's structure has two readings, so no count would mean anything and

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

@@ -66,7 +66,7 @@ Implementation closeout has one authoritative order:
 4. Run the configured pre-approval sequence.
 5. Record final HiLL approval when the final phase is a checkpoint.
 6. Run the configured post-approval sequence.
-7. Mark implementation complete and emit the implementation success output.
+7. Check the journal (`oat project journal check --at implement-preflight`), then mark implementation complete and emit the implementation success output.
 
 The configured exit gate is independent from the mandatory lifecycle review,
 root-owned phase reviews, and optional `oat_phase_review_gate`. It must reach an
@@ -91,7 +91,7 @@ After implementation closeout finishes:
    - GitHub PR feedback delegates to `oat-project-review-receive-remote`
    - Review artifacts delegate to `oat-project-review-receive`
    - 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. Before any completion write it runs the read-only `oat project closeout-check`: a configured, autonomous, or lite closeout whose `oat_post_implement_sequence` snapshot is missing, malformed, or incomplete stops and routes back to `oat-project-implement`, and `oat project complete-state` refuses the same state. There is no override; see the [CLI reference](../../reference/cli-reference.md).
+5. **Complete** (`oat-project-complete`) — accepts `pr_open` or `complete` (an `in_progress` project is routed back to `oat-project-implement`, because the journal and `state.md` must agree at completion), auto-refreshes `summary.md` before closeout when needed, and archives when selected by the workflow preference or completion prompt. Before any completion write it runs the read-only `oat project closeout-check`: a configured, autonomous, or lite closeout whose `oat_post_implement_sequence` snapshot is missing, malformed, or incomplete stops and routes back to `oat-project-implement`, and `oat project complete-state` refuses the same state. There is no override for that invariant. Completion then refreshes the journal's Final Summary and `summary.md` prose from observed facts, runs the summary staged, and validates the journal with `oat project journal check --at completion` before any roll-up, seal, archive or lifecycle write; a refusal stops completion with the reason, line and owner, and `complete-state` rechecks the same evaluator before its write. A journal-only override line under `## Deviations from Plan / Design` can cover an authorized gap such as lost commit evidence, never the closeout invariant; see the [CLI reference](../../reference/cli-reference.md) and [Project Artifacts](../../reference/project-artifacts.md#the-implementation-journal).
 
 ### Project-recap gate (non-lite)
 
@@ -157,7 +157,7 @@ On completion, OAT treats archive handling as an explicit closeout choice:
 - If `.oat/config.json` sets `archive.awsProfile` and/or `archive.awsRegion`, those values are forwarded to every `aws` invocation triggered by completion (preflight checks + `aws s3 sync`) and override any ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` / `AWS_REGION` / `AWS_DEFAULT_REGION` values. The repo's archive-scoped credentials are treated as deliberate intent so users don't have to unset shell env vars before running completion. See [`config-and-local-state.md`](../../reference/config-and-local-state.md) for the full precedence chain.
 - If `.oat/config.json` sets `archive.summaryExportPath`, completion copies `summary.md` to `<archive.summaryExportPath>/20260401-<project>.md`.
 - Missing or unusable AWS CLI configuration blocks synced terminal cleanup when S3 durability is configured; when S3 sync is not configured, it is not part of the durability requirement.
-- `oat repo archive sync` can later sync all archived projects, or one named archived project, back down from S3; it selects the latest dated remote snapshot and materializes it into the local bare archive tree.
+- `oat repo archive sync` can later sync all archived projects, or one named archived project, back down from S3, materializing each snapshot into the local bare archive tree under its full local name (generation 2 of `<project>` restores to `<project>-g2`, never over generation 1). Archive names follow one contract, `<project>[-gN][-<scope>]` locally and `<YYYYMMDD>-<project>[-gN][-<scope>]` in S3, where `-<scope>` appears only when another scope's archive already held the unqualified name. An unnamed sync restores the latest dated snapshot of every local archive. A named sync takes an exact snapshot name first, then a full generation name such as `<project>-g2` or `<project>-g2-local`, then a generation family: `<project>-<scope>` restores that scope's latest generation, and the base `<project>` restores every family of the project (the unqualified one and each scope-qualified one) at its latest generation, then latest date. A project whose own name ends in `-gN` or `-<scope>` reads as that generation or qualifier, so its name can resolve to the same archive directory as a shorter-named project's; sync it by exact snapshot name to remove the ambiguity.
 - Persisted archive metadata binds the snapshot to the source-ref SHA, allowing
   an interrupted closeout or legacy complete record to resume without
   rematerializing an active project. Dashboard and list surfaces omit fully

package/assets/docs/workflows/projects/reviews/index.md

@@ -259,6 +259,24 @@ Final review `passed` gate requires:
 A goal milestone delivery is gated by its passed, fresh integrated review and
 exit carrier rather than by a `final` row.
 
+## Receipts in the journal
+
+`oat-project-review-receive` writes one receipt per received review: a
+phase-scoped receipt in that phase's section of `implementation.md`, a final,
+multi-phase, milestone or remote (PR) receipt under `## Reviews and Gates`,
+never after `## References`. Each receipt lists every finding's identity and
+substance, its disposition and rationale, the fix task or approved deferral it
+links to, and the final outcome; approved deferrals are also lines under
+`## Deferred Findings`. The review file path is a local-only citation: reviews
+are not archived, so the journal and plan must stand without it, and an
+unresolved review path is never a completion defect.
+
+Code reviews run `oat project journal check --at review --scope <phases>`
+first; its reasons reach the reviewer in the Review Scope. A finding that a
+mechanical pointer or projection refresh resolves (stale overview totals, a
+run line to re-render, a lagging resume pointer) is refresh-only and belongs to
+closeout's refresh, never a fix task.
+
 ## Complexity review at budget exhaustion
 
 When a review or gate budget runs out, another round of the same review is

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.21",
-  "docs-config": "0.3.21",
-  "docs-theme": "0.3.21",
-  "docs-transforms": "0.3.21"
+  "cli": "0.3.23",
+  "docs-config": "0.3.23",
+  "docs-theme": "0.3.23",
+  "docs-transforms": "0.3.23"
 }

package/assets/skills/oat-cursor-cloud-projects/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep
 metadata:
-  version: 1.1.3
+  version: 1.1.4
 ---
 
 # OAT in Cursor Cloud
@@ -33,7 +33,8 @@ end-to-end requests route to `oat-project-autonomous` after orientation.
 
 - A shell and Node/npm are available.
 - Read `references/cursor-cloud-mechanics.md` only when model-family identity,
-  dispatch-surface catalogs, or degraded review evidence is needed.
+  dispatch-surface catalogs, degraded review evidence, or a learning write is
+  needed.
 
 ## Mode Assertion
 
@@ -62,7 +63,7 @@ context without taking ownership of a lifecycle phase.
 - Verifying or installing the supported OAT CLI.
 - Comparing skill versions as a freshness check.
 - Loading Cursor mechanics and org-layer context skills when relevant.
-- Recording environment anomalies and degraded routes in project learnings.
+- Recording environment anomalies and degraded routes as project-log learnings.
 
 **Self-Correction Protocol:**
 
@@ -243,9 +244,10 @@ user version >= repo version
 It never chooses the source:
 
 - user version equal to or higher than repo → read the user copy;
-- repo version higher than user → still read the user copy, append an anomaly
-  to `oat-execution-learnings.md`, and flag the user tier for refresh with
-  `oat tools update` or an environment rebuild;
+- repo version higher than user → still read the user copy, record the anomaly
+  as a learning through the project-log learning write in
+  `references/cursor-cloud-mechanics.md` (Learning Write), and flag the user
+  tier for refresh with `oat tools update` or an environment rebuild;
 - if freshness is safety-critical, refresh and re-verify before continuing;
   stop if the user tier cannot be refreshed safely.
 
@@ -283,8 +285,10 @@ the provider dispatch algorithm.
   environment when integrated systems require them. Do not hard-depend on,
   name, or emulate an absent org layer.
 - When an expected skill, MCP server, CLI surface, or credential is absent,
-  record the gap in the active project's `oat-execution-learnings.md`. Continue
-  only through a documented integrity-preserving route.
+  record the gap as a learning in the active project's `project-log.md` through
+  the Learning Write in `references/cursor-cloud-mechanics.md`; with the
+  project log disabled it warns once and records nothing. Continue only through
+  a documented integrity-preserving route.
 
 Return an orientation summary:
 

package/assets/skills/oat-cursor-cloud-projects/references/cursor-cloud-mechanics.md

@@ -92,10 +92,71 @@ That provider reference owns Cursor launch, acceptance, continuation, retry,
 and recovery mechanics. `oat-project-dispatch-subagents` owns lifecycle scope
 and policy adaptation. Do not duplicate those contracts here.
 
+## Learning Write
+
+Cloud learnings — environment anomalies, setup gaps, degraded checks, freshness
+anomalies and missing skills, MCP servers, CLI surfaces or credentials — are
+category-bearing judgment entries in the active project's `project-log.md`,
+written only through `oat project log append`. Never create or append to
+`oat-execution-learnings.md`.
+
+Give each observation a stable, whitespace-free source id unique to this run
+and observation (for example `cloud-<run id>-<NN>`) and retain it for retries;
+it is both `--source` and `--idempotency-key`, so a replay appends nothing.
+Write the learning title as `--area` and the body as `Observation:`,
+`Impact:`, `Recommendation:` and, when it applies, `Uncertainty:` lines.
+
+```bash
+# Learning write (shared by oat-project-autonomous, oat-cursor-cloud-projects
+# and oat-project-goal): oat_record_learning <category> <source-id> <title> <body>
+oat_record_learning() {
+  local category="$1" source="$2" title="$3" body="$4" type result
+  case "$category" in
+    gotcha | environment-limited) type=friction ;;
+    efficiency | candidate-skill-content) type=worked-well ;;
+    documentation-gap | decision) type=feedback ;;
+    *)
+      echo "oat: unknown learning category '$category'" >&2
+      return 1
+      ;;
+  esac
+  result=$(oat project log append --json --project "$PROJECT_PATH" \
+    --type "$type" --scope project --area "$title" \
+    --category "$category" \
+    --source "$source" \
+    --origin "${LEARNING_ORIGIN:?set to the producer skill name}" \
+    --idempotency-key "$source" \
+    --body "$body") || {
+    printf '%s\n' "$result" >&2
+    return 1
+  }
+  if printf '%s' "$result" | grep -Eq '"status": *"skipped"'; then
+    echo "oat: warning: project log disabled (workflow.projectLog=false); learning $source not recorded" >&2
+  fi
+}
+```
+
+Set `LEARNING_ORIGIN=oat-cursor-cloud-projects`. Use the six categories
+verbatim; an environment anomaly or a missing surface is usually
+`environment-limited`, a stale user tier `gotcha`. The write maps the category
+to the judgment type (`gotcha`, `environment-limited` → `friction`;
+`efficiency`, `candidate-skill-content` → `worked-well`; `documentation-gap`,
+`decision` → `feedback`).
+
+Call it unconditionally; do not read `workflow.projectLog` yourself. The
+append consults that flag only while `project-log.md` does not exist: with the
+log disabled and absent it creates nothing and reports `status: skipped`, the
+write prints one warning line, records nothing, and orientation continues. An
+existing `project-log.md` keeps accepting categorized learnings whatever the
+flag says (`DR-260718-automatic-create-on-first`). Commit `project-log.md`, when it
+exists, with the next bookkeeping commit for the project (a synced project uses
+`oat project push`).
+
 ## Degraded Route Evidence
 
 Degradation is a pre-launch selection outcome, not a post-accept fallback.
-Record it in the canonical dispatch record plus project learnings.
+Record it in the canonical dispatch record plus one learning (see Learning
+Write).
 
 Use this shape for the Cursor-specific evidence supplied to the generic record:
 
@@ -149,7 +210,7 @@ independence:
 degradation:
   present: true
   reason: catalog-contained-one-dispatchable-family
-learnings_entry: oat-execution-learnings.md#<entry>
+learnings_entry: <learning source id>
 ```
 
 Include the exact configured invocation evidence required by the generic record

package/assets/skills/oat-docs/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.0.6
+  version: 1.0.7
 ---
 
 # OAT Docs
@@ -89,29 +89,15 @@ Read the user's question from `$ARGUMENTS`. If no question was provided or the q
 
 > "What would you like to know about OAT? I can help with workflows, CLI commands, skill authoring, configuration, project lifecycle, and more."
 
-Classify the question into one or more topic areas to guide the search:
-
-| Topic Area       | Docs Path                                                       | Key Content                                  |
-| ---------------- | --------------------------------------------------------------- | -------------------------------------------- |
-| Getting started  | `getting-started/quickstart.md`, `getting-started/bootstrap.md` | Installation, first project setup            |
-| Concepts         | `getting-started/concepts.md`                                   | Core OAT concepts and terminology            |
-| CLI commands     | `reference/cli-reference.md`                                    | Full CLI command reference                   |
-| Tool packs       | `getting-started/tool-packs.md`                                 | Installing and managing skill packs          |
-| Skills           | `contributing/skills.md`                                        | Skill authoring, SKILL.md format             |
-| Workflows        | `workflows/projects/`                                           | Project lifecycle, state machine, artifacts  |
-| Ideas            | `workflows/ideas/`                                              | Idea capture and brainstorming               |
-| Provider sync    | `provider-sync/`                                                | Multi-provider sync, config, commands        |
-| Documentation    | `docs-tooling/`                                                 | Docs analysis and apply workflows            |
-| Contributing     | `contributing/`                                                 | Code contributions, design principles, hooks |
-| File locations   | `reference/file-locations.md`                                   | Where OAT puts things                        |
-| Directory layout | `reference/oat-directory-structure.md`                          | `.oat/` and `.agents/` structure             |
-| Troubleshooting  | `reference/troubleshooting.md`                                  | Common issues and fixes                      |
+Read `DOCS_ROOT/index.md` and its `## Contents` section. Derive a temporary topic map from the installed labels, summaries, and link targets; do not assume OAT's repository layout or a fixed set of topic paths. Choose the entries that match the question and descend through their authored `index.md` Contents maps when needed. Resolve each link relative to its containing file and verify it exists before reading it.
+
+If the installed index has no usable Contents or a linked target is missing, report that specific stale or incomplete installation. Search within `DOCS_ROOT` for the requested terms to find existing evidence, and recommend updating the installed docs when appropriate. Never invent a replacement path or fall back to the repository.
 
 ### Step 3: Search and Read Documentation
 
 Based on the topic classification:
 
-1. **Read the most relevant docs file(s)** — start with the primary match from the topic table. All paths are relative to `DOCS_ROOT` (`~/.oat/docs/`).
+1. **Read the most relevant docs file(s)** — start with the primary match from the topic map derived in Step 2. All paths are relative to `DOCS_ROOT` (`~/.oat/docs/`).
 2. **Search for specific terms** — if the question mentions specific concepts, commands, or features, use Grep to find mentions across `~/.oat/docs/`.
 3. **Follow cross-references** — if the primary doc references other pages, read those for complete context.
 4. **Check the index** — read the `index.md` of relevant directories to discover additional relevant pages.
@@ -143,7 +129,7 @@ Frame these as suggestions, not automatic actions. Let the user decide.
 ```
 Based on the docs, here's how OAT project workflows work: [answer]
 
-You can read more in `workflows/projects/lifecycle.md`.
+Cite the installed workflow page discovered through Contents.
 
 Would you like me to:
 - Start a new project? (I'd invoke oat-project-lite for single-sitting work, oat-project-brief for one delivery planned as a Project Brief, oat-project-goal for an outcome delivered over several milestones, or oat-project-quick-start for a larger quick workflow)
@@ -190,7 +176,7 @@ Both create a project directory under your projects root
 state.md, plan.md, and implementation.md; quick and spec-driven modes also use
 discovery.md.
 
-See: workflows/projects/lifecycle.md, getting-started/quickstart.md
+See: the actual installed workflow and getting-started pages found through Contents.
 
 Would you like me to create a project for you?
 ```
@@ -203,20 +189,20 @@ Would you like me to create a project for you?
 
 ```
 Tool packs are bundles of related OAT skills that you install together.
-There are four packs:
+Describe the packs listed by the installed tool-pack documentation, for example:
 
-- **core** — Diagnostics and docs skills (oat-doctor, oat-docs).
-  Always installed at user level. 2 skills.
+- **core** — Diagnostics and docs skills.
+  Read the installed docs for scope and current membership.
 - **workflows** — Project lifecycle skills (discover, plan, implement,
-  review, PR). 26 skills total.
-- **ideas** — Brainstorming and idea capture skills. 4 skills.
+  review, PR).
+- **ideas** — Brainstorming and idea capture skills.
 - **utility** — Cross-cutting tools (docs analysis, code review,
-  skill creation). 9 skills.
+  skill creation).
 
 Install with: oat init tools
 Manage with: oat tools list, oat tools update, oat tools outdated
 
-See: getting-started/tool-packs.md
+See: the installed tool-pack page discovered through Contents.
 
 Would you like me to check which packs you have installed? (I'd run /oat-doctor --summary)
 ```

package/assets/skills/oat-docs-analyze/SKILL.md

@@ -3,9 +3,9 @@ name: oat-docs-analyze
 description: Run when you need to evaluate documentation structure, navigation, and coverage against the OAT documentation contract. Produces a severity-rated analysis artifact for oat-docs-apply.
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Bash(oat docs nav sync --check:*), Glob, Grep, AskUserQuestion, Task
+allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: '1.6.2'
+  version: '1.6.3'
 ---
 
 # Docs Analysis
@@ -162,6 +162,8 @@ Capture the evidence sources that will justify later findings and recommendation
 - existing `index.md` trees and repeated directory patterns
 - exact missing or stale paths, commands, and page references
 
+For framework apps, also read [Legacy scaffold checks](references/legacy-scaffold-checks.md). Apply those checks to the actual installed app, cite the observed file and source contract, and report discrepancies in Findings and Recommendations. These are read-only checks, not bootstrap post-patches. Do not change app-shell configuration during analysis or assume docs-apply can edit it; identify the manual upgrade needed when outside apply's current scope.
+
 Do **not** infer docs structure conventions from a tiny sample of pages when the broader
 tree or config disagrees.
 

package/assets/skills/oat-docs-analyze/references/legacy-scaffold-checks.md

@@ -0,0 +1,16 @@
+# Legacy scaffold checks
+
+Evaluate existing framework apps against the current contracts below. A match produces an evidence-backed finding in the analysis artifact, never an automatic rewrite. Cite the actual app path and line, the missing contract, confidence and a specific repair. Respect intentional user customization; when intent is unclear, use `ask_user`.
+
+| Observed older shape                                                                                                                             | Finding and repair                                                                                                                                                                                                                                                                                                                                                                                | Contract source                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| Fumadocs `next.config.js` replaces `createDocsConfig` with `createMDX()({ reactStrictMode: true, turbopack: { root: __dirname } })`              | High: static-export settings are missing and `__dirname` is invalid in ESM. Recommend a manual app-config upgrade to `createDocsConfig({ basePath, turbopack: { root: dirname(fileURLToPath(import.meta.url)) } })`, preserving `output: 'export'`, `trailingSlash`, `images.unoptimized`, base path and client environment. Verify the installed docs-config supports forwarding the root first. | `@open-agent-toolkit/docs-config` factory and the current Fumadocs template |
+| Layout lacks Next `metadata`, or site title differs between branding, metadata and authored headings                                             | Medium: site identity or document metadata is inconsistent. Report exact mismatches; titles belong in layout metadata and branding, not `createDocsConfig`.                                                                                                                                                                                                                                       | Fumadocs layout template and Next metadata export                           |
+| Getting Started has an empty description, bare commands with no working directory, or claims lint runs when package scripts disable it           | Medium: setup guidance disagrees with package scripts or page metadata. Recommend corrected prose backed by the actual scripts.                                                                                                                                                                                                                                                                   | Rendered scaffold package scripts and page frontmatter                      |
+| Node prerequisite is a fixed old major or tells readers to guess from repo pins                                                                  | Medium: compare `.nvmrc` first, then root `package.json` `engines.node`; quote the detected requirement. When neither exists, disclose the CLI minimum rather than claiming a repo pin.                                                                                                                                                                                                           | Repository Node pin and current scaffold renderer                           |
+| Authored `docs/index.md` says it is generated, or contributing lacks the generated-files boundary                                                | Medium: distinguish authored `docs/index.md` from the generated app-root manifest. Document committed `docs/**/meta.json` and `oat docs nav sync` separately.                                                                                                                                                                                                                                     | `oat docs generate-index` and `oat docs nav sync`                           |
+| Contents links omit `.md` despite real Markdown targets                                                                                          | Medium: recommend `.md`-suffixed source links, which the build transforms into routes.                                                                                                                                                                                                                                                                                                            | Authored Contents contract and docs-transforms links plugin                 |
+| Contributing duplicates agent runtime rules rather than pointing to app-root `AGENTS.md`                                                         | Low: recommend consolidating runtime instructions into the existing agent guidance after approval; preserve custom rules.                                                                                                                                                                                                                                                                         | Docs-app guidance and contributing audience boundary                        |
+| MkDocs setup says `setup-docs.sh` creates a virtual environment, config calls `tooling` an object, or index points at an assumed `docs/index.md` | Medium: verify the actual script and `.oat/config.json`. The scaffold installs with the selected Python, uses a framework string, and seeds index/config as `mkdocs.yml`.                                                                                                                                                                                                                         | MkDocs setup script, documentation schema and scaffold config               |
+
+A user-owned dynamic app may intentionally omit static export. Do not apply a static-export finding to it without evidence that static output is required. Likewise, verify commands and filenames against the target repository; these patterns identify discrepancies, not authority to overwrite customization.

package/assets/skills/oat-docs-apply/SKILL.md

@@ -3,9 +3,9 @@ name: oat-docs-apply
 description: Run when you have a docs analysis artifact and want to generate or update documentation structure and content. Creates a branch, applies approved changes, and optionally opens a PR.
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Bash(oat:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: '1.4.3'
+  version: '1.4.4'
 ---
 
 # Docs Apply

package/assets/skills/oat-docs-authoring/SKILL.md

@@ -3,10 +3,10 @@ name: oat-docs-authoring
 description: Use when authoring or restructuring targeted content inside an existing OAT Markdown surface or OAT/Fumadocs docs app. Preserves OAT docs navigation, generated indexes, and validation boundaries.
 argument-hint: '[docs task or target path]'
 disable-model-invocation: false
-allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: '1.1.2'
+  version: '1.1.3'
 ---
 
 # OAT Docs Authoring

package/assets/skills/oat-docs-authoring/references/lifecycle-boundaries.md

@@ -42,8 +42,7 @@ Stop and reroute when you notice:
 ## Migration Pointer
 
 Full MkDocs-to-OAT-Fumadocs migration is not bootstrap and is not targeted
-authoring. Use the standalone `mkdocs-to-oat-fumadocs-refactor-guide.md` handoff
-when available, and keep the migration in an OAT project or explicit migration
+authoring. Use the bundled [MkDocs-to-OAT-Fumadocs migration guide](mkdocs-to-oat-fumadocs-refactor-guide.md), and keep the migration in an OAT project or explicit migration
 branch with owner-review items for unverifiable claims.
 
 For migration-sensitive follow-up after the migration workflow has created a

package/assets/skills/oat-docs-authoring/references/mkdocs-to-oat-fumadocs-refactor-guide.md

@@ -0,0 +1,73 @@
+# MkDocs to OAT/Fumadocs migration guide
+
+Use this standalone handoff for an explicitly approved migration of an existing MkDocs site. Bootstrap creates an app; targeted authoring edits content; neither performs a full migration. Keep migration work in an OAT project or an explicit migration branch, with the agreed scope and owner recorded before changes.
+
+This guide is reconstructed from current OAT CLI, template and authoring contracts. The older project-local handoff mentioned in OAT's docs-authoring project summary was unavailable; this is not a copy of that historical document.
+
+## Preflight: inventory before mutation
+
+1. Read repository and docs-local instructions, `mkdocs.yml`, `.oat/config.json`, Python dependency files, docs package scripts and deployment workflows. Resolve the actual content root, published URL/base path and build output; do not assume `docs/` or GitHub Pages.
+2. Inventory every source page, attachment, image, local link, anchor, nav entry and public URL. Record pages outside nav too. Keep a before/after mapping for every source path and URL; never silently drop an unlisted page.
+3. Inventory MkDocs-specific features: admonitions, tabs, includes/macros, plugin-generated pages, API generation, Mermaid, custom assets/theme, search and redirects. Distinguish supported conversion from manual work and unsupported features.
+4. Find claims requiring code/config evidence, confidential material, unresolved product behavior and owner-only knowledge. Record owner-review items rather than guessing or publishing uncertain claims.
+5. Discover validation commands and required runtimes from scripts, CI and contributor instructions. Establish a baseline with exact commands and exit codes, including existing failures. Agree on the target app location, dependency policy, URL preservation strategy and deployment change with the user.
+
+Produce an inventory and proposed migration scope for approval. Do not overwrite the MkDocs app, clear its configuration, delete Python tooling or switch deployment as a side effect of preparing a proposal.
+
+## Phase 1: create the approved target app
+
+Use `oat docs init --help` to inspect installed capabilities. Scaffold Fumadocs into an empty, approved destination with `--framework fumadocs`, a package/app name, site name, description and target directory. Bootstrap can guide this step, but creating a second app does not imply support for two active `documentation` entries: the current config describes one surface. Explicitly agree when the configured docs root will switch, and preserve the old config for rollback.
+
+Read the rendered package scripts and configuration. The current Fumadocs template uses Next static export, trailing slashes and unoptimized images through `createDocsConfig`. For nested-standalone repos only, it forwards an ESM-safe app directory as `turbopack.root`; monorepo and single-package scaffolds use Next.js root discovery. Preserve the site's base path and `NEXT_PUBLIC_BASE_PATH`; set site identity through layout metadata and `DocsLayout` branding, not factory title options.
+
+Install using the repository's package-manager conventions. Keep dependency or workspace changes visible in the migration diff. Do not delete the old site yet.
+
+## Phase 2: migrate content without losing source
+
+Copy approved content and assets into the target content root, retaining the source until parity is verified. Use the inventory to account for every file.
+
+`oat docs migrate` converts supported MkDocs admonitions and injects missing frontmatter in `.md` files. It is a dry run by default; `--apply` writes changes. `--config` supplies MkDocs nav title hints, not a complete navigation or app migration. For example, from the repository root:
+
+```bash
+# Replace paths with the approved destination and preserved source config.
+oat docs migrate --docs-dir apps/handbook/docs --config documentation/mkdocs.yml
+# Review the preview and approve the content conversion before writing.
+oat docs migrate --docs-dir apps/handbook/docs --config documentation/mkdocs.yml --apply
+```
+
+The command does not migrate app shells, deployment, plugins, macros, redirects or all Markdown extensions. Review seeded descriptions for meaningful content; metadata injection is not editorial completion. Convert unsupported syntax manually within the approved scope, preferring `.md` and using `.mdx` only where components require it. Preserve code examples, cautions, provenance and external attributions.
+
+## Phase 3: preserve navigation, links and URLs
+
+Create authored `index.md` pages with purpose and `## Contents` maps in each content directory. Map every retained page into the approved tree; use `.md` or `subdir/index.md` targets and the current dash-bullet Contents grammar. When consolidating `overview.md`, carry its content and inbound references into `index.md` and retain the old-URL mapping.
+
+Run `oat docs nav sync --target-dir <app-root>` to generate committed `docs/**/meta.json` navigation from authored maps. Resolve unlisted pages explicitly. Do not hand-edit generated navigation. The separate app-root `index.md` manifest is generated by `oat docs generate-index` through the scaffold's `predev`/`prebuild`; it is not the authored root page.
+
+Rewrite inbound links, relative assets and anchors using the before/after map. Test public URLs under the real base path. Choose an approved host-compatible recovery for moved URLs; do not assume Next redirects work with static export. If old URLs cannot be preserved, report the exact break and obtain a decision before deployment changes or source deletion.
+
+## Phase 4: validate the migration
+
+Discover and run the target app's actual lint, format, build and any link checks. Do not treat disabled/no-op scripts as validation. Run nav sync's read-only `--check` form to check committed navigation. Run existing repository gates required for package, config and workflow changes; keep exact exit codes and distinguish new failures from the baseline.
+
+Inspect the static output and use the available browser to spot-check:
+
+- landing and deeply nested pages, sidebar labels/order and search;
+- old and new URLs, anchors, relative links and base-path assets;
+- admonitions, tabs, tables, Mermaid, code blocks and custom components;
+- title/description metadata, theme and layout behavior.
+
+A successful build does not prove rendering or link parity. If a check cannot run, record the missing evidence and owner action; do not mark it verified. Review every inventory entry as migrated, deliberately retained, or explicitly approved for retirement, with a reason.
+
+## Phase 5: review, switch and retain rollback
+
+Present the content conservation diff, URL map, validation evidence, unresolved owner-review items, config changes and deployment proposal. Obtain user approval before switching the configured docs surface, changing publication workflows or retiring the old site. Use `oat-docs-analyze` for a read-only audit and the appropriate reviewed workflow for follow-up changes; do not assume docs-apply may edit app-shell or deployment configuration.
+
+Only after parity and approval, remove obsolete MkDocs dependencies/configuration and update repository guidance to the new authored source, generated artifacts and commands. Keep an explicit rollback reference to the prior site/config/deployment. Package publishing and production deployment require their own authorization.
+
+## Final report
+
+Report the approved scope, changed files and commits; source-to-target page and URL dispositions; commands and exit codes; rendered spot checks; the configured docs root and publication behavior; known failures and unverified evidence; owner-review items and decisions; and the rollback reference. State whether the migration is ready for owner acceptance, rather than treating the absence of build errors as acceptance.
+
+## Current contract references
+
+Within this installed skill, read [lifecycle boundaries](lifecycle-boundaries.md), [the Fumadocs contract](oat-fumadocs-contract.md) and [validation](validation.md). Load `authoring-docs` from installed scope for universal evidence and writing guidance. Inspect installed CLI help and rendered templates before executing commands; the consuming repository's instructions and approved migration scope remain authoritative.