ultimate-brain 0.5.0 → 0.6.1

package/dist/commands/modules.js

@@ -0,0 +1,54 @@
+import { BrainError } from "../lib/errors.js";
+import { atomicWriteFile } from "../lib/fs-safe.js";
+import { appendLog } from "../lib/log.js";
+import { isModuleName, missingFor, MODULE_DATABASES, MODULE_DEFAULTS, MODULES, modulesOf, withModules } from "../lib/modules.js";
+import { describeErrors, loadSchemas } from "../lib/schemas.js";
+/** `brain modules` (spec/cli.md §5.20). */
+export const modulesListCommand = {
+    name: "modules",
+    usage: "brain modules [--json]",
+    summary: "List the optional modules, whether each is on, and the Notion pieces it still lacks.",
+    options: {},
+    maxPositionals: 0,
+    needsBrain: true,
+    async run({ brain }) {
+        const on = modulesOf(brain.config);
+        const modules = MODULES.map((name) => ({ name, on: on[name], default: MODULE_DEFAULTS[name], databases: [...MODULE_DATABASES[name]], missing: missingFor(brain.config, name) }));
+        const human = modules.map((module) => `${module.on ? "on " : "off"} ${module.name}${module.on && module.missing.length > 0 ? ` (missing: ${module.missing.join(", ")})` : ""}\n`).join("");
+        return { data: { modules }, human };
+    },
+};
+export const modulesOnCommand = switchCommand(true);
+export const modulesOffCommand = switchCommand(false);
+function switchCommand(value) {
+    const word = value ? "on" : "off";
+    return {
+        name: `modules ${word}`,
+        usage: `brain modules ${word} <module> [--json]`,
+        summary: `Switch an optional module ${word} in brain.json.`,
+        options: {},
+        maxPositionals: 1,
+        needsBrain: true,
+        async run({ args, brain, now }) {
+            const [name] = args.positionals;
+            if (name === undefined)
+                throw new BrainError("USAGE", `brain modules ${word} needs a module: ${MODULES.join(", ")}`);
+            if (!isModuleName(name))
+                throw new BrainError("USAGE", `Unknown module: ${name}. Optional modules: ${MODULES.join(", ")} (core has no switch)`);
+            const module = name;
+            const config = brain.config;
+            const missing = missingFor(config, module);
+            if (modulesOf(config)[module] === value) {
+                return { data: { module, on: value, changed: false, missing }, human: `${module} is already ${word}\n` };
+            }
+            // An absent block means every module is on (schema §12): write it out whole, then switch.
+            const next = withModules(config, { ...modulesOf(config), [module]: value });
+            const schemas = loadSchemas();
+            if (!schemas.brain(next))
+                throw new BrainError("BRAIN_CONFIG_INVALID", `brain.json would be invalid: ${describeErrors(schemas.brain.errors).join("; ")}`);
+            await atomicWriteFile(brain.root, "brain.json", `${JSON.stringify(next, null, 2)}\n`);
+            await appendLog(brain.root, now, [{ op: "modules", id: "-", title: module, pairs: [["state", word]] }]);
+            return { data: { module, on: value, changed: true, missing }, human: `${module}: ${word}${value && missing.length > 0 ? ` (Notion still needs: ${missing.join(", ")})` : ""}\n` };
+        },
+    };
+}

package/dist/commands/source.js

@@ -1,58 +1,16 @@
 import { BrainError } from "../lib/errors.js";
-import { rangesProblem, splitParts } from "../lib/parts.js";
 import { lineDiff } from "../lib/diff.js";
-import { hasInboxBody } from "../lib/sync.js";
-import { formatTimestamp } from "../lib/time.js";
 import { Workspace } from "../lib/workspace.js";
-/** `brain source full-text <src-id> [--parts <range>[,<range>…]]` (spec/cli.md §5.17, 0043). */
+/** `brain source full-text` (spec/cli.md §5.17): retired in 0.6.0 by decision 0049. Writes nothing. */
 export const sourceFullTextCommand = {
     name: "source full-text",
     usage: "brain source full-text <src-id> [--parts <range>[,<range>…]] [--json]",
-    summary: "Ask for a source's text on its Inbox row: all of it, or the parts given. The next render writes it once and clears the row's box.",
+    summary: "Retired in 0.6.0: use Keep as document on the source's Inbox row.",
     options: { parts: "string" },
     maxPositionals: 1,
     needsBrain: true,
-    async run({ args, brain, now }) {
-        const [id] = args.positionals;
-        if (id === undefined)
-            throw new BrainError("USAGE", "Name the source: brain source full-text <src-id>");
-        const workspace = await Workspace.open(brain);
-        const note = workspace.get(id);
-        if (note === undefined)
-            throw new BrainError("UNKNOWN_ID", `No note with id ${id}`);
-        const invalid = (message) => { throw new BrainError("INPUT_INVALID", message, [{ pointer: "", message }]); };
-        if (note.type !== "source")
-            invalid(`${id} is a ${note.type}, not a source`);
-        if (!hasInboxBody(note))
-            invalid(`${id} has no Inbox body the brain writes (a minutes or capture source, or an attached file)`);
-        const count = splitParts(note.body).parts.length;
-        const raw = args.options.parts;
-        const parts = raw === undefined ? undefined : raw.split(",").map((part) => part.trim());
-        if (parts !== undefined) {
-            if (parts.some((part) => part === ""))
-                invalid(`--parts ${raw} has an empty item`);
-            const problem = rangesProblem(parts, count);
-            if (problem !== null)
-                invalid(`--parts ${problem}`);
-        }
-        const requested = formatTimestamp(now);
-        const document = workspace.edit(note);
-        document.attributes.notion_text = "full";
-        if (parts === undefined)
-            delete document.attributes.notion_parts;
-        else
-            document.attributes.notion_parts = parts;
-        document.attributes.notion_text_requested = requested;
-        // System fields only: `updated` stays (spec/cli.md §3.6.6).
-        workspace.save(note.path, document);
-        const errors = workspace.newErrors();
-        if (errors.length > 0)
-            throw new BrainError("INPUT_INVALID", errors.map((issue) => `${issue.path}: ${issue.rule}: ${issue.message}`).join("; "));
-        await workspace.commit([{ op: "full-text", id: note.id, title: String(note.attributes.title), pairs: [["parts", parts === undefined ? "all" : parts.join(",")]] }], now);
-        return {
-            data: { id: note.id, path: note.path, parts: count, notion_text: "full", notion_parts: parts ?? null, notion_text_requested: requested },
-            human: `${note.path}: full text${parts === undefined ? "" : ` (parts ${parts.join(", ")} of ${count})`} on the next publish\n`,
-        };
+    async run() {
+        throw new BrainError("RETIRED", "brain source full-text was retired in 0.6.0: use Keep as document");
     },
 };
 /** `brain source diff <src-id>` (spec/cli.md §5.19, 0045): the lines that changed from the version it replaces. */

package/dist/commands/status.js

@@ -6,6 +6,7 @@ import { lintBrain } from "../lib/lint.js";
 import { scanNotes } from "../lib/notes.js";
 import { describeErrors, loadSchemas } from "../lib/schemas.js";
 import { isRecord } from "../lib/input.js";
+import { databaseId, modulesOf } from "../lib/modules.js";
 import { expandPath, linkedRepos, workTreeTop } from "../lib/repos.js";
 const NOTE_TYPES = ["area", "project", "person", "org", "meeting", "decision", "question", "concept", "source", "view", "goal", "memory", "reference"];
 const PROPOSAL_STATUSES = ["pending", "approved", "edited", "rejected", "applied", "closed"];
@@ -61,6 +62,7 @@ export const statusCommand = {
             notes: noteCounts,
             proposals: proposalCounts,
             notion,
+            modules: modulesOf(brain.config),
             settings,
             repos,
             index_stale: currentIndex !== index,
@@ -72,12 +74,10 @@ export const statusCommand = {
 };
 function readNotion(config) {
     const notion = config.notion;
-    const databases = notion.databases;
     const configured = [];
     const missing = [];
-    for (const key of ["areas", "goals", "key_results", "projects", "meetings", "people", "orgs", "decisions", "questions", "review", "inbox", "concepts", "references"]) {
-        const value = key === "inbox" && databases.inbox === undefined ? databases.capture_inbox : databases[key];
-        (typeof value === "string" && value !== "" ? configured : missing).push(key);
+    for (const key of ["areas", "goals", "key_results", "projects", "meetings", "people", "orgs", "decisions", "questions", "review", "inbox", "concepts", "documents"]) {
+        (databaseId(config, key) !== "" ? configured : missing).push(key);
     }
     const tasks = notion.tasks;
     return { configured, missing, tasks_database: typeof tasks.database === "string" && tasks.database !== "" };

package/dist/commands/sync.js

@@ -1,6 +1,7 @@
 import { readJsonInput } from "../lib/input.js";
 import { applyPlan, buildPlan, parsePlan, parseSnapshot, record, render, renderTasks } from "../lib/sync.js";
 import { Workspace } from "../lib/workspace.js";
+import { modulesOf } from "../lib/modules.js";
 import { BrainError } from "../lib/errors.js";
 import { lintWarnings } from "../lib/warnings.js";
 export const syncPlanCommand = {
@@ -43,7 +44,8 @@ export const syncRenderCommand = {
 export const syncTasksCommand = {
     name: "sync tasks", usage: "brain sync tasks (--meeting <mtg-id> | --source <src-id>) --input <file|-> [--json]", summary: "Render action-item task payloads for a meeting or source.", options: { meeting: "string", source: "string", input: "string" }, maxPositionals: 0, needsBrain: true,
     async run({ args, brain }) { const meeting = args.options.meeting; const source = args.options.source; const input = args.options.input; if ((meeting === undefined) === (source === undefined) || input === undefined)
-        throw new BrainError("USAGE", "sync tasks needs exactly one of --meeting or --source, and --input"); return { data: renderTasks(await Workspace.open(brain), meeting ?? source, await readJsonInput(input, "sync tasks")), human: "Task payloads rendered.\n" }; },
+        throw new BrainError("USAGE", "sync tasks needs exactly one of --meeting or --source, and --input"); if (!modulesOf(brain.config).tasks)
+        throw new BrainError("MODULE_OFF", "The Tasks module is off: brain modules on tasks"); return { data: renderTasks(await Workspace.open(brain), meeting ?? source, await readJsonInput(input, "sync tasks")), human: "Task payloads rendered.\n" }; },
 };
 export const syncRecordCommand = {
     name: "sync record", usage: "brain sync record --input <file|-> [--dry-run] [--json]", summary: "Record successful Notion publication results.", options: { input: "string", "dry-run": "boolean" }, maxPositionals: 0, needsBrain: true,

package/dist/commands/upgrade.js

@@ -5,7 +5,9 @@ import { promisify } from "node:util";
 import { BrainError } from "../lib/errors.js";
 import { atomicWriteFile, ensureDirectory } from "../lib/fs-safe.js";
 import { appendLog } from "../lib/log.js";
+import { isRecord } from "../lib/input.js";
 import { lintBrain } from "../lib/lint.js";
+import { modulesOf, withModules } from "../lib/modules.js";
 import { scanNotes } from "../lib/notes.js";
 import { assertPlainPath, installedProduct, listShippedSkillFiles } from "../lib/skills.js";
 const exec = promisify(execFile);
@@ -50,32 +52,33 @@ export const upgradeCommand = {
             changes.push({ path: "CLAUDE.md", action: "created", content: "@AGENTS.md\n" });
         else
             unchanged += 1;
-        // 0.3.0: Inbox is the former Capture Inbox. Keep the database id, but retire the old key.
+        // 0.3.0: Inbox is the former Capture Inbox; 0.6.0: Documents are the former References (0049).
+        // Keep each database id, but retire the old key. 0.6.0 also writes the modules block (0048).
         const brainJson = "brain.json";
         await assertPlainPath(root, brainJson);
         const brainText = await readOptional(join(root, brainJson));
         if (brainText !== null) {
             try {
-                const config = JSON.parse(brainText);
+                let config = JSON.parse(brainText);
+                let changed = false;
                 const notion = config.notion;
-                if (notion !== null && typeof notion === "object" && !Array.isArray(notion)) {
-                    const databases = notion.databases;
-                    if (databases !== null && typeof databases === "object" && !Array.isArray(databases)) {
-                        const values = databases;
-                        if (values.capture_inbox !== undefined) {
-                            const inbox = typeof values.inbox === "string" && values.inbox !== "" ? values.inbox : values.capture_inbox;
-                            const nextDatabases = {};
-                            for (const [key, value] of Object.entries(values)) {
-                                if (key === "capture_inbox")
-                                    nextDatabases.inbox = inbox;
-                                else if (key !== "inbox")
-                                    nextDatabases[key] = value;
-                            }
-                            const next = { ...config, notion: { ...notion, databases: nextDatabases } };
-                            changes.push({ path: brainJson, action: "updated", content: `${JSON.stringify(next, null, 2)}\n` });
-                        }
+                if (isRecord(notion) && isRecord(notion.databases)) {
+                    let databases = notion.databases;
+                    for (const [old, key] of [["capture_inbox", "inbox"], ["references", "documents"]]) {
+                        if (databases[old] === undefined)
+                            continue;
+                        databases = renameKey(databases, old, key);
+                        changed = true;
                     }
+                    if (changed)
+                        config = { ...config, notion: { ...notion, databases } };
+                }
+                if (isRecord(config) && !("modules" in config)) {
+                    config = withModules(config, modulesOf(config));
+                    changed = true;
                 }
+                if (changed)
+                    changes.push({ path: brainJson, action: "updated", content: `${JSON.stringify(config, null, 2)}\n` });
             }
             catch {
                 changes.push({ path: brainJson, action: "skipped" });
@@ -261,3 +264,15 @@ async function gitDirty(root) {
         return false;
     return (await exec("git", ["status", "--porcelain"], { cwd: root })).stdout !== "";
 }
+/** Rename `old` to `key` in place; when `key` already holds an id, just drop `old` (spec/cli.md §5.15 step 5). */
+function renameKey(values, old, key) {
+    const value = typeof values[key] === "string" && values[key] !== "" ? values[key] : values[old];
+    const next = {};
+    for (const [name, existing] of Object.entries(values)) {
+        if (name === old)
+            next[key] = value;
+        else if (name !== key)
+            next[name] = existing;
+    }
+    return next;
+}

package/dist/lib/errors.js

@@ -1,6 +1,7 @@
 /** Error codes and exit codes from spec/cli.md §3.4–3.5. */
 export const EXIT_CODES = {
     USAGE: 2,
+    RETIRED: 2,
     BRAIN_NOT_CONFIGURED: 3,
     BRAIN_NOT_FOUND: 3,
     BRAIN_IS_PRODUCT_REPO: 3,
@@ -15,6 +16,7 @@ export const EXIT_CODES = {
     REPO_NOT_FOUND: 4,
     REPO_IS_BRAIN: 4,
     REPO_COMMIT_UNKNOWN: 4,
+    MODULE_OFF: 4,
     TARGET_NOT_EMPTY: 5,
     ALREADY_A_BRAIN: 5,
     OUTSIDE_ROOT: 5,

package/dist/lib/index-builder.js

@@ -11,7 +11,7 @@ const SECTIONS = [
     ["question", "Questions"],
     ["meeting", "Meetings"],
     ["concept", "Concepts"],
-    ["reference", "References"],
+    ["reference", "Documents"],
 ];
 const NON_KNOWLEDGE = new Set(["source", "view", "proposal"]);
 const TYPES = [...SECTIONS.map(([type]) => type), "source", "view", "proposal", "memory"];
@@ -118,7 +118,7 @@ function typeFields(note, byId) {
         case "meeting":
             return [["date", scalar(a.date)], ["project", refs(a.projects)]];
         case "reference":
-            return [["area", ref(a.area)], ["project", refs(a.projects)]];
+            return [["origin", scalar(a.origin)], ["area", ref(a.area)], ["project", refs(a.projects)]];
         default:
             return [];
     }

package/dist/lib/lint.js

@@ -13,7 +13,7 @@ const ID = /^(area|gol|prj|per|org|mtg|dec|que|con|ref|src|mem|prp|vw)-[0-9abcde
 const REFERENCE_KEYS = new Set([
     "area", "goal", "client", "org", "projects", "people", "attendees", "decided_in", "raised_in", "deciders",
     "source", "sources", "decisions", "questions", "answer", "target", "supersedes", "merge_into", "project",
-    "generated_from", "facts", "notes", "answer_note", "links", "attached_to", "changes", "replaces", "deferred_from",
+    "generated_from", "facts", "notes", "answer_note", "links", "attached_to", "changes", "replaces", "deferred_from", "promoted_from",
 ]);
 /** Where each kind of view must live (spec/schema.md §2, 0041, 0043). */
 const VIEW_FOLDERS = {
@@ -237,8 +237,15 @@ export function lintBrain(input) {
                 const reference = typeof target === "string" ? byId.get(target) : undefined;
                 if (reference !== undefined && reference.type !== "reference")
                     err("update-body", lineOfKey(note, a.kind === "update_body" ? "target" : "changes"), `update_body targets ${reference.id}, a ${reference.type}; only a reference has its body replaced (0045)`);
+                if (reference?.type === "reference" && reference.attributes.origin === "promoted")
+                    err("update-body", lineOfKey(note, a.kind === "update_body" ? "target" : "changes"), `update_body targets ${reference.id}, a promoted Document, whose body is yours (0049)`);
             }
         }
+        if (note.type === "reference" && typeof a.promoted_from === "string") {
+            const from = byId.get(a.promoted_from);
+            if (from !== undefined && from.type !== "decision" && from.type !== "concept")
+                err("promoted-from", lineOfKey(note, "promoted_from"), `promoted_from names ${a.promoted_from}, a ${from.type}, not a decision or concept (0049)`);
+        }
         if (note.type === "source" && typeof a.replaces === "string") {
             const replaced = byId.get(a.replaces);
             if (replaced !== undefined && replaced.type !== "source")

package/dist/lib/modules.js

@@ -0,0 +1,91 @@
+import { isRecord } from "./input.js";
+/** The optional modules of spec/schema.md §12 (decision 0048), in contract order. */
+export const MODULES = ["knowledge", "orgs", "documents", "reports", "tasks", "planning"];
+export const MODULE_DEFAULTS = {
+    knowledge: true,
+    orgs: true,
+    documents: false,
+    reports: false,
+    tasks: false,
+    planning: false,
+};
+/** The `notion.databases` keys each module owns. Reports and Tasks own none (Tasks uses `notion.tasks`). */
+export const MODULE_DATABASES = {
+    knowledge: ["decisions", "questions", "concepts"],
+    orgs: ["orgs"],
+    documents: ["documents"],
+    reports: [],
+    tasks: [],
+    planning: ["goals", "key_results"],
+};
+const MODULE_FOR_TYPE = {
+    decision: "knowledge",
+    question: "knowledge",
+    concept: "knowledge",
+    org: "orgs",
+    reference: "documents",
+    goal: "planning",
+};
+export function isModuleName(value) {
+    return MODULES.includes(value);
+}
+/** Which modules are on: every module when the block is absent, else each absent key at its default. */
+export function modulesOf(config) {
+    const block = config.modules;
+    if (!isRecord(block))
+        return Object.fromEntries(MODULES.map((name) => [name, true]));
+    return Object.fromEntries(MODULES.map((name) => [name, typeof block[name] === "boolean" ? block[name] : MODULE_DEFAULTS[name]]));
+}
+/** The module a note type belongs to, or null for a core type (or one that is never published). */
+export function moduleForType(type) {
+    return MODULE_FOR_TYPE[type] ?? null;
+}
+/** The module a `notion.databases` key belongs to, or null for a core database. */
+export function moduleForDatabase(key) {
+    const name = MODULES.find((module) => MODULE_DATABASES[module].includes(key));
+    return name ?? null;
+}
+/** Whether rows of this note type are published and taken in. */
+export function typeIsOn(config, type) {
+    const module = moduleForType(type);
+    return module === null || modulesOf(config)[module];
+}
+/**
+ * Read a `notion.databases` id, accepting the keys renamed by `brain upgrade`: `inbox` was
+ * `capture_inbox` and `documents` was `references` (schema §12, 0049). Empty string when unset.
+ */
+export function databaseId(config, key) {
+    const notion = config.notion;
+    const databases = isRecord(notion) && isRecord(notion.databases) ? notion.databases : {};
+    const legacy = key === "inbox" ? "capture_inbox" : key === "documents" ? "references" : null;
+    const value = databases[key] === undefined && legacy !== null ? databases[legacy] : databases[key];
+    return typeof value === "string" ? value : "";
+}
+/** The Notion pieces a module still lacks: its empty database ids, and `tasks` when the tasks database is unset. */
+export function missingFor(config, module) {
+    const missing = MODULE_DATABASES[module].filter((key) => databaseId(config, key) === "");
+    if (module === "tasks") {
+        const notion = config.notion;
+        const tasks = isRecord(notion) && isRecord(notion.tasks) ? notion.tasks : {};
+        if (typeof tasks.database !== "string" || tasks.database === "")
+            missing.push("tasks");
+    }
+    return missing;
+}
+/**
+ * A copy of `config` with `block` as its `modules` block: in place when it has one, else after
+ * `settings`, or after `budgets` when there is no `settings`, or at the end (spec/cli.md §5.15 step 5).
+ */
+export function withModules(config, block) {
+    const anchor = "modules" in config ? "modules" : "settings" in config ? "settings" : "budgets" in config ? "budgets" : null;
+    const next = {};
+    for (const [key, value] of Object.entries(config)) {
+        if (key !== "modules")
+            next[key] = value;
+        if (key === anchor)
+            next.modules = block;
+    }
+    if (anchor === null)
+        next.modules = block;
+    return next;
+}

package/dist/lib/note-new.js

@@ -3,7 +3,6 @@ import { BrainError } from "./errors.js";
 import { serializeNewFile } from "./frontmatter.js";
 import { generateId, TYPE_PREFIX } from "./ids.js";
 import { assertNoProblems, escapePointer, isRecord, unknownKeys } from "./input.js";
-import { rangesProblem, splitParts } from "./parts.js";
 import { newNotePath } from "./paths.js";
 import { formatDate, formatTimestamp } from "./time.js";
 const ITEM_KEYS = ["type", "id", "title", "file_date", "frontmatter", "body"];
@@ -52,16 +51,16 @@ export function checkNoteInput(value, pointer, withId = true) {
                 at(`frontmatter/${escapePointer(key)}`, "is set by the CLI");
         }
         if (value.type === "source") {
-            // Order, overlap and the part count are not in the JSON Schema (spec/cli.md §5.5).
-            if (value.frontmatter.notion_text_requested !== undefined)
-                at("frontmatter/notion_text_requested", "is set by brain source full-text");
-            const parts = value.frontmatter.notion_parts;
-            if (Array.isArray(parts) && typeof value.body === "string") {
-                const problem = rangesProblem(parts, splitParts(value.body).parts.length);
-                if (problem !== null)
-                    at("frontmatter/notion_parts", problem);
+            // Read on existing sources, never written again (spec/cli.md §5.5, 0049).
+            if (value.frontmatter.keep !== undefined)
+                at("frontmatter/keep", "is the name before 0.6.0: use only_keep");
+            for (const key of ["notion_text", "notion_parts", "notion_text_requested"]) {
+                if (value.frontmatter[key] !== undefined)
+                    at(`frontmatter/${key}`, "is retired in 0.6.0: Keep as document gives the whole text");
             }
         }
+        if (value.type === "reference" && value.frontmatter.origin === undefined)
+            at("frontmatter/origin", "is required on a new Document: whole, part or promoted");
     }
     return problems;
 }
@@ -125,16 +124,34 @@ export function stageNotes(workspace, items, pointerOf, options) {
         if (repo !== undefined && !repoNames.has(repo))
             parents.push({ pointer: `${pointerOf(index)}/frontmatter/repo`, message: `${String(repo)} is not a linked repo in brain.json repos` });
     });
+    parents.push(...documentProblems(workspace, items, pointerOf));
     assertNoProblems(parents);
+    assertPlacesExist(workspace, items, pointerOf);
     const today = formatDate(options.now);
     const taken = new Set([...existing, ...seen]);
     const result = { created: [], skipped: [], pointers: new Map() };
+    const wholeKept = new Map();
     items.forEach((item, index) => {
         const lf = item.body.replace(/\r\n?/g, "\n");
         const body = lf === "" || lf.endsWith("\n") ? lf : `${lf}\n`;
         const attributes = { type: item.type, title: item.title, ...item.frontmatter };
         if (KNOWLEDGE_TYPES.has(item.type))
             attributes.lifecycle = options.lifecycle ?? "draft";
+        if (item.type === "reference" && attributes.origin === "whole") {
+            // The source's own text needs no Review; one whole Document per source (spec/cli.md §5.5, 0049).
+            const source = String(attributes.sources[0]);
+            const kept = workspace.notes.find((note) => note.type === "reference" && note.attributes.origin === "whole" && Array.isArray(note.attributes.sources) && note.attributes.sources[0] === source)?.id
+                ?? wholeKept.get(source);
+            if (kept !== undefined) {
+                result.skipped.push({ input_index: index, reason: "ALREADY_KEPT", existing: kept });
+                return;
+            }
+            attributes.lifecycle = "reviewed";
+        }
+        if (item.type === "reference" && attributes.origin === "promoted") {
+            // A promoted Document stands where its note stands (0049).
+            attributes.lifecycle = workspace.get(String(attributes.promoted_from))?.attributes.lifecycle ?? attributes.lifecycle;
+        }
         if (item.type === "source") {
             const hash = `sha256:${createHash("sha256").update(body, "utf8").digest("hex")}`;
             const sourceKey = attributes.source_key;
@@ -147,13 +164,6 @@ export function stageNotes(workspace, items, pointerOf, options) {
             }
             attributes.content_hash = hash;
             attributes.captured ??= formatTimestamp(options.now);
-            // The kind sets whether the Inbox row shows the text (0043): full for email and chat.
-            if (attributes.notion_text === undefined && attributes.attached_to === undefined) {
-                if (attributes.kind === "email" || attributes.kind === "chat")
-                    attributes.notion_text = "full";
-                else if (attributes.kind === "document" || attributes.kind === "note")
-                    attributes.notion_text = "digest";
-            }
         }
         const id = item.id ?? generateId(TYPE_PREFIX[item.type], taken);
         taken.add(id);
@@ -165,10 +175,74 @@ export function stageNotes(workspace, items, pointerOf, options) {
         const path = newNotePath(item.type, item.title, date, (candidate) => workspace.exists(candidate), attributes.source_key);
         workspace.write(path, serializeNewFile(attributes, body));
         result.created.push({ id, type: item.type, title: item.title, path });
+        if (item.type === "reference" && attributes.origin === "whole")
+            wholeKept.set(String(attributes.sources[0]), id);
         result.pointers.set(path, pointerOf(index));
     });
     return result;
 }
+/** Normalized body as `stageNotes` writes it: LF line endings and a trailing newline. */
+function writtenBody(body) {
+    const lf = body.replace(/\r\n?/g, "\n");
+    return lf === "" || lf.endsWith("\n") ? lf : `${lf}\n`;
+}
+function sha256(body) {
+    return `sha256:${createHash("sha256").update(body, "utf8").digest("hex")}`;
+}
+/** The Document rules of spec/cli.md §5.5 (0049) that the JSON Schema can't state. */
+function documentProblems(workspace, items, pointerOf) {
+    const problems = [];
+    const promoted = new Map();
+    for (const note of workspace.notes)
+        if (note.type === "reference" && note.attributes.origin === "promoted")
+            promoted.set(String(note.attributes.promoted_from), note.id);
+    items.forEach((item, index) => {
+        if (item.type !== "reference")
+            return;
+        const at = (key, message) => problems.push({ pointer: `${pointerOf(index)}/${key}`, message });
+        const { origin, sources, promoted_from: from } = item.frontmatter;
+        if (origin === "whole") {
+            if (!Array.isArray(sources) || sources.length !== 1 || typeof sources[0] !== "string" || !sources[0].startsWith("src-")) {
+                return at("frontmatter/sources", "a whole Document names exactly one source (src-)");
+            }
+            const id = sources[0];
+            const existing = workspace.get(id);
+            const earlier = items.slice(0, index).find((candidate) => candidate.id === id && candidate.type === "source");
+            const hash = existing?.type === "source" ? existing.attributes.content_hash : earlier !== undefined ? sha256(writtenBody(earlier.body)) : undefined;
+            if (hash === undefined)
+                return at("frontmatter/sources", `${id} is not an existing source or one earlier in the batch`);
+            if (sha256(writtenBody(item.body)) !== hash)
+                at("body", `a whole Document's body must be ${id}'s body byte for byte`);
+        }
+        if (origin === "promoted" && typeof from === "string") {
+            const type = workspace.get(from)?.type;
+            if (type !== "decision" && type !== "concept")
+                return at("frontmatter/promoted_from", `${from} is not an existing decision or concept`);
+            const other = promoted.get(from);
+            if (other !== undefined)
+                return at("frontmatter/promoted_from", `${from} is already promoted to ${other}`);
+            promoted.set(from, item.id ?? `${pointerOf(index)}`);
+        }
+    });
+    return problems;
+}
+/** A source's `area` and `projects` name existing notes of those types (spec/cli.md §5.5, 0050). */
+function assertPlacesExist(workspace, items, pointerOf) {
+    const problems = [];
+    items.forEach((item, index) => {
+        if (item.type !== "source")
+            return;
+        const { area, projects } = item.frontmatter;
+        if (typeof area === "string" && workspace.get(area)?.type !== "area")
+            problems.push({ pointer: `${pointerOf(index)}/frontmatter/area`, message: `${area} is not an existing area` });
+        (Array.isArray(projects) ? projects : []).forEach((project, position) => {
+            if (typeof project === "string" && workspace.get(project)?.type !== "project")
+                problems.push({ pointer: `${pointerOf(index)}/frontmatter/projects/${position}`, message: `${project} is not an existing project` });
+        });
+    });
+    if (problems.length > 0)
+        throw new BrainError("UNKNOWN_ID", `${problems[0].pointer} ${problems[0].message}`, problems);
+}
 /**
  * Throw INPUT_INVALID if the staged writes add lint errors anywhere in the brain (spec/cli.md
  * §3.6.1). Errors in a staged file point at its input item; others name the file and point at `root`.

package/dist/lib/proposals.js

@@ -376,6 +376,8 @@ function resolveFields(workspace, item, pointer, today) {
     if (kind === "update_body") {
         if (target.type !== "reference")
             invalid("target", `is a ${target.type}; update_body replaces the body of a reference`);
+        if (target.attributes.origin === "promoted")
+            invalid("target", `is a promoted Document; its body is yours, edited in Notion (0049)`);
         fields.before_hash = bodyHash(target.body);
     }
     if (kind === "add_link") {