feat(knowledge): seam — plugin skeleton, fold book-distill, library_dir + setup

.claude-plugin/marketplace.json

@@ -92,10 +92,10 @@
       "tags": ["prototype", "spike", "throwaway", "design", "ui", "state-machine", "skill"]
     },
     {
-      "name": "book-distill",
-      "source": "./plugins/book-distill",
+      "name": "knowledge",
+      "source": "./plugins/knowledge",
       "category": "knowledge",
-      "tags": ["book", "distill", "pdf", "epub", "skill", "knowledge", "reference", "documentation"]
+      "tags": ["knowledge", "distill", "book", "pdf", "epub", "skill", "reference", "synthesis", "ingest"]
     },
     {
       "name": "context7",
@@ -241,5 +241,8 @@
       "category": "modeling",
       "tags": ["event-storming", "ddd", "domain-modeling", "bounded-contexts", "miro", "facilitation", "simulation", "skill"]
     }
-  ]
+  ],
+  "renames": {
+    "book-distill": "knowledge"
+  }
 }

README.md

@@ -34,7 +34,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace
 | [`improve-architecture`](plugins/improve-architecture) | Skill | Scans an existing codebase for module-level architecture friction — shallow modules, seam leaks, locality gaps — using Ousterhout's deep-module lens, presents candidates as a self-contained HTML report, and interviews the selected candidate before handing off for planning. |
 | [`mcp-tool-audit`](plugins/mcp-tool-audit) | Skill | Audits MCP server tool definitions against MCP-spec and Anthropic tool-design criteria, returning a per-tool PASS/WARN/FAIL scorecard. Language-agnostic (Python, TypeScript, .NET). |
 | [`prototype`](plugins/prototype) | Skills | Builds throwaway code to answer a design question before committing to architecture. Ships two skills: `/prototype:logic` (an interactive terminal app over a portable state model) and `/prototype:ui` (radically different visual variants on one route). |
-| [`book-distill`](plugins/book-distill) | Skill | Distills a technical book (PDF or EPUB) into concept-organized, author-attributed skill reference files through a structured multi-session read-write pipeline, updating the target skill's routing table. |
+| [`knowledge`](plugins/knowledge) | Skills | Ingests external knowledge into durable, synthesized artifacts. Ships `/knowledge:book-distill` (distills a technical book — PDF or EPUB — into concept-organized, author-attributed skill reference files, updating the target skill's routing table) and `/knowledge:setup` (settles the configurable `library_dir` artifact-landing location). |
 | [`context7`](plugins/context7) | Skill | Looks up current library documentation, API references, and code examples via Context7 — a two-step resolve-then-query workflow over the `ctx7` CLI or the consumer's Context7 MCP server, plus an upstream drift-check `update` action. |
 | [`thariq-skills`](plugins/thariq-skills) | Skill | Ships Anthropic's internal skill-authoring playbook as an on-demand knowledge skill — 9 skill categories, 9 authoring tips (gotchas sections, progressive disclosure, description-as-trigger), and distribution guidance, with a vendored upstream baseline and drift-check update script. |
 | [`boris`](plugins/boris) | Skill | Ships Boris Cherny's Claude Code workflow tips (howborisusesclaudecode.com) as an on-demand knowledge skill — 107 tips across 95 sections routed through topic reference files, with a vendored upstream baseline and drift-check update script. |

plugins/knowledge/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "knowledge",
+  "version": "0.1.1",
+  "description": "Ingest external knowledge into durable, synthesized artifacts. Ships a book-distillation pipeline (PDF/EPUB into concept-organized, author-attributed skill reference files) plus a re-runnable setup action; a configurable library directory governs where synthesized artifacts land in the consuming repo.",
+  "author": {
+    "name": "Melodic Software",
+    "email": "info@melodicsoftware.com"
+  },
+  "license": "MIT",
+  "keywords": ["knowledge", "distill", "book", "pdf", "epub", "skill", "reference", "synthesis", "ingest"],
+  "userConfig": {
+    "library_dir": {
+      "type": "directory",
+      "title": "Knowledge library directory",
+      "description": "Project-relative directory in the consuming repo where synthesized knowledge artifacts land. Default is the repo root. A working-notes or artifacts convention declared in your own project's CLAUDE.md or rules takes precedence.",
+      "default": "."
+    }
+  }
+}

plugins/knowledge/README.md

@@ -0,0 +1,89 @@
+# knowledge
+
+A Claude Code plugin that ingests external knowledge into durable, synthesized
+artifacts. Its first shipped pipeline distills a technical book (PDF or EPUB) into
+concept-organized, author-attributed **skill reference files**; a re-runnable
+`setup` action settles where synthesized artifacts land in the consuming repo.
+
+## Skills
+
+| Skill | Invoke | What it does |
+|---|---|---|
+| `book-distill` | `/knowledge:book-distill` | Turns a technical book (PDF/EPUB) into concept-organized, author-attributed skill reference files through a structured, multi-session read-write pipeline, updating the target skill's routing table. |
+| `setup` | `/knowledge:setup` | Interviews the consumer and persists the `library_dir` config (idempotent — re-run to reconfigure). |
+
+## What book-distill produces
+
+- **Concept-organized reference files** (60-160 lines each), named by what they
+  teach rather than by chapter number, with the author attributed in section
+  headers.
+- **Routing-table and quick-decision-guide updates** to the target skill's
+  `SKILL.md`, so the skill loads the right reference file for a given developer
+  question at query time.
+- **Multi-author merges** — where two books cover the same concept, their
+  content is consolidated into a shared file.
+
+You name the target skill when you invoke `/knowledge:book-distill`, so output
+lands somewhere you chose (`${CLAUDE_PROJECT_DIR}/.claude/skills/<target>/`) —
+either an existing skill it extends or a new one it creates. Cross-session state
+(the file plan, page map, and a checklist) persists under `${CLAUDE_PLUGIN_DATA}`,
+which survives plugin updates.
+
+## Usage caution — copyright
+
+This plugin is a neutral tool; **you own the rights decision** for everything you
+distill with it. A condensed distillation of a copyrighted book is a
+**derivative work** (17 U.S.C. §§ 101, 106) — the copyright holder's exclusive
+rights include preparing and distributing derivatives — so distilled outputs
+carry **redistribution risk**. Keeping a private distillation for your own study
+is a different act from publishing, committing, or sharing one; fair use is a
+defense raised after the fact, not a safe harbor you can assume in advance.
+Publish, commit, or redistribute a distilled output only once you have satisfied
+yourself that doing so is lawful for that book. This is a caution, not legal
+advice.
+
+The distilled output is written into a skill that Claude later **auto-loads as
+model context** — so review it before you commit or share it: treat the source
+book as untrusted input and confirm the distillation reflects the book rather than
+any instructions injected through its text.
+
+## Requirements
+
+- A PDF or EPUB you have the right to read. PDF works natively with Claude
+  Code's Read tool; EPUB requires unzipping and text extraction first.
+
+## Install
+
+```shell
+/plugin marketplace add melodic-software/claude-code-plugins
+/plugin install knowledge@melodic-software
+```
+
+Migrating from the standalone `book-distill` plugin? Nothing to do — the
+marketplace's `renames` map migrates `book-distill@melodic-software` to
+`knowledge@melodic-software` automatically on your next session; the skill is now
+invoked as `/knowledge:book-distill`.
+
+One exception: an **in-progress multi-session distillation** stores its resume
+checklist under the plugin's `${CLAUDE_PLUGIN_DATA}` directory, which is keyed by
+plugin id and is **not** migrated by `renames` (that map rewrites `enabledPlugins`
+and `pluginConfigs`, not plugin data). If you have a distillation in flight, copy
+your old `book-distill` plugin-data directory to the new `knowledge` one before
+resuming so the resume pointer survives.
+
+## Configuration
+
+One option, prompted at enable time (or set any time with `/knowledge:setup`):
+
+| Option | Type | Default | Purpose |
+|---|---|---|---|
+| `library_dir` | directory | `.` (repo root) | Project-relative directory where the plugin's ingestion pipelines land synthesized artifacts. `book-distill` is unaffected — it writes to the target skill you name at invocation — so today this is a reserved seam. A working-notes or artifacts convention declared in your own project's `CLAUDE.md` or rules takes precedence. |
+
+`book-distill` itself writes to a **target skill** you name at invocation, so it
+needs no configuration to run; `library_dir` is the shared artifact-landing seam
+the plugin's ingestion pipelines resolve through.
+
+## License
+
+MIT (SPDX-License-Identifier: MIT). See the LICENSE file at the root of the
+melodic-software/claude-code-plugins repository.

plugins/knowledge/skills/setup/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: setup
+description: "Configure the knowledge plugin for this repository: interview the user, infer a sensible artifact-landing location from the repo layout, and persist the library_dir userConfig option. Use when: 'set up knowledge', 'configure the knowledge plugin', 'knowledge setup', 'where do knowledge artifacts land', or a knowledge skill reports missing or thin config. Re-runnable — safe to invoke again to reconfigure."
+argument-hint: "(no arguments — interactive interview)"
+user-invocable: true
+---
+
+## Purpose
+
+Settle the `library_dir` seam — the project-relative directory where the knowledge plugin's synthesized
+artifacts land in the CONSUMING repo — and persist it so the plugin's skills resolve it deterministically
+instead of re-inferring every run. `library_dir` is a typed `directory` `userConfig` option (seam 1 of the
+extensibility contract): its value lives in `pluginConfigs["knowledge@melodic-software"].options.library_dir`
+and substitutes into skill content as `${user_config.library_dir}`.
+
+Idempotent: re-running reads the current value and offers an update rather than overwriting blind.
+
+## Task
+
+Apply the convention-resolution ladder — config present → use it; absent → infer from the repo and persist;
+cannot infer → ask and offer to persist; otherwise a safe generic default (repo root `.`).
+
+1. **Read the current value first, in precedence order.** Look for `library_dir` under
+   `pluginConfigs["knowledge@melodic-software"].options` in all three scopes and resolve the *effective*
+   value the way Claude Code does — **Local (`.claude/settings.local.json`) > Project
+   (`.claude/settings.json`) > User (`~/.claude/settings.json`)**, local winning. Report the effective
+   value and which scope supplies it; the interview proposes a change against that baseline. If a local
+   override is present, say so explicitly — step 4 writes the *project* (team) value, which stays shadowed
+   by the local override until the developer updates or removes it, so a project-scope edit alone will not
+   change what the plugin actually uses on that machine. Read each scope **narrowly** — query only the
+   single `pluginConfigs["knowledge@melodic-software"].options.library_dir` key (e.g. with `jq`), never
+   loading `.claude/settings.local.json` wholesale: that overlay is secret-bearing (API tokens, env
+   secrets), so do not read or echo unrelated settings content.
+2. **Infer a default before asking.** If no value is set, explore the consuming repo for an existing
+   artifact/notes convention rather than guessing:
+   - A working-notes or artifacts directory declared in the repo's own `CLAUDE.md`, `AGENTS.md`, or
+     `.claude/rules` (that declared convention wins — surface it as the recommended value).
+   - An existing docs or knowledge directory (`docs/`, `knowledge/`, `.claude/notes/`) that synthesized
+     artifacts would naturally join.
+   - If nothing is found, the safe default is the repo root `.` (the plugin's declared `userConfig`
+     default), meaning artifacts land at the top of the consuming repo unless a skill is told otherwise.
+3. **Interview — one decision.** Present the inferred value with a recommendation and let the user accept
+   or edit it. Keep it to the single `library_dir` knob; do not invent further options (Rule of Three — add
+   a knob only when a real repeated repo-specific need surfaces).
+4. **Persist to project scope.** Write the chosen value to the project `.claude/settings.json` at
+   `pluginConfigs["knowledge@melodic-software"].options.library_dir` so it is tracked and shared with the
+   team. Create the `pluginConfigs` / options path if absent; do not disturb unrelated keys. The value is
+   stored verbatim (Claude Code does not normalize a `directory` option to absolute or validate existence),
+   so store it exactly as the user intends it to resolve relative to their working directory.
+5. **Offer the personal overlay.** A per-developer override goes in the local overlay
+   `.claude/settings.local.json` (same `pluginConfigs` path); recommend the consumer keep
+   `.claude/settings.local.json` gitignored if it is not already.
+
+## Output
+
+An updated project `.claude/settings.json` carrying `library_dir`, plus a one-line summary of the value
+written, its scope, and how to re-run this setup to reconfigure. Note in the summary that `library_dir`
+governs where the plugin's ingestion pipelines land synthesized artifacts — `/knowledge:book-distill`
+is unaffected, since it always writes to the target skill you name at invocation.
+
+## What this skill does NOT do
+
+- Run a distillation or ingestion — that is the plugin's pipeline skills (e.g. `/knowledge:book-distill`).
+- Write machine-local state — configuration lives in the consumer's tracked settings, never in the plugin
+  directory or the plugin data directory (`${CLAUDE_PLUGIN_DATA}` is for caches and generated state only).

plugins/teach/skills/teach/SKILL.md

@@ -10,7 +10,7 @@ disable-model-invocation: true
 
 Teach a user interactively across multiple sessions — not by lecturing, but by coaching through the Knowledge-Skills-Wisdom progression grounded in the user's real goals. Maintains persistent learning state so each session builds on prior understanding.
 
-**Use when:** user asks to learn across sessions (`teach me`, `study session`, `help me learn`, `onboard me to`). **Skip when:** one-off inline question (answer directly); task-context codebase investigation (use the project's own code-exploration tooling); extracting book knowledge to a reference file (`/book-distill:book-distill` when installed).
+**Use when:** user asks to learn across sessions (`teach me`, `study session`, `help me learn`, `onboard me to`). **Skip when:** one-off inline question (answer directly); task-context codebase investigation (use the project's own code-exploration tooling); extracting book knowledge to a reference file (`/knowledge:book-distill` when installed).
 
 Two modes share pedagogy but differ in source material:
 
@@ -206,6 +206,6 @@ Learning artifacts persist for months; durable teaching content (references, glo
 ## What This Skill Does NOT Do
 
 - **Does not write production code** — teaches understanding, not implementation. Use the project's own implementation workflow for code changes
-- **Does not replace `/book-distill:book-distill`** — that extracts book knowledge into skill reference files; `/teach:teach` delivers knowledge interactively to the user
+- **Does not replace `/knowledge:book-distill`** — that extracts book knowledge into skill reference files; `/teach:teach` delivers knowledge interactively to the user
 - **Does not do task-context codebase investigation** — that's for the project's code-exploration tooling; `/teach:teach codebase` is structured learning for understanding
 - **Does not auto-invoke** — `disable-model-invocation: true`. The user initiates learning sessions