@open-agent-toolkit/cli 0.0.37 → 0.0.39

package/assets/docs/cli-utilities/tool-packs.md

@@ -144,6 +144,10 @@ Key behavior:
 The `docs` pack contains active documentation and instruction-governance
 workflows:
 
+- **oat-docs-bootstrap** — Guide users through bootstrapping a docs app
+  end-to-end: preflight detection, input gathering, scaffold (via `oat docs
+init`) with capability-gated post-patches, build verification, config
+  inspection, and an educational walkthrough.
 - **oat-docs-analyze** — Analyze a docs surface for contract coverage, nav
   drift, stale claims, and coverage gaps.
 - **oat-docs-apply** — Apply only approved, evidence-backed docs-analysis

package/assets/docs/docs-tooling/add-docs-to-a-repo.md

@@ -52,6 +52,36 @@ quickstart, the docs pair is the part you need immediately.
 
 ## 3. Scaffold the docs app
 
+Two paths — pick one:
+
+### 3a. Preferred: the `oat-docs-bootstrap` skill (guided)
+
+```text
+/oat-docs-bootstrap
+```
+
+The docs-bootstrap skill wraps `oat docs init` with a seven-step guided flow: preflight detection (repo shape + existing-setup conflict surfacing), richer input gathering (including a site name distinct from the package name), the CLI invocation itself, labeled post-patches for open CLI gaps, install + build verification, post-scaffold config inspection, and a chunked educational walkthrough.
+
+What the skill adds over the raw CLI:
+
+- **Preflight + conflict resolution.** Detects existing `documentation` config / docs app dir / root `AGENTS.md` section and walks a deliberate resolution choice (replace, abort, repair, or deferred second-app) before any mutation.
+- **Richer inputs.** Asks for a **site name** separate from the package name, so `createDocsConfig()` / layout branding / page metadata all converge on the same display title.
+- **Post-scaffold patches for open CLI gaps.** Applied only when capability detection shows the CLI hasn't closed the gap. Each patch is labeled (e.g., `<!-- FP-12 patch -->`) so it can be removed deterministically when the upstream fix lands:
+  - **FP-11** — Turbopack `root` for nested-standalone Fumadocs apps (suppresses the multiple-lockfile warning)
+  - **FP-12** — `export const metadata = { title, description }` in `app/layout.tsx` (the only thing that populates page `<title>`, meta description, and Open Graph — `DocsLayout.branding.title` only renders nav chrome, and `createDocsConfig()` ignores `title` / `description` entirely)
+  - **FP-13** — five scaffold-content fixes (empty per-page `description:` frontmatter, bare install/build commands missing `--filter` or `cd`-prefix for monorepo/nested shapes, false `docs:lint` claim when `lint=none`, missing "do not hand-edit" header on generated `index.md`, Node version line that doesn't match the consuming repo's `.nvmrc` / `engines.node`)
+  - **FP-15** — writes a task-framed `<appRoot>/AGENTS.md` bridge file when the CLI hasn't scaffolded one. The bridge is the docs app's runtime agent reference (separate audience from `docs/contributing.md`)
+  - **FP-16** — rewrites `docs/index.md` `## Contents` links to the `.md`-suffixed form that `@open-agent-toolkit/docs-transforms` normalizes at build time (agent-friendlier than extension-less; routes correctly)
+  - **FP-17** — trims `docs/contributing.md`'s "Agent guidance" section to a one-line pointer at the docs-app `AGENTS.md`, restoring the three-surfaces separation
+- **Build verification.** Runs install + build, classifies failures against known patterns, stops on unknown errors rather than guessing.
+- **Config inspection.** Reads `.oat/config.json` back, verifies paths exist on disk, handles the nested-standalone dual-config case, and collects the `requireForProjectCompletion` opt-in explicitly.
+- **Educational walkthrough.** Seven sections covering the `documentation` config, the two-`index.md` model, the `## Contents` contract (with extension discipline), the three agent-instruction surfaces (root `AGENTS.md` pointer / docs-app `AGENTS.md` / `docs/contributing.md`), Fumadocs internals (or MkDocs Minimum Contract), and the OAT docs ecosystem (`oat-project-document`, `oat-docs-analyze`, `oat-docs-apply`).
+- **Optional content kickoff.** Hands off to `oat-docs-analyze` + `oat-docs-apply` if you want to populate initial repo-specific content immediately.
+
+Capability-gated: every post-patch self-ratchets off as CLI fixes land upstream. The skill's labeled markers (`<!-- FP-NN patch -->`) are how you find them later when the CLI catches up.
+
+### 3b. Direct CLI (deterministic / non-interactive)
+
 ```bash
 oat docs init --app-name my-docs
 ```
@@ -76,6 +106,8 @@ oat docs init --app-name my-docs --framework fumadocs --yes
 oat docs init --app-name my-docs --framework mkdocs --yes
 ```
 
+Use 3b when you want a fully headless scaffold (CI, automation) and can accept the raw CLI output without the guided post-patches.
+
 ## 3a. Migrating from MkDocs (optional)
 
 If you have an existing MkDocs site and want to switch to Fumadocs, use the

package/assets/docs/docs-tooling/commands.md

@@ -30,6 +30,8 @@ and **MkDocs Material**.
 
 Use `oat docs init` to scaffold a docs app that follows the OAT docs contract.
 
+> **Consider the `oat-docs-bootstrap` skill instead.** The skill wraps `oat docs init` with preflight detection, richer input gathering (site name distinct from package name), capability-gated post-patches that close open CLI gaps (site-title metadata, Turbopack root, template-content fixes, docs-app `AGENTS.md` bridge, `## Contents` link extensions, `contributing.md` three-surfaces cleanup), build verification, config inspection, and a seven-section educational walkthrough. See [Add Docs to a Repo §3a](add-docs-to-a-repo.md#3a-preferred-the-oat-docs-bootstrap-skill-guided) for the full flow. The CLI documented here remains the authoritative surface for flags and is the right choice when you need a deterministic, non-interactive scaffold (CI, automation).
+
 Key behavior:
 
 - prompts for framework choice (Fumadocs or MkDocs) in interactive mode

package/assets/docs/docs-tooling/workflows.md

@@ -23,6 +23,10 @@ Install the workflow skills with `oat tools install docs` (preferred) or
 
 ### Skills
 
+- `oat-docs-bootstrap` is the guided onramp for adding a docs app to a repo —
+  wraps `oat docs init` with preflight detection, richer input gathering (site
+  name distinct from package name), labeled post-patches for open CLI gaps,
+  build verification, config inspection, and an educational walkthrough
 - `oat-docs-analyze` evaluates a docs surface for structure, drift, coverage,
   contributor guidance, and docs-app contract issues
 - `oat-docs-apply` consumes the analysis artifact and applies only approved,
@@ -45,7 +49,7 @@ skills.
 
 ## Typical flow
 
-1. Bootstrap a docs app with `oat docs init` (choose Fumadocs or MkDocs)
+1. Bootstrap a docs app with `oat-docs-bootstrap` (preferred — guided, includes post-scaffold patches and walkthrough) or `oat docs init` directly (CLI-only / non-interactive workflows)
 2. (Optional) If migrating from MkDocs: `oat docs migrate --docs-dir docs --config mkdocs.yml --apply`
 3. Author docs so every directory has an `index.md` with a `## Contents` section
 4. Keep local `## Contents` sections current

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

@@ -21,7 +21,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Retroactively capture existing work: `oat-project-capture`
 - Run or receive reviews: `oat-project-review-provide`, `oat-project-review-receive`, or the non-project review variants
 - Manage the repo backlog and reference docs: `oat-pjm-add-backlog-item`, `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
-- Work on docs surfaces: `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
+- Work on docs surfaces: `oat-docs-bootstrap` (guided bootstrap of a new docs app), `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
 - Generate a shipping digest or scheduled recap: `oat-wrap-up`
 - Research a topic in depth: `deep-research`
 - Analyze an artifact, codebase, or document: `analyze`
@@ -75,6 +75,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
 === "Docs and instructions"
 
+    - `oat-docs-bootstrap`
     - `oat-docs-analyze`
     - `oat-docs-apply`
     - `oat-agent-instructions-analyze`

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.0.37",
-  "docs-config": "0.0.37",
-  "docs-theme": "0.0.37",
-  "docs-transforms": "0.0.37"
+  "cli": "0.0.39",
+  "docs-config": "0.0.39",
+  "docs-theme": "0.0.39",
+  "docs-transforms": "0.0.39"
 }