ultimate-brain 0.5.0 → 0.6.0

package/.agents/skills/brain-apply/SKILL.md

@@ -113,5 +113,5 @@ In a catch-up these are decided in its read-only pass and confirmed in its one b
 ## Don'ts
 
 - **Don't apply anything the user didn't decide in this chat or in Notion.**
-- **Don't edit notes directly** to "help" a proposal along. If a proposal is wrong, the user rejects or fixes it.
+- **Don't edit notes or proposal files directly** (`sed`, a text editor, a script; U-18) to "help" a proposal along, nor to mark one applied. If a proposal is wrong, the user rejects or fixes it, and `brain sync apply` or `brain apply` writes the result.
 - **Don't re-run `apply` after a failure** without changing the input. Apply is atomic per item, and the failed item is unchanged; fix the cause first.

package/.agents/skills/brain-catch-up/SKILL.md

@@ -1,33 +1,35 @@
 ---
 name: brain-catch-up
-description: Do everything that is waiting in one run. Pulls the user's Notion edits, applies the reviews they decided (Fix included), ingests reviewed meetings, Inbox rows that are Ready, their attachments, the drop folder and linked repos, reads again the inputs the user corrected, writes and refreshes the reports asked for on Ask and Report rows and the full texts asked for on Inbox rows, publishes and pushes, asking every question once at the start and then finishing without stopping. Use when the user says "catch up", "what's next", "do what's waiting" or "process everything".
+description: Do everything that is waiting in one run. Pulls the user's Notion edits, applies the reviews they decided (Fix included), ingests reviewed meetings, Inbox rows that are Ready, their attachments, the drop folder and linked repos, reads again the inputs the user corrected, keeps the documents asked for (whole or in part) and promotes the notes asked for, writes and refreshes the reports asked for, publishes and pushes, asking every question once at the start and then finishing without stopping. Skips the steps of modules that are off. Use when the user says "catch up", "what's next", "do what's waiting" or "process everything".
 ---
 
 # Catch up
 
 One run for everything waiting (decision 0037). It has two halves: a **read-only pass** that finds the work and every question it raises, then **one batch of questions**, then a run that finishes without asking again. Anything that becomes blocked during the run is **skipped** and listed in the report; the rest goes on.
 
-This skill orders the work; the other skills hold the steps. Read each one before running its part: brain-sync (pull and publish), brain-apply (decisions), brain-ingest with its references (meetings, sources, attachments, the drop folder, linked repos), brain-query (reports). Their rules apply unchanged, including the trust rules in the brain's AGENTS.md.
+This skill orders the work; the other skills hold the steps. Read each one before running its part: brain-sync (pull and publish), brain-apply (decisions), brain-ingest with its references (meetings, sources, attachments, the drop folder, linked repos, Documents), brain-query (reports). Their rules apply unchanged, including the trust rules in the brain's AGENTS.md.
 
 **The bar** (decision 0043): over two meetings and one capture, from "go" to the report in under 5 minutes, without the session running out of context. So each input is analysed in its own sub-agent (step 3), Notion is written in one batch at the end (step 4), and nothing already in Notion is written twice. Note the time when the user says "catch up" (or the run starts), and count the notes whose full text the run and its sub-agents read: the run logs both at the end (decision 0045).
 
+**Modules** (decision 0048): `brain status` gives `modules`. A step marked with a module (*Knowledge*, *Orgs*, *Documents*, *Reports*, *Tasks*, *Planning*) runs only when that module is on; when it's off, skip the step and its questions without a word. Core (Inbox, Meetings, Projects, Areas, People, Review) always runs. A module that is on but whose database id is still empty (`brain modules` lists it under `missing`) is named once on the report's Needs you line: "Documents is on but its database isn't set up: say "set up documents"".
+
 Run every CLI command as `brain <command> --brain <brain> --json`. If `brain` is not found (`command not found`), install it with `npm install -g ultimate-brain`, then retry.
 
 ## 1. Read-only pass
 
 This step changes no knowledge: no note, proposal, `brain.json`, commit, Notion page or drop-folder file. Two writes are allowed because they change nothing the user owns: `brain index` may regenerate a stale `index.md` (generated, rebuilt again later in the run), and the working files (`snapshot.json`, `plan.json`, conversions) go in a temporary folder outside the brain.
 
-1. **Status.** Run `brain status`; run `brain index` if `index_stale`. Note `settings` (absent means `publish: ask`, `push: auto`) and which databases are configured. Each Notion part below needs its database configured; skip the ones that aren't and name them once on the report's Needs you line.
-2. **Pull plan.** Brain-sync "Pull", steps 2–4, with the snapshot and plan in the temporary folder: snapshot the databases brain-sync step 2 reads (Areas, Goals, Key Results, Projects, People, Orgs, Decisions, Questions, Concepts, References, Review; never Meetings), whichever are configured, plus the **Inbox rows whose Full text box is ticked** and the **Report rows with Refresh ticked or a What to fix**, with only the properties brain-sync step 2 names; run `sync plan` once, save `plan.json`. It holds the imports, your corrections, the decided Review rows, the conflicts, `full_text_requests` (one per ticked box on a source the brain wrote), `refresh_requests` and `report_fixes`.
+1. **Status.** Run `brain status`; run `brain index` if `index_stale`. Note `settings` (absent means `publish: ask`, `push: auto`), `modules`, and which databases are configured. Each Notion part below needs its database configured; skip the ones that aren't and name them once on the report's Needs you line.
+2. **Pull plan.** Brain-sync "Pull", steps 2–4, with the snapshot and plan in the temporary folder. Read **every** configured database of a module that is on (brain-sync step 2 lists them, Goals, Key Results and Documents included; never Meetings), all pages of each, plus the Inbox rows brain-sync step 2 names. Run `sync plan` once and save `plan.json`. It holds the imports, your corrections, the decided Review rows, the conflicts, `document_requests` and `promote_requests` (*Documents*), and `refresh_requests` and `report_fixes` (*Reports*).
 3. **What to fix on Review rows.** For each `NOTE_TO_READ` and `FIX_TO_READ` conflict, read What to fix against its proposal and decide what it means (brain-apply, "Reading What to fix"). Write down the decision you would apply ("a: launch 2027-03"), or the question it raises. A `FIX_WITHOUT_TEXT` row goes in the batch as a question: "Acme launch review: Fix, but What to fix is empty: what's wrong?"
 4. **Meetings** *(Notion)*. Brain-ingest steps 2 and 3, up to the duplicate check: the Reviewed meetings, oldest first, and each one's pre-check blockers. A meeting the brain already ingested and that is Reviewed again is a **re-read** (decision 0045): the user fixed its minutes; say so in the batch ("Acme sync, read again: only what changed"). Minutes files are ingested only when the user names them, never looked for.
-5. **Inbox.** The rows **ready to take in** (brain-ingest references/sources.md, "capture"; decision 0045): Brain Status **Ready**, and captures still **New** a day or more after they were created. Never a Skipped row, nor a New document, email, chat or note row: those wait for Ready. Oldest first, each with its pre-check blockers. A Ready row with a Brain ID is a **re-read**, as for meetings. A row with Project or Area set needs no project question. A document's empty **Keep** goes in the batch: "Acme requirements (document): what do you want from it? all / just …" (default all). A capture that repeats a source the brain already has: default skip, naming that source and linking its row (sources.md, "Pre-check").
-   **Ask rows** (Kind = Ask, Brain Status New) are requests for a report, not captures, and need no Ready: never ingest one; note its question (the Name), its Project or Area and its **Refresh report** relation, if set, for the report ("Run", step 6).
-   **Attachments** on the rows taken in and the Reviewed meetings: list each file (sources.md, "Attachments"), all selected by default, each with its row's Keep.
-6. **Drop folder.** The queue and its question (sources.md, "The drop folder", steps 1–2: what to keep from each file, and whether one is a new version), without moving anything.
-7. **Linked repos.** For each entry of `repos` in `brain status`: `brain repo changes <name>` (sources.md, "Linked repos"). A repo with `found: false` is named on the Needs you line. More than 10 files: they go in the batch as a list, default all.
-8. **The full-text choice.** For each input that will get its own Inbox row (not a capture, an attachment or minutes), the default by kind: emails and chats full, documents and decks digest. Without an Inbox database (`inbox` missing), there is no row: leave the choice out of the batch, and the CLI's default stands for a later publish.
-9. **Reports.** From `plan.json`: each `refresh_requests` item, and each `report_fixes` item with the proposals its text would become (brain-query, "What to fix on a report"), written down like a Review row's What to fix. Also each report whose last `fixes` entry lists only proposals now applied, rejected or closed, and that wasn't refreshed since: it is due a refresh.
+5. **Inbox.** The rows with Brain Status **Ready**, and only those (decision 0048): never a New or Done row, whatever its Kind or age. Oldest first, each with its pre-check blockers (brain-ingest references/sources.md, "capture"). A Ready row with a Brain ID is a **re-read**, as for meetings. A row with Project or Area set needs no project question. A row's **Only keep** and **Document asked** come with it; an empty Only keep is never asked about (decision 0049). A capture that repeats a source the brain already has: default skip, naming that source and linking its row (sources.md, "Pre-check").
+   **Ask rows** *(Reports)* (Kind = Ask, Brain Status New or Ready) are requests for a report, not captures: never ingest one; note its question (the Name) and its Project or Area for the report ("Run", step 6).
+   **Attachments** on the rows taken in and the Reviewed meetings: list each file (sources.md, "Attachments"), all selected by default. On a row with Document asked ticked, each file becomes a Document (step 1.7).
+6. **Drop folder.** The queue and its question (sources.md, "The drop folder", steps 1–2: whether to keep each file as a document, and whether one is a new version), without moving anything.
+7. **Documents asked for** *(Documents)*. From `plan.json`, each `document_requests` item (a row already taken in whose Document asked box is ticked) and each `promote_requests` item (a decision or concept whose Promote asked box is ticked), plus the Ready rows of step 5 with Document asked ticked and the drop-folder files the user may keep. An item with `existing` is already done: the run only clears its box. None of these asks a question; name them in the batch's opening line ("I'll also keep 2 documents and promote 1 decision").
+8. **Linked repos.** For each entry of `repos` in `brain status`: `brain repo changes <name>` (sources.md, "Linked repos"). A repo with `found: false` is named on the Needs you line. More than 10 files: they go in the batch as a list, default all.
+9. **Reports** *(Reports)*. From `plan.json`: each `refresh_requests` item, and each `report_fixes` item with the proposals its text would become (brain-query, "What to fix on a report"), written down like a Review row's What to fix. Also each report whose last `fixes` entry lists only proposals now applied, rejected or closed, and that wasn't refreshed since: it is due a refresh.
 10. **The backlog.** `brain proposal backlog --dry-run`: the Review notes rows the run will write once for notes from before 0.4.0. They need no question; name them in the batch's opening line ("I'll also write 2 Review notes rows for older notes").
 11. **Pending proposals in chat.** Without a Review database, run `brain proposal list --status pending,approved,edited,rejected`: these go in the batch as chat decisions (brain-apply, chat mode, steps 2–3).
 12. **Your identities.** If `brain.json` has no `owner.person`, add the identities question (brain-connect-notion, step 6).
@@ -41,11 +43,10 @@ Ask once, in one message, numbered and grouped by input, each with the answer yo
 - each What to fix you read, as "Acme sync: 'all except b' → approve the rest, b waits in a row of its own" or "Acme sync: Fix 'a: March' → launch date 2027-03";
 - each meeting's and input's pre-check blockers;
 - the pending proposals, as brain-apply's chat list (default: leave them pending);
-- the drop-folder list, all files selected;
+- the drop-folder list, all files selected, each with "keep as document? no / all / only …" (default **no**) when Documents is on;
 - each attachment, all selected, and each linked repo's files when there are more than 10;
-- the full-text choice, one line per input that gets an Inbox row, saying what it puts in Notion: "4. Requirements doc (40 p) → **digest**: Notion gets a summary and key points; to read the document itself you open the file. Say "4 full" to have the whole text in Notion." Parts work too: "5 full, slides 3–9";
-- each document's Keep, when its row's Keep is empty (default all), and each likely new version (default yes);
-- each Ask row, as "Report on <its question> (default: yes)", or "Refresh <report> for <its question>" when its Refresh report is set; each Report row to refresh, and each report What to fix with the proposals it becomes ("Acme launch report: 'Lucía left Acme in June' → Lucía's org: Acme → none, from June");
+- each likely new version (default yes);
+- *(Reports)* each Ask row, as "Report on <its question> (default: yes)"; each Report row to refresh, and each report What to fix with the proposals it becomes ("Acme launch report: 'Lucía left Acme in June' → Lucía's org: Acme → none, from June");
 - the identities question (default: skip for now, ask again next catch-up). The user's answer is their approval of those aliases;
 - with `settings.publish: ask` and Notion configured: "Publish to Notion at the end?" (default yes). This is the run's only publish question. Without Notion there is nothing to publish: leave it out.
 
@@ -55,33 +56,39 @@ When nothing blocks, don't ask: say what you will do in one line and start. When
 
 0. **The backlog, once** (decision 0041): `brain proposal backlog`. On a brain from before 0.4.0, the first run writes one Review notes row per source over its `draft` notes; every later run writes nothing. Commit any rows it wrote: `review: <n> Review notes rows for the backlog`.
 1. **Pull and apply.** `brain sync apply --input plan.json` (brain-sync steps 6–8), then with `brain apply --input <file>`: the decisions you resolved from What to fix (brain-apply, "Reading What to fix"), the chat decisions from the batch (`decided_by: chat`), and the identities. For the identities, run brain-connect-notion step 6 in full, with the batch answer as the user's approval: the owner-ruling source and, when the owner's person note exists, one `add_link` alias proposal per value applied with `decided_by: chat`; when it doesn't, a new person note (`brain note new`) carrying the aliases; then `brain config set owner.person '"<per- id>"'`. Rebuild and commit as brain-apply "Finish", steps 1–3. Conflicts the user didn't answer stay conflicts.
-2. **Full texts asked for:** `brain source full-text <source> [--parts …]` for each of `plan.json`'s `full_text_requests`, and for each "full text for …" the user asked in chat. Commit: `full-text: <n> sources`.
-3. **Analyse each input in its own sub-agent** (decision 0043): each meeting, Inbox row (with its attachments) and chosen file. A run with one input, or inputs of a page or two each, can analyse them inline instead, one at a time: the sub-agents are there to keep long inputs out of the run's context. Inline is also the way when the session can't start sub-agents. Give each one the brain path, the input (or how to read it), its batch answers and the brain-ingest skill with its references, and have it run, read-only, brain-ingest steps 4–6 and the dry runs of step 7, then return the `note new` batch, the `proposal new` batch (with the input's one `review_notes` and any `answer`), the task items and the report lines. A sub-agent never runs a write, a commit or a Notion call. Run up to 4 at a time. A **re-read** is analysed inline in step 4 instead: its diff needs the new source written first (brain-ingest references/sources.md, "Re-reads and new versions"), and the changed lines are short.
-4. **Write them, one input at a time,** in the order of step 1 (meetings oldest first, then Inbox rows, then files): before each batch, check its new notes against what the inputs before it wrote (`brain index`): a person, project or concept another input already created is linked to that note instead of created twice. Then brain-ingest steps 7.3–10 (the real `note new`, `proposal new`, rebuild, check, log, commit). On `INPUT_INVALID` from a path that changed since the dry run, run the dry run again and fix the links.
-5. **Linked repos:** their files are inputs of steps 3–4 too; after a repo's last file, `brain repo record`, unless a file failed or the user wants some later (sources.md, "Linked repos", step 4).
-6. **Reports,** with brain-query "Report mode":
+2. **Analyse each input in its own sub-agent** (decision 0043): each meeting, Inbox row (with its attachments) and chosen file. A run with one input, or inputs of a page or two each, can analyse them inline instead, one at a time: the sub-agents are there to keep long inputs out of the run's context. Inline is also the way when the session can't start sub-agents. Give each one the brain path, the input (or how to read it), its batch answers, its Only keep and Document asked, and the brain-ingest skill with its references, and have it run, read-only, brain-ingest steps 4–6 and the dry runs of step 7, then return the `note new` batch (with any Documents, brain-ingest references/extraction.md "Documents"), the `proposal new` batch (with the input's one `review_notes` and any `answer`), the task items and the report lines. A sub-agent never runs a write, a commit or a Notion call. Run up to 4 at a time. A **re-read** is analysed inline in step 3 instead: its diff needs the new source written first (brain-ingest references/sources.md, "Re-reads and new versions"), and the changed lines are short.
+3. **Write them, one input at a time,** in the order of step 1 (meetings oldest first, then Inbox rows, then files): before each batch, check its new notes against what the inputs before it wrote (`brain index`): a person, project or concept another input already created is linked to that note instead of created twice. Then brain-ingest steps 7.3–10 (the real `note new`, `proposal new`, rebuild, check, log, commit). On `INPUT_INVALID` from a path that changed since the dry run, run the dry run again and fix the links.
+4. **Linked repos:** their files are inputs of steps 2–3 too; after a repo's last file, `brain repo record`, unless a file failed or the user wants some later (sources.md, "Linked repos", step 4).
+5. **Documents** *(Documents)*, for the inputs already in the brain (step 1.7; the inputs taken in this run wrote theirs in step 3), with brain-ingest references/extraction.md "Documents":
+   1. each `document_requests` item without `existing`: with `only_keep` null, one `whole` Document per file in `files`, or of `source` when `files` is empty; with `only_keep` set, one `part` Document of what it names, in a new `review_notes` for that source;
+   2. each `promote_requests` item without `existing`: one `promoted` Document seeded from the note;
+   3. what the user asked in chat ("also keep the budget from the Acme doc"): a `part` Document from the source the brain already has.
+
+   `ALREADY_KEPT` in `skipped` is fine: that whole Document exists. Rebuild and commit: `documents: <n> kept, <n> promoted`. Each item written, skipped as `ALREADY_KEPT` or carrying `existing` has its box cleared in the publish (step 4.1.4); one that failed keeps it, so the next catch-up tries again.
+6. **Reports** *(Reports)*, with brain-query "Report mode":
    1. each report What to fix: its proposals and `brain report fix` (brain-query, "What to fix on a report"). Commit: `report: fix <title>`;
-   2. each refresh: a Report row with Refresh ticked, an Ask row with Refresh report set (with `asked_in` = that row's page id), or a report whose last `fixes` entry lists only proposals that are applied, rejected or closed (one recorded with `--record-only` waits). Commit: `report: refresh <title>`;
-   3. each other Ask row the user didn't decline: a new report with `asked_in` = the row's page id, its Project and Area. Commit: `report: <title>`.
+   2. each refresh: a Report row with Refresh asked ticked, or a report whose last `fixes` entry lists only proposals that are applied, rejected or closed (one recorded with `--record-only` waits). Commit: `report: refresh <title>`;
+   3. each Ask row the user didn't decline: a new report with `asked_in` = the row's page id, its Project and Area. Commit: `report: <title>`.
 
-For each input, publishing waits for step 4 below. **Skipped, not asked:** an input whose ingest raises a new question or fails is left as it is (the meeting stays Reviewed, the row New or Ready, the file in the queue) and goes on the report's Needs you line. The one hard stop: a lint error in a file this run wrote. Stop the run there, commit nothing more, and report.
+For each input, publishing waits for step 4 below. **Skipped, not asked:** an input whose ingest raises a new question or fails is left as it is (the meeting stays Reviewed, the row Ready, the file in the queue) and goes on the report's Needs you line. The one hard stop: a lint error in a file this run wrote. Stop the run there, commit nothing more, and report.
 
 ## 4. Publish, push, report
 
 1. **Publish** (when `settings.publish` is `auto`, or the user said yes), once for the whole run, following brain-ingest references/notion.md "Publish" for each write, in this order. Run `brain views` first, so the project and area Briefs are current:
-   1. **Pages:** `sync render --changed --plan plan.json`, write every item (pending relations: publish and record those first, then render again, until no item is pending), `sync record`. This publishes the new notes, the proposals, the meetings' relations, every source's Inbox row with its digest and full text, the report rows (then each Ask row's Brain Status to Processed), the cleared Full text boxes, the project and area Briefs, a question's Status = Open, and the Review rows decided more than 30 days ago (`action: trash`, moved to Notion's trash; decision 0045). Write in parallel, up to 10 at a time, and never read a page back after writing it.
-   2. **Tasks,** now that their projects and Inbox rows exist: `sync tasks --meeting` for each ingested meeting and `sync tasks --source` for each ingested source with owner tasks; create each returned item once; `sync record` its page ids. An item still listing `pending_relations` (a project that isn't in Notion) is not created: list it under Check.
-   3. Set Brain Status = Skipped on the Inbox rows the user skipped.
-   4. Log `brain log publish - pages=<n>` and commit `publish: catch up`.
-   5. A meeting read again keeps Brain Status Reviewed until you set it back to **Ingested** through the MCP (brain-ingest step 11): do it for each re-read meeting.
+   1. **Pages:** `sync render --changed --plan plan.json`, write every item (pending relations: publish and record those first, then render again, until no item is pending), `sync record`. This publishes the new notes and Documents, the proposals, the meetings' relations, every source's Inbox row with its digest, the report rows (then each Ask row's Brain Status to Done), the cleared Refresh asked boxes, the project and area Briefs, a question's Status = Open, and the Review rows decided more than 30 days ago (`action: trash`, moved to Notion's trash; decision 0045). Write in parallel, up to 10 at a time, and never read a page back after writing it. **Every write carries its final content:** never create a page or write a body with placeholder text to fill in later (brain-ingest references/notion.md, "One write, final content").
+   2. *(Tasks)* **Tasks,** now that their projects and Inbox rows exist: `sync tasks --meeting` for each ingested meeting and `sync tasks --source` for each ingested source with owner tasks; create each returned item once; `sync record` its page ids. An item still listing `pending_relations` (a project that isn't in Notion) is not created: list it under Check.
+   3. **Skipped rows:** set Brain Status = **Done** on each Inbox row the user said to skip, and its Summary to why ("Skipped: same as Acme requirements"), through the MCP; change nothing else on it (decision 0048).
+   4. *(Documents)* **Clear the boxes:** untick Document asked on each Inbox row of step 3.5 (and of the Ready rows that asked for one) and set its Brain Status to Done; untick Promote asked on each decision or concept row. Only for requests this run carried out or found done (decision 0048).
+   5. Log `brain log publish - pages=<n>` and commit `publish: catch up`.
+   6. A meeting read again keeps Brain Status Reviewed until you set it back to **Ingested** through the MCP (brain-ingest step 11): do it for each re-read meeting.
 2. **Move the drop-folder files** (sources.md, "The drop folder", step 4): after the publish commit, or right after each file's ingest commit when the run doesn't publish.
 3. **Log the run:** `brain log catch-up - notes_read=<n> seconds=<s>`, the notes whose full text the run and its sub-agents read and the seconds from "catch up" to here (decision 0045). Commit it: `log: catch up`.
 4. **Push** per `settings.push` (AGENTS.md, "Write path").
 5. **Report** once, in the shape of brain-ingest step 12, for the whole run, the decisions included:
    ```
-   Done: 9 applied · 3 captures and 2 files ingested · 12 new notes · 1 task for you · 5 old Review rows trashed
-   Needs you: 3 Review rows (2 Review notes rows, 1 answer) · 2 files skipped (too long, say which parts)
+   Done: 9 applied · 3 captures and 2 files ingested · 12 new notes · 2 documents kept · 1 task for you · 5 old Review rows trashed
+   Needs you: 3 Review rows (2 from inputs, 1 answer) · 2 files skipped (too long, say which parts)
    Next: decide in Notion, then "catch up"
    ```
    Without Notion, the Next line is deciding in chat ("what needs my decision"), and "connect the brain to Notion" goes on the Needs you line.
-   Below the three lines: **What came in** (with each input's Notion choice: "digest" or "full text"; each re-read with what changed) and **What changed**, then the **Fixes** you read, repeated back (brain-apply "Finish" step 5), then the **reports written or refreshed**, each with its row, then **Check** (each skipped input with its reason, each attachment that couldn't be read, the notes kept as drafts or left unchanged by a Review notes row, stale proposals, assumptions), as brain-ingest step 12 and brain-apply "Finish" step 5 define them, uncapped. Offer the `settings.publish` switch here when AGENTS.md says to.
+   Below the three lines: **What came in** (each re-read with what changed; each Document with what it keeps) and **What changed**, then the **Fixes** you read, repeated back (brain-apply "Finish" step 5), then the **reports written or refreshed**, each with its row, then **Check** (each skipped input with its reason, each attachment that couldn't be read, the notes kept as drafts or left unchanged by a Review notes row, stale proposals, assumptions), as brain-ingest step 12 and brain-apply "Finish" step 5 define them, uncapped. Offer the `settings.publish` switch here when AGENTS.md says to.

package/.agents/skills/brain-connect-notion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brain-connect-notion
-description: Connect the brain to the user's Notion space after it was built from the notion/ prompts. Gives the agent access to Notion, finds the Brain Data page and its databases, checks each has the properties the brain reads and writes, stores their ids in brain.json, maps the Tasks database and records the owner's identities. Changes nothing in Notion. Use when the user says "connect the brain to Notion", after building the Notion space, when Notion is unreachable, or when a skill reports a Notion database is not configured.
+description: Connect the brain to the user's Notion space after it was built from the notion/ prompts. Gives the agent access to Notion, finds the Brain Data page and its databases, checks each has the properties the brain reads and writes, stores their ids in brain.json, maps the Tasks database and records the owner's identities. Also lists and switches the optional modules (Knowledge, Orgs, Documents, Reports, Tasks, Planning), walking the user through a module's Notion steps when it is turned on. Changes nothing in Notion itself. Use when the user says "connect the brain to Notion", "which modules do I have?", "turn on documents", "turn planning off", after building the Notion space, when Notion is unreachable, or when a skill reports a Notion database is not configured or a module is off.
 ---
 
 # Connect the brain to Notion
@@ -11,6 +11,19 @@ Run CLI commands as `brain <command> --brain <brain> --json`. If `brain` is not
 
 ## Procedure
 
+0. **Modules** (decision 0048), at the first connection, when the user hasn't chosen yet. Run `brain modules` and show the checklist, with what each module adds and its default:
+
+   ```
+   Core (always on): Inbox, Meetings, Projects, Areas, People, Review
+   [x] Knowledge: Decisions, Questions, Concepts
+   [x] Orgs: client and partner organizations
+   [ ] Documents: keep a document, or part of one, as a page
+   [ ] Reports: ask the brain in the Inbox, get a report you can refresh
+   [ ] Tasks: action items as Notion tasks
+   [ ] Planning: Goals and Key Results
+   ```
+
+   Ask once: "Keep these, or change some? (e.g. "add documents")". Write each change with `brain modules on|off <module>`. The steps below look only for the databases of modules that are on; a database that exists for a module that is off is reported ("Goals found; Planning is off: say "turn on planning" to use it"), and its id is still stored.
 1. **Check access.** The Notion connection (MCP) must reach the user's workspace. Search for the page **"Brain Data"**:
    - **No Notion tools in this session:** the agent isn't connected to Notion. Give the user the steps in "Connect your agent to Notion" below for the agent they are using, and stop.
    - **Not found:** the connection can't see the page. With the hosted Notion MCP, the user's own Notion account must have access to Brain Data; with an integration token, open Brain Data in Notion → `•••` → **Connections** → add the integration. Then stop.
@@ -31,9 +44,10 @@ Run CLI commands as `brain <command> --brain <brain> --json`. If `brain` is not
    | Review | `review` |
    | Inbox (called Capture Inbox before 0.3.0) | `inbox` |
    | Concepts | `concepts` |
+   | Documents (called References before migration 0010) | `documents` |
    | Tasks | `notion.tasks.database` (below) |
 
-   A missing database is reported, not invented. The brain works without it, and the skills that need it say so.
+   A missing database is reported, not invented. A missing database of a module that is on is the module's Notion steps still to do ("Turning a module on" below); the brain works without it, and the skills that need it say so.
 3. **Check each database** (read-only). Retrieve the database, then its data source (current Notion API: a database has `data_sources`, and its properties live on the data source). Check that every property in docs/notion-space-design.md §3 for that database exists with the right type: relations point to the right database, and selects have the listed options.
    - Report each difference as `Database · Property: expected …, found …`.
    - Report two select options that share an id (it has happened after adding an option through Notion AI), and suggest deleting and re-adding the option by hand.
@@ -54,8 +68,21 @@ Run CLI commands as `brain <command> --brain <brain> --json`. If `brain` is not
 9. **Report:**
    - the databases connected;
    - anything missing or different from the design (step 3);
+   - the modules on, and those with a database still missing;
    - what to do next: build the Notion space's missing parts, or run `brain-sync` to import the rows you already created in Notion (0021), then ingest reviewed meetings.
 
+## Turning a module on or off
+
+When the user asks ("turn on documents", "turn planning off", "which modules do I have?"), outside the procedure above:
+
+1. **List:** `brain modules`. Report each module as on or off; for one that is on, its `missing` databases.
+2. **Off:** `brain modules off <module>`, commit `modules: <module> off`. Say what stops: "Planning off: catch-up no longer reads Goals or Key Results. Nothing is deleted; turn it on again any time." Nothing changes in Notion; the user may hide the databases themselves.
+3. **On:** `brain modules on <module>`. Then check what Notion still needs. `missing` lists only the module's empty database ids, so it can't tell whether the module's properties, relations and buttons exist (and Reports has no database at all): read the databases `notion/modules/<module>.md` touches (step 3 above) and compare them with the file's steps, through each step's Verify item.
+   - **Everything there:** commit `modules: <module> on`, and say what the next catch-up does with it.
+   - **Something missing** (a database, a property, a relation, a button): walk the user through `notion/modules/<module>.md` in the product repo, from its first step that isn't done, step by step: the Notion AI prompts they paste, the buttons and layouts they set by hand, then find the new database under Brain Data (step 2 above), check it (step 3) and store its id with `brain config set notion.databases.<key> '"<id>"'` (Tasks: step 5). This skill doesn't build anything in Notion itself (decision 0022). Run `brain modules` again (`missing` is empty) and the file's Verify list. Commit `modules: <module> on`.
+   - **The user stops halfway:** the module stays on with a part missing; with a database id missing, its notes are skipped with `DATABASE_NOT_CONFIGURED` until the id is set, and a missing property or button means the requests it carries never arrive. Say so, and that "turn on <module>" picks up where they left off.
+4. **Report** in three lines: what changed, what still needs them in Notion, and the next step.
+
 ## Connect your agent to Notion
 
 The agent reads and writes Notion through a Notion MCP server (decision 0015). Give the user the steps for their agent; they run them in their own terminal, then restart the agent in the brain folder.

package/.agents/skills/brain-howto/references/guide.md

@@ -7,6 +7,19 @@ Your second brain has three parts:
 
 You never edit the Markdown by hand. You work in Notion and talk to your agent.
 
+**Modules.** The space is a core you always have (Inbox, Meetings, Projects, Areas, People, Review) plus the modules you choose:
+
+| Module | Adds | On for a new brain |
+|---|---|---|
+| **Knowledge** | Decisions, Questions, Concepts | yes |
+| **Orgs** | Client and partner organizations | yes |
+| **Documents** | A document, or part of one, kept as a page you can read | no |
+| **Reports** | Ask the brain in the Inbox, and get a report you can refresh | no |
+| **Tasks** | Action items as Notion tasks | no |
+| **Planning** | Goals and Key Results | no |
+
+Change them any time by asking your agent: "turn on documents", "I don't use goals, turn planning off", "which modules do I have?". Turning one on walks you through its Notion steps; turning one off deletes nothing, and the brain simply stops reading and writing its databases. This guide describes every module; skip what you haven't turned on.
+
 ---
 
 ## The Spaces
@@ -21,12 +34,12 @@ The navigation on the left of every page lists the Spaces. Each one has tabs tha
 | **Projects** | Keep projects moving | Active · By area · Deadlines · Gone quiet |
 | **Plan** | Check that your work serves your goals | Goals · Key results · Areas · Projects by goal |
 | **Review** | Decide on the changes the brain proposes | Needs my decision · Sources disagree · Approved recently · Rejected |
-| **Knowledge** | Find what the brain knows, and everything that came in | Decisions · Questions · Concepts · References · People · Orgs · Inbox (What's in my inbox?: captures New or Ready · What came in?: everything ingested, with what it produced) |
+| **Knowledge** | Find what the brain knows, and everything that came in | Decisions · Questions · Concepts · Documents · People · Orgs · Inbox (What's in my inbox?: captures New or Ready · What came in?: everything ingested, with what it produced) |
 | **Archive** (under System) | Find finished and archived records | One tab per database |
 
 **Area pages** collect everything for one area: its goals, projects, tasks, meetings, decisions and open questions in views, and its people and clients as lists at the top. The brain adds a **Brief** toggle at the end: the area's projects with their status, and its recent decisions and open questions. Open one from Plan → Areas.
 
-**Project pages** show the Brief and Decision log (written by the brain), then the project's tasks, meetings, open questions and people, "What came in?" (every input filed under the project), "What do we know?" (its decisions, concepts and references) and **Reports** (the project's reports), then your own "My notes".
+**Project pages** show the Brief and Decision log (written by the brain), then the project's tasks, meetings, open questions and people, "What came in?" (every input filed under the project), "What do we know?" (its decisions, concepts and Documents) and **Reports** (the project's reports), then your own "My notes".
 
 **A Brief shows only what you reviewed.** Decisions and questions still in Draft stay out of it until you accept them in Review. When a section has nothing reviewed yet, it says how many notes are waiting: "Nothing reviewed yet: 4 notes waiting in Review".
 
@@ -90,18 +103,23 @@ Changes to what the brain already knew come first, and a changed fact is marked
 - **Reject** applies nothing, and archives the notes that are still Draft. Nothing is deleted.
 - If a fact changed since the row was written (you edited it in Notion, say), only that item is dropped, and the report says so. The rest applies.
 
-**Rows of their own** are for the calls that need your judgment: two sources that disagree, a new decision replacing an older one, a possible duplicate, and an answer to one of your open questions.
+**Three kinds of row.** Every Review row's Name says which it is:
+- **From <source>:** everything one meeting, email or document brings, lettered as above;
+- **Conflict: …** two sources disagree, a new decision replaces an older one, or two records may be duplicates. These need your judgment, so each has a row of its own;
+- **Answer: …** new material answers one of your open questions.
 
 **Answer rows.** When new material answers one of your open questions, an Answer row says so: "Who owns the mobile app? → Carlos Ruiz owns it". Approve it and the question shows as **Answered** in Notion; Fix it to give the answer yourself; Reject it and the question stays open.
 
 **Type your corrections in What to fix,** never in About, Now or Proposed: those are the brain's, and typing there does nothing.
 
+The row's **Kind** property (hidden in your views) says exactly what the brain proposes:
+
 | Kind | Approve means |
 |---|---|
 | Review Notes | Everything listed: the changes are made, the notes become Reviewed, the links are added. Reject archives the Draft notes |
 | Update Fact | The new value replaces the old one; the old one stays in the history |
 | Add To Note | The text is added to the note |
-| Update Body | A reference note's text is replaced by its new version; Proposed shows the lines that change (`-` old, `+` new) |
+| Update Body | A Document's text is replaced by its new version; Proposed shows the lines that change (`-` old, `+` new) |
 | Add Link | The links listed are added (people to a project, an alias to a person) |
 | Contradiction | Two sources disagree; both claims are kept as contested. Fix with the true value |
 | Supersede | A newer note replaces an older one, which is archived |
@@ -121,7 +139,7 @@ A rejected change can come back if a later meeting says the same thing again.
 - **The minutes are wrong** (a misheard name, a wrong date): fix the minutes on the meeting page, then set Brain Status back to **Reviewed**. The next catch-up reads the meeting again and proposes only what changed, in one Review row. The same goes for a capture: fix its text and set its Brain Status to **Ready**.
 - **The minutes are right, but the brain read them wrong** (the wrong project, a suggestion taken as a decision): on the Review row, set Your call to **Fix** and say what's wrong in What to fix ("c is a suggestion, not a decision", "a belongs to Acme app"). If the row was already approved, tell your agent what's wrong, or set the note's Lifecycle to **Disputed**.
 
-**How do I refresh a report?** Tick **Refresh** on the Report row in the Inbox, then "catch up": the brain rewrites that report in place, as of today, and clears the box. Or create an **Ask the brain** row with **Refresh report** set to the report: the catch-up updates that report and links your question to it. An Ask row with Refresh report empty makes a new report. The earlier versions stay in the brain's history.
+**How do I refresh a report?** Click **Refresh** on the Report row in the Inbox (it ticks **Refresh asked**), then "catch up": the brain rewrites that report in place, as of today, and unticks the box. Or say "refresh the Acme launch report". A new **Ask the brain** row always makes a new report. The earlier versions stay in the brain's history.
 
 **A report says something wrong?** Write it in the Report row's **What to fix** ("Lucía left Acme in June"). The mistake lives in the notes the report rests on, so the next catch-up turns it into Review rows on those notes. Once you approve them, it refreshes the report.
 
@@ -133,16 +151,16 @@ Hover over a property name to see its owner. Each description starts with "Owner
 
 | Owner | Examples | What happens when you edit it |
 |---|---|---|
-| **You** | Status, Priority, Dates, Lifecycle, Archived, Your call, What to fix, Brain Status on meetings and captures, Project, Area and Keep on an Inbox row, Full text, Refresh | Your value stands. The brain reads it but never overwrites it; it clears Full text, Refresh and a report's What to fix once it has acted on them |
+| **You** | Status, Priority, Dates, Lifecycle, Archived, Your call, What to fix, Brain Status on meetings, Project, Area, Kind and Only keep on an Inbox row, the buttons and the boxes they tick (Document asked, Refresh asked, Promote asked) | Your value stands. The brain reads it but never overwrites it; it unticks a button's box and clears a report's What to fix once it has acted on them, and sets a row it took in to Done. It fills Kind only when you left it empty |
 | **Brain** | Summary, Role, Client, Key Facts, Why, Assessment | The next sync reads your edit as a **correction**. Names, summaries and relations change in place; a key fact gets a dated history entry; judgments such as Assessment become a Review proposal |
 | **System** | Brain ID, Last Synced, Ingested At | Don't edit. The brain uses them to match records |
 
 **Page text:**
 - **Brief and Decision log** on project pages, and the **Brief** on area pages, are rewritten by the brain on every sync. Anything you type inside them is lost.
 - **My notes**, and everything else on a page, is yours.
-- Decision, Question, Concept and Reference pages are written entirely by the brain.
+- Decision, Question and Concept pages are written entirely by the brain. So is a Document's page, except a promoted one ("Buttons" below): its text is yours once it's made.
 - A capture's text is yours; the brain only adds its Kind, Summary and what it produced. An Ask row's text is yours too.
-- **Inbox rows the brain creates** (a document, email, web page, a repo file) get a **digest** in their body: what the input is, a summary and the key points, with figures and dates as stated. Emails and chats also get their whole text in a **Full text** toggle. For a document, tick **Full text** on its row (or say "full text for …") and the next catch-up adds it. Both are written once and never read back, so an edit you make there stays in Notion. The original file is the real copy.
+- **Inbox rows the brain creates** (a document, email, web page, a repo file) get a **digest** in their body: what the input is, a summary and the key points, with figures and dates as stated. It is written once and never read back, so an edit you make there stays in Notion. To read the whole input in Notion, keep it as a Document ("Buttons" below). The original file is the real copy. A **Full text** toggle on an older row stays as it is.
 - A question's **Status** is yours. The brain sets it twice at most: **Open** when it creates the question, and **Answered** once, when you approve an Answer row.
 
 **Lifecycle** tells you how far to trust a record:
@@ -155,18 +173,42 @@ Set **Disputed** on anything wrong. The brain stops relying on it, and you can a
 
 ---
 
+## The Inbox and its buttons
+
+Every Inbox row moves through **Brain Status**: **New → Ready → Done**.
+- **New:** a row you created by hand. The brain leaves it alone.
+- **Ready:** the brain takes it in at the next "catch up". **Quick capture** creates its row as Ready.
+- **Done:** the brain took it in, or skipped it and says why in Summary ("Skipped: same as Acme requirements"). Rows the brain creates for documents, emails and web pages start as Done.
+
+**Buttons** ask the brain for something. Each ticks a box on the same row, which reads as "waiting for the brain"; the next "catch up" acts on it and unticks it.
+
+| Button | On | Ticks | The brain then |
+|---|---|---|---|
+| **Keep as document** | Inbox rows | Document asked (and sets the row to Ready) | Keeps the row's file, or its text when it has no file, as a **Document**: the whole of it, or only what you wrote in **Only keep** ("just the requirements table") |
+| **Refresh** | Report rows | Refresh asked | Rewrites the report as of today |
+| **Promote to document** | Decisions, Concepts | Promote asked | Makes a Document from the note, linked both ways, whose text is yours to edit from then on |
+
+**Documents** (the Documents module). A Document is a page you read, linked to its source, project and area:
+- **the whole input:** the text exactly as it came in. It needs no review and is Reviewed straight away;
+- **a part** (Only keep set, or "also keep the budget from the Acme doc"): what you asked for, as a list or a table. It arrives as Draft in the source's Review row, like a new note;
+- **promoted** from a decision or concept: it starts from the note, then you write in it.
+
+The brain still reads every input for decisions, questions and people, whether or not you keep it as a Document. A new version of the file later proposes only the lines that changed.
+
+---
+
 ## Adding things
 
 | You want to add | Do this |
 |---|---|
-| A quick thought, link or idea | **Quick capture** on Home. It lands in Knowledge → Inbox as **New**. Set its **Project** if you know it, so the agent doesn't ask. Set Brain Status to **Ready** when it's ready; a capture still New a day later is taken in anyway. Then "catch up" (or "process my inbox") |
+| A quick thought, link or idea | **Quick capture** on Home. It lands in Knowledge → Inbox as **Ready**. Set its **Project** if you know it, so the agent doesn't ask. A row you create by hand starts as **New**: set it to Ready when it's ready. Then "catch up" (or "process my inbox") |
 | A meeting | **New meeting** on Home, or let Notion AI create it when it starts taking notes |
 | A project, area, goal, person or org | Create the row in Notion (**New project** on Home for projects). The next sync imports it into the brain |
-| A document (PDF, Word, PowerPoint, Excel, saved HTML page, image) | Put it in your drop folder and tell your agent "process my drop folder". It lists the files and asks once which to take, and **what to keep** from each: "all", or "just the requirements". With a Keep, the brain writes one **Reference** note holding just that (a list or a table), linked to its project, and nothing else; a new version of the document later proposes only the lines that changed. Then, each ingested file moves to `processed/` inside the folder, so what's left at the top is what the brain hasn't read yet. Or name one file: "ingest this PDF: ~/Documents/brain-dropbox/proposal.pdf". Word, PowerPoint, Excel and HTML files need MarkItDown installed once: `pipx install 'markitdown[all]'` |
+| A document (PDF, Word, PowerPoint, Excel, saved HTML page, image) | Put it in your drop folder and tell your agent "process my drop folder". It lists the files and asks once which to take, and, with Documents on, whether to **keep each as a document**: "no" (the default: the brain only reads it), "all", or "only the requirements" ("The Inbox and its buttons"). A new version of a document later proposes only the lines that changed. Then, each ingested file moves to `processed/` inside the folder, so what's left at the top is what the brain hasn't read yet. Or name one file: "ingest this PDF: ~/Documents/brain-dropbox/proposal.pdf". Word, PowerPoint, Excel and HTML files need MarkItDown installed once: `pipx install 'markitdown[all]'` |
 | A web page | Give your agent the link: "ingest this page: https://…". For a page behind a login, save it as a PDF in your drop folder instead |
-| A file from your phone | Attach it to a **Quick capture** (or to the meeting page), with Project set if you know it, and **Keep** to say what you want from the file. Set the row to **Ready**; the next catch-up reads the file with the row. Files on project and area pages are not read |
+| A file from your phone | Attach it to a **Quick capture** (or to the meeting page), with Project set if you know it. To keep the file itself as a Document, click **Keep as document** (and write in **Only keep** if you want just a part). The row is Ready; the next catch-up reads the file with the row. Files on project and area pages are not read |
 | A repo's knowledge (decisions, docs, changelog) | "link the repo at ~/code/acme-api to the area Clients, files decisions/** and docs/*.md". Each catch-up then reads the files changed since the last one; the first time, it asks which to take. The brain never writes to the repo |
-| A question for a full report | **Ask the brain** on Home: type the question as the Name ("Where do we stand with the Acme launch?"). The next catch-up answers with a **Report** row in the Inbox, linked from yours, and on the project's or area's page under **Reports**. To bring it up to date later, tick **Refresh** on it ("Correcting what came in") |
+| A question for a full report | **Ask the brain** on Home: type the question as the Name ("Where do we stand with the Acme launch?"). The next catch-up answers with a **Report** row in the Inbox, linked from yours, and on the project's or area's page under **Reports**. To bring it up to date later, click **Refresh** on it ("Correcting what came in"). Needs the Reports module |
 | An email, chat thread or note | Paste it into a **Quick capture** (keep who sent it and when). For a thread, run **`/Clean email`** on the page: Brain Assistant gives each message a heading with names and date ("Tomás Vidal → Lucía Fernández · 3 Dec 2026"), its own text word for word below it, and a divider before the next, newest first. It drops addresses, signatures, disclaimers, quoted copies and Teams, Zoom or Meet blocks, and rewrites the page right away (the page history keeps the original), asking first only when something is truly unclear. Then set the row to **Ready** and "catch up". Or paste it straight to your agent: "ingest this email" |
 | A task | Add it in Tasks. Action items from meetings, and your own from documents, emails and captures, are created for you |
 
@@ -212,7 +254,9 @@ Run these in Claude Code or Codex, from your brain's folder.
 | Bring Notion edits and new rows into the brain, and publish its changes | "sync with Notion" |
 | Ask what the brain knows | "what did we decide about …?", "who is …?", "when is the … launch?" |
 | Get a report on a subject: where it stands, a timeline, decisions, open questions, people and gaps | "report on the Acme launch". It includes notes you haven't reviewed, marked *(not reviewed)*, and is published as a Report row. "refresh the Acme launch report" rewrites it as of today |
-| Have a document's whole text in Notion | "full text for the Acme brief", or "slides 3–9 of the launch deck" (or tick Full text on its Inbox row) |
+| Keep a document, or part of one, as a page | "keep the Acme brief as a document", "also keep the budget from the Acme doc" (or click **Keep as document** on its Inbox row) |
+| Turn a decision or concept into a page you write in | "promote Use Supabase for auth to a document" (or click **Promote to document** on it) |
+| Turn a module on or off | "turn on documents", "turn planning off", "which modules do I have?" |
 | Read a repo into the brain | "link the repo at <path> to the area <name>, files <patterns>" |
 | Ask how the system works | "how do I …?", "why didn't … ?" (or ask Brain Assistant in Notion) |
 | Change the Notion structure (a property, an option, a view) | "add a property to Projects …". Structure is changed in the product first, then in Notion |
@@ -236,10 +280,12 @@ Run these in Claude Code or Codex, from your brain's folder.
 | A Review row with What to fix is still pending | The agent couldn't tell what it meant, or it described a different change | Answer the agent's question, or look for the new row it proposed |
 | A Fix row is still pending | What to fix is empty | Say what's wrong in What to fix |
 | A row "Deferred from …" appeared | You approved a row "all except …": the items you left out wait there | Decide it like any other row |
-| A capture wasn't taken in | It is still New and less than a day old, or it is Skipped; a document, email or note waits for Ready | Set it to **Ready**, then "catch up" |
+| A capture wasn't taken in | It is still **New**: the brain takes in only Ready rows | Set it to **Ready**, then "catch up" |
 | You fixed the minutes after the ingest, and nothing changed | The meeting is still Ingested | Set it back to **Reviewed**, then "catch up" |
 | You want to see what the brain made from a document | Every input has a row in Knowledge → Inbox → What came in?, and on its project's page | Open the row: the body has the digest, and Decisions, Questions, Concepts and People list what it produced |
 | A Brief says "Nothing reviewed yet" | Its notes are still Draft | Approve their Review notes rows, then "catch up" |
-| A document's row shows only the digest | Documents and decks get a digest by default | Tick **Full text** on the row, then "catch up" |
-| A capture was skipped | It repeats a source the brain already has; the report names that source | Nothing, or say "ingest it anyway" if it adds something |
+| A document's row shows only the digest | Inbox rows get a digest; the whole text lives in a Document | Click **Keep as document** on the row, then "catch up" |
+| A capture is Done but produced nothing | It repeats a source the brain already has; its Summary says "Skipped: same as …" | Nothing, or say "ingest it anyway" if it adds something |
+| A button's box stays ticked | No catch-up has run since, or the module is off | "catch up"; if the report says the module is off, "turn on documents" (or reports) |
+| Goals, Tasks or Documents aren't updated any more | Their module is off | "which modules do I have?", then "turn on …" |
 | A file attached to a capture wasn't read | Its format can't be read, or the file is broken | The catch-up's Check line names the file and the fix |

package/.agents/skills/brain-ingest/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brain-ingest
-description: Ingest into the brain reviewed meeting minutes from Notion or a file, documents (PDF, Word, PowerPoint, Excel, HTML, images), web pages by URL, pasted emails, chat threads and notes, the Notion Inbox, files attached in Notion, and the changed files of a linked repo. Snapshots each input as a source, matches it against what the brain already knows, writes new notes (meeting, people, decisions, questions, concepts, and a reference note for what you asked to keep from a document) as drafts, with one Review row per source holding them and every change to existing knowledge, proposes answers to open questions, reads a corrected input again for only what changed, and creates action items as Notion tasks. Use when the user says "ingest my meetings", "process the reviewed minutes", "ingest this PDF", "ingest this page <url>", "ingest this email", "process my inbox", "process my drop folder", "link the repo at <path>", or after marking meetings Reviewed.
+description: Ingest into the brain reviewed meeting minutes from Notion or a file, documents (PDF, Word, PowerPoint, Excel, HTML, images), web pages by URL, pasted emails, chat threads and notes, the Notion Inbox, files attached in Notion, and the changed files of a linked repo. Snapshots each input as a source, matches it against what the brain already knows, writes new notes (meeting, people, decisions, questions, concepts) as drafts, keeps an input as a Document (whole, or a part) when asked, with one Review row per source holding the new notes and every change to existing knowledge, proposes answers to open questions, reads a corrected input again for only what changed, and creates action items as Notion tasks. Use when the user says "ingest my meetings", "process the reviewed minutes", "ingest this PDF", "ingest this page <url>", "ingest this email", "process my inbox", "process my drop folder", "link the repo at <path>", or after marking meetings Reviewed.
 ---
 
 # Ingest into the brain
@@ -60,7 +60,9 @@ The rules in the brain's AGENTS.md apply throughout (if the brain has none, they
    - contradictions with the loaded notes;
    - action items.
 
-   Keep every claim attached to its subject, and copy values verbatim. Hold the result in memory as two lists: **new notes** and **changes to existing notes**. A document with a **Keep** yields one `reference` note and nothing else (references/extraction.md, "Keep").
+   Keep every claim attached to its subject, and copy values verbatim. Hold the result in memory as two lists: **new notes** and **changes to existing notes**. *(Documents)* When the input is to be kept as a document (Document asked on its row, the drop folder's answer, or the user's words), add its **Documents** to the new notes: references/extraction.md, "Documents". The notes are extracted either way (decision 0049).
+
+   **A re-read** analyses only the changed lines, and a changed line **corrects** what the old line said (decision 0045, U-18): propose to replace the old statement (references/extraction.md "Re-reads": an `update_fact` for a fact, else an `add_to_note` worded as a correction), never to add the new wording as a second claim next to the old one, and never mark the pair ambiguous.
 
 7. **Write new notes.** Write **one** `brain note new` batch containing the source, the meeting, new people, new decisions and new questions (shapes in [references/cli-inputs.md](references/cli-inputs.md) §2).
    1. **Get ids** with `brain id new <type> --count <n>`, so the notes can reference each other by id. The meeting lists its `decisions` and `questions`, and each decision's `decided_in` and each question's `raised_in` names the meeting, so the pair is consistent.
@@ -71,18 +73,20 @@ The rules in the brain's AGENTS.md apply throughout (if the brain has none, they
 8. **Propose changes.** Write every change to an existing note in **one** `brain proposal new` batch ([references/cli-inputs.md](references/cli-inputs.md) §3):
    - a fact change → `update_fact`;
    - text to add to an existing note → `add_to_note`;
-   - a reference note's new text, from a new version of its document → `update_body` (references/extraction.md, "Keep");
+   - a Document's new text, from a new version of its file → `update_body` (references/extraction.md, "Documents"); never on a promoted Document, whose body is the user's;
    - a link to add to an existing note's list → `add_link`: a new or existing person joining a project's `people`, an attendee missing from an existing meeting, a new alias for an existing person (decision 0028);
    - two sources disagreeing → `contradiction`;
    - a new decision replacing an older one → write the new decision in step 7, then `supersede`;
    - a likely duplicate → `merge`;
    - a new decision or question for a meeting that already existed before this run → `new_item`.
 
-   - a new note this run wrote, every `add_link`, `update_fact`, `update_body` and `add_to_note` → **one** `review_notes` item for the input (decisions 0041, 0043, 0045): `{ "kind": "review_notes", "source": "<mtg-id, or the src- id for any other input>", "notes": [<every knowledge note step 7 created: the meeting, people, decisions, questions, concepts, references; never the source>] }`, with `notes: []` when the input created none (a re-read). The CLI folds every change and link item with the same `source` into it, fact changes first, so they are lettered items of that one Review row, and writes its title ("From Acme sync: 2 changes, 1 new note and 1 link"). Send the change items as usual, each with its own `title` and `why`. Only judgment calls get rows of their own: `contradiction`, `supersede`, `merge`, `new_item` and `answer`;
+   - a new note this run wrote, every `add_link`, `update_fact`, `update_body` and `add_to_note` → **one** `review_notes` item for the input (decisions 0041, 0043, 0045): `{ "kind": "review_notes", "source": "<mtg-id, or the src- id for any other input>", "notes": [<every knowledge note step 7 created: the meeting, people, decisions, questions, concepts, `part` Documents; never the source, and never a `whole` Document, which needs no Review>] }`, with `notes: []` when the input created none (a re-read). The CLI folds every change and link item with the same `source` into it, fact changes first, so they are lettered items of that one Review row, and writes its title ("From Acme sync: 2 changes, 1 new note and 1 link"). Send the change items as usual, each with its own `title` and `why`. Only judgment calls get rows of their own: `contradiction`, `supersede`, `merge`, `new_item` and `answer`;
    - the material answers an open question the brain already has → `answer`, on that question: the answer in one sentence, the quote as `why`, and `answer_note` = the note that answers it when there is one (usually a decision step 7 created).
 
    `DUPLICATE_PENDING`, `ALREADY_LINKED` and `ALREADY_ANSWERED` skips are fine: the change is already waiting for review, already made, or the question already has an answer. `NOTHING_TO_REVIEW` means the input created no note and no link: fine too.
 
+   **Never edit a proposal or a note file yourself** (`sed`, a text editor, a script; U-18): the CLI writes them, with their hashes and log entries. A proposal that came out wrong is rejected or fixed through brain-apply; a new batch with the right values is written instead, and the wrong one is closed when the user rejects it. If lint fails on a file this run wrote, stop (step 9).
+
 9. **Rebuild and check.** Run `brain index`, `brain views`, then `brain lint`. If lint reports an **error in a file this run wrote**, stop: report it and do not commit. Errors that were already there before the run are not yours to fix here; mention them.
 
 10. **Log and commit.** Run `brain log ingest <mtg-id> created=<n> proposals=<n> tasks=<n>`. Commit in the brain repo: `ingest: <meeting title> <date> (<n> new, <n> proposals)`. If this run does not publish, push now (step 11, "Push"); otherwise push after the publish commit.
@@ -108,7 +112,7 @@ The rules in the brain's AGENTS.md apply throughout (if the brain has none, they
     - **Next:** one action, or one question when the user must decide something. Without Notion, the next action is deciding the proposals in chat ("what needs my decision"), or connecting Notion ("connect the brain to Notion"), after which a sync publishes everything.
 
     **Below the three lines, the report grows with what came in** (decision 0037, amended 2026-10-18). A run that only moved counts stops at three lines. Otherwise add, per input, one line each, and leave nothing out because the list is long:
-    - **What came in:** every new project, decision (with its assessment), open question and risk, every fact that changed (old → new), new people with their role, and each reference note with what it keeps. A one-line summary of what a document or thread is about comes first. For a re-read: "Acme sync, read again: 1 change (launch 2027-02 → 2027-03)".
+    - **What came in:** every new project, decision (with its assessment), open question and risk, every fact that changed (old → new), new people with their role, and each Document with what it keeps ("the whole file", or what Only keep named). A one-line summary of what a document or thread is about comes first. For a re-read: "Acme sync, read again: 1 change (launch 2027-02 → 2027-03)".
     - **Check:** every assumption the user should verify: a date taken from today or from a month only, a fact marked ambiguous, a name left unlinked, a part of a document not analysed.
     - **Action items** that didn't become tasks.
 

package/.agents/skills/brain-ingest/references/cli-inputs.md

@@ -47,11 +47,12 @@ A document, a web page, then a pasted email:
 - **Capture:** `source_key` is `notion:<row page id>`, `kind` is `capture`, `origin_edited` is the row's `last_edited_time`.
 - **`summary`** (every kind except minutes, added in the real run of step 6, not the step 3 dry run), in `frontmatter` like every field below: one line on what the source taught. It is the Inbox row's Summary.
 - **`digest`** (in `frontmatter`; every kind except minutes, captures and attachments, added with `summary`; decision 0043): the key points by section and the figures and dates as stated, in Markdown. It is the body of the Inbox row.
-- **`notion_text`** and **`notion_parts`:** leave them out unless the user chose otherwise; the CLI writes `full` for `email` and `chat`, `digest` for `document` and `note`. `"notion_text": "full", "notion_parts": ["3-9"]` puts slides 3 to 9 on the row. Never send `notion_text_requested`: only `brain source full-text` writes it.
+- **Never send `notion_text`, `notion_parts`, `notion_text_requested` or `keep`:** they are retired (decision 0049) and the CLI refuses them (`INPUT_INVALID`). A whole text to read in Notion is a `whole` Document (§2, "Documents").
 - **A linked repo's file** (decision 0042) adds `"repo": "<name>", "repo_path": "decisions/0041-review.md", "commit": "<the listing's to, 40 hex>"` to a `document` with a `file:` key, `file_name` = the path's last segment and `converter: verbatim` for a text file.
-- **`keep`** (decision 0045; `document`, `email`, `chat` or `note` only, never a capture): what the user asked to keep, as written (`"keep": "just the requirements"`). Leave it out for "all".
+- **`only_keep`** (decision 0049; any kind but `minutes` and `capture`, attached files included): what the user asked to keep as a Document, as written (`"only_keep": "just the requirements"`), from the row's Only keep, the drop folder's "only …" or the user's words. Leave it out when the whole input is kept, or none of it. An attached file takes its row's Only keep.
+- **`area`** and **`projects`** (decision 0050): the Area and Project the user set on the Inbox row (or the meeting), as brain ids. Each must be an existing area or project, else the CLI refuses the batch (`UNKNOWN_ID`). Leave them out when the row has none.
 - **`replaces`** (decision 0045): on a re-read or a new version, the `src-` id of the version it follows. The CLI then dedupes it by content only, and refuses an id that isn't a source or that another source already replaces (`INPUT_INVALID`).
-- **A file attached in Notion** adds `"attached_to": "<the parent's src- id>"` to a `document` with a `file:` key, and has no `digest`, `notion_text` or `notion_parts`. The parent must exist already or come earlier in the same batch.
+- **A file attached in Notion** adds `"attached_to": "<the parent's src- id>"` to a `document` with a `file:` key, and has no `digest`. The parent must exist already or come earlier in the same batch.
 - **Title:** `<title> (<kind>)`; for a web page, `<title>` is the page's own title. **`file_date`:** the text's own date (a document's date, a web page's stated publication or update date, an email's sent date); for a capture, the row's Created date; else today.
 - **Dates in the notes:** a new note's timeline `from` is the date the text gives, else the source's `file_date`; `learned` is always today (the day the brain learned it).
 - **Duplicates:** the CLI also skips a source whose `file:` key, or whose `capture` row, was already ingested, even if the text differs.
@@ -91,18 +92,27 @@ Things the CLI checks that are easy to get wrong:
 - **The meeting body uses relative links**, e.g. `../people/…`, `../decisions/…`, `../../projects/<slug>/project.md`.
 - **Sources (`sources`) of knowledge notes are the meeting id.** The meeting itself cites the source snapshot.
 
-### A reference note (decision 0045)
+### Documents (decisions 0045, 0049)
 
-What a Keep produces, in the same batch as its source:
+A Document is a `reference` note with an `origin` (references/extraction.md, "Documents"). In the same batch as its source when the input is new; on its own for a source already in the brain.
 
 ```json
+{ "type": "reference", "id": "ref-6p2v8k4m", "title": "Acme website brief",
+  "frontmatter": { "origin": "whole", "summary": "Acme's brief for the new website, as sent.",
+                   "area": "area-2m7c4h8n", "projects": ["prj-9x4t1b7e"], "sources": ["src-5t8n2v6q"] },
+  "body": "<the source's body, byte for byte>" }
 { "type": "reference", "id": "ref-4k8m2q7w", "title": "Acme website: requirements",
-  "frontmatter": { "summary": "The requirements from Acme's website brief.", "projects": ["prj-9x4t1b7e"],
+  "frontmatter": { "origin": "part", "summary": "The requirements from Acme's website brief.", "projects": ["prj-9x4t1b7e"],
                    "area": "area-2m7c4h8n", "sources": ["src-5t8n2v6q"] },
   "body": "## Requirements\n\n- Login with email\n- Launch in 2027-02\n" }
+{ "type": "reference", "id": "ref-9w3c7n2t", "title": "Use Supabase for auth",
+  "frontmatter": { "origin": "promoted", "promoted_from": "dec-3f7k9m2q", "summary": "Acme moves auth from Firebase to Supabase.",
+                   "projects": ["prj-9x4t1b7e"], "sources": ["mtg-8c4n2p7w"] },
+  "body": "Acme moves auth from Firebase to Supabase.\n\n## Decision\nUse Supabase for auth.\n" }
 ```
 
-`sources` is required. It goes in the input's `review_notes` like any new note.
+- **`origin` is required.** `whole`: `sources` is exactly that one `src-` id and the body is its body byte for byte, or the CLI refuses it; the CLI writes it as `reviewed`, and a second one of the same source comes back in `skipped` as `ALREADY_KEPT` (fine). `part`: a draft that goes in the input's `review_notes` like any new note. `promoted`: `promoted_from` names an existing decision or concept that has no promoted Document yet; it takes that note's lifecycle; `sources` may be left out.
+- Leave `whole` and `promoted` Documents out of `review_notes`: they need no Review.
 
 ## 3. The proposals batch
 
@@ -126,7 +136,7 @@ What a Keep produces, in the same batch as its source:
 - **`title`** reads as a Review row: `<subject> <field>: <old> → <new>`.
 - **Other kinds** (spec/schema.md §11):
   - `add_to_note`: `target`, `content`. A link in `content` is relative to the target note's folder.
-  - `update_body` (decision 0045): `target` = a `reference` note, `content` = its whole new body, every unchanged line copied exactly. The CLI stores the old body's hash, so a body changed meanwhile is caught as stale, and refuses a `content` equal to the body (`NO_CHANGE`).
+  - `update_body` (decisions 0045, 0049): `target` = a Document (`reference` note) whose `origin` isn't `promoted`, `content` = its whole new body, every unchanged line copied exactly. The CLI stores the old body's hash, so a body changed meanwhile is caught as stale, and refuses a `content` equal to the body (`NO_CHANGE`).
   - `contradiction`: `target`, `field`, `after` (the target must have a current value).
   - `supersede`: `target` = the new note, `supersedes` = the old one.
   - `merge`: `target` = the duplicate, `merge_into` = the survivor.