@falkenslab/agent-kit 0.14.0 → 0.16.0

package/README.md

@@ -1,110 +1,110 @@
-<h1>
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-readme-dark.svg">
-    <img src="docs/assets/logo-readme.svg" alt="agent-kit" height="64">
-  </picture>
-</h1>
-
-[![npm](https://img.shields.io/npm/v/@falkenslab/agent-kit?logo=npm)](https://www.npmjs.com/package/@falkenslab/agent-kit)
-[![npm downloads](https://img.shields.io/npm/dm/@falkenslab/agent-kit)](https://www.npmjs.com/package/@falkenslab/agent-kit)
-[![types](https://img.shields.io/npm/types/@falkenslab/agent-kit)](https://www.npmjs.com/package/@falkenslab/agent-kit)
-[![node](https://img.shields.io/node/v/@falkenslab/agent-kit)](https://nodejs.org/)
-[![license](https://img.shields.io/npm/l/@falkenslab/agent-kit)](LICENSE)
-[![docs](https://img.shields.io/badge/docs-falkenslab.github.io%2Fagent--kit-4453b8)](https://falkenslab.github.io/agent-kit/)
-
-A foundation for building AI agents on top of the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk). It isn't an agent itself: it solves once what every agent needs (human oversight, safety, memory and a good terminal interface), so each concrete agent only has to write what belongs to its own domain: what it knows how to do, with which tools, and how it talks.
-
-## What an agent built with it can do
-
-- **Work at different levels of oversight.** Autonomous, guided (it asks for permission before anything that can't be undone or that other people will see) or step by step (it asks before every action), and a plan mode where it only reads and plans until you let it act. Within the same conversation you can switch among guided, step by step and plan.
-- **Ask a person for help.** It asks for approvals, or stops so someone can do something by hand, such as signing in to a website. It can be answered from the keyboard or from another program driving it, for example a desktop app.
-- **Remember between sessions.** It keeps its own knowledge base, a small wiki of notes that grows with every session, and keeps the original documents you give it or that it downloads untouched. Each conversation stays in the project's folder, so you can pick it up again with `--continue` (the latest one) or `/resume` (any of them).
-- **Speak your language.** Its interface comes in English, Spanish, French or German, the system's by default or the one you ask for with `--language=fr`, and it answers in that language unless you write to it in another one.
-- **Delegate to subagents safely.** Only to the ones it declares, always waiting for their result, and without the main agent being able to slip past its own limits through them.
-- **Stay within limits.** It only reads and writes in the folders that belong to it, and never in protected files, such as one holding passwords.
-- **Use external tools.** MCP servers of its own or of the project, and skills and commands organized in plugins.
-- **Leave a trail.** It records every action and the whole conversation, with secrets hidden.
-- **Look the way you want.** The terminal's colors come from a theme by roles (the agent's replies, tool results, the focused option, borders…): pass only the ones you want to change, as a color name, a hex or a function.
-- **Chat in a terminal the way Claude Code does.** Full screen, with the reply written live and its markdown already formatted, the tools it uses summed up in one line (Ctrl+O unfolds it), panels for approvals, history and search, a suggestion for the next message, pasted blocks, file mentions with `@`, mouse selection (right-click to copy), and the agent's status in the tab and in the Windows taskbar.
-- **Also work without a terminal.** The same foundation runs inside a desktop app or a server, which bring their own interface.
-
-## Examples
-
-### Captain Whiskers
-
-[Captain Whiskers](./examples/captain-whiskers) is a toy agent to see the kit in action: a retired pirate cat who tells jokes in the terminal, in your language. It starts full screen with its logo and has a small crew of subagents: one looks for new jokes on the web, another rates them before they're told, and a third tells the time with a tool of the captain's own. It lets you try the different levels of oversight and is the best starting point for an agent of your own. Its README explains how to run it.
-
-![Captain Whiskers in Windows Terminal: its logo at the top, the conversation in the middle and the framed prompt at the bottom, with a suggestion for the next message](docs/assets/captain-whiskers.png)
-
-### teacher-agent
-
-[teacher-agent](https://github.com/falkenslab/teacher-agent) is a real assistant for Moodle teachers. It signs in with your account in a Chrome window and works as you would: it grades submissions, answers in the forum, creates or reviews content and sums up how the class is going. It asks for your permission before publishing anything students will see, and takes notes about the course to remember everything in the next session.
-
-Oversight, memory, safety and the chat come from the kit; teacher-agent brings what it knows about Moodle and driving the browser.
-
-## Installation
-
-```
-npm install @falkenslab/agent-kit
-```
-
-To try changes to the kit without publishing them, point to a local clone with `"file:../agent-kit"` in your `package.json` and build it with `npm run build` after each change.
-
-Requires Node.js 20 or later.
-
-## A minimal agent
-
-An agent only describes what belongs to it (who it is, which MCP servers, skills and subagents it has) and picks a level of oversight; the kit sets up the session and the chat:
-
-```ts
-import path from "node:path";
-import { buildSessionOptions, ensureClaudeAuth, runChatInk, type AgentSpec, type BaseSessionConfig } from "@falkenslab/agent-kit";
-
-// The only part specific to the agent: who it is and what it has.
-const spec: AgentSpec<BaseSessionConfig> = {
-  buildSystemPrompt: () => "You are a pirate cat who tells jokes. Always answer in character.",
-  buildMcpServers: () => ({}), // its own MCP servers, if any
-  pluginRoots: () => [], // folders with skills and commands
-  buildSubagents: () => undefined, // subagents, if it delegates to any
-};
-
-await ensureClaudeAuth(); // offers to create a Claude token if it finds none
-
-const config: BaseSessionConfig = { mode: "guided", projectDir: process.cwd() };
-
-// Each run gets a folder of its own under .run/ (keep it out of git): its log, its
-// transcript and the conversation, to pick it up again with --continue or /resume.
-await runChatInk((run) => buildSessionOptions(config, run.dir, spec, { run }), {
-  runsDir: path.resolve(".run"),
-  header: { title: "My agent" },
-  mode: config.mode, // Shift+Tab cycles through guided, step by step and plan
-  fullscreen: true,
-  theme: { toolResult: "gray", selection: "#ffb86c" }, // only the colors you want to change
-});
-```
-
-Save it as `agent.ts` in a project with the kit and `tsx` installed and `"type": "module"` in its `package.json`, and run it with `npx tsx agent.ts`. Captain Whiskers is this same skeleton with more pieces: skills, subagents and its logo.
-
-## Documentation
-
-The full documentation is at **[falkenslab.github.io/agent-kit](https://falkenslab.github.io/agent-kit/)**: a tutorial, guides for every part of the kit (modes, human in the loop, security, tools, subagents, the knowledge base, the terminal UI, runs, languages, themes, hosts without a terminal), recipes, and an API reference generated from the source, for each released version.
-
-For whoever works on the kit itself, the specification in [`.minispec/`](./.minispec/README.md) explains how each part is built and why, including the SDK behaviors checked by hand that motivate several of its safeguards.
-
-## Development
-
-| Command | What it does |
-| --- | --- |
-| `npm run build` | Builds the kit into `dist/` |
-| `npm run typecheck` | Checks the types without building |
-| `npm run lint` | Checks the code style |
-| `npm test` | Runs all the tests |
-| `npm run docs:install` | Installs the documentation site's dependencies (once) |
-| `npm run docs:start` | Serves the documentation site locally, reloading on changes |
-| `npm run docs:build` | Builds the documentation site (fails on broken links) |
-
-To run a single test file:
-
-```
-npx tsx --test test/tui/promptErrors.test.ts
-```
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-readme-dark.svg">
+    <img src="docs/assets/logo-readme.svg" alt="agent-kit" height="64">
+  </picture>
+</h1>
+
+[![npm](https://img.shields.io/npm/v/@falkenslab/agent-kit?logo=npm)](https://www.npmjs.com/package/@falkenslab/agent-kit)
+[![npm downloads](https://img.shields.io/npm/dm/@falkenslab/agent-kit)](https://www.npmjs.com/package/@falkenslab/agent-kit)
+[![types](https://img.shields.io/npm/types/@falkenslab/agent-kit)](https://www.npmjs.com/package/@falkenslab/agent-kit)
+[![node](https://img.shields.io/node/v/@falkenslab/agent-kit)](https://nodejs.org/)
+[![license](https://img.shields.io/npm/l/@falkenslab/agent-kit)](LICENSE)
+[![docs](https://img.shields.io/badge/docs-falkenslab.github.io%2Fagent--kit-4453b8)](https://falkenslab.github.io/agent-kit/)
+
+A foundation for building AI agents on top of the [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk). It isn't an agent itself: it solves once what every agent needs (human oversight, safety, memory and a good terminal interface), so each concrete agent only has to write what belongs to its own domain: what it knows how to do, with which tools, and how it talks.
+
+## What an agent built with it can do
+
+- **Work at different levels of oversight.** Autonomous, guided (it asks for permission before anything that can't be undone or that other people will see) or step by step (it asks before every action), and a plan mode where it only reads and plans until you let it act. Within the same conversation you can switch among guided, step by step and plan.
+- **Ask a person for help.** It asks for approvals, or stops so someone can do something by hand, such as signing in to a website. It can be answered from the keyboard or from another program driving it, for example a desktop app.
+- **Remember between sessions.** It keeps its own knowledge base, a small wiki of notes that grows with every session, and keeps the original documents you give it or that it downloads untouched. Each conversation stays in the project's folder, so you can pick it up again with `--continue` (the latest one) or `/resume` (any of them).
+- **Speak your language.** Its interface comes in English, Spanish, French or German, the system's by default or the one you ask for with `--language=fr`, and it answers in that language unless you write to it in another one.
+- **Delegate to subagents safely.** Only to the ones it declares, always waiting for their result, and without the main agent being able to slip past its own limits through them.
+- **Stay within limits.** It only reads and writes in the folders that belong to it, and never in protected files, such as one holding passwords.
+- **Use external tools.** MCP servers of its own or of the project, and skills and commands organized in plugins.
+- **Leave a trail.** It records every action and the whole conversation, with secrets hidden.
+- **Look the way you want.** The terminal's colors come from a theme by roles (the agent's replies, tool results, the focused option, borders…): pass only the ones you want to change, as a color name, a hex or a function.
+- **Chat in a terminal the way Claude Code does.** Full screen, with the reply written live and its markdown already formatted, the tools it uses shown in as much detail as the agent chooses (each call with its result, the calls alone, or one line per group; Ctrl+O unfolds them), panels for approvals, history and search, a suggestion for the next message, pasted blocks, file mentions with `@`, mouse selection (right-click to copy), and the agent's status in the tab and in the Windows taskbar.
+- **Also work without a terminal.** The same foundation runs inside a desktop app or a server, which bring their own interface.
+
+## Examples
+
+### Captain Whiskers
+
+[Captain Whiskers](./examples/captain-whiskers) is a toy agent to see the kit in action: a retired pirate cat who tells jokes in the terminal, in your language. It starts full screen with its logo and has a small crew of subagents: one looks for new jokes on the web, another rates them before they're told, and a third tells the time with a tool of the captain's own. It lets you try the different levels of oversight and is the best starting point for an agent of your own. Its README explains how to run it.
+
+![Captain Whiskers in Windows Terminal: its logo at the top, the conversation in the middle and the framed prompt at the bottom, with a suggestion for the next message](docs/assets/captain-whiskers.png)
+
+### teacher-agent
+
+[teacher-agent](https://github.com/falkenslab/teacher-agent) is a real assistant for Moodle teachers. It signs in with your account in a Chrome window and works as you would: it grades submissions, answers in the forum, creates or reviews content and sums up how the class is going. It asks for your permission before publishing anything students will see, and takes notes about the course to remember everything in the next session.
+
+Oversight, memory, safety and the chat come from the kit; teacher-agent brings what it knows about Moodle and driving the browser.
+
+## Installation
+
+```
+npm install @falkenslab/agent-kit
+```
+
+To try changes to the kit without publishing them, point to a local clone with `"file:../agent-kit"` in your `package.json` and build it with `npm run build` after each change.
+
+Requires Node.js 20 or later.
+
+## A minimal agent
+
+An agent only describes what belongs to it (who it is, which MCP servers, skills and subagents it has) and picks a level of oversight; the kit sets up the session and the chat:
+
+```ts
+import path from "node:path";
+import { buildSessionOptions, ensureClaudeAuth, runChatInk, type AgentSpec, type BaseSessionConfig } from "@falkenslab/agent-kit";
+
+// The only part specific to the agent: who it is and what it has.
+const spec: AgentSpec<BaseSessionConfig> = {
+  buildSystemPrompt: () => "You are a pirate cat who tells jokes. Always answer in character.",
+  buildMcpServers: () => ({}), // its own MCP servers, if any
+  pluginRoots: () => [], // folders with skills and commands
+  buildSubagents: () => undefined, // subagents, if it delegates to any
+};
+
+await ensureClaudeAuth(); // offers to create a Claude token if it finds none
+
+const config: BaseSessionConfig = { mode: "guided", projectDir: process.cwd() };
+
+// Each run gets a folder of its own under .run/ (keep it out of git): its log, its
+// transcript and the conversation, to pick it up again with --continue or /resume.
+await runChatInk((run) => buildSessionOptions(config, run.dir, spec, { run }), {
+  runsDir: path.resolve(".run"),
+  header: { title: "My agent" },
+  mode: config.mode, // Shift+Tab cycles through guided, step by step and plan
+  fullscreen: true,
+  theme: { toolResult: "gray", selection: "#ffb86c" }, // only the colors you want to change
+});
+```
+
+Save it as `agent.ts` in a project with the kit and `tsx` installed and `"type": "module"` in its `package.json`, and run it with `npx tsx agent.ts`. Captain Whiskers is this same skeleton with more pieces: skills, subagents and its logo.
+
+## Documentation
+
+The full documentation is at **[falkenslab.github.io/agent-kit](https://falkenslab.github.io/agent-kit/)**: a tutorial, guides for every part of the kit (modes, human in the loop, security, tools, subagents, the knowledge base, the terminal UI, runs, languages, themes, hosts without a terminal), recipes, and an API reference generated from the source, for each released version.
+
+For whoever works on the kit itself, the specification in [`.minispec/`](./.minispec/README.md) explains how each part is built and why, including the SDK behaviors checked by hand that motivate several of its safeguards.
+
+## Development
+
+| Command | What it does |
+| --- | --- |
+| `npm run build` | Builds the kit into `dist/` |
+| `npm run typecheck` | Checks the types without building |
+| `npm run lint` | Checks the code style |
+| `npm test` | Runs all the tests |
+| `npm run docs:install` | Installs the documentation site's dependencies (once) |
+| `npm run docs:start` | Serves the documentation site locally, reloading on changes |
+| `npm run docs:build` | Builds the documentation site (fails on broken links) |
+
+To run a single test file:
+
+```
+npx tsx --test test/tui/promptErrors.test.ts
+```

package/assets/knowledge-plugin/.claude-plugin/plugin.json

@@ -1,4 +1,4 @@
 {
   "name": "knowledge",
-  "description": "Built-in knowledge base workflows (an LLM wiki): page templates, ingesting sources, querying the knowledge base and health-checking it."
+  "description": "Built-in knowledge base workflows (an LLM wiki) over the kit's knowledge_* tools: ingesting sources, querying the knowledge base and health-checking it."
 }

package/assets/knowledge-plugin/commands/ingest.md

@@ -4,4 +4,4 @@ description: Ingest material into the knowledge base right now - the files or to
 
 Apply the `knowledge-ingest` skill right now to: $ARGUMENTS
 
-If nothing is given above, find every file in the sources folder that has no summary page in the knowledge base yet (check `index.md` and `summaries/`) and ingest them all. When you're done, summarize which pages you created and updated, and anything you couldn't read.
+If nothing is given above, ingest every original `list_sources` reports as new, and update the summaries of the ones it reports as changed. When you're done, summarize which pages you created and updated, and anything you couldn't read.

package/assets/knowledge-plugin/commands/lint.md

@@ -2,4 +2,4 @@
 description: Health-check the knowledge base right now - broken links, orphans, duplicates, contradictions, gaps
 ---
 
-Apply the `knowledge-lint` skill right now over the whole knowledge base. Fix what's mechanical (links, index, missing back-links) and report the rest: what needs the human's decision, and the gaps worth filling next.
+Apply the `knowledge-lint` skill right now over the whole knowledge base. Fix what's mechanical (broken links, orphans, links to retired pages) and report the rest: what needs the human's decision, and the gaps worth filling next.

package/assets/knowledge-plugin/skills/knowledge-ingest/SKILL.md

@@ -1,42 +1,36 @@
 ---
 name: knowledge-ingest
-description: Ingest one source into the knowledge base - a file in sources/, a document, a page - creating its summary page, creating or updating the concept and entity pages it touches, linking everything both ways, and updating index.md and log.md.
+description: Ingest one source into the knowledge base - an original in sources/, a document, a page - creating its summary page, creating or updating the concept and entity pages it touches, and logging it.
 ---
 
 # Ingesting a source into the knowledge base
 
-A source is ingested once, and from then on the knowledge base holds what it taught: later sessions read the pages, not the original again. Ingesting is not summarizing a file in isolation - its value is in how it connects to what the knowledge base already knows. Load the `knowledge-pages` skill first for the page templates.
+A source is ingested once, and from then on the knowledge base holds what it taught: later sessions read the pages, not the original again. Its value is in how it connects to what the knowledge base already knows. Work only through the `knowledge_*` tools; links between pages are ids, `[Bowline](concept/bowline)`, and the index and backlinks are kept for you.
 
 ## 1. Check it isn't already ingested
 
-Look for it in `index.md` (Summaries) or `Grep` its file name or URL inside the knowledge base. If it already has a page:
-- unchanged source: nothing to do;
-- the source changed or the page is thin: update that page instead of creating another.
+`list_sources` gives each original's status and summary pages: *new* needs ingesting; *ingested* has a page; *changed* changed after its ingest (update its summary). For a document from elsewhere, `knowledge_search` its title or URL.
 
 ## 2. Read it for real
 
-Read the whole source, not its first page. If it exists only outside the sources folder (a downloaded document, a remote file), save it with `save_to_sources` first, so the original is kept as obtained.
+Read the whole source, not its first page (a long PDF in parts: `list_sources` gives its pages). Its path is `sources/<path>` in the project folder, not in this skill's folder. `Read` reads PDFs and images; `extract_text` reads DOCX, PPTX (with its speaker notes) and XLSX. If it exists only outside the sources folder, keep the original first: `download_to_sources` for a URL (a web page is kept as markdown too: read that one), `save_to_sources` for a file in the run's folder, `request_file` to ask the person for one.
 
 ## 3. Write the summary page
 
-Create `summaries/<slug>.md` with the template: summary, key points (literal wording where exactness matters), frontmatter `file`/`url` pointing to the original.
+`knowledge_create` with type `summary` (call it once without content to get the template), and the field `file` (the original, relative to sources/) or `url`. Key points quote literally where exactness matters. Create the new concept and entity pages it feeds in the same call (`also`): they can link to each other.
 
 ## 4. Update concepts and entities
 
-For every concept or entity the source explains or relies on:
-- no page yet: create it;
-- page exists: add what is new (a better definition, an example, a nuance, a fact) with `Edit`, and link the summary under "Sources".
+For every concept or entity the source explains or relies on, `knowledge_search` it first (under other names and aliases too: a duplicate page is worse than none):
+- no page yet: create it, with the summary (`also`) or on its own;
+- page exists: add what is new (a better definition, an example, a nuance) with `knowledge_edit`, and link the summary under its sources.
 
-Check first whether it exists under another name (`Grep` the knowledge base for the term and look at `aliases`): a duplicate page is worse than none.
+If the source contradicts a page, record both versions with attribution in both pages; don't overwrite.
 
-## 5. Link both ways and look for conflicts
+## 5. Close
 
-Every link you added from page A to page B needs its counterpart in B. If the source contradicts an existing page, record both versions with attribution in both pages - don't overwrite.
+`knowledge_log` with operation `ingest`, the source's title and the pages created and updated. Rewrite the `overview` (`knowledge_rewrite`) only if the source changes the big picture. When ingesting several sources in a row, log once at the end.
 
-## 6. Close
+## An original that was wrong or replaced
 
-- `index.md`: new pages, and one-line descriptions that changed.
-- `log.md`: `## [date] ingest | <source title>` with the pages created and updated.
-- `overview.md`: only if the source changes the big picture.
-
-When ingesting several sources in a row, do steps 1-5 for each and close once at the end.
+`retire_source` (the person approves it) moves it aside and marks its summary retired (wrong) or superseded (replaced). Then `knowledge_check` lists the passages that cite it: after a wrong one, correct or remove what it taught (`knowledge_edit`, or `knowledge_retire` for a page that was only about it); after a replaced one, ingest the new original and re-ground those passages on it.

package/assets/knowledge-plugin/skills/knowledge-lint/SKILL.md

@@ -1,26 +1,30 @@
 ---
 name: knowledge-lint
-description: Health-check the knowledge base - broken links, pages missing from index.md, orphan pages, one-way links, duplicated concepts, mentioned-but-missing concepts, contradictions, gaps - fix what's mechanical and report the rest.
+description: Health-check the knowledge base - broken links, orphan pages, links to retired pages, missing or changed originals, duplicated concepts, mentioned-but-missing concepts, contradictions, gaps - fix what's mechanical and report the rest.
 ---
 
 # Linting the knowledge base
 
-A knowledge base maintained across sessions drifts: links break, pages go unlisted, the same concept appears under two names. Lint it when asked and after a large ingest. Load `knowledge-pages` first for the templates.
+A knowledge base maintained across sessions drifts. Lint it when asked and after a large ingest.
 
-## Checks
+## 1. The mechanical checks, in one call
 
-Use `Glob` to list pages and `Grep` (always with `path` inside the knowledge base) to find links, instead of reading every page in full.
+`knowledge_check` returns broken links, orphan pages, links to retired pages, summaries whose original is gone, originals that are new, changed or missing, and the passages that cite a retired original. The index and backlinks are kept by the store: there's nothing to fix there.
 
-1. **Broken links**: a relative link whose target file doesn't exist. Fix it if the right target is obvious (a typo, a page under a close name); otherwise report it.
-2. **Index**: every page is listed in `index.md` and every entry there points to an existing page. Fix it.
-3. **Orphans**: pages nothing links to (`Grep` for the file name). Link them from where they belong, or report why they don't belong anywhere.
-4. **One-way links**: a summary that feeds a concept which doesn't list it back... Add the missing side.
-5. **Duplicates**: two pages for the same idea under different names. Merge the content into one, mark the other as superseded (never delete it) and repoint links.
-6. **Missing pages**: terms that several pages treat as concepts or entities but have no page. Create them if the material is there; otherwise list them.
-7. **Contradictions**: claims that disagree across pages without being recorded as such. Record both sides, attributed.
-8. **Provenance**: claims with no traceable source. Add the link, or mark them as unsourced.
-9. **Gaps**: files in the sources folder with no summary page yet, concepts mentioned but never explained by any source. Report them - they are what to ingest or find next.
+- **Broken links**: fix them with `knowledge_edit` when the right target is obvious (a typo, a page under a close name: `knowledge_search`); otherwise report them.
+- **Orphans**: link them from the pages where they belong, or report why they don't belong anywhere.
+- **Links to retired pages, passages citing a retired original**: correct or re-ground them.
+- **New or changed originals**: report them as what to ingest or update next (or do it, if asked).
+
+## 2. The checks that need judgement
+
+Use `knowledge_index` and `knowledge_search`; read only the pages a check needs.
+
+- **Duplicates**: two pages for the same idea under different names. Merge the content into one with `knowledge_edit`, `knowledge_supersede` the other (never delete it) and repoint links.
+- **Missing pages**: terms that several pages treat as concepts or entities but have no page. Create them if the material is there; otherwise list them.
+- **Contradictions**: claims that disagree across pages without being recorded as such. Record both sides, attributed.
+- **Provenance**: claims with no traceable source. Add the link, or mark them as unsourced.
 
 ## Close
 
-Append `## [date] lint | <summary>` to `log.md` listing what was fixed. Then report to the human: what you fixed, and what needs their decision or more material. Don't make judgement calls silently - merging pages that are only similar, or choosing between contradictory sources, goes in the report.
+`knowledge_log` with operation `lint` and what was fixed. Then report to the person: what you fixed, and what needs their decision or more material. Don't make judgement calls silently: merging pages that are only similar, or choosing between contradictory sources, goes in the report.

package/assets/knowledge-plugin/skills/knowledge-query/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: knowledge-query
-description: Answer a question from the knowledge base - find the relevant pages through the index, read them, answer with links to them, and file the answer back as a synthesis page when it is worth keeping.
+description: Answer a question from the knowledge base - find the relevant pages, read them, answer citing them, and file the answer back as a synthesis page when it is worth keeping.
 ---
 
 # Querying the knowledge base
 
 The knowledge base exists so a question doesn't start from zero. Answer from it first; go back to the originals or the web only for what it doesn't hold.
 
-1. **Start from the index.** Read `index.md`, pick the pages that can matter, read those (not the whole knowledge base). `Grep` inside the knowledge base for terms and aliases the index doesn't reveal.
-2. **Answer from the pages**, linking each one you drew on. Say what comes from the knowledge base, what comes from an original in the sources folder (read it if the knowledge base is thin or contradictory) and what comes from outside (label it as such).
+1. **Find the pages.** `knowledge_search` the question's terms (and their synonyms), or `knowledge_index` for the catalog; `knowledge_read` only the pages that matter.
+2. **Answer from the pages**, citing each one you drew on. Say what comes from the knowledge base, what from an original in the sources folder (read it if the knowledge base is thin or contradictory) and what from outside (label it as such).
 3. **Say what is missing.** If the knowledge base can't answer part of the question, say so and name the source that would fill it, instead of filling the gap from memory silently.
-4. **File it back.** If the answer is a comparison, an analysis or a report that will be asked again, save it as `syntheses/<slug>.md` (template in `knowledge-pages`) with links to its inputs, add it to `index.md`, and log it: `## [date] query | <question>`. A quick factual answer needs no page.
-5. **Feed the knowledge base.** If answering revealed a concept or fact that has no page, or a contradiction, fix that in the knowledge base too and log it.
+4. **File it back.** If the answer is a comparison, an analysis or a report that will be asked again, `knowledge_create` a `synthesis` page with links to its inputs, and `knowledge_log` it (operation `query`). A quick factual answer needs no page.
+5. **Feed the knowledge base.** If answering revealed a concept with no page, or a contradiction, fix that too and log it.

package/assets/knowledge-plugin-files/.claude-plugin/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "knowledge",
+  "description": "Built-in knowledge base workflows (an LLM wiki): page templates, ingesting sources, querying the knowledge base and health-checking it."
+}

package/assets/knowledge-plugin-files/commands/ingest.md

@@ -0,0 +1,7 @@
+---
+description: Ingest material into the knowledge base right now - the files or topic given, or everything in sources/ not ingested yet
+---
+
+Apply the `knowledge-ingest` skill right now to: $ARGUMENTS
+
+If nothing is given above, ingest every original `list_sources` reports as new, and update the summaries of the ones it reports as changed. When you're done, summarize which pages you created and updated, and anything you couldn't read.

package/assets/knowledge-plugin-files/commands/lint.md

@@ -0,0 +1,5 @@
+---
+description: Health-check the knowledge base right now - broken links, orphans, duplicates, contradictions, gaps
+---
+
+Apply the `knowledge-lint` skill right now over the whole knowledge base. Fix what's mechanical (links, index, missing back-links) and report the rest: what needs the human's decision, and the gaps worth filling next.

package/assets/knowledge-plugin-files/commands/query.md

@@ -0,0 +1,5 @@
+---
+description: Answer a question from the knowledge base, and file the answer back if it is worth keeping
+---
+
+Apply the `knowledge-query` skill right now to answer: $ARGUMENTS

package/assets/knowledge-plugin-files/skills/knowledge-ingest/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: knowledge-ingest
+description: Ingest one source into the knowledge base - a file in sources/, a document, a page - creating its summary page, creating or updating the concept and entity pages it touches, linking everything both ways, and updating index.md and log.md.
+---
+
+# Ingesting a source into the knowledge base
+
+A source is ingested once, and from then on the knowledge base holds what it taught: later sessions read the pages, not the original again. Ingesting is not summarizing a file in isolation - its value is in how it connects to what the knowledge base already knows. Load the `knowledge-pages` skill first for the page templates.
+
+## 1. Check it isn't already ingested
+
+`list_sources` gives each original's status and summary pages: *new* needs ingesting; *ingested* has a page; *changed* changed after its ingest. For a document from elsewhere, look for it in `index.md` (Summaries) or `Grep` its URL inside the knowledge base. If it already has a page:
+- unchanged source: nothing to do;
+- the source changed or the page is thin: update that page instead of creating another.
+
+## 2. Read it for real
+
+Read the whole source, not its first page (a long PDF in parts: `list_sources` gives its pages). If it exists only outside the sources folder, keep the original first: `download_to_sources` for a URL (a web page is kept as markdown too: read that one), `save_to_sources` for a file in the run's folder, `request_file` to ask the person for one. `Read` reads PDFs and images; read DOCX, PPTX (with its speaker notes) and XLSX with `extract_text`.
+
+## 3. Write the summary page
+
+Create `summaries/<slug>.md` with the template: summary, key points (literal wording where exactness matters), frontmatter `file`/`url` pointing to the original.
+
+## 4. Update concepts and entities
+
+For every concept or entity the source explains or relies on:
+- no page yet: create it;
+- page exists: add what is new (a better definition, an example, a nuance, a fact) with `Edit`, and link the summary under "Sources".
+
+Check first whether it exists under another name (`Grep` the knowledge base for the term and look at `aliases`): a duplicate page is worse than none.
+
+## 5. Link both ways and look for conflicts
+
+Every link you added from page A to page B needs its counterpart in B. If the source contradicts an existing page, record both versions with attribution in both pages - don't overwrite.
+
+## 6. Close
+
+- `index.md`: new pages, and one-line descriptions that changed.
+- `log.md`: `## [date] ingest | <source title>` with the pages created and updated.
+- `overview.md`: only if the source changes the big picture.
+
+When ingesting several sources in a row, do steps 1-5 for each and close once at the end.
+
+## An original that was wrong or replaced
+
+`retire_source` (the person approves it) moves it aside and marks its summary retired (wrong) or superseded (replaced by a better one). Then update `index.md`, and fix the pages that cite it (`Grep` its file name): after a wrong one, correct or remove what it taught; after a replaced one, ingest the new original and re-ground those passages on it.

package/assets/knowledge-plugin-files/skills/knowledge-lint/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: knowledge-lint
+description: Health-check the knowledge base - broken links, pages missing from index.md, orphan pages, one-way links, duplicated concepts, mentioned-but-missing concepts, contradictions, gaps - fix what's mechanical and report the rest.
+---
+
+# Linting the knowledge base
+
+A knowledge base maintained across sessions drifts: links break, pages go unlisted, the same concept appears under two names. Lint it when asked and after a large ingest. Load `knowledge-pages` first for the templates.
+
+## Checks
+
+Use `Glob` to list pages and `Grep` (always with `path` inside the knowledge base) to find links, instead of reading every page in full.
+
+1. **Broken links**: a relative link whose target file doesn't exist. Fix it if the right target is obvious (a typo, a page under a close name); otherwise report it.
+2. **Index**: every page is listed in `index.md` and every entry there points to an existing page. Fix it.
+3. **Orphans**: pages nothing links to (`Grep` for the file name). Link them from where they belong, or report why they don't belong anywhere.
+4. **One-way links**: a summary that feeds a concept which doesn't list it back... Add the missing side.
+5. **Duplicates**: two pages for the same idea under different names. Merge the content into one, mark the other as superseded (never delete it) and repoint links.
+6. **Missing pages**: terms that several pages treat as concepts or entities but have no page. Create them if the material is there; otherwise list them.
+7. **Contradictions**: claims that disagree across pages without being recorded as such. Record both sides, attributed.
+8. **Provenance**: claims with no traceable source. Add the link, or mark them as unsourced.
+9. **Gaps**: originals `list_sources` reports as new (no summary yet), changed (their summary may be stale) or missing (deleted by hand: their summaries point nowhere), and concepts mentioned but never explained by any source. Report them - they are what to ingest, update or find next.
+
+## Close
+
+Append `## [date] lint | <summary>` to `log.md` listing what was fixed. Then report to the human: what you fixed, and what needs their decision or more material. Don't make judgement calls silently - merging pages that are only similar, or choosing between contradictory sources, goes in the report.

package/assets/knowledge-plugin-files/skills/knowledge-query/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: knowledge-query
+description: Answer a question from the knowledge base - find the relevant pages through the index, read them, answer with links to them, and file the answer back as a synthesis page when it is worth keeping.
+---
+
+# Querying the knowledge base
+
+The knowledge base exists so a question doesn't start from zero. Answer from it first; go back to the originals or the web only for what it doesn't hold.
+
+1. **Start from the index.** Read `index.md`, pick the pages that can matter, read those (not the whole knowledge base). `Grep` inside the knowledge base for terms and aliases the index doesn't reveal.
+2. **Answer from the pages**, linking each one you drew on. Say what comes from the knowledge base, what comes from an original in the sources folder (read it if the knowledge base is thin or contradictory) and what comes from outside (label it as such).
+3. **Say what is missing.** If the knowledge base can't answer part of the question, say so and name the source that would fill it, instead of filling the gap from memory silently.
+4. **File it back.** If the answer is a comparison, an analysis or a report that will be asked again, save it as `syntheses/<slug>.md` (template in `knowledge-pages`) with links to its inputs, add it to `index.md`, and log it: `## [date] query | <question>`. A quick factual answer needs no page.
+5. **Feed the knowledge base.** If answering revealed a concept or fact that has no page, or a contradiction, fix that in the knowledge base too and log it.

package/dist/core/agentSpec.d.ts

@@ -1,4 +1,5 @@
 import type { AgentDefinition as SdkSubagentDefinition, McpServerConfig, SettingSource } from "@anthropic-ai/claude-agent-sdk";
+import type { KnowledgeStore, PageType } from "./knowledgeStore.js";
 /**
  * The human-supervision spectrum every agent built on this kit shares, independent of
  * domain: "interactive" pauses before every single action, "guided" only pauses before a
@@ -49,6 +50,11 @@ export interface BaseSessionConfig {
      * language (see language.ts). Pass the same value to the chat, wizard or progress view.
      */
     language?: string;
+    /**
+     * The time zone the date and time tools answer in (`current_time`, `date_math`), an IANA
+     * name such as "Europe/Madrid"; the system's if not given.
+     */
+    timeZone?: string;
 }
 /**
  * Everything actually *about the domain* that `buildSessionOptions()` needs but doesn't
@@ -104,12 +110,31 @@ export interface AgentSpec<TConfig extends BaseSessionConfig> {
     /**
      * The built-in knowledge base (see knowledge.ts): when `config.knowledgeDir` is set, the kit
      * appends its "Knowledge base" rules to the system prompt and loads its plugin (skills
-     * knowledge-pages/knowledge-ingest/knowledge-query/knowledge-lint, commands /knowledge:ingest, /knowledge:query,
-     * /knowledge:lint), so the agent maintains its notes as an interlinked wiki. On by default;
+     * knowledge-ingest/knowledge-query/knowledge-lint, commands /knowledge:ingest, /knowledge:query,
+     * /knowledge:lint), so the agent maintains its notes as an interlinked wiki, through the
+     * `knowledge_*` tools by default (see `knowledgeTools`). On by default;
      * set `false` for an agent that writes its own rules for `knowledgeDir` (or wants plain
      * notes) — `knowledgePromptSection()`/`knowledgePluginRoot()` are exported to reuse the pieces.
      */
     knowledgeBase?: boolean;
+    /**
+     * How the agent reaches the built-in knowledge base: `"store"` (the default), only through
+     * the kit's `knowledge_*` tools over a `KnowledgeStore`, never with the file tools, so the
+     * storage can change and the wiki's rules are kept by code (ADR-024); `"files"`, with the
+     * file tools on `knowledgeDir` and the rules in the prompt, as before.
+     */
+    knowledgeTools?: "store" | "files";
+    /**
+     * The agent's own page types for the built-in knowledge base, besides the kit's four
+     * (summary, concept, entity, synthesis): each with its folder (`""` for the root), index
+     * section, description (told to the model) and template.
+     */
+    knowledgePageTypes?: PageType[];
+    /**
+     * The knowledge base's store, instead of the kit's over markdown files in `knowledgeDir`
+     * (e.g. a database or a vector store implementing `KnowledgeStore`).
+     */
+    knowledgeStore?(config: TConfig): KnowledgeStore;
     /**
      * Whether the kit tells the agent (and each subagent) to reply in the resolved language
      * (`config.language`, `--language`, the system's), following the human if they write in

package/dist/core/extractText.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Word, PowerPoint and Excel originals as markdown: the SDK's `Read` refuses DOCX and PPTX
+ * (confirmed empirically), and course material is often both. The libraries are optional
+ * peer dependencies of the kit (`mammoth` for DOCX, `fflate` to open PPTX and XLSX, which
+ * are zips of XML); without them the caller is told what to install.
+ */
+export declare const EXTRACTABLE: Set<string>;
+export declare class MissingLibraryError extends Error {
+    readonly library: string;
+    constructor(library: string, options?: ErrorOptions);
+}
+/** An original's text as markdown; `from`/`to` pick slides of a deck. */
+export declare function extractText(file: string, from?: number, to?: number): Promise<string>;