Route Docs

---
name: route-docs
description: >
  Change where project documentation is stored — local files, Obsidian
  vault, Notion workspace, or a per-type split — and regenerate the doc
  scaffold to match. TRIGGER when the user says "change doc routing",
  "switch docs to Obsidian", "move docs to Notion", "route docs locally",
  "change documentation storage", "reroute docs", "switch from local to
  Obsidian", "set up doc routing", "change where docs are stored",
  "/nyann:route-docs".
  Do NOT trigger on "bootstrap this project" — bootstrap runs doc routing
  as one step of the full pipeline. Do NOT trigger on "generate CLAUDE.md"
  — that's `gen-claudemd`. Do NOT trigger on "optimize CLAUDE.md" —
  that's `optimize-claudemd`.
---

# route-docs

Standalone doc-routing and scaffold regeneration. Composes
`bin/route-docs.sh` (produces a DocumentationPlan) and
`bin/scaffold-docs.sh` (materializes the local-target portion) so the
user can change doc storage after initial bootstrap without
re-running the full pipeline.

## 1. Resolve profile and current state

1. Load the active profile via `bin/load-profile.sh <name>`.
2. Run `bin/detect-stack.sh --path .` for a StackDescriptor (optional;
   used by scaffold-docs for stack-aware architecture templates).
3. Check which doc targets already exist (`docs/`, `memory/`,
   `docs/decisions/`, etc.) so the user sees what will change.

## 2. Determine the routing spec

The user's intent maps to a `--routing` value:

| User says | Routing spec |
|---|---|
| "everything local" | `all:local` (default) |
| "docs in Obsidian" | `all:obsidian` |
| "docs in Notion" | `all:notion` |
| "PRDs in Notion, ADRs in Obsidian, rest local" | `prd:notion,adrs:obsidian,research:local,architecture:local` |

If the user's intent is ambiguous, **you MUST call the `AskUserQuestion`
tool** (not plain text):

```json
{
  "questions": [
    {
      "question": "Where should documentation be stored?",
      "header": "Routing",
      "multiSelect": false,
      "options": [
        { "label": "Local (Recommended)", "description": "docs/ directory in the repo" },
        { "label": "Obsidian", "description": "Route to an Obsidian vault via MCP" },
        { "label": "Notion", "description": "Route to a Notion workspace via MCP" },
        { "label": "Custom split", "description": "Different backend per doc type" }
      ]
    }
  ]
}
```

`memory` is always local regardless of routing.

For any non-local routing, first run `bin/detect-mcp-docs.sh` to
discover available MCP connectors. The result is an MCP doc-targets
JSON; pass it to route-docs via `--mcp-targets <path>`. Without this,
route-docs will reject non-local backends because it validates each
chosen backend against `--mcp-targets.available[]`.

For MCP-routed targets, also collect the required parameters:
- **Obsidian**: `--obsidian-vault <name>` and optionally
  `--obsidian-folder <path>`.
- **Notion**: `--notion-parent <id-or-url>`.

## 3. Preview the plan

Run route-docs in preview mode:

```
bin/route-docs.sh \
  --profile <profile-path> \
  [--routing <spec>] \
  [--mcp-targets <mcp-doc-targets.json>] \
  [--obsidian-vault <name>] [--obsidian-folder <path>] \
  [--notion-parent <id>] \
  [--project-name <name>]
```

Output is a DocumentationPlan JSON
(`schemas/documentation-plan.schema.json`). Show the user:

- Each doc type (architecture, prd, adrs, research, memory, plus
  any v1.6.0+ archetype-aware types — api_reference, runbook,
  deployment, glossary — when `use_archetype_scaffolds` is enabled
  on the profile) and its target (local path, obsidian, notion).
- The computed `storage_strategy` (local / obsidian / notion / split).
- Which local files will be created by the scaffolder.
- Which MCP targets require skill-layer creation (Obsidian pages,
  Notion databases).

## 3b. Doc conformance check (v1.9.0+)

Before scaffolding, check for existing docs at non-canonical paths:

```
bin/detect-doc-conformance.sh --target <cwd> --archetype <archetype>
```

If the output is non-empty, offer to reorganize before scaffolding
(same flow as bootstrap step 4c — "reorganize all" / "let me pick" /
"leave as-is"). Reorganization ensures content is preserved at the
canonical paths rather than creating blank templates alongside existing
docs at wrong paths.

## 4. Scaffold local targets

On confirmation:

```
bin/scaffold-docs.sh \
  --plan <plan-path> \
  [--stack <stack-path>] \
  [--project-name <name>] \
  --target <cwd>
```

The scaffolder is idempotent — existing files are never overwritten.
Only gaps get filled.

For MCP-routed targets (type != local), scaffold-docs skips them with
a note. The skill layer handles MCP page creation via the configured
MCP server (Obsidian / Notion) as documented in
`skills/bootstrap-project/references/mcp-routing.md`.

## 5. Regenerate CLAUDE.md

After the scaffold, the CLAUDE.md doc-map table may be stale.
Suggest running `/nyann:gen-claudemd` to refresh the managed block
with the new routing.

## 6. Report

- Doc types and their new targets.
- Files created by scaffold-docs.
- MCP targets that need manual page creation (if any).
- Storage strategy summary.

## When to hand off

- "Regenerate CLAUDE.md with the new routing" → `gen-claudemd` skill.
- "Check repo health after rerouting" → `doctor` skill.
- "Set up the full project from scratch" → `bootstrap-project` skill.
- "Create Obsidian/Notion pages" → the MCP creation flow is documented
  in `skills/bootstrap-project/references/mcp-routing.md`; follow
  those instructions for the non-local targets.