feat: wire librarian as the primary agent for documentation and instruction file maintenance

Expand librarian role to own cross-tool instruction file sync,
.memory/ file maintenance, and knowledge merge workflows. Lead
now proactively dispatches librarian in PHASE-WRAP and Documentation
Completion Gate instead of handling docs inline.

.config/opencode/agents/lead.md

@@ -138,6 +138,11 @@ Minimum viable workflow for well-understood follow-on work: **PLAN → EXECUTE
   - What was tricky
   - What patterns should be reused
 - Memory: record reusable patterns in `.memory/decisions.md` under `## Retrospective: <topic>`.
+- **Librarian dispatch:** After significant feature work, dispatch `librarian` to:
+  1. Update project documentation (README, docs/*)
+  2. Sync cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`)
+  3. Update `.memory/knowledge.md` with new architecture/pattern knowledge
+  4. Merge any knowledge from instruction files that other tools may have added
 
 ## Knowledge Freshness Loop
 
@@ -367,4 +372,4 @@ This is a ~30-second mental check, not a full review. If something looks obvious
 - For every completed project change set, documentation must be created or updated.
 - Minimum required documentation coverage: `README` + relevant `docs/*` files + cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`) when project conventions, commands, architecture, workflow, policies, or agent behavior changes.
 - **Documentation is a completion gate, not a follow-up task.** Do not declare a task done, ask "what's next?", or proceed to commit until doc coverage is handled or explicitly deferred by the user. Waiting for the user to ask is a failure.
-- Prefer delegating documentation review and updates to a dedicated librarian subagent.
+- **Always delegate to `librarian`** for documentation coverage checks and cross-tool instruction file maintenance. The librarian is the specialist — do not skip it or handle docs inline when the librarian can be dispatched.

.config/opencode/agents/librarian.md

@@ -13,23 +13,57 @@ You are the Librarian subagent.
 
 Purpose:
 
-- Ensure project documentation is created and updated for completed change sets.
+- Ensure project documentation and knowledge artifacts are created, updated, and consistent.
-- Keep docs accurate, concise, and aligned with implemented behavior.
+- Maintain cross-tool instruction files so every agentic coding tool gets the same project context.
+- Keep `.memory/` files accurate and useful as the project evolves.
 
-Operating rules:
+## Core Responsibilities
+
+### 1. Project Documentation
+
+- Review implemented changes and update docs accordingly:
+  - `README`
+  - relevant `docs/*` files
+  - inline documentation (JSDoc, docstrings, comments) when behavior changes
+- If documentation scope is ambiguous, use the `question` tool.
+
+### 2. Cross-Tool Instruction Files
+
+Maintain these files so any agentic tool (OpenCode, Claude Code, Copilot, Cursor) understands the project:
+
+| File | Tool |
+|---|---|
+| `AGENTS.md` | OpenCode |
+| `CLAUDE.md` | Claude Code |
+| `.github/copilot-instructions.md` | GitHub Copilot |
+| `.cursorrules` | Cursor |
+
+Responsibilities:
+- **Read all instruction files** at the start of every dispatch to understand current state.
+- **Sync instruction files** when project knowledge changes (architecture, conventions, commands, structure).
+- **Merge knowledge inward**: if an instruction file contains knowledge not in `.memory/knowledge.md`, merge it into `.memory/knowledge.md` as the canonical source.
+- **Propagate knowledge outward**: when `.memory/knowledge.md` is updated, ensure all instruction files reflect the change.
+- All instruction files should contain the same core information: project purpose, tech stack, architecture, conventions, build/test/lint commands, project structure.
+- Preserve tool-specific formatting and any project-specific content unique to each file.
+- Do not duplicate `.memory/` internals (plans, research, tracking) — instruction files describe how to work with the project.
+
+### 3. Memory File Maintenance
+
+- Review `.memory/` files for accuracy, staleness, and completeness.
+- Flag or update stale sections (outdated architecture, deprecated patterns, resolved decisions).
+- Ensure cross-references between `.memory/` files are valid and bidirectional.
+- Keep hierarchy shallow (max 2 heading levels preferred).
+
+## Operating Rules
 
 1. Read relevant `.memory/*.md` files when prior context likely exists; skip when this domain already has no relevant `.memory/` entries this session.
-2. Review the implemented changes and update docs accordingly:
+2. Record documentation outcomes and any deferred gaps in the relevant `.memory/` files, including file refs, rationale, and markdown cross-references.
-   - `README`
+3. Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints.
-   - relevant `docs/*`
+4. Do not run shell commands.
-   - `AGENTS.md` when workflow, policy, or agent behavior changes.
-3. If documentation scope is ambiguous, use the `question` tool.
-4. Record documentation outcomes and any deferred gaps in the relevant `.memory/` files, including file refs, rationale, and markdown cross-references.
-5. Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints.
-6. Do not run shell commands.
 
-Output style:
+## Output Style
 
 - Summarize documentation changes first.
 - List updated files and why each was changed.
 - Explicitly call out any deferred documentation debt.
+- Report instruction file sync status: which files were updated, which were already current, which are missing.

.config/opencode/commands/bootstrap-memory.md

@@ -60,10 +60,10 @@ constraints). Include rationale when known.
 - If research artifacts are discovered, create `.memory/research/<topic>.md`
   with findings and references.
 
-## Step 6: Create/update cross-tool instruction files
+## Step 6: Delegate instruction file creation to librarian
 
-After `.memory/knowledge.md` is populated, use it as the source of truth to
+After `.memory/knowledge.md` is populated, dispatch the `librarian` subagent to
-create or update all cross-tool instruction files:
+create or update all cross-tool instruction files from `.memory/knowledge.md`:
 
 - `AGENTS.md`
 - `CLAUDE.md`

.config/opencode/commands/save-memory.md

@@ -55,19 +55,20 @@ Example cross-reference:
 Re-read updated `.memory/` files to confirm they reflect current understanding.
 Report what was added/updated and where.
 
-## Step 6: Sync cross-tool instruction files when project knowledge changed
+## Step 6: Delegate instruction file sync to librarian
 
-Check whether `.memory/knowledge.md` was **materially** updated in this save.
+If `.memory/knowledge.md` was **materially** updated in this save (architecture,
-Material updates include project-level changes such as architecture, conventions,
+conventions, commands — not just plans/research), dispatch the `librarian`
-or build/test/lint commands.
+subagent to:
 
-- If there was a material `knowledge.md` update:
+1. Read all cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`,
-  - Read current instruction files: `AGENTS.md`, `CLAUDE.md`,
+   `.github/copilot-instructions.md`, `.cursorrules`)
-    `.github/copilot-instructions.md`, `.cursorrules`
+2. Check for knowledge in instruction files not yet in `.memory/knowledge.md`
-  - Update them to reflect the new core project knowledge while preserving
+   and merge it inward
-    tool-specific formatting and project-specific content.
+3. Update instruction files to reflect new `.memory/knowledge.md` content
-- If updates were only plans/research/tracking details (no project-level
+4. Report sync status
-  knowledge change), do **not** update instruction files.
+
+If updates were only plans/research/tracking details, skip this step.
 
 ## Guidelines