Prepare librarian schema migration release

Author: nvk

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "llm-wiki",
-  "version": "0.10.2",
+  "version": "0.13.0",
   "description": "LLM-compiled knowledge base plugin. Natural language routing, collector catalogs, topic archive lifecycle, inventory tracking, dataset manifests, collection ingestion for external wikis/spec repos, truth-seeking audits, session resume, concurrent-safe indexes, topic-isolated wikis, parallel multi-agent research, thesis mode (--mode thesis), repo assessment, Obsidian dual-linking, lint-as-migration, retardmax mode, and --min-time sustained research.",
   "owner": {
     "name": "nvk"
@@ -10,7 +10,7 @@
     {
       "name": "wiki",
       "description": "LLM-compiled knowledge base. Commands: /wiki (natural language router + init/status), /wiki:ingest, /wiki:ingest-collection, /wiki:collect, /wiki:inventory, /wiki:dataset, /wiki:archive, /wiki:compile, /wiki:query (quick/standard/deep/--resume), /wiki:research (5-10 parallel agents, --new-topic, --min-time, --mode thesis), /wiki:audit, /wiki:librarian, /wiki:assess, /wiki:plan, /wiki:lint, /wiki:output, /wiki:retract, /wiki:project.",
-      "version": "0.10.2",
+      "version": "0.13.0",
       "author": {
         "name": "nvk"
       },

.claude/release-checklist.md

@@ -19,6 +19,7 @@ Standard process for testing and shipping a new version of the llm-wiki plugin.
      ```
 
 1. **Bump `plugin.json`** — both files must match:
+   - `.claude-plugin/marketplace.json`
    - `claude-plugin/.claude-plugin/plugin.json`
    - `plugins/llm-wiki/.codex-plugin/plugin.json`
 
@@ -29,6 +30,7 @@ Standard process for testing and shipping a new version of the llm-wiki plugin.
    ./scripts/sync-codex-plugin.sh
    ./scripts/sync-opencode-plugin.sh
    ./tests/test-plugin-validate.sh
+   ./tests/test-docs-consistency.sh
    ./tests/test-structure.sh
    ./tests/test-local-cli-lint.sh
    ./tests/test-codex-sync.sh

.gitignore

@@ -5,6 +5,7 @@
 # Codex local/project-local state
 .codex/
 .tmp/
+__pycache__/
 
 # macOS
 .DS_Store

AGENTS.md

@@ -54,10 +54,11 @@ All content lives here. One topic per wiki. Isolated indexes, focused queries.
 ```
 ~/wiki/topics/<name>/
 ├── .obsidian/                     # Obsidian vault config (optional)
-├── .librarian/                    # Optional: wiki-only maintenance reports
+├── .librarian/                    # Optional: maintenance reports + derived caches
 ├── .audit/                        # Optional: umbrella audit reports
 ├── _index.md                      # Master index: stats, navigation, recent changes
 ├── config.md                      # Title, scope, conventions
+├── schema.md                      # Optional: topic-local vocabulary/conventions
 ├── log.md                         # Activity log for this topic
 ├── inbox/                         # Drop zone — user dumps files here
 │   └── .processed/
@@ -735,18 +736,28 @@ content.
 
 ### Librarian
 
-Content-level wiki maintenance: staleness detection, quality scoring, factual verification, semantic coherence, deduplication. Produces scored reports — never modifies content without confirmation. Archived topics are skipped by default.
+Content-level wiki maintenance: staleness detection, quality scoring, factual
+verification, semantic coherence, deduplication, and proposal-only topic schema
+advice. Produces scored reports — never modifies content without confirmation.
+Archived topics are skipped by default.
 
 **Subcommands**:
-- **scan**: Score all wiki articles for staleness and quality. Two-tier: quick metadata scan first, deep content read only for articles below threshold or with `volatility: hot`. Checkpoints after each article for crash recovery. Results to `.librarian/scan-results.json` and `.librarian/REPORT.md`.
+- **scan**: Score all wiki articles for staleness and quality. Two-tier: quick metadata scan first, deep content read only for articles below threshold or with `volatility: hot`. Checkpoints after each article for crash recovery. Results to `.librarian/scan-results.json` and `.librarian/REPORT.md`. Optional `--passes schema` may write `output/schema-proposal-<topic>-YYYY-MM-DD.md`; it must not create/update `schema.md` without explicit acceptance.
 - **report**: Display the latest scan report.
 - **fix <id>**: Apply a proposed fix from the report (Phase 3 — not yet implemented).
 
 **Staleness scoring** (0-100): four dimensions at 25 points each — source freshness, verification recency, compilation recency, source chain integrity. Decay curves scaled by article `volatility` tier (hot/warm/cold).
 
 **Quality scoring** (0-100): four dimensions at 25 points each — source diversity, content depth, cross-reference density, summary quality. Articles scoring below 40 on either dimension are flagged.
 
-Flags: `--article <path>` (single article), `--resume` (from checkpoint), `--passes <list>` (staleness, quality — future: verification, coherence, dedup).
+Flags: `--article <path>` (single article), `--resume` (from checkpoint),
+`--passes <list>` (staleness, quality, optional schema — future:
+verification, coherence, dedup).
+
+Schema migration for existing wikis is lazy and proposal-first. Existing wikis
+without `schema.md` remain valid and silent. Status/resume may show a one-line
+optional nudge for active wikis with roughly 10+ compiled articles and no
+recent schema proposal/report. Applying a schema proposal is explicit.
 
 ### Plan
 

CLAUDE.md

@@ -35,6 +35,7 @@ git -C ~/.claude/plugins/marketplaces/llm-wiki remote set-url origin https://git
 
 ```bash
 ./tests/test-plugin-validate.sh   # plugin manifest + command frontmatter
+./tests/test-docs-consistency.sh   # README command table + manifest/version drift
 ./tests/test-structure.sh          # wiki fixture validation (84 assertions)
 ./tests/test-local-cli-lint.sh     # local scripts/llm-wiki lint helper
 ./tests/test-session-capture.sh    # deterministic session capture helper
@@ -71,6 +72,7 @@ Requires `ANTHROPIC_API_KEY`. Costs ~$2-5 per run.
 - **Added a new lint rule**: add a defect fixture in `generate-defect-fixtures.sh` and a negative test case in `test-structure.sh`.
 - **Changed frontmatter schema** (new required field, renamed enum): update the golden wiki fixture files to match, update `test-structure.sh` field/enum lists, regenerate defect fixtures.
 - **Added a new command**: add a frontmatter check to `test-plugin-validate.sh` if it's not picked up by the wildcard. Add a behavioral eval in `promptfooconfig.yaml` for routing.
+- **Changed user-facing command docs or versions**: update README command rows and all plugin/marketplace manifest versions together, then run `test-docs-consistency.sh`.
 - **Changed the fuzzy router**: add or update test cases in `promptfooconfig.yaml` covering the new routing behavior plus negative controls.
 - **Added a new reference file**: `test-plugin-validate.sh` has three `for ref in ...` loops (Claude-side existence, Codex-side copied-reference validation, OpenCode-side symlink reachability) — add the new filename to all three.
 - **Changed directory structure** (new `raw/` or `wiki/` subdirectory): update `test-structure.sh` C1 directory list and C11 placement checks. Update the golden wiki fixture if needed.

README.md

@@ -19,6 +19,12 @@ LLM-compiled knowledge bases for any AI agent. Parallel multi-agent research, co
 
 ## Changelog
 
+**v0.13.0** — **Librarian schema migration groundwork.**
+- Adds deterministic docs/version consistency checks so command tables, manifests, generated mirrors, and reference lists do not drift silently.
+- Stabilizes local lint fixtures with a deterministic test date override.
+- Documents the next-run librarian schema migration nudge for existing wikis: report/proposal first, explicit `schema.md` apply later.
+- Clarifies the optional index/server layer as a read-only, rebuildable acceleration cache rather than source-of-truth state.
+
 **v0.12.0** — **Feedback curator.**
 - Captures high-signal user corrections, preferences, approvals, and plan acceptance as redacted candidates under `HUB/.sessions/feedback/`.
 - Ignores generic acknowledgements like `ok`, `thanks`, and `cool`.
@@ -466,9 +472,14 @@ folder move plus `wikis.json`, hub index, and log updates.
 | `/wiki:audit report` | Display the latest umbrella audit report |
 | `/wiki:librarian` | Focused wiki maintenance: staleness and quality scan for the `wiki/` layer |
 | `/wiki:librarian --article <path>` | Scan a single article |
+| `/wiki:librarian scan --passes staleness,quality,schema` | Optionally generate a schema proposal for established wikis without changing articles |
 | `/wiki:librarian report` | Display the latest librarian scan report |
+| `/wiki:refresh [<article-path>|--due]` | Re-check article sources for changed facts and offer human-gated updates |
 | `/wiki:output <type>` | Generate: summary, report, study-guide, slides, timeline, glossary, comparison |
 | `/wiki:output <type> --retardmax` | Ship it now — rough but comprehensive, iterate later |
+| `/wiki:project new <slug> "goal"` | Group related outputs under `output/projects/<slug>/` with a plain `WHY.md` rationale |
+| `/wiki:project list\|show\|add\|archive` | Manage output project folders without duplicating project state into frontmatter |
+| `/wiki:retract <source-path> --reason "why"` | Remove a bad source, map blast radius, and flag downstream claims for review |
 | `/wiki:ll` | Extract lessons learned from the current session into the wiki |
 | `/wiki:ll --dry-run` | Preview extracted lessons without writing |
 | `/wiki:ll --rules` | Also suggest CLAUDE.md / AGENTS.md rule additions |

claude-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "wiki",
   "description": "LLM-compiled knowledge base. Natural language routing, collector catalogs, topic archive lifecycle, inventory tracking, dataset manifests, collection ingestion for external wikis/spec repos, truth-seeking audits, session resume, automated session capture, feedback curation, context rehydration, concurrent-safe derived indexes, topic-isolated wikis, parallel multi-agent research, thesis-driven investigation, repo assessment, Obsidian dual-linking, retardmax mode, and --min-time sustained research.",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "author": {
     "name": "nvk"
   },

claude-plugin/commands/librarian.md

@@ -35,7 +35,9 @@ 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`. Future: `verification,coherence,dedup`.
+- **--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
@@ -125,6 +127,31 @@ After all articles are scored:
 5. For articles the user selects to refresh: invoke the refresh protocol from `commands/refresh.md` for that article.
 6. For articles the user selects to verify: update `verified:` to today in the article's frontmatter.
 
+#### 3b. Optional Schema Advisory Pass
+
+Run only when `schema` is included in `--passes`.
+
+1. Check whether `<wiki-root>/schema.md` exists. If it exists, treat the schema
+   as advisory unless it explicitly declares a stricter mode.
+2. Derive observed topic vocabulary from existing markdown:
+   - article titles, aliases, tags, and categories;
+   - See Also links and markdown link neighborhoods;
+   - raw source types, collection manifests, and source tags;
+   - inventory kinds/entities/corpora and dataset manifests when present;
+   - recurring output/project names and prefixes.
+3. If no schema exists and the wiki is small (roughly fewer than 10 compiled
+   articles) with no obvious repeated category/link/source confusion, report
+   `schema skipped: wiki too small` and do not write a proposal.
+4. If a schema would help, write
+   `output/schema-proposal-<topic>-YYYY-MM-DD.md`. The proposal may recommend
+   entity types, relationship verbs, article subtypes, source conventions, and
+   inventory/dataset boundaries.
+5. Do **not** create or update `schema.md` during the scan. Applying a proposal
+   is a separate explicit user decision.
+6. Add schema findings to `scan-results.json` and `REPORT.md` under a
+   `Schema Advice` section, including whether the state is `absent`,
+   `proposed`, `advisory`, or `strict`.
+
 #### 4. Generate Reports
 
 1. Compile all results from checkpoint into `scan-results.json` (format per `references/librarian.md`).

claude-plugin/commands/wiki.md

@@ -206,6 +206,14 @@ Show wiki status. Before reading any `_index.md`, stale-check it: count `.md` fi
    - Read `config.md` for title and description
    - Count actual files for accuracy
    - Show: title, location, source/article/inventory/dataset/output counts, inbox pending, last compiled/lint dates, last 5 recent changes
+   - If the topic is active, has roughly 10+ compiled articles, has no root
+     `schema.md`, has no recent `output/schema-proposal-*.md`, and has no
+     recent `.librarian/REPORT.md` already covering schema advice, show one
+     optional next-run migration nudge:
+     `Optional upgrade: this wiki is large enough to benefit from a librarian schema pass. It will only write a report/proposal, not change articles. Run: /wiki:librarian scan --passes staleness,quality,schema`
+   - Do not block normal status/query/compile/ingest on this nudge. Do not
+     auto-create `schema.md`, proposal outputs, or dismissal files from status.
+     Suppress the nudge when a schema or recent schema proposal already exists.
 
 3. List available subcommands
 

claude-plugin/skills/wiki-manager/SKILL.md

@@ -179,6 +179,16 @@ Flow: Read `_index.md` → identify relevant articles by summary/tag → read ar
 See [references/linting.md](references/linting.md).
 Flow: Check structure → indexes → links → content → coverage → report → optionally auto-fix. Default lint keeps active material healthy and reports archived topics as skipped. Use `--include-archived` or `--archived-only` for explicit archived structural maintenance.
 
+### Librarian
+See [references/librarian.md](references/librarian.md).
+Flow: Scan the active topic's compiled `wiki/` layer → score staleness, quality,
+source-chain integrity, and link health → write `.librarian/scan-results.json`
+and `.librarian/REPORT.md` → recommend ranked next actions. Optional
+`--passes schema` may write a proposal output for a topic-local `schema.md`,
+but it must not create or modify `schema.md` without explicit user acceptance.
+Librarian is the article-health advisor; it does not replace lint's structural
+checks or audit's broader trust review.
+
 ### Audit
 See [references/audit.md](references/audit.md).
 Flow: Run or reuse the librarian pass → inspect artifact dependency chains across `output/`, `wiki/`, and `raw/` → escalate with fresh source checks and targeted research until trust verdicts converge → write `.audit/REPORT.md`.