@latysh-development/monolith 0.1.0-alpha.0 → 0.1.0-alpha.1

package/README.md

@@ -29,34 +29,64 @@ decisions — instead of relying on an assistant's unaided memory.
 
 ## Why MONOLITH?
 
-AI assistants lose context between sessions, and what a project "knows" ends up
-scattered across chats, notes and habits. MONOLITH keeps that knowledge in the
-project itself, in a form both a person and an assistant can read, check and
-trust — using mechanisms that are deterministic and testable.
+You are deep in a task when a good idea arrives — one that has nothing to do
+with what you are doing right now. Switching to it would break your focus, so
+you postpone it. A few hours later it is buried in a long chat, or simply gone.
+
+A conversation history is a poor place to keep it. It is tied to one session,
+it is hard to search, and an AI assistant that starts a new session does not
+carry it over. A thought that only lives in a chat lasts as long as the chat.
+
+MONOLITH keeps that knowledge in the project itself: ideas, structured project
+context and recorded decisions, as plain Markdown that both a person and an
+assistant can read, check and commit. You save the idea, and keep working.
+
+> **Your AI assistant may forget the conversation. Your project shouldn't forget the ideas.**
+
+Ideas are where MONOLITH started, not where it ends: the same approach — durable,
+inspectable, deterministic — also covers project state and execution governance.
 
 ## What MONOLITH Does
 
+- **Idea Capture** — save a thought that is unrelated to the current task, without losing focus. You decide what to save; ideas are stored as one Markdown file each in `.monolith/memory/long-term/ideas/`, independent of the active story, and are managed with `monolith idea add|list|show` or by an assistant that follows your project's instructions.
 - **Observable** — `monolith brief` summarizes project state in the terminal, including whether it looks stale; Mission Control shows it in a local, read-only web interface.
 - **Structured** — structure is extracted from a project's own markdown (frontmatter, headings, explicit links) into an explicit relationship graph. No embeddings, no LLM, no fuzzy matching.
 - **Governed** — protocols, skills and cognitive modes describe how an assistant reads and updates project memory; missions and checkpoints record progress. This is a recorded discipline, not a runtime gate.
 - **Reproducible** — same input, same output. State lives in a schema-versioned file written with a lock and atomic replace; Durable State adds a hash-chained event log.
 - **Bounded** — managed files are read and written through strict primitives that refuse symlinks; `monolith validate` never executes project code; Mission Control has no write endpoint.
 
+## Idea Capture Example
+
+```bash
+monolith idea add \
+  --title 'Automatic Tool Tests' \
+  --description 'Generate tests from business tool contracts'
+
+monolith idea list
+monolith idea show IDEA-001
+```
+
+`IDEA-001` is a demonstration ID; the real ID is printed by `idea add`, and
+`idea list` shows every saved idea.
+
+With an AI assistant, you can simply say: *"Save this idea for later."* The
+assistant then saves it by running `monolith idea add` — it does not edit idea
+files itself. This works because `monolith init` installs instructions and an
+`idea-capture` skill for the assistant; it is not guaranteed for an arbitrary
+model without that setup. Details and limits: [`monolith idea` in the CLI reference](./docs/reference/cli.md#monolith-idea).
+
+Ideas are saved and recalled **manually**. There is no automatic idea detection,
+no automatic recall or reminders, no idea status management and no idea UI yet.
+
 ## Quick Start
 
-Requires Node.js >= 20. MONOLITH is an alpha package that is **not published
-to npm**. Build it from a clone:
+Requires Node.js >= 20. Install the published alpha package from npm:
 
 ```bash
-git clone https://github.com/Demion-L/the_monolith.git
-cd the_monolith
-pnpm install
-pnpm build
-npm link             # exposes the `monolith` command (or run: node dist/cli/index.js)
+npm install -g @latysh-development/monolith@alpha
 ```
 
-Once the first alpha is published, `npm install -g @latysh-development/monolith@alpha`
-becomes the primary install path ([release notes](./docs/release/alpha-installation.md)).
+To build from source instead, see the [installation and release guide](./docs/release/alpha-installation.md).
 
 Then, in a project directory:
 
@@ -71,6 +101,23 @@ monolith ui          # Mission Control at http://127.0.0.1:4173 ; Ctrl+C to stop
 instance, and it does not open a browser — open the printed address yourself.
 All commands: [CLI reference](./docs/reference/cli.md).
 
+## Updating an Existing Project
+
+If a project was initialised with an earlier MONOLITH version, bring it up to the current agent integration (agent entry point and Idea Capture) with:
+
+```bash
+monolith update            # preview: shows the plan, writes nothing
+monolith update --apply    # applies the safe changes
+```
+
+- The first command only prints a plan and does not modify the project.
+- The second applies the safe changes (missing MONOLITH-owned files and managed blocks).
+- Your project memory (`active.md`, `decisions.md`, roadmap, stories, ideas) and your own files are preserved.
+- A managed block you have edited is never overwritten automatically.
+- On a conflict the command writes nothing to that file and reports that manual resolution is required.
+
+Details and the full list of verdicts: [`monolith update` in the CLI reference](./docs/reference/cli.md#monolith-update).
+
 ## Architecture
 
 ```text
@@ -104,7 +151,7 @@ listing — not an official partnership, endorsement or certification.
 
 ## Documentation
 
-- [CLI reference](./docs/reference/cli.md) — every command, `init`, `validate`, `brief`, `mission`, `durable`, `ui`
+- [CLI reference](./docs/reference/cli.md) — every command, `init`, `validate`, `brief`, `idea`, `mission`, `durable`, `ui`
 - [Mission Control](./docs/reference/mission-control.md) — sections, LIVE/DEMO, skins, limitations
 - [Security & Limitations](./docs/reference/security-and-limitations.md) — threat model, platform and filesystem caveats
 - [Programmatic API](./docs/reference/write-scope-api.md) · [Development](./docs/reference/development.md)
@@ -113,8 +160,8 @@ listing — not an official partnership, endorsement or certification.
 
 ## Project Status
 
-**Alpha** (`0.1.0-alpha.0`). The API and CLI are experimental and may change
-without notice. Not published to npm. Durable State and the Coordinatorium
+**Alpha** (`0.1.0-alpha.1`). The API and CLI are experimental and may change
+without notice. Published to npm under the alpha dist-tag. Durable State and the Coordinatorium
 (`monolith durable`, `monolith mission`) are experimental and are not part of
 the Quick Start.
 

package/dist/brief/collect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../src/brief/collect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwBH,OAAO,KAAK,EACV,UAAU,EAMX,MAAM,YAAY,CAAC;AAepB,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,QAAa,CAAC;AAsRnD,wBAAsB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAkEpE"}
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../../src/brief/collect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwBH,OAAO,KAAK,EACV,UAAU,EAOX,MAAM,YAAY,CAAC;AAiBpB,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,QAAa,CAAC;AA8TnD,wBAAsB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAqEpE"}

package/dist/brief/collect.js

@@ -18,9 +18,11 @@ import { discoverDocs } from './docs.js';
 import { extractCurrentStory } from './story.js';
 import { selectActiveMissions, selectRecentFinishedMissions, selectLatestCheckpoint, hasCheckpointOrderMismatch, } from './selectors.js';
 import { stateFilePath, validateState, createInitialState, MAX_STATE_BYTES } from '../coordinatorium/index.js';
-import { ACTIVE_MD_REL, PROTOCOLS_DIR, ROADMAP_INDEX_REL, STORY_INDEX_REL, HANDOFF_REL } from './constants.js';
+import { ACTIVE_MD_REL, PARKED_IDEAS_LIMIT, PROTOCOLS_DIR, ROADMAP_INDEX_REL, STORY_INDEX_REL, HANDOFF_REL } from './constants.js';
 import { evaluateFreshness, parseActiveStoryClaim, parseRoadmapActiveStory, parseRoadmapStatuses, parseStoryIndexStatuses, } from './freshness.js';
 import { readGitSignals } from './git-signals.js';
+import { ideaStore, listIdeas } from '../ideas/index.js';
+import { ideaNumber } from '../ideas/format.js';
 const RECENT_FINISHED_MISSIONS_LIMIT = 5;
 /** SEC-001B.1: `active.md` is a short hand-written context file (~3 KB today). */
 export const MAX_ACTIVE_CONTEXT_BYTES = 256 * 1024;
@@ -211,6 +213,42 @@ function collectStory(targetDir, monolithRoot, root, diagnostics) {
         provenance: { source: extraction.lineRange ? `${relPath}:${extraction.lineRange}` : relPath },
     };
 }
+const IDEAS_UNREADABLE_LISTED = 3;
+/**
+ * IDEA-002A: the `inbox` ideas, via the Idea Capture reader (`listIdeas`: bounded,
+ * symlink/hardlink/special-file refusing, never writes). A file that cannot be read
+ * as an idea is not counted and is reported as one warning — it never breaks the
+ * brief. Idea content is untrusted; only ids and titles are kept.
+ */
+function collectParkedIdeas(targetDir, diagnostics) {
+    const empty = { total: 0, items: [] };
+    let entries;
+    try {
+        entries = listIdeas(ideaStore(targetDir));
+    }
+    catch (err) {
+        const code = err instanceof Error && 'code' in err ? String(err.code) : 'ERROR';
+        diagnostics.push({
+            code: 'IDEAS_UNREADABLE',
+            severity: 'warn',
+            message: `The ideas directory was not read (${code}); parked ideas are not shown.`,
+        });
+        return empty;
+    }
+    const inbox = entries.flatMap((e) => (e.ok && e.idea.status === 'inbox' ? [e.idea] : []));
+    inbox.sort((a, b) => ideaNumber(b.id) - ideaNumber(a.id));
+    const bad = entries.flatMap((e) => (e.ok ? [] : [e]));
+    if (bad.length > 0) {
+        const listed = bad.slice(0, IDEAS_UNREADABLE_LISTED).map((e) => `${e.id} (${e.code})`).join(', ');
+        const more = bad.length > IDEAS_UNREADABLE_LISTED ? `, and ${bad.length - IDEAS_UNREADABLE_LISTED} more` : '';
+        diagnostics.push({
+            code: 'IDEAS_UNREADABLE',
+            severity: 'warn',
+            message: `${bad.length} idea file(s) could not be read and are not counted as parked: ${listed}${more}. Run \`monolith idea show <id>\`.`,
+        });
+    }
+    return { total: inbox.length, items: inbox.slice(0, PARKED_IDEAS_LIMIT).map((i) => ({ id: i.id, title: i.title })) };
+}
 /**
  * Best-effort read of one state document for the freshness check. A missing,
  * refused or unreadable file simply contributes no evidence — freshness never
@@ -286,6 +324,7 @@ export async function collect(targetDir) {
         items: discoverDocs(targetDir, adrDirs, (fields) => fields.get('status') === 'accepted', diagnostics),
         provenance: { source: adrDirs.join(', ') },
     };
+    const parkedIdeas = monolithInitialized ? collectParkedIdeas(targetDir, diagnostics) : { total: 0, items: [] };
     return {
         identity,
         monolithInitialized,
@@ -295,6 +334,7 @@ export async function collect(targetDir) {
         story,
         mandatoryProtocols,
         adrs,
+        parkedIdeas,
         diagnostics,
         freshness,
         freshnessEvidence,

package/dist/brief/constants.d.ts

@@ -7,4 +7,6 @@ export declare const PROTOCOLS_DIR = "protocols";
 export declare const ROADMAP_INDEX_REL = "context/maps/roadmap-index.md";
 export declare const STORY_INDEX_REL = "memory/working/story-index.md";
 export declare const HANDOFF_REL = "context/boot/HANDOFF.md";
+/** IDEA-002A: most parked ideas the brief ever lists; the rest is a "+N more" count. */
+export declare const PARKED_IDEAS_LIMIT = 3;
 //# sourceMappingURL=constants.d.ts.map

package/dist/brief/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/brief/constants.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,eAAO,MAAM,aAAa,6BAA6B,CAAC;AACxD,sIAAsI;AACtI,eAAO,MAAM,eAAe,aAAa,CAAC;AAC1C,eAAO,MAAM,aAAa,cAAc,CAAC;AACzC,qGAAqG;AACrG,eAAO,MAAM,iBAAiB,kCAAkC,CAAC;AACjE,eAAO,MAAM,eAAe,kCAAkC,CAAC;AAC/D,eAAO,MAAM,WAAW,4BAA4B,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/brief/constants.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,eAAO,MAAM,aAAa,6BAA6B,CAAC;AACxD,sIAAsI;AACtI,eAAO,MAAM,eAAe,aAAa,CAAC;AAC1C,eAAO,MAAM,aAAa,cAAc,CAAC;AACzC,qGAAqG;AACrG,eAAO,MAAM,iBAAiB,kCAAkC,CAAC;AACjE,eAAO,MAAM,eAAe,kCAAkC,CAAC;AAC/D,eAAO,MAAM,WAAW,4BAA4B,CAAC;AACrD,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,IAAI,CAAC"}

package/dist/brief/constants.js

@@ -7,3 +7,5 @@ export const PROTOCOLS_DIR = 'protocols';
 export const ROADMAP_INDEX_REL = 'context/maps/roadmap-index.md';
 export const STORY_INDEX_REL = 'memory/working/story-index.md';
 export const HANDOFF_REL = 'context/boot/HANDOFF.md';
+/** IDEA-002A: most parked ideas the brief ever lists; the rest is a "+N more" count. */
+export const PARKED_IDEAS_LIMIT = 3;

package/dist/brief/render.d.ts

@@ -48,6 +48,13 @@
  * two forces INCOMPLETE. P0 is never dropped. All project-controlled
  * strings, provenance pointers included, pass through
  * `sanitizeSingleLine` (N-1).
+ *
+ * Advisory section (IDEA-002B): Parked Ideas is the one data-holding section whose
+ * budget degradation does NOT force INCOMPLETE. It is user-saved side context, not
+ * project state; its degradation stays visible (fewer items, count, or a marker
+ * whenever they fit) but `Completeness` and `--strict` keep describing only the
+ * project context that existed before ideas did. Unreadable idea files are
+ * reported by the `IDEAS_UNREADABLE` warning, which is not an error.
  */
 import type { BriefModel } from './types.js';
 export declare const DEFAULT_MAX_CHARS = 6000;

package/dist/brief/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/brief/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAsE,MAAM,YAAY,CAAC;AAYjH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAGtC,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,YAAY,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,YAAY,CAAC;CAC5B;AAiVD,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,GAAE,MAA0B,GAAG,YAAY,CAsE5F"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/brief/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,KAAK,EAAE,UAAU,EAA0F,MAAM,YAAY,CAAC;AAYrI,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAGtC,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,YAAY,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,YAAY,CAAC;CAC5B;AAwXD,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,GAAE,MAA0B,GAAG,YAAY,CAgF5F"}

package/dist/brief/render.js

@@ -48,8 +48,15 @@
  * two forces INCOMPLETE. P0 is never dropped. All project-controlled
  * strings, provenance pointers included, pass through
  * `sanitizeSingleLine` (N-1).
+ *
+ * Advisory section (IDEA-002B): Parked Ideas is the one data-holding section whose
+ * budget degradation does NOT force INCOMPLETE. It is user-saved side context, not
+ * project state; its degradation stays visible (fewer items, count, or a marker
+ * whenever they fit) but `Completeness` and `--strict` keep describing only the
+ * project context that existed before ideas did. Unreadable idea files are
+ * reported by the `IDEAS_UNREADABLE` warning, which is not an error.
  */
-import { ACTIVE_MD_REL } from './constants.js';
+import { ACTIVE_MD_REL, PARKED_IDEAS_LIMIT } from './constants.js';
 import { sanitizeSingleLine, sanitizeMultiLine } from './sanitize.js';
 // Shorthand for the existing single-line sanitizer — applied to every string
 // that originates in project files or configuration (N-1), including
@@ -352,6 +359,41 @@ function fitItemList(header, items, footer, remaining, omittedMarkerFn, minimalF
     }
     return { text: '', consumed: 0, lossFlag: true };
 }
+const PARKED_IDEA_TITLE_MAX = 80;
+function formatParkedIdea(i) {
+    const title = san(i.title);
+    const shown = title.length > PARKED_IDEA_TITLE_MAX ? `${title.slice(0, PARKED_IDEA_TITLE_MAX - 1).replace(/[\ud800-\udbff]$/, '')}…` : title;
+    return `  ${san(i.id)}  ${shown}\n`;
+}
+/**
+ * IDEA-002A: Parked Ideas — the lowest-priority section. Nothing at all when there
+ * are none (so a project without ideas renders exactly as before). Under budget
+ * pressure it first lists fewer ideas, then only the count, then a one-line
+ * marker, then nothing. Each step is flagged in `lossFlag`, but `render` does not
+ * count it towards Completeness (advisory section, see the Completeness contract).
+ * Listing at most `PARKED_IDEAS_LIMIT` ideas is the design, not a loss.
+ */
+function buildParkedIdeasSection(ideas, remaining) {
+    if (!ideas || ideas.total === 0)
+        return { text: '', consumed: 0, lossFlag: false };
+    const header = `\n## Parked Ideas (${ideas.total})\n`;
+    const explore = '  Explore: `monolith idea list`\n';
+    const wanted = Math.min(PARKED_IDEAS_LIMIT, ideas.items.length);
+    const noun = (n) => (n === 1 ? 'idea' : 'ideas');
+    const candidates = [];
+    for (let k = wanted; k >= 1; k--) {
+        const rest = ideas.total - k;
+        const body = ideas.items.slice(0, k).map(formatParkedIdea).join('');
+        const more = rest > 0 ? `\n  +${rest} more ${noun(rest)}\n` : '';
+        const text = header + body + more + explore;
+        candidates.push({ text, consumed: text.length, lossFlag: k < wanted });
+    }
+    const countOnly = `${header}  ${ideas.total} ${noun(ideas.total)}, not listed (budget)\n${explore}`;
+    const marker = `\n[Parked Ideas (${ideas.total}) omitted — budget; \`monolith idea list\`]\n`;
+    for (const text of [countOnly, marker, BARE_OMIT_MARKER])
+        candidates.push({ text, consumed: text.length, lossFlag: true });
+    return candidates.find((c) => c.consumed <= remaining) ?? { text: '', consumed: 0, lossFlag: true };
+}
 const P3_TEXT = '\n## More\n' +
     '  Full checkpoint history: `monolith mission checkpoints <id>`\n' +
     '  Mission detail: `monolith mission show <id>`\n' +
@@ -394,6 +436,15 @@ export function render(model, maxChars = DEFAULT_MAX_CHARS) {
         p2 += finishedSection.text;
         remaining -= finishedSection.consumed;
         budgetLoss = budgetLoss || finishedSection.lossFlag;
+        // Parked ideas are optional extra context: they get what is left after everything
+        // else, and never the room the static P3 pointer block would have had. Their
+        // budget loss is shown locally (fewer ideas / count / marker) but deliberately does
+        // not feed `budgetLoss`: saving an idea must not flip an unchanged project's brief
+        // to INCOMPLETE and break `--strict` checks of the main project context.
+        const p3Fits = P3_TEXT.length <= remaining;
+        const ideasSection = buildParkedIdeasSection(model.parkedIdeas, p3Fits ? remaining - P3_TEXT.length : remaining);
+        p2 += ideasSection.text;
+        remaining -= ideasSection.consumed;
         if (P3_TEXT.length <= remaining) {
             p3 = P3_TEXT;
             remaining -= p3.length;

package/dist/brief/types.d.ts

@@ -17,7 +17,7 @@ export type DiagnosticSeverity = 'info' | 'warn' | 'error';
  * budget decision is made, which is what lets render() reserve space for
  * them deterministically (see render.ts's two-phase budget accounting).
  */
-export type BriefDiagnosticCode = 'MONOLITH_NOT_INITIALIZED' | 'STATE_NOT_INITIALIZED' | 'STATE_EMPTY' | 'STATE_UNREADABLE' | 'STATE_LEGACY_SCHEMA_MIGRATED' | 'MULTIPLE_ACTIVE_MISSIONS' | 'CHECKPOINT_ORDER_MISMATCH' | 'ACTIVE_MD_MISSING' | 'ACTIVE_MD_REJECTED' | 'ACTIVE_MD_UNREADABLE' | 'ACTIVE_MD_NO_CURRENT_STORY' | 'CONFIG_UNREADABLE' | 'CONFIG_ADR_DIRS_INVALID' | 'DOC_DIR_UNREADABLE' | 'DOC_FILE_UNREADABLE' | 'DOC_DIR_OUTSIDE_PROJECT' | 'PATH_OUTSIDE_PROJECT' | 'WRITE_ARTIFACTS_PRESENT';
+export type BriefDiagnosticCode = 'MONOLITH_NOT_INITIALIZED' | 'STATE_NOT_INITIALIZED' | 'STATE_EMPTY' | 'STATE_UNREADABLE' | 'STATE_LEGACY_SCHEMA_MIGRATED' | 'MULTIPLE_ACTIVE_MISSIONS' | 'CHECKPOINT_ORDER_MISMATCH' | 'ACTIVE_MD_MISSING' | 'ACTIVE_MD_REJECTED' | 'ACTIVE_MD_UNREADABLE' | 'ACTIVE_MD_NO_CURRENT_STORY' | 'CONFIG_UNREADABLE' | 'CONFIG_ADR_DIRS_INVALID' | 'DOC_DIR_UNREADABLE' | 'DOC_FILE_UNREADABLE' | 'DOC_DIR_OUTSIDE_PROJECT' | 'PATH_OUTSIDE_PROJECT' | 'WRITE_ARTIFACTS_PRESENT' | 'IDEAS_UNREADABLE';
 export interface BriefDiagnostic {
     code: BriefDiagnosticCode;
     severity: DiagnosticSeverity;
@@ -84,6 +84,20 @@ export interface ProjectIdentity {
     monolithRoot: string;
     provenance: Provenance;
 }
+/** IDEA-002A: one parked (status `inbox`) idea, as shown by the brief. */
+export interface ParkedIdeaRef {
+    id: string;
+    title: string;
+}
+/**
+ * IDEA-002A: the `inbox` ideas, projected from the Idea Capture store (never
+ * re-parsed here). `items` holds at most `PARKED_IDEAS_LIMIT` entries, newest
+ * numeric id first; `total` counts every readable `inbox` idea.
+ */
+export interface ParkedIdeasSummary {
+    total: number;
+    items: ParkedIdeaRef[];
+}
 export interface BriefModel {
     identity: ProjectIdentity;
     monolithInitialized: boolean;
@@ -93,6 +107,8 @@ export interface BriefModel {
     story: StorySummary;
     mandatoryProtocols: ProtocolIndex;
     adrs: AdrIndex;
+    /** IDEA-002A: optional so a hand-built model without it renders as before. */
+    parkedIdeas?: ParkedIdeasSummary;
     /** Collect-time diagnostics, in deterministic (collection-order) sequence. */
     diagnostics: BriefDiagnostic[];
     /**

package/dist/brief/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/brief/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/brief/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEzE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC3B,0BAA0B,GAC1B,uBAAuB,GACvB,aAAa,GACb,kBAAkB,GAClB,8BAA8B,GAC9B,0BAA0B,GAC1B,2BAA2B,GAC3B,mBAAmB,GACnB,oBAAoB,GACpB,sBAAsB,GACtB,4BAA4B,GAC5B,mBAAmB,GACnB,yBAAyB,GACzB,oBAAoB,GACpB,qBAAqB,GACrB,yBAAyB,GACzB,sBAAsB,GACtB,yBAAyB,GACzB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CACjC;AAED,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,IAAI,CAAC;AAEzE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,gFAAgF;IAChF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,mFAAmF;IACnF,cAAc,EAAE,OAAO,EAAE,CAAC;IAC1B,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,+FAA+F;IAC/F,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,UAAU,EAAE,OAAO,CAAC;IACpB,8EAA8E;IAC9E,sBAAsB,EAAE,OAAO,CAAC;IAChC,gFAAgF;IAChF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oFAAoF;IACpF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,eAAe,CAAC;IAC1B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,WAAW,EAAE,kBAAkB,CAAC;IAChC,QAAQ,EAAE,eAAe,CAAC;IAC1B,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,KAAK,EAAE,YAAY,CAAC;IACpB,kBAAkB,EAAE,aAAa,CAAC;IAClC,IAAI,EAAE,QAAQ,CAAC;IACf,8EAA8E;IAC9E,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,8EAA8E;IAC9E,WAAW,EAAE,eAAe,EAAE,CAAC;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC"}

package/dist/cli/index.js

@@ -11,6 +11,8 @@
  *   monolith mission    — manage Tactical Coordinatorium mission lifecycle
  *   monolith brief       — deterministic, bounded project context summary
  *   monolith durable     — inspect/verify/maintain Durable State task logs
+ *   monolith idea        — capture and recall deferred ideas (add/list/show)
+ *   monolith update      — add missing Idea Capture infrastructure to an existing instance
  *   monolith ui          — launch Mission Control (read-only dashboard)
  */
 import { MONOLITH_VERSION } from '../version.js';
@@ -38,6 +40,13 @@ Commands:
               accepted ADRs) — read-only, no LLM/network/ERG involved.
   durable     Inspect and maintain Durable State (long-running task logs):
               list | show | assess | packet | verify | retention.
+  idea        Capture a deferred thought without leaving the current task, and
+              recall it later: add | list | show. Plain Markdown files, no LLM.
+  update      Bring an existing instance up to Idea Capture & Recall. Preview by
+              default (changes nothing). --apply creates MONOLITH-managed files
+              and may add or refresh managed sections inside your existing
+              files; your text outside those sections is kept, and conflicting
+              edits are never overwritten (see 'monolith update --help').
   ui          Launch Mission Control, the read-only web dashboard, on
               127.0.0.1 (default port 4173). 'ui dev' adds Vite hot reload
               (source checkout only). See 'monolith ui --help'.
@@ -60,6 +69,14 @@ Durable usage:
   monolith durable verify [taskId]            (exit 2 if a log fails verification)
   monolith durable retention --retain-days N [--compact-after N] [--apply]
 
+Idea usage:
+  monolith idea add --title "..." (--description "..." | --description-stdin) [--context "..."]
+  monolith idea list
+  monolith idea show <id>
+
+Update usage:
+  monolith update [--apply]
+
 UI usage:
   monolith ui [--port N]
   monolith ui dev [--port N]
@@ -72,6 +89,12 @@ async function main() {
     const args = process.argv.slice(2);
     // `ui` owns its own --help / --version-like flags (`monolith ui dev --help`).
     const ownsHelp = args[0] === 'ui';
+    if (args[0] === 'update' && (args.includes('--help') || args.includes('-h'))) {
+        const { UPDATE_USAGE } = await import('../update/cli.js');
+        console.log(UPDATE_USAGE);
+        process.exit(0);
+        return;
+    }
     if (args.length === 0 || (!ownsHelp && (args.includes('--help') || args.includes('-h')))) {
         console.log(USAGE);
         process.exit(0);
@@ -141,6 +164,16 @@ async function main() {
             await runDurableCommand(args.slice(1));
             break;
         }
+        case 'idea': {
+            const { runIdeaCommand } = await import('../ideas/cli.js');
+            await runIdeaCommand(args.slice(1));
+            break;
+        }
+        case 'update': {
+            const { runUpdate } = await import('../update/cli.js');
+            process.exitCode = await runUpdate(args.slice(1));
+            break;
+        }
         case 'ui': {
             const { runUi } = await import('./ui.js');
             process.exit(await runUi(args.slice(1)));

package/dist/discovery/compose.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DISCOVERY-001C — unified Project Map composer (ADR-021). Internal.
+ *
+ * A pure transformation of TWO finished results into one Markdown text: a `DiscoveryResult`
+ * (structural facts, evidence OBSERVED_FILE-class) and a `DocumentationResult` (what documents
+ * claim, evidence DOCUMENT_TEXT). It reads no file, starts no analyzer, calls no model, opens no
+ * connection, keeps no clock and modifies neither input.
+ *
+ * Identity. Neither contract carries a project identity (no id, no root, no digest); both only say
+ * that they were derived from "a traversal". So the composer cannot confirm that the two results
+ * describe the same project and says so in the output. It does not guess from paths or names.
+ *
+ * Trust. The two sources are never merged: structure comes from the existing renderer, unchanged;
+ * documentation gets its own section, and every statement made by a document is shown as an
+ * unverified claim. The statuses of the two analyzers are shown side by side, never combined.
+ *
+ * Markdown safety. Every untrusted string goes through the renderer's `markdownCodeSpan` (control and
+ * bidi characters are shown as [U+XXXX], an inline code span cannot be closed by its content) and sits
+ * in a list item; headings and structure are fixed text. Document text is never interpreted.
+ */
+import { type DiscoveryResult } from './contracts.js';
+import { type DocumentationResult } from './docs.js';
+/**
+ * Composes the unified Project Map. Throws `DiscoveryError('RESULT_INVALID')` if either input fails
+ * its own validator (the message names which input and the first violations, never a value).
+ */
+export declare function composeProjectMap(discovery: DiscoveryResult, documentation: DocumentationResult): string;
+//# sourceMappingURL=compose.d.ts.map

package/dist/discovery/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/discovery/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAqD,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACzG,OAAO,EAKL,KAAK,mBAAmB,EAEzB,MAAM,WAAW,CAAC;AAgCnB;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,eAAe,EAAE,aAAa,EAAE,mBAAmB,GAAG,MAAM,CAoGxG"}

package/dist/discovery/compose.js

@@ -0,0 +1,159 @@
+/**
+ * DISCOVERY-001C — unified Project Map composer (ADR-021). Internal.
+ *
+ * A pure transformation of TWO finished results into one Markdown text: a `DiscoveryResult`
+ * (structural facts, evidence OBSERVED_FILE-class) and a `DocumentationResult` (what documents
+ * claim, evidence DOCUMENT_TEXT). It reads no file, starts no analyzer, calls no model, opens no
+ * connection, keeps no clock and modifies neither input.
+ *
+ * Identity. Neither contract carries a project identity (no id, no root, no digest); both only say
+ * that they were derived from "a traversal". So the composer cannot confirm that the two results
+ * describe the same project and says so in the output. It does not guess from paths or names.
+ *
+ * Trust. The two sources are never merged: structure comes from the existing renderer, unchanged;
+ * documentation gets its own section, and every statement made by a document is shown as an
+ * unverified claim. The statuses of the two analyzers are shown side by side, never combined.
+ *
+ * Markdown safety. Every untrusted string goes through the renderer's `markdownCodeSpan` (control and
+ * bidi characters are shown as [U+XXXX], an inline code span cannot be closed by its content) and sits
+ * in a list item; headings and structure are fixed text. Document text is never interpreted.
+ */
+import { DiscoveryError } from './contracts.js';
+import { validateDiscoveryResult } from './contracts.js';
+import { DOCUMENTATION_DIAGNOSTIC_AFFECTS_COMPLETENESS, validateDocumentationResult, } from './docs.js';
+import { markdownCodeSpan as code, renderProjectMapProposal } from './render.js';
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+function textShown(text, status) {
+    if (status === 'WITHHELD')
+        return '(withheld: contains unsafe characters)';
+    return status === 'TRUNCATED' ? `${code(text)} (truncated)` : code(text);
+}
+function lines(o) {
+    const { startLine, endLine } = o.source;
+    if (startLine === undefined)
+        return 'whole file';
+    return endLine === undefined || endLine === startLine ? `line ${startLine}` : `lines ${startLine}-${endLine}`;
+}
+function docDiagnosticLine(d) {
+    const known = Object.prototype.hasOwnProperty.call(DOCUMENTATION_DIAGNOSTIC_AFFECTS_COMPLETENESS, d.code);
+    const origin = d.code.startsWith('TRAVERSAL_')
+        ? 'reported by the traversal'
+        : known && DOCUMENTATION_DIAGNOSTIC_AFFECTS_COMPLETENESS[d.code]
+            ? 'documentation analysis; makes the result PARTIAL'
+            : 'documentation analysis; does not by itself make the result PARTIAL';
+    const parts = [`${code(d.code)} (${origin})`];
+    if (d.path !== undefined)
+        parts.push(`path ${code(d.path)}`);
+    if (d.count !== undefined)
+        parts.push(`count ${d.count}`);
+    return `- ${parts.join(', ')}: ${code(d.message)}`;
+}
+/** Lowers every heading of the (trusted, fixed-text) renderer output by two levels. Project data cannot start a line with `#`: it only appears inside code spans, and line breaks inside it are escaped. */
+const demote = (markdown) => markdown.replace(/^(#+) /gm, '##$1 ');
+/**
+ * Composes the unified Project Map. Throws `DiscoveryError('RESULT_INVALID')` if either input fails
+ * its own validator (the message names which input and the first violations, never a value).
+ */
+export function composeProjectMap(discovery, documentation) {
+    const dv = validateDiscoveryResult(discovery);
+    if (dv.length > 0)
+        throw new DiscoveryError('RESULT_INVALID', `cannot compose: the DiscoveryResult failed validation (${dv.length} violation(s)): ${dv.slice(0, 3).join('; ')}`);
+    const cv = validateDocumentationResult(documentation);
+    if (cv.length > 0)
+        throw new DiscoveryError('RESULT_INVALID', `cannot compose: the DocumentationResult failed validation (${cv.length} violation(s)): ${cv.slice(0, 3).join('; ')}`);
+    const out = [];
+    const line = (s = '') => void out.push(s);
+    line('# PROJECT MAP');
+    line();
+    line('This document puts two separate results side by side: structure observed in the project tree, and what the project’s Markdown documents say. They are not merged and not compared with each other. It is a proposal for a reader to review.');
+    // ------------------------------------------------------------ structure
+    line();
+    line('## Observed Project Structure');
+    line();
+    line('- Source: a Discovery result (evidence from the traversal: directory entries, file names, package.json fields).');
+    line('- Where the text below says documentation was not analysed, it refers to this Discovery result only; see Documentation Overview for the separate documentation result.');
+    line();
+    out.push(demote(renderProjectMapProposal(discovery)).replace(/\n+$/, ''));
+    // ---------------------------------------------------------------- docs
+    const { stats, observations } = documentation;
+    line();
+    line('## Documentation Overview');
+    line();
+    line('- Source: a Documentation result. Everything below is the content of documents as written by their authors. It is UNVERIFIED: it has not been compared with the code and may be wrong or out of date.');
+    line(`- Analysis completeness: ${documentation.completeness}`);
+    line(documentation.completeness === 'PARTIAL'
+        ? '  - Some documentation information was not extracted; see Diagnostics below. Counts are lower bounds.'
+        : '  - Everything inside the declared scope was handled. COMPLETE does not mean that every Markdown construct was recognised; see the supported subset in Trust & Coverage Notes.');
+    line(`- Reproducible: ${documentation.reproducible ? 'Yes' : 'No'}`);
+    line(`- Traversal behind it: completeness ${documentation.traversal.completeness}, reproducible ${documentation.traversal.reproducible ? 'Yes' : 'No'}`);
+    line(`- Schema version: ${documentation.schemaVersion}`);
+    line(`- Documents listed as present: ${stats.candidateDocuments}; analysed: ${stats.documentsAnalyzed}; present but not analysed: ${stats.documentsNotAnalyzed}`);
+    line(`- Bytes read: ${stats.bytesRead}; observations recorded: ${stats.observations}`);
+    const byPath = new Map();
+    for (const o of observations) {
+        const g = byPath.get(o.source.path);
+        if (g)
+            g.push(o);
+        else
+            byPath.set(o.source.path, [o]);
+    }
+    line();
+    line('### Documents');
+    line();
+    if (byPath.size === 0)
+        line('- No documents were recorded.');
+    for (const [path, group] of byPath) {
+        line(`- ${code(path)}`);
+        for (const o of group) {
+            if (o.kind === 'DOCUMENT_PRESENT') {
+                const size = [o.bytes === undefined ? '' : plural(o.bytes, 'byte', 'bytes'), o.lines === undefined ? '' : plural(o.lines, 'line', 'lines')].filter(Boolean).join(', ');
+                line(`  - File observed (evidence ${o.evidence}); ${o.analysis === 'ANALYZED' ? 'content analysed' : 'content NOT analysed'}${size ? `; ${size}` : ''}`);
+            }
+        }
+        const headings = group.filter((o) => o.kind === 'HEADING');
+        const sections = group.filter((o) => o.kind === 'SECTION');
+        const links = group.filter((o) => o.kind === 'LINK');
+        if (headings.length > 0) {
+            line(`  - Headings written in the document (${headings.length} recorded; evidence ${headings[0].evidence}):`);
+            for (const o of headings)
+                if (o.kind === 'HEADING')
+                    line(`    - ${lines(o)}, level ${o.level}: ${textShown(o.text, o.textStatus)}`);
+        }
+        if (sections.length > 0) {
+            line(`  - Text ranges between headings (${sections.length} recorded; evidence ${sections[0].evidence}):`);
+            for (const o of sections)
+                if (o.kind === 'SECTION')
+                    line(`    - ${lines(o)}, opened by heading ${o.headingOrdinal}${o.parentHeadingOrdinal === undefined ? '' : ` under heading ${o.parentHeadingOrdinal}`}: ${plural(o.ownTextLineGroups, 'text line group', 'text line groups')} of its own`);
+        }
+        if (links.length > 0) {
+            line(`  - Inline links written in the document (${links.length} recorded, not necessarily all; evidence ${links[0].evidence}; targets are not resolved or checked):`);
+            for (const o of links)
+                if (o.kind === 'LINK')
+                    line(`    - ${lines(o)}, ${o.linkType}: target ${code(o.target)}, text ${textShown(o.text, o.textStatus)}`);
+        }
+    }
+    line();
+    line('### Documentation Diagnostics');
+    line();
+    if (documentation.diagnostics.length === 0)
+        line('- No diagnostics were reported.');
+    for (const d of documentation.diagnostics)
+        line(docDiagnosticLine(d));
+    // --------------------------------------------------------------- trust
+    const limits = documentation.limits;
+    line();
+    line('## Trust & Coverage Notes');
+    line();
+    line('- Structural facts in Observed Project Structure were obtained by observing the file tree and, for package.json, declared fields. They are observations, not verified descriptions of how the project works.');
+    line('- Everything in Documentation Overview is unverified document content (evidence DOCUMENT_TEXT). The only observed item there is that a document file exists (evidence OBSERVED_FILE). No documentary statement has been confirmed by the code.');
+    line('- Common origin of the two results is NOT confirmed: neither result carries a project identity, so this document cannot tell whether they describe the same project or the same moment. No such link is asserted.');
+    line('- The two analyzers keep separate statuses and they are not combined:');
+    line(`  - Structural Discovery: completeness ${discovery.completeness}, reproducible ${discovery.reproducible ? 'Yes' : 'No'}`);
+    line(`  - Documentation Analysis: completeness ${documentation.completeness}, reproducible ${documentation.reproducible ? 'Yes' : 'No'}`);
+    line('- COMPLETE refers only to the scope each analyzer declares. It is not a statement that the project or its documents were fully understood.');
+    line('- Documentation scope: README.md at the project root and *.md files under docs/ that the traversal listed. Supported Markdown subset: ATX headings; one-line inline links; fenced code blocks, front matter, HTML comment lines and indented lines are skipped. Not recognised: setext headings, reference-style links, autolinks, images, raw HTML, constructs split over lines, headings or links inside quotes or lists.');
+    line('- Link and heading counts are counts of recognised constructs, not the number of links or headings in a document.');
+    line(`- Documentation limits: documents ${limits.maxDocuments}; bytes per document ${limits.maxDocumentBytes}; total bytes ${limits.maxTotalBytes}; headings per document ${limits.maxHeadingsPerDocument}; links per document ${limits.maxLinksPerDocument}; text length ${limits.maxTextLength}; link target length ${limits.maxTargetLength}; line length ${limits.maxLineLength}; observations ${limits.maxObservations}; diagnostics ${limits.maxDiagnostics}.`);
+    line('- Not observing something is not evidence that it does not exist.');
+    return `${out.join('\n')}\n`;
+}