@open-agent-toolkit/cli 0.3.13 → 0.3.14

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,44 @@ skills.
 
 ## Typical flow
 
+Diagram: bootstrap once, then analyze, approve and apply only agreed improvements.
+
+```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 +139,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/{guide → getting-started}/concepts.md

@@ -7,14 +7,31 @@ description: Mental model for canonical assets, provider views, scopes, skills,
 
 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.
 
-## Capability Stack
+## Choose What to Adopt
 
 ```mermaid
-flowchart TD
-  BASE["Provider sync + CLI\ncanonical assets, status, sync, docs commands"] --> MIDDLE["Reusable skills + tooling\nideas, docs workflows, repo helpers"]
-  MIDDLE --> TOP["Optional workflow layer\ntracked projects, reviews, PR flow, HiLL"]
+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.
@@ -27,10 +44,11 @@ flowchart LR
   OAT --> CLAUDE[".claude/"]
   OAT --> CURSOR[".cursor/"]
   OAT --> COPILOT[".github/"]
-  OAT --> GEMINI[".gemini/"]
   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)
@@ -60,22 +78,22 @@ Skills are structured workflow instructions stored in `.agents/skills`, while CL
 
 Use these docs next:
 
-- [Skills](../workflows/skills/index.md)
+- [Skills](../skills/index.md)
 - [Contributing Skills](../contributing/skills.md)
 
 ## The Three Usage Modes
 
-OAT can be adopted in three layers:
+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 layers stack. You can stay at the interop layer, use only the tooling layer, or adopt the full lifecycle when you need tracked discovery, planning, implementation, review, and PR flow.
+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)
+- [Quickstart](quickstart.md)
 - [Workflow & Projects](../workflows/projects/index.md)
 
 ## Human-in-the-Loop Lifecycle
@@ -85,4 +103,4 @@ The workflow system supports explicit checkpoints so a project can pause at sele
 Use these docs next:
 
 - [Workflow & Projects](../workflows/projects/index.md)
-- [Hill Checkpoints](../workflows/projects/hill-checkpoints.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"]
+}