brain-framework 18.3.0__tar.gz → 18.5.0__tar.gz

{brain_framework-18.3.0 → brain_framework-18.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brain-framework
-Version: 18.3.0
+Version: 18.5.0
 Summary: 🧠 Brain Framework: from information to informed actions.
 Keywords: ai,ai-agents,agent-memory,context-engineering,knowledge-management,local-first,mcp,model-context-protocol,python,second-brain
 Author: Médéric Hurier
@@ -43,7 +43,7 @@ A second brain for you, your team and your AI agents, on your own computer. Gath
 
 [![CI](https://github.com/fmind/brain-framework/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fmind/brain-framework/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/brain-framework?color=174EA6)](https://pypi.org/project/brain-framework/) [![Python](https://img.shields.io/pypi/pyversions/brain-framework)](https://pypi.org/project/brain-framework/) [![License: MIT](https://img.shields.io/badge/license-MIT-174EA6)](https://github.com/fmind/brain-framework/blob/main/LICENSE)
 
-[Why](https://github.com/fmind/brain-framework#why-a-second-brain) · [How it works](https://github.com/fmind/brain-framework#how-it-works) · [Try it](https://github.com/fmind/brain-framework#try-it) · [Agents](https://github.com/fmind/brain-framework#open-your-agent-in-your-brain) · [Good to know](https://github.com/fmind/brain-framework#good-to-know) · [Four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/) · [Documentation](https://fmind.github.io/brain-framework/)
+[Why](https://github.com/fmind/brain-framework#why-a-second-brain) · [How it works](https://github.com/fmind/brain-framework#how-it-works) · [Try it](https://github.com/fmind/brain-framework#try-it) · [Agents](https://github.com/fmind/brain-framework#open-your-agent-in-your-brain) · [Good to know](https://github.com/fmind/brain-framework#good-to-know) · [Four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/) · [Documentation](https://fmind.github.io/brain-framework/)
 
 <a href="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-loop.svg">
   <img
@@ -84,7 +84,7 @@ Questions that once took a tour of your tools become one prompt, once you write
 - **Every source, even the ones no product connects.** Mail, calendar, documents, chat, issues and pull requests, of course. But also the release notes and security advisories of the tools you depend on, model retirement dates, provider incidents, mentions of your projects on Hacker News or Bluesky, your domains' certificates and mail security, repository traffic that GitHub forgets after 14 days and your past agent sessions. If you can script it, you can collect it.
 - **Unlimited integrations, both ways.** A sensor is a small program that prints JSON: wrap a CLI such as `gh`, `gws` or `gcloud`, call an API, drive a browser, query a database or parse an export. The same CLIs, APIs and MCP servers then let your agent act on what it learned: draft the issue, answer the thread, fix the alert.
 - **One vocabulary, one knowledge graph.** Each tool names things its own way. You declare a small ontology in `bf.yaml` and sensors map provider fields into it at collection, so the same project, person or repository connects across every tool. BF turns those explicit links into a graph you navigate in one read, each claim pointing back to its evidence.
-- **Private by design.** Your brain is a folder on your disk. BF has no account, server or telemetry and runs no AI model; search and read work offline.
+- **Private by design.** Your brain is a folder on your disk. BF has no account, server or telemetry and never runs a model itself: [prompts](https://fmind.github.io/brain-framework/docs/prompts/) launch your agent harness. Search and read work offline.
 - **Portable and versioned.** Markdown notes, JSON records and scripts: open them in any editor, grep them, copy them to another machine. Keep the brain in a private Git repository for history, rollback, review and conflict resolution.
 - **For you or your whole team.** A personal brain stays on your laptop. A team brain is a private Git repository with one clone per teammate, so decisions, reviewed evidence and next steps are shared by everyone and their agents. Your personal brain can include the team's in its searches.
 - **Any agent, guided by skills.** Claude Code, Codex, GitHub Copilot, Antigravity or your own agent reach the same brain through the `bf` command, packaged skills or MCP. The skills teach them to find evidence, keep notes current, connect sources and maintain the brain.
@@ -122,9 +122,10 @@ A brain gives your work the structure of a detective's case file, in plain files
 | `concepts/` | Knowledge you will reuse elsewhere, with its evidence and limits.            | “Explain the product before asking for signup.”                      |
 | `actions/`  | One work session: objective, inputs, outputs, outcome and next step.         | `actions/2026-09-27_website-review/ACTION.md`, resumed the next day. |
 | `routines/` | Deterministic programs you review, run on demand, on a schedule or from Git. | A weekly review that drafts an action listing projects to revisit.   |
+| `prompts/`  | Markdown prompts your agent harness runs; each run's reply is a record.      | An assistant that reviews new mail and chat every half hour.         |
 | `evals/`    | Saved questions with the evidence that search or read must return.           | “Why one page?” must return the project's Decision section.          |
 
-Notes are Markdown with YAML metadata, records are JSON, and `bf validate` checks both. The SQLite search cache in `.bf/` is disposable and rebuilds itself from the files. See the [file conventions](https://fmind.github.io/brain-framework/docs/brain/#directory-reference).
+Notes are Markdown with YAML metadata, records are JSON, and `bf validate` checks both. `bf init --full` creates `sensors/` and `routines/`; create `prompts/` when you add a [prompt](https://fmind.github.io/brain-framework/docs/prompts/). A prompt's records hold model output, so search weighs them at half, like a low-priority source. The SQLite search cache in `.bf/` is disposable and rebuilds itself from the files. See the [file conventions](https://fmind.github.io/brain-framework/docs/brain/#directory-reference).
 
 ### `bf.yaml`, the coordination hub
 
@@ -157,7 +158,7 @@ watch: # keep sources fresh and alert on failure
   notifications: failure
 ```
 
-BF runs each program with its configured arguments and no shell, bounds its time and output, validates what it prints and keeps its stderr in `logs/`. A failed run never changes your evidence. `bf watch` keeps due sensors and routines fresh in a terminal dashboard, and `bf schedule` generates native systemd, launchd or cron jobs for you to install. See [sensors](https://fmind.github.io/brain-framework/docs/sensors/), [routines](https://fmind.github.io/brain-framework/docs/routines/) and [watch and schedule](https://fmind.github.io/brain-framework/docs/schedule/).
+BF runs each program with its configured arguments and no shell, bounds its time and output, validates what it prints and keeps its stderr in `logs/`. A failed run never changes your evidence. `bf watch` keeps due sensors, routines and prompts fresh in a terminal dashboard, and `bf schedule` generates native systemd, launchd or cron jobs for you to install. See [sensors](https://fmind.github.io/brain-framework/docs/sensors/), [routines](https://fmind.github.io/brain-framework/docs/routines/) and [watch and schedule](https://fmind.github.io/brain-framework/docs/schedule/).
 
 ### One vocabulary, set at collection
 
@@ -181,22 +182,7 @@ Reading files gives you one document at a time, and grep finds words, not connec
 bf read project:new-website
 ```
 
-The reply holds the project note and its backlinks, grouped by relation: four records from four tools, side by side, in the shared vocabulary (trimmed here to refs, kinds and statuses):
-
-```json
-{
-  "relation": "project",
-  "total": 4,
-  "items": [
-    { "ref": "gcloud:deployment", "fields": { "kind": "deployment", "status": "healthy" } },
-    { "ref": "github:implementation", "fields": { "kind": "pull-request", "status": "merged" } },
-    { "ref": "jira:review", "fields": { "kind": "issue", "status": "In review" } },
-    { "ref": "workspace:brief", "fields": { "kind": "brief", "status": "approved" } }
-  ]
-}
-```
-
-From there, follow typed [relations](https://fmind.github.io/brain-framework/docs/links/#name-a-relation) such as `author`, `owner`, `depends-on` or your own. Each claim keeps the note section or record that asserted it, so an answer can always cite its evidence. `bf export` prints the whole graph as JSON Lines for DuckDB or networkx.
+The reply holds the project note and its backlinks, grouped by relation: under `project`, four records from four tools side by side in the shared vocabulary, the Jira review `In review`, the GitHub pull request `merged`, the Gcloud deployment `healthy` and the Workspace brief `approved`. The [four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/#collect-four-tools) shows the reply. From there, follow typed [relations](https://fmind.github.io/brain-framework/docs/links/#name-a-relation) such as `author`, `owner`, `depends-on` or your own. Each claim keeps the note section or record that asserted it, so an answer can always cite its evidence. `bf export` prints the whole graph as JSON Lines for DuckDB or networkx.
 
 ### Act, then learn
 
@@ -210,64 +196,22 @@ Retrieval assembles the context; people and agents do the work, through the CLIs
   >
 </a>
 
-The graph keeps conclusions current. Each project knows the evidence it links to: when a linked record changes after the note's last edit, `bf read` flags the project for review and names the record to read first, so a decision does not silently outlive its linked evidence. Try it in the [four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/#follow-a-change). [Routines](https://fmind.github.io/brain-framework/docs/routines/) run deterministic reviews and checks, such as a weekly review action or `bf validate` before each Git commit, and retrieval cases in `evals/` confirm that the questions you rely on still find their evidence as the brain grows.
+The graph keeps conclusions current. Each project knows the evidence it links to: when a linked record changes after the note's last edit, `bf read` flags the project for review and names the record to read first, so a decision does not silently outlive its linked evidence. Try it in the [four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/#follow-a-change). [Routines](https://fmind.github.io/brain-framework/docs/routines/) run deterministic reviews and checks, such as a weekly review action or `bf validate` before each Git commit, and retrieval cases in `evals/` confirm that the questions you rely on still find their evidence as the brain grows.
 
 ## Try it
 
-Start with one decision you can find again. You need Linux or macOS and [uv](https://docs.astral.sh/uv/getting-started/installation/), which installs the tested Python 3.14 if needed ([install details](https://fmind.github.io/brain-framework/docs/upgrades/#install)). No model or provider account is required.
+You need Linux or macOS and [uv](https://docs.astral.sh/uv/getting-started/installation/), which installs the tested Python 3.14 if needed ([install details](https://fmind.github.io/brain-framework/docs/upgrades/#install)). No model or provider account is required.
 
 ```bash
 uv tool install --python 3.14 brain-framework
 bf --version
 ```
 
-If your shell cannot find `bf`, run `uv tool update-shell` and open a new shell. Then create your brain:
-
-```bash
-bf init ~/brain
-cd ~/brain
-```
-
-Create `projects/new-website.md` in your editor, or ask your agent to save this fictional decision. Use today's date for `updated`:
-
-```markdown
----
-type: project
-status: draft
-updated: 2026-09-27
-summary: Launch a product website that helps visitors understand the product.
----
-
-# New website
-
-## Decision
-
-Start with a single product page because visitors need a clear explanation before signing up.
-
-## Next actions
-
-- [ ] Draft the product page.
-```
-
-Find the reason, read its source and check the brain:
-
-```bash
-bf search "visitors clear explanation"
-bf read projects/new-website.md#decision
-bf validate
-```
-
-Search returns this match in `items` (other fields omitted):
-
-```json
-{ "ref": "projects/new-website.md#decision", "title": "New website — Decision" }
-```
-
-`read` returns the original Decision section with its note's status and date, and validation reports `"valid":true`. Edit the note and search again: BF notices changes on its own. The [getting-started guide](https://fmind.github.io/brain-framework/docs/getting-started/) continues with a first collected source and a link from the decision to its evidence, and the [four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/) runs the whole loop offline on fictional Workspace, Jira, GitHub and Gcloud records.
+Then follow [Getting started](https://fmind.github.io/brain-framework/docs/getting-started/): create a brain, save a decision, find its reason and link it to a first collected source. The [four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/) then runs the whole loop offline on fictional Workspace, Jira, GitHub and Gcloud records.
 
 ## Open your agent in your brain
 
-Use the same brain with [Claude Code](https://code.claude.com/docs/en/overview), [Codex](https://openai.com/codex/), [GitHub Copilot](https://github.com/features/copilot) or any agent host that can run a command. Start your terminal agent in `~/brain` and give it this prompt:
+Use the same brain with [Claude Code](https://code.claude.com/docs/en/overview), [Codex](https://openai.com/codex/), [GitHub Copilot](https://github.com/features/copilot) or any agent host that can run a command. After Getting started, start your terminal agent in `~/brain` and give it this prompt:
 
 > Use the bf CLI. Find why we chose a single product page. Read the source, cite its ref and tell me the project's next action.
 
@@ -284,11 +228,9 @@ Each host reads its own folder: for Claude Code, use `~/.claude/skills` instead.
 | `bf-use`      | Find evidence, cite it, and keep projects and concepts current.                 |
 | `bf-action`   | Start, resume and hand off a tracked work session: `/bf-action website-review`. |
 | `bf-setup`    | Install BF, create a brain, connect the agent and choose sources worth adding.  |
-| `bf-maintain` | Run sensors and routines, check the brain and upgrade it safely.                |
-
-Working in a code repository instead? The [example session hook](https://github.com/fmind/brain-framework/tree/main/examples/hooks) prints the project that declares the repository, its next task and linked evidence when the session starts. Hosts that prefer tools can call `search` and `read` through [MCP](https://fmind.github.io/brain-framework/docs/mcp/). See the [agent guide](https://fmind.github.io/brain-framework/docs/agents/).
+| `bf-maintain` | Run sensors, routines and prompts, check the brain and upgrade it safely.       |
 
-Agents can read this documentation as Markdown: [llms.txt](https://fmind.github.io/brain-framework/llms.txt) indexes every guide with a summary, [llms-full.txt](https://fmind.github.io/brain-framework/llms-full.txt) holds their full text, and each guide's Markdown sits at its URL followed by `index.md`.
+Working in a code repository instead? The [example session hook](https://github.com/fmind/brain-framework/tree/main/examples/hooks) prints the project that declares the repository, its next task and linked evidence when the session starts. During collection, a usable cached reply carries an “Index refreshing” note. Hosts that prefer tools can call `search` and `read` through [MCP](https://fmind.github.io/brain-framework/docs/mcp/). See the [agent guide](https://fmind.github.io/brain-framework/docs/agents/), which also points agents to this documentation as Markdown.
 
 ## Bring your tools
 
@@ -323,7 +265,7 @@ A brain is a folder, so Git gives it history, rollback, review and conflict reso
 
 1. **It runs on your computer, not in someone else's cloud.** That is a feature: your agent works where you can watch it, interrupt it and inspect every file it reads or writes, instead of a black box on a remote server. Sensors collect while your machine is on, through `bf watch` or a native schedule.
 1. **It takes some setup.** Each source needs its access: an API key, `gh auth login`, `gws` or `gcloud` authentication, then a sensor you review. Providers ship better CLIs and MCP servers every month, so this keeps getting easier, and the `bf-setup` skill walks your agent through it.
-1. **It needs an agent harness for the reasoning.** BF runs no model: it collects, validates, searches and connects. Claude Code, Codex, Copilot, Antigravity or another harness does the thinking, so the privacy of what your agent reads depends on that harness's data terms. BF sends no telemetry or personal data to us; see [privacy and security](https://fmind.github.io/brain-framework/docs/privacy/) for a fully local setup.
+1. **It needs an agent harness for the reasoning.** BF never runs a model itself: it collects, validates, searches and connects, and its [prompts](https://fmind.github.io/brain-framework/docs/prompts/) launch your harness. Claude Code, Codex, Copilot, Antigravity or another harness does the thinking, so the privacy of what your agent reads depends on that harness's data terms. BF sends no telemetry or personal data to us; see [privacy and security](https://fmind.github.io/brain-framework/docs/privacy/) for a fully local setup.
 1. **It finds what was said and linked, not what was meant.** Search matches words and explicit identities, without embeddings, and incomplete results say so. Search and read never contact providers: collect again when you need newer evidence. See [what BF does not do](https://fmind.github.io/brain-framework/docs/concepts/#what-bf-does-not-do).
 
 [Browse the commands](https://fmind.github.io/brain-framework/docs/commands/) · [Report an issue](https://github.com/fmind/brain-framework/issues) · [Contribute](https://github.com/fmind/brain-framework/blob/main/CONTRIBUTING.md) · [MIT licensed](https://github.com/fmind/brain-framework/blob/main/LICENSE) · [Third-party notices](https://github.com/fmind/brain-framework/blob/main/THIRD_PARTY_NOTICES.md)

{brain_framework-18.3.0 → brain_framework-18.5.0}/README.md

@@ -15,7 +15,7 @@ A second brain for you, your team and your AI agents, on your own computer. Gath
 
 [![CI](https://github.com/fmind/brain-framework/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fmind/brain-framework/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/brain-framework?color=174EA6)](https://pypi.org/project/brain-framework/) [![Python](https://img.shields.io/pypi/pyversions/brain-framework)](https://pypi.org/project/brain-framework/) [![License: MIT](https://img.shields.io/badge/license-MIT-174EA6)](https://github.com/fmind/brain-framework/blob/main/LICENSE)
 
-[Why](https://github.com/fmind/brain-framework#why-a-second-brain) · [How it works](https://github.com/fmind/brain-framework#how-it-works) · [Try it](https://github.com/fmind/brain-framework#try-it) · [Agents](https://github.com/fmind/brain-framework#open-your-agent-in-your-brain) · [Good to know](https://github.com/fmind/brain-framework#good-to-know) · [Four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/) · [Documentation](https://fmind.github.io/brain-framework/)
+[Why](https://github.com/fmind/brain-framework#why-a-second-brain) · [How it works](https://github.com/fmind/brain-framework#how-it-works) · [Try it](https://github.com/fmind/brain-framework#try-it) · [Agents](https://github.com/fmind/brain-framework#open-your-agent-in-your-brain) · [Good to know](https://github.com/fmind/brain-framework#good-to-know) · [Four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/) · [Documentation](https://fmind.github.io/brain-framework/)
 
 <a href="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-loop.svg">
   <img
@@ -56,7 +56,7 @@ Questions that once took a tour of your tools become one prompt, once you write
 - **Every source, even the ones no product connects.** Mail, calendar, documents, chat, issues and pull requests, of course. But also the release notes and security advisories of the tools you depend on, model retirement dates, provider incidents, mentions of your projects on Hacker News or Bluesky, your domains' certificates and mail security, repository traffic that GitHub forgets after 14 days and your past agent sessions. If you can script it, you can collect it.
 - **Unlimited integrations, both ways.** A sensor is a small program that prints JSON: wrap a CLI such as `gh`, `gws` or `gcloud`, call an API, drive a browser, query a database or parse an export. The same CLIs, APIs and MCP servers then let your agent act on what it learned: draft the issue, answer the thread, fix the alert.
 - **One vocabulary, one knowledge graph.** Each tool names things its own way. You declare a small ontology in `bf.yaml` and sensors map provider fields into it at collection, so the same project, person or repository connects across every tool. BF turns those explicit links into a graph you navigate in one read, each claim pointing back to its evidence.
-- **Private by design.** Your brain is a folder on your disk. BF has no account, server or telemetry and runs no AI model; search and read work offline.
+- **Private by design.** Your brain is a folder on your disk. BF has no account, server or telemetry and never runs a model itself: [prompts](https://fmind.github.io/brain-framework/docs/prompts/) launch your agent harness. Search and read work offline.
 - **Portable and versioned.** Markdown notes, JSON records and scripts: open them in any editor, grep them, copy them to another machine. Keep the brain in a private Git repository for history, rollback, review and conflict resolution.
 - **For you or your whole team.** A personal brain stays on your laptop. A team brain is a private Git repository with one clone per teammate, so decisions, reviewed evidence and next steps are shared by everyone and their agents. Your personal brain can include the team's in its searches.
 - **Any agent, guided by skills.** Claude Code, Codex, GitHub Copilot, Antigravity or your own agent reach the same brain through the `bf` command, packaged skills or MCP. The skills teach them to find evidence, keep notes current, connect sources and maintain the brain.
@@ -94,9 +94,10 @@ A brain gives your work the structure of a detective's case file, in plain files
 | `concepts/` | Knowledge you will reuse elsewhere, with its evidence and limits.            | “Explain the product before asking for signup.”                      |
 | `actions/`  | One work session: objective, inputs, outputs, outcome and next step.         | `actions/2026-09-27_website-review/ACTION.md`, resumed the next day. |
 | `routines/` | Deterministic programs you review, run on demand, on a schedule or from Git. | A weekly review that drafts an action listing projects to revisit.   |
+| `prompts/`  | Markdown prompts your agent harness runs; each run's reply is a record.      | An assistant that reviews new mail and chat every half hour.         |
 | `evals/`    | Saved questions with the evidence that search or read must return.           | “Why one page?” must return the project's Decision section.          |
 
-Notes are Markdown with YAML metadata, records are JSON, and `bf validate` checks both. The SQLite search cache in `.bf/` is disposable and rebuilds itself from the files. See the [file conventions](https://fmind.github.io/brain-framework/docs/brain/#directory-reference).
+Notes are Markdown with YAML metadata, records are JSON, and `bf validate` checks both. `bf init --full` creates `sensors/` and `routines/`; create `prompts/` when you add a [prompt](https://fmind.github.io/brain-framework/docs/prompts/). A prompt's records hold model output, so search weighs them at half, like a low-priority source. The SQLite search cache in `.bf/` is disposable and rebuilds itself from the files. See the [file conventions](https://fmind.github.io/brain-framework/docs/brain/#directory-reference).
 
 ### `bf.yaml`, the coordination hub
 
@@ -129,7 +130,7 @@ watch: # keep sources fresh and alert on failure
   notifications: failure
 ```
 
-BF runs each program with its configured arguments and no shell, bounds its time and output, validates what it prints and keeps its stderr in `logs/`. A failed run never changes your evidence. `bf watch` keeps due sensors and routines fresh in a terminal dashboard, and `bf schedule` generates native systemd, launchd or cron jobs for you to install. See [sensors](https://fmind.github.io/brain-framework/docs/sensors/), [routines](https://fmind.github.io/brain-framework/docs/routines/) and [watch and schedule](https://fmind.github.io/brain-framework/docs/schedule/).
+BF runs each program with its configured arguments and no shell, bounds its time and output, validates what it prints and keeps its stderr in `logs/`. A failed run never changes your evidence. `bf watch` keeps due sensors, routines and prompts fresh in a terminal dashboard, and `bf schedule` generates native systemd, launchd or cron jobs for you to install. See [sensors](https://fmind.github.io/brain-framework/docs/sensors/), [routines](https://fmind.github.io/brain-framework/docs/routines/) and [watch and schedule](https://fmind.github.io/brain-framework/docs/schedule/).
 
 ### One vocabulary, set at collection
 
@@ -153,22 +154,7 @@ Reading files gives you one document at a time, and grep finds words, not connec
 bf read project:new-website
 ```
 
-The reply holds the project note and its backlinks, grouped by relation: four records from four tools, side by side, in the shared vocabulary (trimmed here to refs, kinds and statuses):
-
-```json
-{
-  "relation": "project",
-  "total": 4,
-  "items": [
-    { "ref": "gcloud:deployment", "fields": { "kind": "deployment", "status": "healthy" } },
-    { "ref": "github:implementation", "fields": { "kind": "pull-request", "status": "merged" } },
-    { "ref": "jira:review", "fields": { "kind": "issue", "status": "In review" } },
-    { "ref": "workspace:brief", "fields": { "kind": "brief", "status": "approved" } }
-  ]
-}
-```
-
-From there, follow typed [relations](https://fmind.github.io/brain-framework/docs/links/#name-a-relation) such as `author`, `owner`, `depends-on` or your own. Each claim keeps the note section or record that asserted it, so an answer can always cite its evidence. `bf export` prints the whole graph as JSON Lines for DuckDB or networkx.
+The reply holds the project note and its backlinks, grouped by relation: under `project`, four records from four tools side by side in the shared vocabulary, the Jira review `In review`, the GitHub pull request `merged`, the Gcloud deployment `healthy` and the Workspace brief `approved`. The [four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/#collect-four-tools) shows the reply. From there, follow typed [relations](https://fmind.github.io/brain-framework/docs/links/#name-a-relation) such as `author`, `owner`, `depends-on` or your own. Each claim keeps the note section or record that asserted it, so an answer can always cite its evidence. `bf export` prints the whole graph as JSON Lines for DuckDB or networkx.
 
 ### Act, then learn
 
@@ -182,64 +168,22 @@ Retrieval assembles the context; people and agents do the work, through the CLIs
   >
 </a>
 
-The graph keeps conclusions current. Each project knows the evidence it links to: when a linked record changes after the note's last edit, `bf read` flags the project for review and names the record to read first, so a decision does not silently outlive its linked evidence. Try it in the [four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/#follow-a-change). [Routines](https://fmind.github.io/brain-framework/docs/routines/) run deterministic reviews and checks, such as a weekly review action or `bf validate` before each Git commit, and retrieval cases in `evals/` confirm that the questions you rely on still find their evidence as the brain grows.
+The graph keeps conclusions current. Each project knows the evidence it links to: when a linked record changes after the note's last edit, `bf read` flags the project for review and names the record to read first, so a decision does not silently outlive its linked evidence. Try it in the [four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/#follow-a-change). [Routines](https://fmind.github.io/brain-framework/docs/routines/) run deterministic reviews and checks, such as a weekly review action or `bf validate` before each Git commit, and retrieval cases in `evals/` confirm that the questions you rely on still find their evidence as the brain grows.
 
 ## Try it
 
-Start with one decision you can find again. You need Linux or macOS and [uv](https://docs.astral.sh/uv/getting-started/installation/), which installs the tested Python 3.14 if needed ([install details](https://fmind.github.io/brain-framework/docs/upgrades/#install)). No model or provider account is required.
+You need Linux or macOS and [uv](https://docs.astral.sh/uv/getting-started/installation/), which installs the tested Python 3.14 if needed ([install details](https://fmind.github.io/brain-framework/docs/upgrades/#install)). No model or provider account is required.
 
 ```bash
 uv tool install --python 3.14 brain-framework
 bf --version
 ```
 
-If your shell cannot find `bf`, run `uv tool update-shell` and open a new shell. Then create your brain:
-
-```bash
-bf init ~/brain
-cd ~/brain
-```
-
-Create `projects/new-website.md` in your editor, or ask your agent to save this fictional decision. Use today's date for `updated`:
-
-```markdown
----
-type: project
-status: draft
-updated: 2026-09-27
-summary: Launch a product website that helps visitors understand the product.
----
-
-# New website
-
-## Decision
-
-Start with a single product page because visitors need a clear explanation before signing up.
-
-## Next actions
-
-- [ ] Draft the product page.
-```
-
-Find the reason, read its source and check the brain:
-
-```bash
-bf search "visitors clear explanation"
-bf read projects/new-website.md#decision
-bf validate
-```
-
-Search returns this match in `items` (other fields omitted):
-
-```json
-{ "ref": "projects/new-website.md#decision", "title": "New website — Decision" }
-```
-
-`read` returns the original Decision section with its note's status and date, and validation reports `"valid":true`. Edit the note and search again: BF notices changes on its own. The [getting-started guide](https://fmind.github.io/brain-framework/docs/getting-started/) continues with a first collected source and a link from the decision to its evidence, and the [four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/) runs the whole loop offline on fictional Workspace, Jira, GitHub and Gcloud records.
+Then follow [Getting started](https://fmind.github.io/brain-framework/docs/getting-started/): create a brain, save a decision, find its reason and link it to a first collected source. The [four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/) then runs the whole loop offline on fictional Workspace, Jira, GitHub and Gcloud records.
 
 ## Open your agent in your brain
 
-Use the same brain with [Claude Code](https://code.claude.com/docs/en/overview), [Codex](https://openai.com/codex/), [GitHub Copilot](https://github.com/features/copilot) or any agent host that can run a command. Start your terminal agent in `~/brain` and give it this prompt:
+Use the same brain with [Claude Code](https://code.claude.com/docs/en/overview), [Codex](https://openai.com/codex/), [GitHub Copilot](https://github.com/features/copilot) or any agent host that can run a command. After Getting started, start your terminal agent in `~/brain` and give it this prompt:
 
 > Use the bf CLI. Find why we chose a single product page. Read the source, cite its ref and tell me the project's next action.
 
@@ -256,11 +200,9 @@ Each host reads its own folder: for Claude Code, use `~/.claude/skills` instead.
 | `bf-use`      | Find evidence, cite it, and keep projects and concepts current.                 |
 | `bf-action`   | Start, resume and hand off a tracked work session: `/bf-action website-review`. |
 | `bf-setup`    | Install BF, create a brain, connect the agent and choose sources worth adding.  |
-| `bf-maintain` | Run sensors and routines, check the brain and upgrade it safely.                |
-
-Working in a code repository instead? The [example session hook](https://github.com/fmind/brain-framework/tree/main/examples/hooks) prints the project that declares the repository, its next task and linked evidence when the session starts. Hosts that prefer tools can call `search` and `read` through [MCP](https://fmind.github.io/brain-framework/docs/mcp/). See the [agent guide](https://fmind.github.io/brain-framework/docs/agents/).
+| `bf-maintain` | Run sensors, routines and prompts, check the brain and upgrade it safely.       |
 
-Agents can read this documentation as Markdown: [llms.txt](https://fmind.github.io/brain-framework/llms.txt) indexes every guide with a summary, [llms-full.txt](https://fmind.github.io/brain-framework/llms-full.txt) holds their full text, and each guide's Markdown sits at its URL followed by `index.md`.
+Working in a code repository instead? The [example session hook](https://github.com/fmind/brain-framework/tree/main/examples/hooks) prints the project that declares the repository, its next task and linked evidence when the session starts. During collection, a usable cached reply carries an “Index refreshing” note. Hosts that prefer tools can call `search` and `read` through [MCP](https://fmind.github.io/brain-framework/docs/mcp/). See the [agent guide](https://fmind.github.io/brain-framework/docs/agents/), which also points agents to this documentation as Markdown.
 
 ## Bring your tools
 
@@ -295,7 +237,7 @@ A brain is a folder, so Git gives it history, rollback, review and conflict reso
 
 1. **It runs on your computer, not in someone else's cloud.** That is a feature: your agent works where you can watch it, interrupt it and inspect every file it reads or writes, instead of a black box on a remote server. Sensors collect while your machine is on, through `bf watch` or a native schedule.
 1. **It takes some setup.** Each source needs its access: an API key, `gh auth login`, `gws` or `gcloud` authentication, then a sensor you review. Providers ship better CLIs and MCP servers every month, so this keeps getting easier, and the `bf-setup` skill walks your agent through it.
-1. **It needs an agent harness for the reasoning.** BF runs no model: it collects, validates, searches and connects. Claude Code, Codex, Copilot, Antigravity or another harness does the thinking, so the privacy of what your agent reads depends on that harness's data terms. BF sends no telemetry or personal data to us; see [privacy and security](https://fmind.github.io/brain-framework/docs/privacy/) for a fully local setup.
+1. **It needs an agent harness for the reasoning.** BF never runs a model itself: it collects, validates, searches and connects, and its [prompts](https://fmind.github.io/brain-framework/docs/prompts/) launch your harness. Claude Code, Codex, Copilot, Antigravity or another harness does the thinking, so the privacy of what your agent reads depends on that harness's data terms. BF sends no telemetry or personal data to us; see [privacy and security](https://fmind.github.io/brain-framework/docs/privacy/) for a fully local setup.
 1. **It finds what was said and linked, not what was meant.** Search matches words and explicit identities, without embeddings, and incomplete results say so. Search and read never contact providers: collect again when you need newer evidence. See [what BF does not do](https://fmind.github.io/brain-framework/docs/concepts/#what-bf-does-not-do).
 
 [Browse the commands](https://fmind.github.io/brain-framework/docs/commands/) · [Report an issue](https://github.com/fmind/brain-framework/issues) · [Contribute](https://github.com/fmind/brain-framework/blob/main/CONTRIBUTING.md) · [MIT licensed](https://github.com/fmind/brain-framework/blob/main/LICENSE) · [Third-party notices](https://github.com/fmind/brain-framework/blob/main/THIRD_PARTY_NOTICES.md)

{brain_framework-18.3.0 → brain_framework-18.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brain-framework"
-version = "18.3.0"
+version = "18.5.0"
 description = "🧠 Brain Framework: from information to informed actions."
 readme = "README.md"
 requires-python = ">=3.14"

{brain_framework-18.3.0 → brain_framework-18.5.0}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 # https://packaging.python.org/en/latest/specifications/pyproject-toml/
 [project]
 name = "brain-framework"
-version = "18.3.0"
+version = "18.5.0"
 description = "🧠 Brain Framework: from information to informed actions."
 readme = "README.md"
 requires-python = ">=3.14"

{brain_framework-18.3.0 → brain_framework-18.5.0}/src/bf/__init__.py

@@ -2,7 +2,7 @@
 
 import os
 
-__version__ = "18.3.0"
+__version__ = "18.5.0"
 
 
 def main() -> None:

{brain_framework-18.3.0 → brain_framework-18.5.0}/src/bf/cli.py

@@ -51,7 +51,7 @@ from bf.models import (
 from bf.retrieve import edges, identities, read, search
 from bf.schemas import Kind, document
 from bf.storage import Store, expand, relative, writer
-from bf.update import run_routines, update
+from bf.update import KINDS, ProgramKind, run_prompt, run_routines, update
 from bf.validate import validate
 
 
@@ -160,6 +160,7 @@ SensorOption = Annotated[
 RoutineOption = Annotated[
     list[str] | None, typer.Option("--routine", help="Select a routine; repeat to select several.")
 ]
+PromptOption = Annotated[list[str] | None, typer.Option("--prompt", help="Select a prompt; repeat to select several.")]
 # Every brain starts with knowledge and verification; the other folders are created as needed or with --full.
 FOLDERS = ("projects", "actions")
 OPTIONAL = ("memories", "assets", "sensors", "routines", "skills")
@@ -510,9 +511,9 @@ def perform(
         # A mistyped option, such as --dryrun, is invalid input instead of an argument to a routine that then runs
         # for real: routine arguments that start with a dash follow `--`.
         typer.Argument(
-            metavar="[ROUTINE] [ARGS]...",
-            help="A routine from bf.yaml, then arguments appended to its command; with --hook, only arguments. "
-            "Put -- before arguments that start with a dash.",
+            metavar="[PROGRAM] [ARGS]...",
+            help="A routine from bf.yaml, then arguments appended to its command, or a prompt; with --hook, only "
+            "arguments. Put -- before arguments that start with a dash.",
         ),
     ] = None,
     hook: Annotated[
@@ -521,32 +522,49 @@ def perform(
     ] = "",
     brain: RunOption = "",
     dry_run: Annotated[
-        bool, typer.Option(help="Run the routines, but write no action and record no run; logs still grow.")
+        bool,
+        typer.Option(
+            help="Run the routines or the prompt, but write no action or record and record no run; logs still grow."
+        ),
     ] = False,
     forward: Annotated[
         bool,
         typer.Option(
             "--stdin",
-            help="Pass piped input to the routine. A hook passes what Git pipes to the routines it runs; otherwise "
-            "none.",
+            help="Pass piped input to the routine, or as a prompt's {{input}}. A hook passes what Git pipes to the "
+            "routines it runs; otherwise none.",
         ),
     ] = False,
 ) -> None:
-    """Run one routine, or every routine of a hook, now; a hook's piped input reaches each routine."""
+    """Run one routine or prompt, or every routine of a hook, now; a hook's piped input reaches each routine."""
     values = tuple(arguments or ())
     if hook:
         _option("--hook", _slug, hook)
         names, args = (), values
     elif values and not values[0].strip():
-        raise typer.BadParameter("give a routine name; an empty value names none", param_hint="ROUTINE")
+        raise typer.BadParameter("give a routine or prompt name; an empty value names none", param_hint="PROGRAM")
     elif values:
         names, args = values[:1], values[1:]
     else:
-        raise typer.BadParameter("name a routine, or pass --hook EVENT", param_hint="ROUTINE")
+        raise typer.BadParameter("name a routine or prompt, or pass --hook EVENT", param_hint="PROGRAM")
     store = execution(brain)
+    config = load(store)
+    if names and names[0] in config.prompts:
+        if args:
+            raise typer.BadParameter("a prompt takes no arguments; pipe its input with --stdin", param_hint="ARGS")
+        stdin = _input() if forward else b""
+        try:
+            text = stdin.decode("utf-8")
+        except UnicodeError as error:
+            raise Error("prompt input must be UTF-8 text") from error
+        result = run_prompt(store, names[0], text=text, dry_run=dry_run)
+        emit(result)
+        if not result["ok"]:
+            raise typer.Exit(1)
+        return
     # Git closes a hook's input; an agent's shell can hold its own open, so a direct run reads it only on request,
     # and a hook only for the routines it runs: a hook that no routine lists succeeds at once.
-    stdin = _input() if forward or (hook and hooked(load(store), hook)) else b""
+    stdin = _input() if forward or (hook and hooked(config, hook)) else b""
     result = run_routines(store, names=names, hook=hook, args=args, stdin=stdin, dry_run=dry_run)
     emit(result)
     if not result["ok"]:
@@ -558,22 +576,42 @@ def refresh(
     brain: RunOption = "",
     sensor: SensorOption = None,
     routine: RoutineOption = None,
+    prompt: PromptOption = None,
+    kind: Annotated[
+        list[str] | None,
+        typer.Option(help="Run only this kind of program: sensor, routine or prompt; repeat for several."),
+    ] = None,
     dry_run: Annotated[
-        bool, typer.Option(help="List due sensors and routines with their windows; run nothing.")
+        bool, typer.Option(help="List due sensors, routines and prompts with their windows; run nothing.")
     ] = False,
 ) -> None:
-    """Run due sensors, then due routines, of one brain, then refresh its search cache."""
-    result = update(execution(brain), dry_run=dry_run, sensors=tuple(sensor or ()), routines=tuple(routine or ()))
+    """Run due sensors, then due routines, then due prompts, of one brain, then refresh its search cache."""
+    result = update(
+        execution(brain),
+        dry_run=dry_run,
+        sensors=tuple(sensor or ()),
+        routines=tuple(routine or ()),
+        prompts=tuple(prompt or ()),
+        kinds=_kinds(kind or []),
+    )
     emit(result)
     if not result["ok"]:
         raise typer.Exit(1)
 
 
+def _kinds(values: list[str]) -> frozenset[ProgramKind]:
+    """The program kinds an update runs; none given runs every kind."""
+    if unknown := sorted(set(values) - KINDS):
+        raise typer.BadParameter(f"{unknown[0]} is not sensor, routine or prompt", param_hint="--kind")
+    return cast("frozenset[ProgramKind]", frozenset(values)) if values else KINDS
+
+
 @app.command("watch", rich_help_panel="Collect and automate")
 def monitor(
     brain: RunOption = "",
     sensor: SensorOption = None,
     routine: RoutineOption = None,
+    prompt: PromptOption = None,
     interval: Annotated[
         int | None,
         typer.Option(min=5, max=86400, help="Seconds between cycles; overrides bf.yaml watch.interval (default 60)."),
@@ -605,6 +643,7 @@ def monitor(
         execution(brain),
         sensors=tuple(sensor or ()),
         routines=tuple(routine or ()),
+        prompts=tuple(prompt or ()),
         interval=interval,
         poll_interval=poll_interval,
         notifications=notify,
@@ -617,6 +656,7 @@ def scheduling(
     brain: RunOption = "",
     sensor: SensorOption = None,
     routine: RoutineOption = None,
+    prompt: PromptOption = None,
     backend: Annotated[
         Literal["auto", "systemd", "launchd", "cron"],
         typer.Option(help="Scheduler format; auto detects available platform tools."),
@@ -656,6 +696,7 @@ def scheduling(
             executable=executable,
             sensors=tuple(sensor or ()),
             routines=tuple(routine or ()),
+            prompts=tuple(prompt or ()),
         )
     )
 
@@ -677,7 +718,7 @@ def report(
         ),
     ] = False,
 ) -> None:
-    """Show each brain's cache, notes, records, sensor and routine freshness, errors, logs and usage."""
+    """Show each brain's cache, notes, records, sensor, routine and prompt freshness, errors, logs and usage."""
     if watch:
         if check:
             raise typer.BadParameter("cannot be combined with --check", param_hint="--watch")
@@ -809,6 +850,7 @@ def _input() -> bytes:
 _GIVEN = {
     "--brain": "give a brain name or path; an empty value would select another brain",
     "--hook": "give an event name; an empty value would run the first argument as a routine",
+    "--prompt": "give a prompt name; an empty value names none",
     "--output": "give a directory; an empty value would name the brain's root",
     "--reproject": "give a sensor name; an empty value would rebuild the cache instead",
     "--routine": "give a routine name; an empty value names none",