openwriter 0.18.0 → 0.19.0

package/dist/server/documents.js

@@ -129,12 +129,12 @@ export function listDocuments() {
                 // tag overlay from one HTTP round-trip instead of N. The server already
                 // has the parsed frontmatter in hand here; emitting tags is free.
                 ...(Array.isArray(data.tags) && data.tags.length > 0 ? { tags: data.tags } : {}),
-                // Enrichment fields — also free at this point since data is in hand.
-                // See brief 2026-05-18-frontmatter-enrichment-system.
+                // Enrichment fields — free at this point since data is in hand.
+                // v0.19.0 schema: only logline (LLM) + status (agent) + enrichmentStale
+                // (system) are surfaced. domain / concepts / docRole stayed on disk for
+                // legacy docs but are no longer read (lazy migration via mark_enriched).
+                // See brief 2026-05-21-simplify-enrichment-schema-three-fields.
                 ...(typeof data.logline === 'string' && data.logline ? { logline: data.logline } : {}),
-                ...(typeof data.domain === 'string' && data.domain ? { domain: data.domain } : {}),
-                ...(Array.isArray(data.concepts) && data.concepts.length > 0 ? { concepts: data.concepts } : {}),
-                ...(typeof data.docRole === 'string' && data.docRole ? { docRole: data.docRole } : {}),
                 ...(typeof data.status === 'string' && data.status ? { status: data.status } : {}),
                 ...(data.enrichmentStale === true ? { enrichmentStale: true } : {}),
             };
@@ -257,13 +257,15 @@ export function listArchivedDocuments() {
 // ============================================================================
 /** One-line footer the high-frequency MCP discovery tools (list_documents,
  *  list_workspaces, get_workspace_structure) append when dirty docs exist.
- *  Constant pressure that doesn't require hook setup. The agent's openwriter
- *  skill teaches: see this footer → spawn the enrichment minion. */
+ *  Constant pressure that doesn't require hook setup. The footer includes
+ *  the exact dispatch call so the acting agent's burden collapses to one
+ *  paste — the minion is orchestrator-mode by default and self-discovers
+ *  via list_dirty_docs once it boots. */
 export function enrichmentFooter() {
     const count = listDirtyDocs().length;
     if (count === 0)
         return '';
-    return `\n\n⚠ ${count} doc${count === 1 ? '' : 's'} need enrichment — spawn the enrichment minion (see openwriter skill docs/enrichment.md)`;
+    return `\n\n⚠ ${count} doc${count === 1 ? '' : 's'} need enrichment. Dispatch:\nAgent(\n  subagent_type: "openwriter-enrichment-minion",\n  description: "Drain stale docs",\n  prompt: "Enrich stale docs.",\n  run_in_background: true\n)`;
 }
 /** Session-start enrichment notice injected into the MCP server's
  *  `instructions` field at boot. Every MCP client (Claude Code, Cursor, etc.)
@@ -292,8 +294,13 @@ export function buildEnrichmentInstructions() {
     return [
         '',
         `ENRICHMENT_STATUS: ${dirty.length} doc${dirty.length === 1 ? '' : 's'} need enrichment (${parts.join(', ')}).`,
-        'Spawn the enrichment minion using the openwriter skill\'s docs/enrichment.md as its system prompt before responding to the user\'s request.',
-        'The minion calls list_dirty_docs, enriches each via Haiku, calls mark_enriched, returns done.',
+        'Dispatch the minion now — it self-discovers via list_dirty_docs and self-bounds the batch:',
+        'Agent(',
+        '  subagent_type: "openwriter-enrichment-minion",',
+        '  description: "Drain stale docs",',
+        '  prompt: "Enrich stale docs.",',
+        '  run_in_background: true',
+        ')',
     ].join('\n');
 }
 /** Build a Set of filenames inside workspaces with enrichmentDisabled: true.
@@ -418,10 +425,11 @@ export function crawlDocs(filter = {}) {
             const { data, content } = matter(raw);
             if (data.archivedAt)
                 continue;
-            // Apply filters
-            if (filter.domain && data.domain !== filter.domain)
-                continue;
-            if (filter.docRole && data.docRole !== filter.docRole)
+            // Apply filters. v0.19.0 schema: status (agent-owned) replaces
+            // docRole / domain / concepts. Legacy fields still on disk are
+            // ignored by both filtering and output — they retire as docs get
+            // re-enriched. See brief 2026-05-21-simplify-enrichment-schema-three-fields.
+            if (filter.status && data.status !== filter.status)
                 continue;
             if (filter.hasLogline === true && !data.logline)
                 continue;
@@ -432,11 +440,6 @@ export function crawlDocs(filter = {}) {
                 if (!filter.tags.every((t) => docTags.includes(t)))
                     continue;
             }
-            if (filter.concepts && filter.concepts.length > 0) {
-                const docConcepts = Array.isArray(data.concepts) ? data.concepts : [];
-                if (!filter.concepts.every((c) => docConcepts.includes(c)))
-                    continue;
-            }
             const trimmed = content.trim();
             out.push({
                 docId: data.docId || '',
@@ -444,10 +447,7 @@ export function crawlDocs(filter = {}) {
                 title: data.title || f.replace(/\.md$/, ''),
                 wordCount: trimmed ? trimmed.split(/\s+/).length : 0,
                 ...(typeof data.logline === 'string' && data.logline ? { logline: data.logline } : {}),
-                ...(typeof data.domain === 'string' && data.domain ? { domain: data.domain } : {}),
                 ...(Array.isArray(data.tags) && data.tags.length > 0 ? { tags: data.tags } : {}),
-                ...(Array.isArray(data.concepts) && data.concepts.length > 0 ? { concepts: data.concepts } : {}),
-                ...(typeof data.docRole === 'string' && data.docRole ? { docRole: data.docRole } : {}),
                 ...(typeof data.status === 'string' && data.status ? { status: data.status } : {}),
                 ...(data.enrichmentStale === true ? { enrichmentStale: true } : {}),
             });

package/dist/server/mcp.js

@@ -363,7 +363,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'list_documents',
-        description: 'List all documents. Shows title, docId, word count, last modified, active flag, and enrichment fields (logline, domain, docRole) when present. Use the docId to target documents in other tools.',
+        description: 'List all documents. Shows title, docId, word count, last modified, active flag, and enrichment fields (logline, status, STALE marker) when present. Use the docId to target documents in other tools. v0.19.0: three-field enrichment schema — logline (LLM), status (agent: canonical / draft), STALE (system).',
         schema: {},
         handler: async () => {
             const docs = listDocuments();
@@ -372,10 +372,10 @@ export const TOOL_REGISTRY = [
                 const id = d.docId ? ` [${d.docId}]` : '';
                 const date = d.lastModified.split('T')[0];
                 const enrichBits = [];
-                if (d.domain)
-                    enrichBits.push(d.domain);
-                if (d.docRole)
-                    enrichBits.push(d.docRole);
+                // v0.19.0: only canonical surfaces — draft is the default and would
+                // clutter the listing on every doc.
+                if (d.status === 'canonical')
+                    enrichBits.push('canonical');
                 if (d.enrichmentStale === true)
                     enrichBits.push('STALE');
                 const enrichTag = enrichBits.length > 0 ? ` (${enrichBits.join(', ')})` : '';
@@ -415,8 +415,9 @@ export const TOOL_REGISTRY = [
             content_type: z.enum(['document', 'tweet', 'reply', 'quote', 'article', 'linkedin', 'newsletter', 'blog']).describe('Required. Use "document" for plain documents. Tweet/reply/quote/article/linkedin/newsletter/blog set type-specific metadata automatically.'),
             url: z.string().optional().describe('Tweet URL — REQUIRED for content_type "reply" or "quote" (e.g. "https://x.com/user/status/123"). Sets tweetContext.url automatically. Ignored for other content types.'),
             afterId: z.string().optional().describe('Place the new doc immediately after this docId (8-char hex) or containerId inside its parent. Omit to append to the bottom of the parent (the default — matches ascending-order convention: newest at bottom). Requires workspace.'),
+            status: z.enum(['canonical', 'draft']).optional().describe('Agent-owned lifecycle. "canonical" = committed to spine / load-bearing for the workspace (use for Beats docs that have locked, Research Notes, Master References). "draft" = working / not load-bearing yet / scratch (DUMP docs, first-pass beats). Defaults to "draft" when omitted. Change later via set_metadata({ status: ... }) on lifecycle transitions. v0.19.0.'),
         },
-        handler: async ({ title, path, workspace, container, empty, content_type, url, afterId }) => {
+        handler: async ({ title, path, workspace, container, empty, content_type, url, afterId, status }) => {
             // Require url for reply/quote
             if ((content_type === 'reply' || content_type === 'quote') && !url) {
                 return { content: [{ type: 'text', text: `Error: content_type "${content_type}" requires a url parameter (e.g. "https://x.com/user/status/123").` }] };
@@ -444,18 +445,25 @@ export const TOOL_REGISTRY = [
             // Track the spinner key so catch can clear exactly this entry
             // (not siblings from a concurrent declare_writes).
             let spinnerKey = null;
+            // v0.19.0: agent-owned status. Defaults to "draft" when not supplied —
+            // canonical is reserved for docs that have committed to the workspace
+            // spine (Beats, Research Notes, Master References). Agent flips to
+            // canonical via set_metadata({ status: "canonical" }) on lifecycle
+            // transitions. See brief 2026-05-21-simplify-enrichment-schema-three-fields.
+            const statusMeta = { status: status ?? 'draft' };
             try {
                 if (empty) {
                     // Immediate switch — no spinner, no populate_document needed
                     const result = createDocument(title, undefined, path);
                     setAgentLock(result.filename);
-                    // Apply type-specific metadata
+                    // Apply status + type-specific metadata in one merge
+                    const initMeta = { ...statusMeta };
                     if (content_type) {
                         const typeMeta = resolveTypeMeta(content_type, url);
-                        if (typeMeta) {
-                            setMetadata(typeMeta);
-                        }
+                        if (typeMeta)
+                            Object.assign(initMeta, typeMeta);
                     }
+                    setMetadata(initMeta);
                     let wsInfo = '';
                     if (wsTarget) {
                         // Resolve afterId: it may be a docId (8-char hex) or containerId.
@@ -478,8 +486,11 @@ export const TOOL_REGISTRY = [
                 }
                 // Two-step flow: create file on disk WITHOUT switching the user's view.
                 // The spinner persists in the sidebar until populate_document is called.
+                // Merge status with any content-type metadata so it lands on the first
+                // disk write.
                 const typeMeta = content_type ? resolveTypeMeta(content_type, url) : undefined;
-                const result = createDocumentFile(title, path, typeMeta);
+                const initialMeta = { ...statusMeta, ...(typeMeta || {}) };
+                const result = createDocumentFile(title, path, initialMeta);
                 let wsInfo = '';
                 if (wsTarget) {
                     const afterRef = afterId ? (filenameByDocId(afterId) ?? afterId) : null;
@@ -733,7 +744,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'set_metadata',
-        description: 'Update frontmatter metadata on a document. Merges with existing metadata — only provided keys are changed. Use for summaries, character lists, tags, arc notes, or any organizational data. Saves to disk immediately.',
+        description: 'Update frontmatter metadata on a document. Merges with existing metadata — only provided keys are changed. Use for summaries, character lists, tags, arc notes, or any organizational data. Saves to disk immediately. Lifecycle convention (v0.19.0): use `set_metadata({ status: "canonical" })` when a doc commits to the workspace spine (Beats locks, Research Note becomes load-bearing); use `set_metadata({ status: "draft" })` when a doc is superseded or demoted. Status is the agent\'s field — the enrichment minion never writes it.',
         schema: {
             docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
             metadata: z.record(z.any()).describe('Key-value pairs to merge into frontmatter. Set a key to null to remove it.'),
@@ -801,16 +812,12 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'mark_enriched',
-        description: 'Mark one or more documents as freshly enriched. Stamps openwriter-maintained baselines (lastEnrichedAt, lastEnrichedCharCount, lastEnrichedSentences) atomically with the supplied enrichment fields, and clears enrichmentStale. The agent never touches the sentence-hash layer — openwriter computes the baseline from current canonical content. Accepts an array so a workspace-wide sweep is one call. See brief 2026-05-18-frontmatter-enrichment-system.',
+        description: 'Mark one or more documents as freshly enriched. Stamps openwriter-maintained baselines (lastEnrichedAt, lastEnrichedCharCount, lastEnrichedSentences) atomically with the supplied logline, clears enrichmentStale, and retires legacy enrichment fields (domain, concepts, docRole, and any LLM-written status). The agent never touches the sentence-hash layer — openwriter computes the baseline from current canonical content. Accepts an array so a workspace-wide sweep is one call. Schema simplified in v0.19.0: only logline is LLM-written; status is now agent-owned via create_document / set_metadata; domain / concepts / docRole are gone. See brief 2026-05-21-simplify-enrichment-schema-three-fields.',
         schema: {
             docs: z.array(z.object({
                 docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
-                logline: z.string().optional().describe('Précis (non-fiction) or logline (fiction). Under 250 chars. Describe the content, not the kind of doc.'),
-                domain: z.string().optional().describe('Single domain classification from the workspace vocab.'),
-                concepts: z.array(z.string()).optional().describe('Named concepts the doc references.'),
-                docRole: z.string().optional().describe('Doc role: canonical / vignette / reference / draft / chapter / beat.'),
-                status: z.string().optional().describe('Doc status: draft / canonical / stale. Archive state is implied by archivedAt.'),
-            })).describe('One or more docs to mark enriched. Single-doc calls are a length-1 array.'),
+                logline: z.string().max(150).describe('Précis (non-fiction) or logline (fiction). Under 150 chars. Describe the content, not the kind of doc.'),
+            }).strict()).describe('One or more docs to mark enriched. Single-doc calls are a length-1 array. Strict schema — passing domain / concepts / docRole / status will fail validation (v0.19.0 schema simplification).'),
         },
         handler: async ({ docs }) => {
             const now = new Date().toISOString();
@@ -828,23 +835,19 @@ export const TOOL_REGISTRY = [
                     const blocks = tiptapToBlocks(canonical);
                     const lastEnrichedSentences = harvestSentenceHashes(blocks);
                     const lastEnrichedCharCount = harvestCharCount(blocks);
-                    // Build the atomic enrichment payload.
+                    // Build the atomic enrichment payload. v0.19.0: only logline is
+                    // LLM-written. The legacy fields (domain / concepts / docRole) get
+                    // retired on this write — `LEGACY_FIELDS_TO_RETIRE` is deleted from
+                    // the merged metadata so disk slowly converges to the new schema
+                    // as each doc gets re-enriched (lazy migration path from the brief).
                     const update = {
                         lastEnrichedAt: now,
                         lastEnrichedCharCount,
                         lastEnrichedSentences,
                         enrichmentStale: false,
+                        logline: item.logline,
                     };
-                    if (item.logline !== undefined)
-                        update.logline = item.logline;
-                    if (item.domain !== undefined)
-                        update.domain = item.domain;
-                    if (item.concepts !== undefined)
-                        update.concepts = item.concepts;
-                    if (item.docRole !== undefined)
-                        update.docRole = item.docRole;
-                    if (item.status !== undefined)
-                        update.status = item.status;
+                    const LEGACY_FIELDS_TO_RETIRE = ['domain', 'concepts', 'docRole'];
                     if (target.isActive) {
                         // Active doc: setMetadata mutates state.metadata but doesn't bump
                         // docVersion on its own — without an explicit bump, save() would
@@ -853,6 +856,9 @@ export const TOOL_REGISTRY = [
                         // writeToDisk's staleness check will see the just-stamped baseline
                         // (volumeRatio=1, drift=0) and NOT flip the flag back to true.
                         setMetadata(update);
+                        const liveMeta = getMetadata();
+                        for (const k of LEGACY_FIELDS_TO_RETIRE)
+                            delete liveMeta[k];
                         bumpDocVersion();
                         save();
                         broadcastMetadataChanged(getMetadata());
@@ -863,6 +869,8 @@ export const TOOL_REGISTRY = [
                         // serialize cycle before the new baseline lands). Disk write +
                         // cache invalidation mirrors set_metadata's non-active path.
                         const newMeta = { ...target.metadata, ...update };
+                        for (const k of LEGACY_FIELDS_TO_RETIRE)
+                            delete newMeta[k];
                         const markdown = tiptapToMarkdown(target.document, target.title, newMeta);
                         atomicWriteFileSync(target.filePath, markdown);
                         invalidateDocCache(target.filePath);
@@ -896,13 +904,11 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'crawl',
-        description: 'Bulk-read enriched fields per doc, filtered by criteria. The crawl primitive — agents use this to scan the workspace shelf at concept level (~150 tokens/doc) and decide which bodies to actually read. Filters compose with AND semantics. Empty filter returns every non-archived doc. No bodies, no nodes, no pending overlay.',
+        description: 'Bulk-read enriched fields per doc, filtered by criteria. The crawl primitive — agents use this to scan the workspace shelf at concept level (~60 tokens/doc) and decide which bodies to actually read. Filters compose with AND semantics. Empty filter returns every non-archived doc. No bodies, no nodes, no pending overlay. v0.19.0 schema: status (canonical / draft) replaces docRole / domain / concepts filters — those legacy filters were dropped because the fields they queried had no authority discipline. See brief 2026-05-21-simplify-enrichment-schema-three-fields.',
         schema: {
             workspaceFile: z.string().optional().describe('Scope to one workspace.'),
-            domain: z.string().optional().describe('Exact domain match.'),
             tags: z.array(z.string()).optional().describe('Docs must have ALL listed tags.'),
-            concepts: z.array(z.string()).optional().describe('Docs must reference ALL listed concepts.'),
-            docRole: z.string().optional().describe('Exact docRole match (canonical / vignette / reference / draft / chapter / beat).'),
+            status: z.enum(['canonical', 'draft']).optional().describe('Agent-owned lifecycle filter. "canonical" returns the trusted-shelf docs (load-bearing for the workspace); "draft" returns working / superseded / scratch docs. The common crawl is `status: canonical`.'),
             hasLogline: z.boolean().optional().describe('True = only docs with a logline; false = only docs without one.'),
         },
         handler: async (filter) => {
@@ -953,7 +959,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'get_workspace_structure',
-        description: 'Get the full structure of a workspace: tree of containers and docs, per-doc enrichment (logline, domain, tags, docRole, stale flag), plus workspace-level context (characters, settings, rules) and enrichment metadata (schema, vocab, logline). Use to understand a workspace at concept level before reading bodies.',
+        description: 'Get the full structure of a workspace: tree of containers and docs, per-doc enrichment (logline, status, tags, stale flag), plus workspace-level context (characters, settings, rules) and enrichment metadata (schema, vocab, logline). Use to understand a workspace at concept level before reading bodies. v0.19.0: enrichment fields shown per-doc are logline (LLM-owned), status (agent-owned: canonical / draft), tags, and the STALE marker (system-owned).',
         schema: {
             filename: z.string().describe('Workspace manifest filename (e.g. "my-novel-a1b2c3d4.json")'),
         },
@@ -970,10 +976,11 @@ export const TOOL_REGISTRY = [
                         const e = enrichByFile.get(node.file);
                         const tags = e?.tags ?? [];
                         const enrichBits = [];
-                        if (e?.domain)
-                            enrichBits.push(e.domain);
-                        if (e?.docRole)
-                            enrichBits.push(e.docRole);
+                        // v0.19.0: status (agent-owned) replaces domain + docRole.
+                        // Only "canonical" is worth surfacing — draft is the default
+                        // and would add noise on every line.
+                        if (e?.status === 'canonical')
+                            enrichBits.push('canonical');
                         if (tags.length > 0)
                             enrichBits.push(`tags: ${tags.join(', ')}`);
                         if (e?.enrichmentStale === true)
@@ -1023,7 +1030,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'get_item_context',
-        description: 'Get progressive-disclosure context for a document: workspace-level context (characters, settings, rules, vocab), the doc\'s own enrichment (logline, domain, concepts, docRole, status), tags, and the enrichmentStale flag. Use before writing to understand context, or before reading to decide whether a body read is necessary.',
+        description: 'Get progressive-disclosure context for a document: workspace-level context (characters, settings, rules, vocab), the doc\'s own enrichment (logline, status), tags, and the enrichmentStale flag. Use before writing to understand context, or before reading to decide whether a body read is necessary. v0.19.0: returns the three-field enrichment schema — logline (LLM), status (agent), enrichmentStale (system).',
         schema: {
             workspaceFile: z.string().describe('Workspace manifest filename'),
             docId: z.string().describe('Document docId (8-char hex from list_documents)'),
@@ -1039,14 +1046,10 @@ export const TOOL_REGISTRY = [
                 const enriched = crawlDocs({ workspaceFile });
                 const docEnrich = enriched.find((e) => e.filename === filename);
                 if (docEnrich) {
+                    // v0.19.0 three-field schema: logline (LLM), status (agent),
+                    // enrichmentStale (system). domain / concepts / docRole dropped.
                     if (docEnrich.logline)
                         base.logline = docEnrich.logline;
-                    if (docEnrich.domain)
-                        base.domain = docEnrich.domain;
-                    if (docEnrich.concepts)
-                        base.concepts = docEnrich.concepts;
-                    if (docEnrich.docRole)
-                        base.docRole = docEnrich.docRole;
                     if (docEnrich.status)
                         base.status = docEnrich.status;
                     if (docEnrich.enrichmentStale === true)
@@ -1811,20 +1814,18 @@ export const TOOL_REGISTRY = [
             const enriched = raw.slice(0, cap).map((r) => {
                 let docId = null;
                 let logline;
-                let domain;
-                let docRole;
+                let status;
                 let tags;
                 try {
                     const filePath = resolveDocPath(r.filename);
                     const fileRaw = readFileSync(filePath, 'utf-8');
                     const fm = matter(fileRaw);
                     docId = fm.data?.docId || null;
+                    // v0.19.0 three-field schema: logline (LLM), status (agent), tags.
                     if (typeof fm.data?.logline === 'string')
                         logline = fm.data.logline;
-                    if (typeof fm.data?.domain === 'string')
-                        domain = fm.data.domain;
-                    if (typeof fm.data?.docRole === 'string')
-                        docRole = fm.data.docRole;
+                    if (typeof fm.data?.status === 'string')
+                        status = fm.data.status;
                     if (Array.isArray(fm.data?.tags) && fm.data.tags.length > 0)
                         tags = fm.data.tags;
                 }
@@ -1837,8 +1838,7 @@ export const TOOL_REGISTRY = [
                     snippet: r.snippet,
                     matchedTag: r.matchedTag,
                     ...(logline ? { logline } : {}),
-                    ...(domain ? { domain } : {}),
-                    ...(docRole ? { docRole } : {}),
+                    ...(status ? { status } : {}),
                     ...(tags ? { tags } : {}),
                 };
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "The open-source writing surface for AI agents. Markdown-native editor with pending change review — your agent writes, you accept or reject.",
   "type": "module",
   "license": "MIT",