@open-agent-toolkit/cli 0.3.23 → 0.3.24

package/assets/skills/authoring-docs/references/templates.md

@@ -547,3 +547,57 @@ docs/
 
 - <Explicitly out-of-scope docs>
 ```
+
+## IA Proposal
+
+Use for bootstrap or an existing-tree `--ia` analysis. This proposes structure;
+it neither persists an IA decision nor materializes a preset. Feature and QA
+validation page templates are not included; use the page-type guidance to
+plan their content.
+
+````markdown
+# IA Proposal: {surface}
+
+## Evidence and guidance
+
+- Resolved sources, in order: {path/URL, provenance: explicit/conversation/shared/user/builtin}
+- Local authority: {AGENTS/contributing paths and relevant rules}
+- Repo signals: {manifests, navigators, bin, routers, IaC, e2e, docs, units}
+- Readers and work contexts: {who must succeed at what}
+- Entry key per track: {task/domain/capability/unit/command/page type}
+- Page purposes: {one primary job per representative page}
+- Verification overlay: {triad/agent-only/none and evidence}
+- Size gate: {page count and amount of structure justified}
+- Canonical facts elsewhere and links to preserve: {paths/URLs}
+- Unresolved conflicts: {ask_user finding with source citations, or none}
+
+## Candidate A: {reader-facing name}
+
+Nearest preset: {approved label}. Choose when: {signals and tradeoffs}.
+
+```text
+{track-or-section}/
+  {page.md} — {page's one job}
+  {page.md} — {page's one job}
+{track-or-section}/
+  {page.md} — {page's one job}
+  {page.md} — {page's one job}
+  {page.md} — {page's one job}
+```
+
+Use a two-level tree and 5–8 representative page placements. For Flat Small,
+first-level labels are grouped headings in one index, not new directories.
+
+## Candidate B: {alternative reader-facing name}
+
+Nearest preset: {approved label}. Choose when: {different plausible signals}.
+
+{Second two-level tree with 5–8 representative page placements and page jobs.}
+
+## Recommendation and open decisions
+
+{Preferred candidate, evidence and tradeoffs. Ask only decision-changing
+questions. Record an explicit choice before replacement or a second app.
+Existing docs default to analyze → apply of approved recommendations.
+No private exemplar text, copied external contents or unapproved moves.}
+````

package/assets/skills/authoring-docs/references/workflow.md

@@ -80,7 +80,12 @@ Most docs serve one or more of these readers:
 - support engineer
 - AI agent making future changes
 
-Write pages for actual tasks, not org-chart abstractions.
+Map personas to tracks by work context: consumers and CLI/API users usually
+enter through tasks or contracts; maintainers through domains and operations;
+product stakeholders through behavior; independent QA through validation;
+agents through exact task inputs and checks. One person may use several tracks.
+Use the five axes in [Information Architecture](information-architecture.md)
+before naming a preset. Write pages for actual tasks, not org-chart abstractions.
 
 ## 5. Decide the Minimum Useful Set
 

package/assets/skills/authoring-docs/references/writing-style.md

@@ -93,7 +93,7 @@ Use notes for useful context, not ordinary tips.
 - Use one `#` heading per page.
 - Do not skip heading levels.
 - Use fenced code blocks with language identifiers.
-- Use `sh` for shell commands.
+- Use `bash` for shell commands unless the example is POSIX-only (`sh`) or local repository conventions require another fence.
 - Use `txt` for command output.
 - Do not include shell prompts unless the prompt itself matters.
 - Use angle brackets for placeholders, such as `<environment>`.

package/assets/skills/authoring-docs/scripts/resolve-guidance.mjs

@@ -0,0 +1,53 @@
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+
+// Select inputs only. The consuming skill reads Markdown and checks Contents,
+// local authority and conflicts; this helper never fetches or writes a source.
+const { values } = parseArgs({
+  options: {
+    builtin: { type: 'string' },
+    'ia-guidance': { type: 'string', multiple: true },
+    'conversation-guidance': { type: 'string', multiple: true },
+  },
+});
+const explicit = values['ia-guidance'];
+const conversation = values['conversation-guidance'];
+if (explicit && conversation) {
+  throw new Error(
+    'Use one explicit source list; reconcile argument/conversation disagreement with the user first.',
+  );
+}
+const input = JSON.parse(readFileSync(0, 'utf8'));
+if (input.status !== 'ok' || input.key !== 'documentation.guidance') {
+  throw new Error(
+    'Expected successful oat config get documentation.guidance --json output.',
+  );
+}
+let locations;
+let source;
+if (explicit || conversation) {
+  locations = explicit ?? conversation;
+  source = explicit ? 'explicit' : 'conversation';
+} else if (input.value !== null && input.value !== undefined) {
+  if (!['shared', 'user'].includes(input.source)) {
+    throw new Error(
+      `Unsupported documentation.guidance config source: ${input.source}`,
+    );
+  }
+  locations = Array.isArray(input.value) ? input.value : [input.value];
+  source = input.source;
+} else {
+  locations = [values.builtin];
+  source = 'builtin';
+}
+if (
+  !locations.length ||
+  locations.some((location) => typeof location !== 'string' || !location.trim())
+) {
+  throw new Error(
+    'Guidance requires non-empty path/URL strings (or --builtin for fallback).',
+  );
+}
+process.stdout.write(
+  `${JSON.stringify({ sources: locations.map((location) => ({ location: location.trim(), source })) }, null, 2)}\n`,
+);

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

@@ -1,11 +1,12 @@
 ---
 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.
+argument-hint: '[target] [--ia] [--ia-guidance <path|url>]'
 disable-model-invocation: true
 user-invocable: true
-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
+allowed-tools: Read, Write, Bash(git:*), Bash(oat config:*), Bash(oat docs nav sync --check:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(node:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: '1.6.3'
+  version: '1.7.0'
 ---
 
 # Docs Analysis
@@ -85,6 +86,38 @@ When executing this skill, provide lightweight progress feedback so the user can
 
 ## Process
 
+### Shared authoring method and optional IA proposal
+
+Independently probe each exact `authoring-docs/SKILL.md` in order:
+`${SKILL_DIR}/..` from the loaded skill (`SKILL_DIR` is the absolute directory
+containing that loaded `SKILL.md`), `${HOME}/.agents/skills`, then
+`<repo-root>/.agents/skills`. Bind the first matching `authoring-docs` directory
+once as `AUTHORING_DOCS_ROOT`; load `${AUTHORING_DOCS_ROOT}/SKILL.md` and use
+that same root for every authoring-docs reference and script, never ambient
+discovery. If none is found, name `authoring-docs`, stop this handoff, and give
+the intended-scope recovery command: `oat tools install docs --scope <user|project>`
+or `oat tools update --pack docs --scope <user|project>`.
+
+Always use its landing-page contract, section entries and one-purpose-per-page
+rule for the quality pass even without `--ia`. For IA work, read
+`${AUTHORING_DOCS_ROOT}/references/guidance-sources.md` and use the source-aware config-get
+interface/helper: explicit `--ia-guidance` or conversation → repo → user →
+built-in. Preserve selected source order and cite locators/provenance in the
+analysis artifact. External Markdown packs require `index.md` and `## Contents`;
+non-repo inputs stay read-only and private contents never enter the artifact.
+
+`--ia` is a skill argument, not a CLI docs command. It adds the shared IA Proposal
+to the **same analysis artifact and existing artifact-review loop**. Read manifests,
+UI navigators/journeys, CLI `bin`, routers, IaC, `e2e/`/`.maestro/`, existing docs
+and independent monorepo units. Ask only decision-changing questions about reader
+work contexts, independent verification, canonical facts and link survival.
+Use the five axes before presets and show two plausible two-level trees with
+5–8 representative page placements each, page jobs, nearest approved presets
+and tradeoffs. A UI alone does not justify Product/Engineering/QA; size chooses
+depth, not audience. For an existing tree respect AGENTS/contributing authority;
+conflicts are `ask_user`, with both source citations. Propose only: no IA
+persistence, restructure action or scaffold materialization in this stage.
+
 ### Step 0: Resolve Docs Target and Analysis Mode
 
 Determine the documentation root using explicit docs-app evidence before generic
@@ -267,8 +300,8 @@ For each evaluated page or directory:
    syntax intentionally shown inside inline code, fenced examples, or template
    snippets.
 4. Check Markdown hygiene: opening code fences need language identifiers; shell
-   examples should follow local fence conventions, defaulting to `sh` unless
-   local guidance uses `bash` or the block needs Bash-only syntax.
+   examples should follow local fence conventions, defaulting to `bash` unless
+   the example is POSIX-only (`sh`) or local guidance requires another fence.
 5. Flag empty headings, multiple document-level H1s outside intentional imported
    README contexts, overlong frontmatter descriptions when local guidance
    defines a limit, ellipsis-truncated descriptions, and README-copy metadata

package/assets/skills/oat-docs-analyze/references/analysis-artifact-template.md

@@ -15,6 +15,18 @@ oat_analysis_commit: { commitHash }
 **Surface Type:** {mkdocs-app|oat-fumadocs-app|docs-tree|root-markdown}
 **Commit:** {short-hash}
 
+## IA guidance and proposal
+
+- Selected sources in order: {locator + explicit/conversation/shared/user/builtin provenance}
+- Resolved index entries: {entry paths/URLs; external Markdown has index.md + Contents}
+- Local authority: {AGENTS/contributing source citations}
+- Conflicts/unreadable sources: {ask_user with both citations, or none}
+- IA proposal: {when --ia, embed the shared authoring-docs IA Proposal template:
+  two two-level trees, 5–8 placements each, page jobs, nearest approved presets,
+  evidence and tradeoffs; otherwise not requested}
+
+Do not copy private guidance contents or persist an IA decision from this report.
+
 ## Summary
 
 - **Files evaluated:** {N}

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 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.4'
+  version: '1.4.5'
 ---
 
 # Docs Apply
@@ -200,6 +200,24 @@ If branch creation fails because of unrelated local changes, ask the user to res
 
 ### Step 4: Apply Approved Changes
 
+Independently probe each exact `authoring-docs/SKILL.md` in order:
+`${SKILL_DIR}/..` from the loaded skill (`SKILL_DIR` is the absolute directory
+containing that loaded `SKILL.md`), `${HOME}/.agents/skills`, then
+`<repo-root>/.agents/skills`. Bind the first matching `authoring-docs` directory
+once as `AUTHORING_DOCS_ROOT`; load `${AUTHORING_DOCS_ROOT}/SKILL.md` and use
+that same root for every authoring-docs reference and script, never ambient
+discovery. If none is found, name `authoring-docs`, stop this handoff, and give
+the intended-scope recovery command: `oat tools install docs --scope <user|project>`
+or `oat tools update --pack docs --scope <user|project>`.
+
+Before content actions, use its page-purpose, landing, placement and five-axis IA
+method within the approved recommendation scope. Carry the analysis artifact's ordered guidance
+locators/provenance into the apply plan; do not silently re-resolve different
+sources. Verify cited inputs still exist and remain read-only outside the repo.
+Local AGENTS/contributing rules stay authoritative; a conflict is `ask_user`
+and blocks that recommendation pending a fresh analysis/user decision. Cite
+sources without copying private contents. This hook adds no restructure action.
+
 Before the first approved write, initialize `OWNED_OUTPUT_FILES=()`. Append
 each exact successfully created, modified or removed path at that write,
 including both names of a rename and any generated navigation/index file this

package/assets/skills/oat-docs-apply/references/apply-plan-template.md

@@ -12,6 +12,15 @@ oat_docs_target: { docs-target-path }
 **Source Analysis:** `{analysis-artifact-path}`
 **Docs Target:** `{docs-target-path}`
 
+## Guidance provenance
+
+- Analysis-selected IA sources, in order: {locators + provenance}
+- Local authority: {AGENTS/contributing citations}
+- Read-only sources verified: {resolved entries or blocked recommendation IDs}
+- Conflicts: {ask_user disposition or none}
+
+Keep the analysis selection; do not copy private contents or invent missing evidence.
+
 ## Instructions
 
 Review the full recommendation set first, then choose a review mode:

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

@@ -1,12 +1,12 @@
 ---
 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]'
+argument-hint: '[docs task or target path] [--ia-guidance <path|url>]'
 disable-model-invocation: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: '1.1.3'
+  version: '1.2.0'
 ---
 
 # OAT Docs Authoring
@@ -14,9 +14,8 @@ metadata:
 Use this skill for targeted documentation authoring and small structural edits
 inside an existing OAT Markdown surface or OAT/Fumadocs docs app.
 
-This is a thin wrapper over `authoring-docs`. Load `authoring-docs` for
-universal evidence gathering, page-type selection, writing style, templates,
-and review standards. Keep this wrapper focused on OAT Markdown/Fumadocs placement,
+This is a thin wrapper over `authoring-docs` for universal evidence gathering,
+page-type selection, writing style, templates, and review standards. Keep this wrapper focused on OAT Markdown/Fumadocs placement,
 navigation, generated artifacts, validation, and lifecycle boundaries.
 
 ## Prerequisites
@@ -111,9 +110,22 @@ Use `references/docs-root-resolution.md` before assuming any path. OAT docs apps
 commonly live outside `apps/oat-docs`, and `.oat/config.json` may describe the
 generated root index separately from the authored docs root.
 
-If the request needs universal documentation standards, load `authoring-docs`
-and use its reference map for evidence gathering, page type, writing style,
-templates, and review rubric.
+Independently probe each exact `authoring-docs/SKILL.md` in order:
+`${SKILL_DIR}/..` from the loaded skill (`SKILL_DIR` is the absolute directory
+containing that loaded `SKILL.md`), `${HOME}/.agents/skills`, then
+`<repo-root>/.agents/skills`. Bind the first matching `authoring-docs` directory
+once as `AUTHORING_DOCS_ROOT`; load `${AUTHORING_DOCS_ROOT}/SKILL.md` and use
+that same root for every authoring-docs reference and script, never ambient
+discovery. If none is found, name `authoring-docs`, stop this handoff, and give
+the intended-scope recovery command: `oat tools install docs --scope <user|project>`
+or `oat tools update --pack docs --scope <user|project>`.
+
+Use the bound skill's reference map for evidence gathering, page type, writing
+style, templates and review rubric. For IA work use its five-axis method and
+`${AUTHORING_DOCS_ROOT}/references/guidance-sources.md`: explicit `--ia-guidance` or
+conversation → repo config → user config → built-in. Cite ordered source
+locators/provenance in the handoff; respect AGENTS/contributing authority,
+keep non-repo sources read-only and report conflicts as `ask_user`.
 
 ### Step 2: Inspect Evidence and Local Maps
 

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

@@ -1,12 +1,12 @@
 ---
 name: oat-docs-bootstrap
 description: Use when bootstrapping or adopting an OAT documentation surface in a repo. Guides the user through preflight detection, richer input gathering than the raw CLI, `oat docs init` invocation with gated post-patches for open CLI gaps, build verification, post-scaffold config inspection, and an educational walkthrough. Supports plain Markdown (file-level path), Fumadocs (full path), and MkDocs (lean path with defined minimum contract).
-argument-hint: '<optional-target-dir>'
+argument-hint: '<optional-target-dir> [--ia-guidance <path|url>]'
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: '1.3.3'
+  version: '1.4.0'
 ---
 
 # Docs Bootstrap
@@ -114,13 +114,15 @@ OAT ▸ DOCS BOOTSTRAP
 
 The detailed framework procedures below apply to Fumadocs/MkDocs. When the selected tooling is `markdown`, use this path for Steps 2–7 instead; never run framework post-patches, the FP-15 AGENTS bridge, dependency discovery/install, package/Turbo patches, or a site build. Step 1 remains the shared read-only detector.
 
-1. **Preflight and routing:** Read `documentation.tooling` as a non-empty string. A non-string value (including a legacy object with a `framework` field) is invalid/undeclared tooling in the CLI; surface it for a user decision before proceeding, without silently clearing or retagging it. Declared tooling is authoritative: configured Markdown uses `documentation.root` literally, including when it contains a child named `docs`; declared frameworks or unknown stacks are not plain-doc adoption candidates. With no declared tooling, check framework evidence first (`mkdocs.yml`, Fumadocs/Next config and docs-app package scripts/dependencies), then inspect the chosen dedicated content directory for authored `.md`/`.mdx` pages. A repository-root README alone is insufficient; an empty selected directory is fresh setup. For a populated plain tree, lead with **adopt and audit**, **audit only**, or **abort**. Audit only delegates read-only to `oat-docs-analyze` and exits. Adoption requires the explicit user choice and CLI `--adopt`; `--yes` alone never authorizes it. An incompatible declared root/index/tooling requires a user decision, with no silent clearing or retagging. Keep the existing explicitly authorized framework replacement path when a framework is selected.
+1. **Preflight and routing:** Read `documentation.tooling` as a non-empty string. A non-string value (including a legacy object with a `framework` field) is invalid/undeclared tooling in the CLI; surface it for a user decision before proceeding, without silently clearing or retagging it. Declared tooling is authoritative: configured Markdown uses `documentation.root` literally, including when it contains a child named `docs`; declared frameworks or unknown stacks are not plain-doc adoption candidates. With no declared tooling, check framework evidence first (`mkdocs.yml`, Fumadocs/Next config and docs-app package scripts/dependencies), then inspect the chosen dedicated content directory for authored `.md`/`.mdx` pages. A repository-root README alone is insufficient; an empty selected directory is fresh setup. For a populated plain tree, default to `oat-docs-analyze` then `oat-docs-apply` for approved repairs and exit without scaffolding. Offer **adopt and audit**, **audit only**, or **abort** when adoption is explicitly requested. Audit only delegates read-only to `oat-docs-analyze` and exits. Adoption requires the explicit user choice and CLI `--adopt`; `--yes` alone never authorizes it. An incompatible declared root/index/tooling requires a user decision, with no silent clearing or retagging. Keep the existing explicitly authorized framework replacement path when a framework is selected.
 2. **Gather inputs:** Offer “Markdown (plain files), Fumadocs, or MkDocs?” Collect documentation title (`--site-name`), dedicated relative target directory (default `docs` in every repo shape), and optional description. Reuse an existing compatible configured Markdown root. Ask no app/package name, package-manager, site-runtime, or dependency questions. Lint and format default to `none`; describe selected existing repository tools only, without installing them. Validate a nonempty title and a dedicated in-repository target, excluding the repository root and escaping symlinks. Confirm fresh setup or additive adoption, title, root, and audit handoff. `appName` is absent and `conflictResolution` is `adopt`, `audit`, `abort`, or null for this path.
+   Before Markdown CLI invocation, run **Step 2.5** for fresh setup and explicitly selected adoption; it is not bypassed by this condensed path.
+
 3. **Invoke CLI:** Probe `$CLI_CMD docs init --help` and require advertised Markdown/`--adopt` support before invocation; if missing, report the needed CLI update rather than fabricating scaffold files. Run `$CLI_CMD docs init --framework markdown --target-dir <root> --site-name <title> --description <description> --lint none --format none --yes`, adding `--adopt` only for explicit adoption. Pass the selected lint/format values when using existing tools. Never pass app-only flags. An optional `--dry-run` previews file/config/guidance changes without writes; it does not count as a completed bootstrap. Capture terminal/JSON results, exact exit, created/preserved files, config changes, guidance action, and audit advice. `partial`/exit 1 with manual-required or blocked guidance means unresolved guidance; real runs may have created files, whereas dry-runs have only planned files. Report actual state and stop before claiming completion. Other refusals also stop without post-patches. For success, read config back to resolve the actual content root and authored index.
 4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions. Fresh setup creates only authored `index.md` and `contributing.md` in the target; verify no docs-root AGENTS, app package, framework config, dependencies, or root build changes. Run already documented lint/link/format checks when applicable; otherwise inspect files/links directly. Adoption preserves existing bytes and may leave missing child indexes, metadata, context, or links: record these as audit gaps for analyze/apply rather than repairing them or calling the tree fully conformant. Distinguish successful setup verification from content-conformance findings.
 5. **Inspect config:** `documentation.tooling` is the string `markdown`; `root` is the literal content directory; `index` is its authored entrypoint, normally `<root>/index.md`. Markdown introduces no `documentation.config`. Preserve unrelated config/excludes/completion settings. Verify deterministic managed root Documentation guidance names that root, Markdown tooling, authored index, and `<root>/contributing.md`; preserve manual/local guidance and surface unresolved disposition. The Step 5e completion opt-in remains available using the docs root rather than an app name, without silently changing an existing value. No nested app-config reconciliation or framework patch inspection applies.
 6. **Walkthrough:** In short chunks, show actual config and `<root>/index.md`: useful context plus the Contents map, title/description metadata, sibling `page.md` and child `section/index.md` links, exclusions and asset-only exceptions. Explain adding a page/section and updating the nearest authored map without overwriting existing context. Root AGENTS Documentation guidance and `<root>/contributing.md` establish agent/human conventions; a preexisting local AGENTS file remains authoritative, but bootstrap creates none. Authored indexes are edited directly. Optional generated inventories require explicit external output, e.g. `$CLI_CMD docs generate-index --docs-dir <root> --output .oat/docs-manifest.md`; output must stay outside the full configured content root and cannot overwrite the configured authored index even with a narrowed `--docs-dir`. Generation does not repoint `documentation.index`. Markdown bootstrap never generates a manifest automatically. Skip framework deep dives and preview-server/build commands.
-7. **Audit handoff and summary:** Offer `oat-docs-analyze` against the literal configured root, followed by `oat-docs-apply` only for approved repairs. An adopted incomplete tree needs that audit; config/guidance alone prove no full conformance. Explain `oat-project-document` for source-backed project deltas. Summarize tooling, actual root/authored index, created/preserved files, guidance/config disposition, file-check outcomes, unresolved audit gaps, optional manifest ownership, and exact skill handoff. For dry-run/partial/refusal, label the outcome accordingly rather than printing BOOTSTRAP COMPLETE. No app, install, build, patch, or dev-command fields apply.
+7. **Audit handoff and summary:** Offer `oat-docs-analyze` against the literal configured root, followed by `oat-docs-apply` only for approved repairs. An adopted incomplete tree needs that audit; config/guidance alone prove no full conformance. Explain `oat-project-document` for source-backed project deltas. Summarize tooling, actual root/authored index, created/preserved files, guidance/config disposition, ordered IA guidance locators/provenance and proposal recommendation/conflicts, file-check outcomes, unresolved audit gaps, optional manifest ownership, and exact skill handoff. For dry-run/partial/refusal, label the outcome accordingly rather than printing BOOTSTRAP COMPLETE. No app, install, build, patch, or dev-command fields apply.
 
 ### Step 1: Preflight Detector
 
@@ -155,7 +157,7 @@ Read (do not modify):
 
 Build `conflicts: []` by adding an entry for each finding:
 
-- If `configDocumentation` is non-null → `{ kind: 'existing-config', detail: <summary of what's there> }`
+- If `configDocumentation` declares a docs surface (`root`, `tooling`, `index` or `config`) → `{ kind: 'existing-config', detail: <summary of what's there> }`. A guidance-only section is an IA input, not evidence of an existing docs surface; retain it and continue fresh setup.
 - If `docsAppPath` exists on disk → `{ kind: 'existing-app-dir', detail: <path + whether it has uncommitted changes> }`
 - If `agentsMdSection` is true → `{ kind: 'existing-agents-section', detail: <what the section says> }`
 
@@ -208,7 +210,7 @@ Print `[2/7] Gathering inputs…` at the start of this step.
 
 **2a. Resolve Preflight conflicts (if any).**
 
-If `conflicts[]` from Preflight is non-empty, present them together and collect a `conflictResolution`. See the **Conflict Resolution Contract** sub-procedure below for the exact semantics of each option. Do not proceed to input questions until the user has chosen a resolution.
+If `conflicts[]` from Preflight is non-empty, present them together and default to `repair`: run `oat-docs-analyze` (with `--ia` when structure is requested), review its artifact, then `oat-docs-apply` for approved repairs and exit. Use replacement or a second app only after an explicit user choice; a generic request to bootstrap is insufficient. See the **Conflict Resolution Contract** below. Do not scaffold until that contract is satisfied.
 
 If `conflicts[]` is empty, skip conflict handling and go to 2b.
 
@@ -271,14 +273,14 @@ Input Result:
 
 #### Conflict Resolution Contract (sub-procedure)
 
-When Preflight (Step 1) records non-empty `conflicts[]`, present them to the user together and collect exactly one resolution. Each resolution below has a precise definition in terms of **allowed mutations**, **preserved state**, and **stop conditions**. The Scaffold Runner (Step 3) reads the chosen resolution and adjusts its behavior; it never reinvents these semantics.
+When Preflight (Step 1) records non-empty `conflicts[]`, present them together and default to `repair` unless the user explicitly selects another resolution. Record exactly one resolution. Each resolution below has a precise definition in terms of **allowed mutations**, **preserved state**, and **stop conditions**. The Scaffold Runner (Step 3) reads the chosen resolution and adjusts its behavior; it never reinvents these semantics.
 
 Resolution options:
 
 - **`replace`** — Treat the existing docs setup as disposable and scaffold fresh.
   - **Allowed mutations (executed by this sub-procedure before Scaffold Runner begins):**
     - Remove the existing docs app directory (`existingDocs.docsAppPath`), if present on disk.
-    - Remove the `documentation` section from `$REPO_ROOT/.oat/config.json`, if present. The CLI will rewrite it during init.
+    - Clear the replaced surface fields in `documentation` in `$REPO_ROOT/.oat/config.json`, preserving `documentation.guidance` if present. The CLI will rewrite surface ownership during init; advisory guidance is unrelated to the discarded scaffold.
     - Remove the `## Documentation` section from `$REPO_ROOT/AGENTS.md`, if present. The CLI upserts its own.
   - **Preserved state:** Everything outside the three touchpoints above. Git history is preserved — deletions are tracked normally and remain recoverable via `git revert` / `git checkout`.
   - **Stop conditions:**
@@ -336,10 +338,10 @@ Preflight detected existing docs setup:
   - existing-agents-section: AGENTS.md has a ## Documentation section
 
 How should I proceed?
-  1. replace    — remove the existing docs app and scaffold fresh at the same path
-  2. second-app — (deferred) add a new docs app alongside; not available in current CLI
-  3. abort      — exit without changes
-  4. repair     — run `oat-docs-analyze` / `oat-docs-apply` on the existing setup
+  1. repair     — default: run `oat-docs-analyze` / `oat-docs-apply` on the existing setup
+  2. replace    — explicit choice required: remove the existing docs app and scaffold fresh
+  3. second-app — explicit choice required; deferred because current CLI cannot support it
+  4. abort      — exit without changes
 
 Choose:
 ```
@@ -351,10 +353,47 @@ Record the user's choice as `conflictResolution` in the Input Result. If the use
 No matter which resolution the user picks, the Scaffold Runner (Step 3) **never** invokes `oat docs init` until:
 
 1. The chosen resolution's "Allowed mutations" have **completed successfully**, and
-2. The working-tree state **matches what the CLI expects** for that resolution (e.g., for `replace`: the target directory is empty or absent, the `documentation` config section is cleared, the root `AGENTS.md` `## Documentation` section is cleared; for `abort` / `repair`: the skill has already exited).
+2. The working-tree state **matches what the CLI expects** for that resolution (e.g., for `replace`: the target directory is empty or absent, the `documentation` surface fields are cleared (any `guidance` input is preserved), the root `AGENTS.md` `## Documentation` section is cleared; for `abort` / `repair`: the skill has already exited).
 
 If any mutation fails or any invariant check fails, **stop the flow before scaffold** and surface the error. A partial resolution followed by a scaffold produces a worse end state than either doing nothing or completing the resolution cleanly.
 
+### Step 2.5: IA Discovery and Proposal
+
+Run for fresh Markdown, Fumadocs and MkDocs setup, and explicit adoption, before
+any scaffold invocation. An existing surface routed to repair takes this stage
+through `oat-docs-analyze --ia`; it does not return to scaffold afterward.
+
+1. Independently probe each exact `authoring-docs/SKILL.md` in order:
+   `${SKILL_DIR}/..` from the loaded skill (`SKILL_DIR` is the absolute directory
+   containing that loaded `SKILL.md`), `${HOME}/.agents/skills`, then
+   `<repo-root>/.agents/skills`. Bind the first matching `authoring-docs` directory
+   once as `AUTHORING_DOCS_ROOT`; load `${AUTHORING_DOCS_ROOT}/SKILL.md` and use
+   that same root for every authoring-docs reference and script, never ambient
+   discovery. If none is found, name `authoring-docs`, stop this handoff, and give
+   the intended-scope recovery command: `oat tools install docs --scope <user|project>`
+   or `oat tools update --pack docs --scope <user|project>`.
+   Read `${AUTHORING_DOCS_ROOT}/references/guidance-sources.md` and
+   `${AUTHORING_DOCS_ROOT}/references/information-architecture.md`.
+   Resolve explicit `--ia-guidance`/conversation → repo → user → built-in and
+   retain ordered locators/provenance. These are skill inputs, not new CLI flags.
+2. Read repo signals: manifests, UI navigators and journeys, CLI `bin`, routers,
+   IaC, `e2e/` or `.maestro/`, existing docs, independently consumed monorepo units.
+   Read AGENTS/contributing authority first. Do not infer triad needs from UI alone.
+3. Ask only decision-changing questions about readers/work contexts, independent
+   verification, canonical facts elsewhere and links that must survive.
+4. Use the shared five axes and IA Proposal template to present **two plausible
+   candidate structures**, each a **two-level tree with 5–8 representative page
+   placements**, one page job per placement and the **nearest approved preset**.
+   Size controls materialized depth; it does not select audience. For Flat Small,
+   use grouped index headings rather than new directories.
+5. Recommend one with evidence and tradeoffs; retain unresolved conflicts as
+   `ask_user` with local/external source citations. Non-repo guidance stays read-only
+   and private exemplars are never copied. Cite ordered sources in the proposal
+   and final summary, including the built-in path when it wins.
+6. Carry the proposal to analyze/apply content kickoff. This stage proposes only:
+   it does not persist an accepted IA, restructure pages or scaffold preset trees.
+   CLI scaffold output remains the existing starter; those capabilities ship later.
+
 ### Step 3: Scaffold Runner
 
 Invoke `oat docs init` with the collected inputs and then apply gated post-patches for any CLI gaps the Capability Detection sub-procedure reports as still-open. The Scaffold Runner probes CLI capabilities, invokes the CLI, and applies the AGENTS.md bridge if still needed. Template content is CLI-owned; report old-scaffold shapes through `oat-docs-analyze`.
@@ -826,6 +865,8 @@ OAT ▸ DOCS BOOTSTRAP COMPLETE
 App:         {appName}
 Location:    {appRoot}
 Framework:   {framework}
+IA guidance: {ordered selected locators + explicit/conversation/shared/user/builtin provenance}
+IA proposal: {candidate recommendation, nearest preset, conflicts or none}
 Config:      {configPath} (documentation section)
 
 Created:

package/dist/commands/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/config/index.js

@@ -12,7 +12,7 @@ import { normalizeDispatchMatrix, validateDispatchRouteTarget, walkDispatchMatri
 import { formatDispatchNotices, terminalReviewerNoticesForMatrix, } from '../../config/dispatch-notices.js';
 import { dispatchPolicyModeDescription, dispatchPolicyPolicyDescription, managedDispatchPolicyValueList, } from '../../config/dispatch-policy-options.js';
 import { parseJsonConfig } from '../../config/json.js';
-import { DEFAULT_INSTRUCTION_SYNC_STRATEGY, INSTRUCTION_SYNC_STRATEGIES, VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, isValidProjectLogDigestBound, normalizeWorkflowPostImplementSequence, readOatConfig, readOatConfigForDefaultScopeRepair, readOatConfigForDocumentationExcludesRepair, readOatConfigForInstructionPointerExcludesRepair, readOatConfigForInstructionSyncStrategyRepair, readOatConfigWithWarnings, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, VALID_POST_IMPLEMENT_LEGACY_SEQUENCES, } from '../../config/oat-config.js';
+import { DEFAULT_INSTRUCTION_SYNC_STRATEGY, INSTRUCTION_SYNC_STRATEGIES, VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, isValidProjectLogDigestBound, normalizeWorkflowPostImplementSequence, normalizeDocumentationGuidance, readOatConfig, readOatConfigForDefaultScopeRepair, readOatConfigForDocumentationExcludesRepair, readOatConfigForInstructionPointerExcludesRepair, readOatConfigForInstructionSyncStrategyRepair, readOatConfigWithWarnings, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, VALID_POST_IMPLEMENT_LEGACY_SEQUENCES, } from '../../config/oat-config.js';
 import { getOwnKey, setOwnKey } from '../../config/own-keys.js';
 import { resolveEffectiveConfig, resolveEnvOverride, } from '../../config/resolve.js';
 import { resolveAssetsRoot } from '../../fs/assets.js';
@@ -67,6 +67,7 @@ const KEY_ORDER = [
     'archive.awsRegion',
     'autoReviewAtCheckpoints',
     'lastPausedProject',
+    'documentation.guidance',
     'documentation.root',
     'documentation.tooling',
     'documentation.config',
@@ -238,6 +239,17 @@ const CONFIG_CATALOG = [
         description: 'Deprecated compatibility alias for workflow.autoReviewAtHillCheckpoints. Prefer `oat config set workflow.autoReviewAtHillCheckpoints <true|false>`.',
         deprecated: { supersededBy: 'workflow.autoReviewAtHillCheckpoints' },
     },
+    {
+        key: 'documentation.guidance',
+        group: 'Documentation Guidance (shared > user)',
+        scope: 'shared | user',
+        file: '.oat/config.json | ~/.oat/config.json',
+        type: 'string | string[]',
+        defaultValue: 'null (skills use built-in IA reference)',
+        mutability: 'read-write',
+        owningCommand: 'oat config set documentation.guidance <path|JSON-array> [--user]',
+        description: 'Ordered advisory Markdown IA sources. Explicit skill input wins, then repo, then user, then built-in. Only path/URL strings are stored.',
+    },
     {
         key: 'documentation.root',
         group: 'Shared Repo (.oat/config.json)',
@@ -1153,6 +1165,12 @@ function validateSurfaceForKey(key, surface) {
     if (surface === 'auto') {
         return;
     }
+    if (key === 'documentation.guidance') {
+        if (surface !== 'shared' && surface !== 'user') {
+            throw new Error('documentation.guidance supports shared or user scope only.');
+        }
+        return;
+    }
     if (key === 'updateNotifications') {
         if (surface !== 'user') {
             throw new Error(`Cannot set 'updateNotifications' at '${surface}' scope. updateNotifications can only be set at user scope (~/.oat/config.json).`);
@@ -1766,6 +1784,55 @@ async function listConfigKeys(repoRoot, userConfigDir, dependencies) {
 async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, dependencies, warn) {
     validateSurfaceForKey(key, surface);
     const effectiveSurface = surface === 'auto' ? defaultSurfaceForKey(key) : surface;
+    if (key === 'documentation.guidance') {
+        const configPath = effectiveSurface === 'user'
+            ? join(userConfigDir, 'config.json')
+            : join(repoRoot, '.oat', 'config.json');
+        const trimmed = rawValue.trim();
+        let guidance;
+        try {
+            guidance = normalizeDocumentationGuidance(trimmed.startsWith('[') ? JSON.parse(trimmed) : trimmed, configPath, effectiveSurface === 'user' ? 'user' : 'shared');
+        }
+        catch {
+            throw new Error('Invalid documentation.guidance value: expected a non-empty path/URL string or ordered non-empty string array.');
+        }
+        let raw = { version: 1 };
+        try {
+            const parsed = parseJsonConfig(await dependencies.readFile(configPath), configPath);
+            if (typeof parsed !== 'object' ||
+                parsed === null ||
+                Array.isArray(parsed)) {
+                throw new Error(`Expected a config object in ${configPath}`);
+            }
+            raw = parsed;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const documentation = raw.documentation;
+        if (documentation !== undefined &&
+            (typeof documentation !== 'object' ||
+                documentation === null ||
+                Array.isArray(documentation))) {
+            throw new Error(`Expected a documentation object in ${configPath}`);
+        }
+        // Patch only the declared input; do not normalize away unrelated or future fields.
+        if (!isDeepStrictEqual(documentation?.guidance, guidance)) {
+            await dependencies.atomicWriteJson(configPath, {
+                ...raw,
+                documentation: {
+                    ...documentation,
+                    guidance,
+                },
+            });
+        }
+        return {
+            key,
+            value: guidance ?? null,
+            source: effectiveSurface,
+        };
+    }
     if (isPjmRemoteConfigKey(key)) {
         const config = await dependencies.readOatConfig(repoRoot);
         const remote = applyPjmRemoteSharedValue(config.pjm?.remote, key, rawValue);
@@ -2326,6 +2393,16 @@ async function unsetConfigValue(repoRoot, userConfigDir, key, surface, dependenc
  * runs only when the normalized pass found nothing to remove.
  */
 async function removeFromSurface(repoRoot, userConfigDir, key, effectiveSurface, path, dependencies) {
+    if (key === 'documentation.guidance') {
+        const configPath = effectiveSurface === 'user'
+            ? join(userConfigDir, 'config.json')
+            : join(repoRoot, '.oat', 'config.json');
+        const repaired = await removeConfigPathOnDisk(configPath, path);
+        if (!repaired)
+            return false;
+        await dependencies.atomicWriteJson(configPath, repaired);
+        return true;
+    }
     if (effectiveSurface === 'user') {
         const configPath = join(userConfigDir, 'config.json');
         const userConfig = await dependencies.readUserConfig(userConfigDir);