@open-agent-toolkit/cli 0.3.13 → 0.3.15

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

@@ -37,7 +37,9 @@ Install the workflow skills with `oat tools install docs` (preferred) or
 - `oat-docs-analyze` evaluates a docs surface for structure, drift, coverage,
   contributor guidance, and docs-app contract issues, then runs the shared
   auto artifact-review loop to verify the generated analysis artifact's
-  evidence, severities, and recommendations
+  evidence, severities, and recommendations (an analysis artifact is the
+  timestamped Markdown findings report that analyze writes under
+  `.oat/repo/analysis/` and that apply later reads)
 - `oat-docs-apply` consumes the analysis artifact and applies only approved,
   evidence-backed recommendations
 - `oat-project-document` performs post-implementation docs sync for a tracked project,
@@ -48,7 +50,8 @@ Install the workflow skills with `oat tools install docs` (preferred) or
 
 ## Contract model
 
-The docs workflow mirrors the agent-instructions analyze/apply split:
+The docs workflow mirrors the
+[agent-instructions analyze/apply split](agent-instructions.md):
 
 - Analyze owns discovery, evidence gathering, confidence, and disclosure decisions
 - Analyze also owns accuracy verification of the generated analysis artifact
@@ -61,6 +64,51 @@ skills.
 
 ## Typical flow
 
+Diagram: bootstrap once, then analyze, approve and apply only agreed improvements.
+
+=== "Diagram"
+
+    ![Bootstrap once with oat docs init into plain Markdown or a docs app, then analyze, plan, and either apply approved changes or stop when all are skipped](/diagrams/docs-workflows-light.svg)
+    ![Bootstrap once with oat docs init into plain Markdown or a docs app, then analyze, plan, and either apply approved changes or stop when all are skipped](/diagrams/docs-workflows-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart TD
+      SETUP["Bootstrap once\nConfirm inputs, then oat docs init"]
+      MD["Markdown\nValidate files and config"]
+      APP["Docs app\nInstall and verify build"]
+      AN["Analyze\nRead docs, write findings"]
+      PLAN["Plan from findings\nNo docs writes yet"]
+      Q{"Approve changes?"}
+      APPLY["Apply approved items\nNew branch, verify, offer PR"]
+      STOP["Skip all\nNo docs changed"]
+      SETUP --> MD
+      SETUP --> APP
+      MD -.-> AN
+      APP -.-> AN
+      AN --> PLAN
+      PLAN --> Q
+      Q -->|"approved"| APPLY
+      Q -->|"all skipped"| STOP
+    ```
+
+- **Setup, once.** `oat-docs-bootstrap` checks the repo without writing, asks
+  you to confirm its inputs, then runs `oat docs init`. Plain Markdown setup validates authored files,
+  configuration and guidance without installing app dependencies or building a
+  site. Fumadocs and MkDocs setup adds the relevant post-patches, installation,
+  build verification and walkthrough.
+- **Analyze.** `oat-docs-analyze` never edits docs. It writes an analysis
+  artifact under `.oat/repo/analysis/` (and updates OAT tracking).
+- **Approve.** `oat-docs-apply` builds a plan from the newest artifact and
+  stops for your decision: apply all, review item by item, or discuss and
+  revise. If the artifact is missing or stale it sends you back to analyze. If
+  you skip every item, nothing changes.
+- **Apply.** Only after approval does apply create a branch, edit the approved
+  docs, regenerate navigation, verify, commit and offer a pull request. Items
+  marked as needing confirmation are confirmed again before they are written.
+- **Repeat.** Re-run analyze afterwards to confirm the result.
+
 1. Bootstrap or explicitly adopt a documentation surface 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, handle that as a separate migration workstream; `oat docs migrate --docs-dir docs --config mkdocs.yml --apply` is only the syntax/frontmatter helper
 3. Use `oat-docs-authoring` for targeted OAT Markdown/Fumadocs authoring work, with `authoring-docs` as the universal documentation-quality baseline
@@ -98,9 +146,297 @@ to open every page.
 - link to deeper setup/config/reference material when full detail is not needed inline
 - let the analysis artifact decide what should be inline, link-only, omitted, or escalated to the user
 
+## authoring-docs
+
+**Invocation:** Ask, “Use authoring-docs to improve the recovery instructions
+in `docs/imports.md` for an on-call engineer.” Skill invocations are agent
+instructions, not shell commands: use `/authoring-docs` where supported,
+`$authoring-docs` in Codex, or the skill's name in a request. This convention
+also applies to the other skills below; example paths refer to your files.
+
+**Prerequisites:** A documentation target, intended reader, and accessible
+sources of truth. No OAT project or OAT documentation configuration is
+required. Source code, configuration, tests, deployment files, and existing
+instructions establish what you can safely document.
+
+**Example scenario:** An import runbook says to retry a job but does not
+explain how an operator confirms that retrying is safe. Ask the skill to
+inspect the actual job behavior and add a reader-focused recovery sequence,
+marking any operational assumption that needs the owner's confirmation.
+
+Choose the page's primary job before writing: a tutorial gets a reader to
+first success, a how-to completes a task, reference provides exact contracts,
+explanation builds understanding, and a runbook supports safe recovery. This
+avoids mixing an introductory story, an exhaustive flag list, and an
+incident procedure into one undifferentiated page. Preserve useful existing
+intent and improve the nearest appropriate page instead of creating a
+parallel documentation surface.
+
+**Expected output:** Evidence-backed Markdown with clear prerequisites,
+steps, expected results, verification, and relevant links. Risky operations
+need recovery or rollback guidance when the sources establish it. Unknown
+ownership, commands, endpoints, or compatibility guarantees remain explicit
+questions rather than invented facts. The handoff identifies changed files,
+sources inspected, checks run, and remaining uncertainty.
+
+**What it does without asking:** It edits the documentation files your
+request covers and can run the repository's documented docs checks. Its
+workflow has no commit, push, or pull-request step.
+
+**Next step:** Run the target repository's documented checks and resolve
+owner-review gaps before sharing. Use [oat-docs-authoring](#oat-docs-authoring)
+when the target also needs OAT placement and navigation conventions.
+
+## oat-docs
+
+**Invocation:** `/oat-docs "How do I choose between a quick and lite project?"`.
+If you provide no question, the skill asks what you want to understand.
+
+**Prerequisites:** Installed bundled OAT documentation under `~/.oat/docs/`
+(install it with `oat init tools core`). No active project is required. If that documentation is missing, the skill
+stops with installation guidance rather than substituting a repository
+checkout that may describe a different release.
+
+**Example scenario:** You are about to plan a small maintenance change and
+want to understand the artifacts and approval boundary of each workflow.
+Ask the skill to explain the choices from the installed documentation before
+starting a project or changing configuration.
+
+**Expected output:** A documentation-backed answer with practical examples
+and pointers to relevant bundled pages. The skill searches and reads the
+actual documentation rather than answering only from remembered behavior.
+It can offer a related setup action or skill, but does not execute that offer
+without confirmation.
+
+**What it does without asking:** Nothing beyond reading. It is a read-only
+question-and-answer skill: it creates or changes no files and runs no
+commands that change state.
+
+**Next step:** Choose the workflow or command that matches your task. If the
+answer suggests setup changes, confirm the exact action separately from the
+question-and-answer conversation.
+
+## oat-docs-authoring
+
+**Invocation:** Ask, “Use oat-docs-authoring to add a retry troubleshooting
+section to the existing imports guide and update its local map if needed.”
+The skill can also be invoked as `/oat-docs-authoring` with your task.
+
+**Prerequisites:** An existing OAT Markdown surface, OAT/Fumadocs app, or
+clearly identified target following OAT conventions, plus the installed
+`authoring-docs` baseline. No active OAT project is required. This is
+a targeted authoring or repair workflow, not bootstrap, a broad audit, or
+bulk application of an analysis report.
+
+**Example scenario:** One documented import error has a new recovery path.
+Update that guide from the actual implementation and tests without
+reorganizing unrelated sections or hand-editing generated sidebar files.
+
+The wrapper adds OAT-specific placement and navigation rules to universal
+authoring standards. Edit authored pages and relevant local `index.md`
+Contents maps together, preserve useful context and local instructions, and
+prefer `.md` unless the page needs JSX. For configured Markdown, use the
+literal content root and authored index, even if it contains a nested
+directory named `docs`; do not create an unnecessary app shell.
+
+**Expected output:** Focused authored-source changes, checked links and
+metadata, and any locally required generated-artifact refresh or freshness
+check. The handoff distinguishes checks actually run from checks unavailable
+or intentionally not applicable. Project-derived release documentation
+belongs in the project-document workflow, not this wrapper.
+
+**What it does without asking:** It edits the authored pages your task
+covers together with the nearest local `index.md` Contents map. When
+navigation changes, it regenerates or freshness-checks derived navigation
+files with the docs app's own scripts, and it runs local validation
+commands when they exist. Its workflow has no commit, push, or
+pull-request step.
+
+**Next step:** Review and validate the focused diff. For broader uncertainty
+about the surface, use [oat-docs-analyze](#oat-docs-analyze); for a new surface,
+use [oat-docs-bootstrap](#oat-docs-bootstrap).
+
+## oat-docs-bootstrap
+
+**Invocation:** `/oat-docs-bootstrap`, optionally with a target directory.
+The conversation chooses Markdown, Fumadocs, or MkDocs and confirms the
+destination before scaffolding or adoption. You do not need to remember the
+framework later: `oat docs nav sync` has no framework flag and detects MkDocs
+or Fumadocs on its own.
+
+**Prerequisites:** An initialized OAT repository with readable
+`.oat/config.json`, `.agents/`, and a runnable OAT CLI. An active project is
+optional: it may provide context for the walkthrough, but setup does not
+require one. The installed CLI must support the selected setup path.
+
+**Example scenario:** Your repository already has useful Markdown guides in
+`documentation/`, and the team wants OAT discovery and authoring guidance
+without a site runtime. Choose additive Markdown adoption, retain those
+guides, and then audit their metadata and local maps. Do not replace the tree
+with a docs app simply because one can be scaffolded.
+
+Preflight only reads. It checks declared documentation configuration before
+discovery and checks framework evidence before assuming a populated
+directory is plain Markdown. The skill then summarizes your choices and asks
+you to confirm them before it runs `oat docs init`. The two setup paths
+differ from that point on.
+
+**Plain Markdown path:** Use this when you want plain Markdown files and no
+site runtime. The skill collects a title, a dedicated repository-relative
+root, and an optional description. It asks no app or package questions and
+never installs dependencies, patches packages, starts a preview server, or
+builds a site. An existing plain tree needs an explicit choice: adopt and
+audit, audit only, or abort. A non-interactive `--yes` alone is not
+permission to adopt. Adoption keeps existing files byte for byte and adds
+only missing baseline files; a fresh setup creates an authored `index.md`
+and `contributing.md` in the root you chose. Missing content conformity
+becomes audit work rather than silent repair. Verification checks files,
+configuration, and links.
+
+**Fumadocs or MkDocs path:** Use this when you want a built documentation
+site. The skill gathers app inputs (the visible site title and the package
+name are different inputs), probes which capabilities the installed CLI
+supports, runs the scaffold, and applies only the relevant post-patches (the
+skill's labeled fixes for known gaps in the CLI's scaffold output).
+Verification installs dependencies and runs a build. If a docs app already
+exists, you choose how to resolve the conflict, and one of the choices,
+`replace`, deletes the existing app.
+
+**What it does without asking:** After you confirm your inputs, bootstrap
+runs `oat docs init`, which writes the `documentation` section of
+`.oat/config.json` and adds or updates a managed `## Documentation` section
+in the root `AGENTS.md`. This happens on both paths. On the Fumadocs or
+MkDocs path it also scaffolds the app, applies post-patches, installs
+dependencies, runs a build, and may patch the root `package.json` so the
+default build leaves the docs app out. It may also write an `AGENTS.md`
+inside the new app when the CLI did not create one. Only after you confirm:
+the `replace` choice deletes the existing docs app directory and clears its
+`documentation` config and root `AGENTS.md` section (it refuses only when
+that directory has uncommitted changes); answering yes to the
+project-completion prompt writes `documentation.requireForProjectCompletion`
+to `.oat/config.json`; and accepting the optional content kickoff at the end
+runs analyze and then apply, which creates a branch and a commit and can
+open a pull request.
+
+**Expected output:** A verified fresh setup or additive adoption, followed
+by a walkthrough of actual configuration, authored indexes, page metadata,
+and contribution conventions. Markdown keeps its configured index authored;
+an optional generated inventory needs an explicit destination outside the
+configured content tree and never replaces it. A dry-run is only a preview.
+A partial result can have created files while still requiring manual
+guidance work; report that state rather than claiming complete bootstrap.
+Optional completion enforcement is an explicit choice, not a hidden side
+effect of initialization.
+
+**Next step:** Bootstrap ends by offering
+[oat-docs-analyze](#oat-docs-analyze) against the configured root, followed
+by [oat-docs-apply](#oat-docs-apply) for repairs you approve. An adopted tree
+needs this audit. Use `oat-project-document` for updates derived from an OAT
+project. For later one-off pages, use
+[oat-docs-authoring](#oat-docs-authoring).
+
+## oat-docs-analyze
+
+**Invocation:** `/oat-docs-analyze` (no arguments). The skill resolves the
+docs surface itself: the configured `documentation.root` and `tooling` in
+`.oat/config.json` first, then framework evidence, then a generic `docs/`
+tree or root Markdown files. It does not rely on a guessed root when the
+repository already declares one.
+
+**Prerequisites:** A Git repository with a docs app, Markdown tree, or
+root-level documentation, and `jq` for tracking updates. No active project
+is required. Configured Markdown does not need an app package, generated
+manifest, or docs-root agent file to qualify for analysis.
+
+**Example scenario:** A team adopted an existing Markdown tree, but users
+still cannot find several supported CLI operations. Analyze the literal
+configured root against command definitions, examples, and local maps so
+the report identifies which capability needs which page or section, rather
+than prescribing a new framework as the fix.
+
+The skill inventories content, checks index-contract coverage, verifies
+substantive claims against repository sources, finds missing or thin
+capability coverage, and checks navigation and drift. A usable finding names
+the evidence, severity, proposed location, and concrete subtopics. Ownership
+or operational claims that local sources cannot establish become
+owner-review gaps, not confident invented instructions.
+
+Existing tracking selects full or delta analysis when its recorded commit
+is valid. The workflow is read-only toward docs and navigation; it writes
+and may correct its own report, then updates analysis tracking. Generated
+navigation is freshness-checked, not repaired during the audit.
+
+**Expected output:** A timestamped `.oat/repo/analysis/docs-*.md` report with
+evidence, confidence, and disclosure decisions, including concrete targets
+for link-only recommendations. By default, a bounded auto artifact-review
+loop checks the report before tracking and handoff. A disabled loop or
+residual findings must remain disclosed; a report's existence alone does
+not mean every recommendation is verified or approved.
+
+**What it does without asking:** It writes the analysis artifact
+`.oat/repo/analysis/docs-<timestamp>.md`, lets its review loop correct that
+report, and then updates its tracking record in `.oat/tracking.json` (used
+to choose a full or delta analysis next time). It does not edit
+documentation pages, navigation files, or `mkdocs.yml`, and it creates no
+branch or commit.
+
+**Next step:** Review the findings and run [oat-docs-apply](#oat-docs-apply)
+for selected recommendations. If evidence or target information is missing,
+repair the analysis contract rather than asking apply to fill it in.
+
+## oat-docs-apply
+
+**Invocation:** `/oat-docs-apply` after reviewing a docs analysis report.
+The skill loads the newest `.oat/repo/analysis/docs-*.md` report. You cannot
+select an older one, so rerun analysis if the newest report is not the one
+you reviewed. It then builds a recommendation plan and asks you to choose
+`apply all`, `apply interactively` (approve, modify, or skip each item), or
+`discuss` before changing anything.
+
+**Prerequisites:** A recent, complete docs analysis artifact and an unchanged
+compatible target. Recommendations need evidence, confidence, disclosure,
+and concrete link targets where applicable. Apply also needs `jq` for
+tracking updates, and `gh` only if you want it to open the pull request. No
+active OAT project is required. Missing analysis or a changed target requires a fresh analysis,
+not conventions invented during apply.
+
+**Example scenario:** The audit found three CLI pages missing from their
+`## Contents` maps, an inaccurate
+example, and a proposed reorganization. Approve only the page listings and
+example correction, leaving the reorganization for discussion. Apply should
+execute those selected actions without broadening the work to every finding.
+
+**Expected output:** Approved changes committed on a new
+`oat/docs-<timestamp>` branch, relevant source/link checks, and declared
+navigation or generated-artifact refreshes. Markdown retains its authored
+index and needs no framework build or nav sync; Fumadocs sidebar metadata is
+regenerated from approved Contents changes, never hand-edited. The summary
+reports the applied plan and checks.
+
+**What it does without asking:** Nothing changes until you approve the plan.
+After you approve it, apply continues without asking again. It creates
+branch `oat/docs-<timestamp>` from your current HEAD and edits only the
+approved files. Items whose disclosure is `ask_user` are confirmed with you
+once more before they are written. For a Fumadocs or MkDocs app it runs
+the verification that fits what changed, such as `oat docs nav sync` and
+the app's existing docs lint, format-check, and build scripts. It then
+commits the changes as `docs: apply approved docs recommendations`. If the
+branch cannot be created (for example because of local changes), it stops
+and asks you to resolve that first. After committing, it asks whether to
+push the branch and open a pull request; only a yes pushes. The PR targets
+`main`, and its body includes the applied plan and the full analysis
+report, so check the report for anything you would not publish. Finally it
+updates `.oat/tracking.json`.
+
+**Next step:** Review the committed diff before you agree to push or open a
+pull request. Rerun analysis if you need a post-apply assessment, and treat
+unapproved recommendations as remaining decisions rather than completed
+work.
+
 ## Related docs
 
 - [`commands.md`](commands.md)
 - [`add-docs-to-a-repo.md`](add-docs-to-a-repo.md)
+- [Improve Agent Instructions](agent-instructions.md)
 - [`../reference/docs-index-contract.md`](../reference/docs-index-contract.md)
 - [`../contributing/skills.md`](../contributing/skills.md)

package/assets/docs/{cli-utilities → getting-started}/bootstrap.md

@@ -46,7 +46,7 @@ After core initialization completes, `oat init` can enter an interactive guided
 1. **Tool packs** — install OAT tool packs. The core pack (diagnostics, passive docs access) is checked by default and always installs at user scope. Guided setup asks whether to customize per-pack scope:
    - choose **Yes** to run the per-pack scope selector for every pack that allows both scopes (`ideas`, `docs`, `workflows`, `utility`, `project-management`, `research`, `brainstorm`)
    - choose **No** to apply additive per-pack defaults without extra scope prompts
-   - on a fresh install every pack defaults to **user** scope, so capabilities follow you across repositories; an existing install keeps its current placement
+   - on a fresh install every pack defaults to **user** scope, so capabilities follow you across repositories; an existing install keeps its current placement. See [Where tool packs install](#where-tool-packs-install) below
    - after placement is chosen, repository `AGENTS.md` guidance is a separate opt-in. Accepting creates the root file with the managed `OAT tools` section when it is absent, and appends that section to an existing file or contained symlink target that lacks it, with one append-only write. An existing file is never replaced: when the section exists but differs, OAT prints a repository-relative, copy-pasteable managed-block patch instead. Declining leaves `AGENTS.md` unchanged
    - installing `project-management` installs the capability only. Adopting it for this repository is a third, separate choice made with `oat pjm init` — see [Install vs. initialize](tool-packs.md#install-vs-initialize)
 2. **Local paths** — multi-select from default gitignored artifact paths (analysis, PR, reviews, ideas). Pre-existing paths are pre-checked; only new paths are added.
@@ -59,6 +59,28 @@ Hook install note:
 - The optional OAT pre-commit hook installs into Git's active hook directory.
 - If a repo uses a managed hook folder such as `.githooks/`, that path must already be configured in Git, or OAT must configure it during the prompt flow before hook install.
 
+What the hook does: before each commit it runs
+`oat status --scope project --hook`, which checks whether the provider views in
+this repository match their canonical sources. If views are out of date or
+missing, it prints `oat: managed provider views are out of sync - run 'oat sync --scope project'`.
+If it finds provider files that OAT does not manage, it prints a note to run
+`oat status --scope project`. The hook only warns: it never blocks a commit,
+because the hook line ends in `|| true`, and it does nothing when `oat` is not
+on your `PATH`. OAT adds its lines between `# >>> oat pre-commit hook >>>` and
+`# <<< oat pre-commit hook <<<` markers, appending them to an existing
+`pre-commit` file rather than replacing it. In Git's default hook directory
+(`.git/hooks/`) the hook belongs to your clone only and is not committed.
+
+To remove the hook, run `oat init --scope project --no-hook` in the
+repository. (Without `--scope project`, `oat init` uses scope `all` and also
+writes under your home directory.) Although its
+help text reads "Skip optional pre-commit hook install", the flag also removes
+an OAT hook that is already installed. It deletes only the marked OAT block
+and keeps any other hook content; if the file contained nothing but the OAT
+block, the file is deleted (or emptied, when it is a symlink). You can also
+delete the lines between the two markers by hand. To install the hook later
+without prompts, run `oat init --scope project --hook`.
+
 **Non-interactive mode:** Fresh-init guided setup offers are interactive-only. If `--setup` is passed in non-interactive mode (`--json`, piped input, non-TTY, or `OAT_NON_INTERACTIVE=1`), guided setup does not prompt: tool packs use additive defaults, local-path and documentation prompts are skipped unless already configured, and provider sync is skipped unless separately requested. Repository guidance also defaults to no write; pass `--project-guidance` to opt in explicitly or `--no-project-guidance` to record an explicit decline.
 
 ```bash
@@ -75,9 +97,42 @@ oat init --project-guidance
 oat init --scope project
 ```
 
+### Where tool packs install
+
+Guided setup uses the same per-pack defaults as `oat tools install`, with one
+difference described at the end of this section. The `--scope` option of `oat tools install` and `oat tools remove` lists `all` as
+its default in `--help`. For `oat tools install`, that default does not mean
+both scopes:
+
+- With no `--scope`, a pack that is not installed yet is installed under your
+  home directory (user scope: `~/.agents/` and `~/.oat/`). A pack that is
+  already installed keeps the scope it has.
+- With `--scope project`, the pack is installed in this repository
+  (`.agents/` and `.oat/`). With `--scope user`, it is installed under your
+  home directory.
+
+The `core` pack can only live under your home directory:
+
+- `oat tools install --scope project`, with no pack name, installs the other
+  seven packs in this repository and still installs `core` under your home
+  directory.
+- `oat tools install core --scope project` exits successfully and prints
+  `Installed core tool pack.`, but it writes nothing, neither in the
+  repository nor in your home directory.
+- `oat tools remove --all --scope project` fails with
+  `Pack core does not allow project scope`, and so does
+  `oat tools remove --all` with no `--scope`.
+
+The difference: guided setup does not take its pack scope from `--scope`.
+`oat init --scope project --setup`, run without an interactive terminal,
+installed all eight packs under the home directory. In an interactive
+terminal, answer **Yes** to the per-pack scope question to choose project
+scope, or install packs afterwards with `oat tools install <pack> --scope project`. See [Where packs install](tool-packs.md#where-packs-install) for
+the full rules and how to remove packs.
+
 Related commands:
 
-- `oat tools ...` (tool-pack install, update, remove, migrate, list, info): `tool-packs.md`
-- `oat pjm init` (adopt project management for this repository): `tool-packs.md#install-vs-initialize`
-- `oat local ...`, `oat doctor`, and other utility commands: `config-and-local-state.md`
-- `oat status` / `oat sync` (provider sync): `../provider-sync/index.md`
+- `oat tools ...` (tool-pack install, update, remove, migrate, list, info): [Tool Packs and Installed Assets](tool-packs.md)
+- `oat pjm init` (adopt project management for this repository): [Install vs. initialize](tool-packs.md#install-vs-initialize)
+- `oat local ...`, `oat doctor`, and other utility commands: [Config and Local State](../reference/config-and-local-state.md)
+- `oat status` / `oat sync` (provider sync): [Provider Sync](../provider-sync/index.md)

package/assets/docs/getting-started/concepts.md

@@ -0,0 +1,120 @@
+---
+title: Core Concepts
+description: Mental model for canonical assets, provider views, scopes, skills, and the optional workflow layer.
+---
+
+# Core Concepts
+
+OAT combines a provider-sync layer, reusable skills and CLI tooling, and an optional workflow system. This page gives the high-level mental model so the detailed docs are easier to navigate.
+
+## Choose What to Adopt
+
+=== "Diagram"
+
+    ![Four independent starting points: align coding tools with Provider Sync, help with one task with reusable skills, resume longer work with workflows, or maintain documentation; add another path whenever useful](/diagrams/adoption-paths-light.svg)
+    ![Four independent starting points: align coding tools with Provider Sync, help with one task with reusable skills, resume longer work with workflows, or maintain documentation; add another path whenever useful](/diagrams/adoption-paths-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      GOAL["What do you\nneed first?"] --> SYNC["Align coding tools\nProvider Sync"]
+      GOAL --> SKILLS["Help with one task\nReusable Skills"]
+      GOAL --> WORK["Resume longer work\nWorkflows"]
+      GOAL --> DOCS["Maintain documentation\nMarkdown or a docs site"]
+      SYNC -.-> LATER["Add another path\nwhenever useful"]
+      SKILLS -.-> LATER
+      WORK -.-> LATER
+      DOCS -.-> LATER
+    ```
+
+- **Provider Sync:** `oat init --scope project`, choose providers, then `oat sync --scope project`.
+- **Reusable skills:** `oat tools install --scope user`; no repository initialization is needed.
+- **Tracked workflows:** `oat init --scope project`, `oat tools install workflows --scope project`, then `/oat-project-quick-start`.
+- **Documentation:** `oat init --scope project`, `oat tools install docs --scope project`, then `/oat-docs-bootstrap` for plain Markdown or a docs site.
+
+Choose a starting point, not a required sequence. Use provider sync to align coding tools, install reusable skills for individual tasks, add tracked workflows for longer work, or maintain plain Markdown or a docs site with Docs Tooling. You can combine these paths later.
+
+Commands below the diagram run in a terminal; `/name` denotes an agent skill (`$name` in Codex). Pack installation has its own scope: project scope targets repository assets, but the core pack is user-only when installed. Skip guided pack setup if you only want provider sync. New tracked projects default to synced storage and need an `origin` remote; choose local project storage for origin-free work.
+
+Continue with [Provider Sync](../provider-sync/index.md), [Tool Packs](tool-packs.md), [Choose a Workflow](../workflows/choose-workflow.md), or [Docs Tooling](../docs-tooling/index.md).
+
+## Canonical Assets and Provider Views
+
+OAT keeps canonical assets in repo-controlled locations and projects provider-specific views from that source of truth. The canonical form is what you edit and review directly; provider views are synchronized outputs that let Claude Code, Cursor, Copilot, Gemini, and Codex consume the same intent in their native layouts.
+
+=== "Diagram"
+
+    ![Canonical skills, agents and rules in .agents/ flow through oat sync into provider views under .claude/, .cursor/, .github/ and .codex/](/diagrams/provider-views-light.svg)
+    ![Canonical skills, agents and rules in .agents/ flow through oat sync into provider views under .claude/, .cursor/, .github/ and .codex/](/diagrams/provider-views-dark.svg)
+
+=== "Mermaid source"
+
+    ```mermaid
+    flowchart LR
+      SKILLS[".agents/skills/"] --> OAT["oat sync"]
+      AGENTS[".agents/agents/"] --> OAT
+      RULES[".agents/rules/"] --> OAT
+      OAT --> CLAUDE[".claude/"]
+      OAT --> CURSOR[".cursor/"]
+      OAT --> COPILOT[".github/"]
+      OAT --> CODEX[".codex/"]
+    ```
+
+Gemini CLI is a native read-only consumer; OAT does not generate a `.gemini/` view through sync.
+
+Use these docs next:
+
+- [Provider Sync](../provider-sync/index.md)
+- [Reference](../reference/index.md)
+
+## Sync, Drift, and Adoption
+
+`oat sync` applies canonical content to provider views, while `oat status` reports whether a provider is in sync, drifted, or missing content. Drift is expected when provider-side files diverge from canonical content; OAT now also covers canonical rule sync and stray adoption so you can bring unmanaged files back under the canonical model deliberately.
+
+Use these docs next:
+
+- [Provider Sync Commands](../provider-sync/commands.md)
+- [Manifest and Drift](../provider-sync/manifest-and-drift.md)
+
+## Scopes
+
+Most OAT operations run in one of three scopes: `project`, `user`, or `all`. Project scope targets the current repository, user scope targets user-level installations, and `all` evaluates both. The same scope model appears across sync, status, and provider configuration commands, so it is worth learning early.
+
+Use these docs next:
+
+- [Scope and Surface](../provider-sync/scope-and-surface.md)
+- [CLI Reference](../reference/cli-reference.md)
+
+## Skills and CLI Commands
+
+Skills are structured workflow instructions stored in `.agents/skills`, while CLI commands provide direct operational entry points like `oat init`, `oat sync`, or `oat docs init`. Some capabilities are primarily CLI-driven, some are primarily skill-driven, and some combine both. As a rule: use the CLI for direct system actions and use skills when you want guided lifecycle execution.
+
+Use these docs next:
+
+- [Skills](../skills/index.md)
+- [Contributing Skills](../contributing/skills.md)
+
+## The Three Usage Modes
+
+OAT offers three capabilities you can use independently:
+
+1. Provider sync and CLI interop only
+2. Provider-agnostic tooling and reusable skills
+3. Optional workflow/project lifecycle
+
+These are choices, not required adoption stages. Use only interoperability, install task-oriented skills, or adopt the lifecycle when you need tracked discovery, planning, implementation, review, and PR flow.
+
+Use these docs next:
+
+- [Quickstart](quickstart.md)
+- [Workflow & Projects](../workflows/projects/index.md)
+
+## Human-in-the-Loop Lifecycle
+
+The workflow system supports explicit checkpoints so a project can pause at selected moments for approval or direction. At the workflow level, HiLL gates control lifecycle routing across discovery, spec, design, plan, and implementation. During implementation, plan-phase checkpoints control where execution pauses between plan phases.
+
+Use these docs next:
+
+- [Workflow & Projects](../workflows/projects/index.md)
+- [Hill Checkpoints](../workflows/projects/planning/hill-checkpoints.md)

package/assets/docs/getting-started/index.md

@@ -0,0 +1,68 @@
+---
+title: Getting Started
+description: 'Install OAT, get a first result in an existing repository, and learn the ideas the rest of the docs use.'
+---
+
+# Getting Started
+
+Open Agent Toolkit (OAT) is a command-line tool and a library of skills
+(instructions your coding agent follows on request) for teams that use more
+than one AI coding tool, or want more structure in how they use one. You keep
+one copy of each skill, agent and rule in your repository, and OAT creates and
+checks the copies each tool reads; when you want it, OAT also adds tracked
+workflows with plans, reviews and human approval points. Start with
+[Quickstart](quickstart.md): it installs the CLI and gives you a first result
+that changes files only inside one repository.
+
+## Contents
+
+- [Quickstart](quickstart.md) - Install the CLI, try it in an existing repository, and choose what to add next.
+- [Core Concepts](concepts.md) - The ideas the rest of the docs rely on: canonical assets, provider views, scopes, skills and the workflow lifecycle.
+- [CLI Bootstrap](bootstrap.md) - What `oat init` sets up in a repository, and the guided setup it offers.
+- [Tool Packs and Installed Assets](tool-packs.md) - The bundled tool packs, where they install, and how to update or remove them.
+
+## Project status
+
+- **Version:** the CLI is published on npm as `@open-agent-toolkit/cli` and is
+  versioned 0.x, that is, before a 1.0 release.
+- **License:** MIT.
+- **Releases:** each version is published on the repository's
+  [GitHub Releases page](https://github.com/voxmedia/open-agent-toolkit/releases)
+  with release notes and the list of merged changes.
+- **Issues:** report problems and requests on the
+  [issue tracker](https://github.com/voxmedia/open-agent-toolkit/issues).
+- **Upgrading:** before you update, read
+  [Upgrading from an earlier CLI](tool-packs.md#upgrading-from-an-earlier-cli),
+  which lists defaults and exit codes that changed between releases.
+
+## Known limits
+
+These limits are documented on the pages linked from each item. A provider
+is a coding agent tool such as Claude Code, Cursor or Codex, and a provider
+view is the file or link that tool reads.
+
+- **Cursor model choice is not verified.** When OAT launches an agent in
+  Cursor, Cursor can run a different model from the one OAT pinned, without an
+  error, and OAT records only the model it requested. See
+  [How each provider applies the cap](../workflows/advanced/dispatch-ceiling.md#how-each-provider-applies-the-cap).
+- **Edits in provider folders are overwritten.** Re-running `oat sync` rewrites
+  provider views from their source in `.agents/`, so an edit made directly in a
+  provider folder such as `.claude/` is lost, and a file you placed at a view's
+  path yourself is replaced. See
+  [Manifest and Drift](../provider-sync/manifest-and-drift.md#quick-look).
+- **The default reviewer independence can fall back.** A review gate's default
+  setting prefers a reviewer from a different model family, but when none is
+  available it falls back to the best available reviewer, which can be from the
+  same family, and only records a warning. See
+  [How independent the reviewer must be](../workflows/advanced/workflow-gates.md#how-independent-the-reviewer-must-be).
+- **Re-running `oat pjm init` removes remote settings.** It replaces the `pjm`
+  section of `.oat/config.json` and deletes any `pjm.remote` settings, so back
+  the file up first. See
+  [Remote Project Management](../workflows/backlog-and-planning/remote-project-management.md#prerequisite).
+- **Ad-hoc reviews run in the agent you invoke them in.** `oat-review-provide`
+  cannot send a review to a different model; to get another model's review,
+  run the skill in that model's coding tool. See
+  [oat-review-provide](../workflows/projects/reviews/review-flavors.md#oat-review-provide).
+- **Gemini CLI gets no generated view.** OAT treats Gemini CLI as a native
+  read-only consumer, and sync does not generate a `.gemini/` view for it. See
+  [Canonical Assets and Provider Views](concepts.md#canonical-assets-and-provider-views).

package/assets/docs/getting-started/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Getting Started",
+  "pages": ["quickstart", "concepts", "bootstrap", "tool-packs"]
+}