/librarian

description: "Keep the active wiki article layer in check: staleness, quality, accuracy, and coherence. Focused maintenance tool; broader trust audits belong to /wiki:audit."
argument-hint: "scan [--article <path>] [--resume] [--passes <list>] [--include-archived] | report | fix <id> [--wiki <name|all>] [--local]"
allowed-tools: Read, Write, Edit, Glob, Grep, Bash(ls:*), Bash(wc:*), Bash(date:*), Bash(mv:*), Bash(mkdir:*), WebFetch, WebSearch, Agent

Your task

**Resolve the wiki.** Do NOT search the filesystem or read reference files — follow these steps: 1. Read `$HOME/.config/llm-wiki/config.json`. If it has `hub_path`, expand leading `~` only (not tildes in `com~apple~CloudDocs`) and prefer that path; use `resolved_path` only as a fallback cache when the expanded `hub_path` is unavailable and `resolved_path` is initialized. If config has only `resolved_path`, use it. If the configured path can be statted but reading `wikis.json` or listing `topics/` fails with `Operation not permitted`, stop and ask the user to grant Full Disk Access/iCloud Drive access to the launcher; do not fall back to `~/wiki` or `resolved_path`. Do not write machine-specific `resolved_path` into shared configs. 2. If no config → read `$HOME/wiki/_index.md`. If it exists → HUB = `$HOME/wiki`. If nothing found, ask the user where to create the wiki. 3. **Wiki location** (first match): `--local` → `.wiki/` in CWD; `--wiki all` → HUB with an `ALL_TOPICS` flag for step 5; `--wiki <name>` → `HUB/wikis.json` lookup with portable path resolution (`<HUB>`, `~`, absolute, or HUB-relative); if the registry path is stale, fall back to `HUB/topics/<name>`; CWD has `.wiki/` → use it; else → HUB. 4. Read `<wiki>/_index.md` to verify. If missing → stop with "No wiki found. Run `/wiki init` first." 5. **Hub-level detection**: Librarian operates on the `wiki/` layer of a single topic wiki. The HUB has no `wiki/` subdirectory — only `wikis.json`, `_index.md`, `log.md`, and `topics/`. If `ALL_TOPICS` is set from `--wiki all`, read registered topic wikis from `HUB/wikis.json` (excluding the synthetic `hub` entry) and iterate the scan against each topic wiki sequentially. If the resolved wiki is the HUB (detected by the presence of `wikis.json` and the absence of a `wiki/` subdir) AND the user did not pass `--wiki <name>`, do NOT proceed with the scan against an empty topic surface. Instead, present a numbered list of registered topic wikis from `HUB/wikis.json` and ask the user to pick one. Re-resolve the wiki path with the selected name (`HUB/topics/<name>/`) and continue.

Read the librarian reference at `skills/wiki-manager/references/librarian.md`. Then execute the requested subcommand.

`/wiki:librarian` is the focused wiki-maintenance tool. It reviews the `wiki/` layer only. If the user wants a broader trust inspection across outputs, provenance, and fresh research, direct them to `/wiki:audit`.

Inventory awareness: librarian reports may recommend inventory records for durable maintenance follow-ups such as stale article clusters, weak source chains, recurring refresh tasks, or watch items. Do not create records during a scan unless the user explicitly asks; include a compact sample shape when suggesting a larger maintenance backlog.

Parse $ARGUMENTS

First argument is the subcommand:

• **scan**: Score all wiki articles for staleness and quality. Default subcommand if none specified.
• **report**: Display the latest `.librarian/REPORT.md`. If no report exists, suggest running `scan` first.
• **fix <id>**: (Phase 3, not yet implemented) Apply a proposed fix. Respond: "Fix operations are not yet available. Use the report to identify issues and address them manually."

Flags (apply to `scan`):

• **--article <path>**: Scan only this article instead of the full wiki. Path relative to wiki root (e.g., `wiki/concepts/librarian-agent.md`).
• **--resume**: Explicitly resume from checkpoint. Also happens automatically if `checkpoint.json` exists.
• **--passes <list>**: Comma-separated list of passes to run. Default:

`staleness,quality`. Optional: `schema` for a proposal-only topic schema migration pass. Future: `verification,coherence,dedup`.

• **--wiki <name|all>**: Target a specific topic wiki, or every registered topic wiki sequentially.
• **--local**: Use project-local `.wiki/`.
• **--include-archived**: Explicitly include archived topic wikis. Archived

topics are skipped by default so stale old interests do not create maintenance chores.

When `--wiki all` is used, iterate active registered topic wikis only unless `--include-archived` is present. If a single `--wiki <name>` target is archived, ask for `--include-archived` or restoration before scanning.

Scan Protocol

0. Initialize

1. Create `.librarian/` directory if it doesn't exist (`mkdir -p`). 2. Check for existing `checkpoint.json`:

• If exists and `--resume` or no explicit flag: read it, report how many articles are already done, continue from where it left off.
• If exists and user started a fresh scan (no `--resume`): warn "Found checkpoint from [date] with N/M articles done. Resume? (y/n)". On "n", delete checkpoint and start fresh.

3. Read `config.md` for `freshness_threshold` (default: 70). 4. Build article list:

• Full scan: `Glob wiki/**/*.md`, exclude `_index.md` files.
• `--article`: just the one file.

5. Subtract already-completed articles (from checkpoint) to get the pending list.

1. Staleness Pass (per article)

For each pending article:

1. Read the article's YAML frontmatter (do NOT read the full body yet — Tier 1 is metadata-only). 2. Read `volatility` (default: `warm`), `verified`, `updated`, `created`, `sources`, `confidence`. 3. For each entry in `sources:`, resolve it with the Source Reference Resolution protocol in `references/wiki-structure.md`. Treat each entry as a complete YAML scalar/path — never split on whitespace. Record resolved count, ambiguous count, and unresolved count. 4. For resolved