@north-light/crouter 0.3.353 → 0.3.354

package/dist/commands/api-client.d.ts

@@ -4,6 +4,7 @@ import type { NodeStatus, SubscriptionRef } from '../core/canvas/types.js';
 import type { Scope } from '../types.js';
 import type { NodeDetailDTO } from '../api/dto/nodes.js';
 import type { NodeMeta, NodeRow } from '../core/canvas/types.js';
+import type { ReportDTO } from '../api/index.js';
 /** Rethrow an `ApiError` as the clean structured CLI error agents parse
  *  (`core/io` `handle`) — instead of the generic "internal bug" stderr path a
  *  raw non-`CrtrError` throw would take. The mapping itself lives in ONE place
@@ -83,6 +84,7 @@ export declare class ApiCanvasSource implements CanvasSource {
      *  live subscriber) subscription to a node that is currently live
      *  (`active`/`idle` status). `subscriptionsOf`'s roster-backed edges carry the
      *  real per-edge `active` flag, so this filter is exact, not an over-report. */
+    newestReport(nodeId: string): Promise<ReportDTO | null>;
     hasActiveLiveSubscription(nodeId: string): Promise<boolean>;
 }
 /** The active read source for a CLI command. Mirrors `resolveCanvasSource`'s

package/dist/commands/api-client.js

@@ -1,4 +1,4 @@
-var m=Object.defineProperty;var a=(s,t)=>m(s,"name",{value:t,configurable:!0});import{closeSync as p,fstatSync as w,openSync as _,readSync as b}from"node:fs";import{join as C}from"node:path";import{ApiError as u}from"../api/index.js";import{localClient as l}from"../api/node-transport.js";import{apiErrorToCliError as g}from"../core/io.js";import{autostartDisabled as S,ensureDaemon as y}from"../daemon/manage.js";import{DAEMON_STARTUP_WINDOW_MS as v}from"../daemon/startup-policy.js";import{readState as N}from"../core/config.js";import{resolveRemoteCanvasTarget as T}from"../core/remote-canvas-target.js";import{RemoteCanvasSource as A}from"../core/canvas/remote-canvas-source.js";import{crtrHome as M}from"../core/canvas/paths.js";function f(s){return{...s,fault:s.fault??null}}a(f,"withRowFault");function I(s,t){throw s instanceof u?g(s,t):s}a(I,"rethrowAsCliError");async function U(s){try{return await h().getNode(s)}catch(t){if(t instanceof u&&t.status===404)return null;I(t)}}a(U,"getNodeOrNull");const O=4096,R=20;function D(){let s;try{s=_(C(M(),"crtrd.log"),"r");const{size:t}=w(s),e=Math.max(0,t-O),i=t-e;if(i<=0)return;const n=Buffer.alloc(i);b(s,n,0,i,e);const o=n.toString("utf8").split(`
-`).filter(c=>c.trim()!=="").slice(-R).join(`
+var m=Object.defineProperty;var a=(s,t)=>m(s,"name",{value:t,configurable:!0});import{closeSync as p,fstatSync as w,openSync as _,readSync as b}from"node:fs";import{join as g}from"node:path";import{ApiError as u}from"../api/index.js";import{localClient as l}from"../api/node-transport.js";import{apiErrorToCliError as C}from"../core/io.js";import{autostartDisabled as y,ensureDaemon as S}from"../daemon/manage.js";import{DAEMON_STARTUP_WINDOW_MS as v}from"../daemon/startup-policy.js";import{readState as N}from"../core/config.js";import{resolveRemoteCanvasTarget as T}from"../core/remote-canvas-target.js";import{RemoteCanvasSource as A}from"../core/canvas/remote-canvas-source.js";import{crtrHome as M}from"../core/canvas/paths.js";function f(s){return{...s,fault:s.fault??null}}a(f,"withRowFault");function I(s,t){throw s instanceof u?C(s,t):s}a(I,"rethrowAsCliError");async function U(s){try{return await h().getNode(s)}catch(t){if(t instanceof u&&t.status===404)return null;I(t)}}a(U,"getNodeOrNull");const R=4096,O=20;function D(){let s;try{s=_(g(M(),"crtrd.log"),"r");const{size:t}=w(s),e=Math.max(0,t-R),i=t-e;if(i<=0)return;const n=Buffer.alloc(i);b(s,n,0,i,e);const o=n.toString("utf8").split(`
+`).filter(c=>c.trim()!=="").slice(-O).join(`
 `).trim();return o===""?void 0:`crtrd.log (tail):
-${o}`}catch{return}finally{if(s!==void 0)try{p(s)}catch{}}}a(D,"readColdStartDiagnostic");function h(s){return process.env.CRTR_API_SOCKET?l({autostart:!1,...s?.timeoutMs!==void 0?{timeoutMs:s.timeoutMs}:{}}):S()?l({autostart:!1,...s?.timeoutMs!==void 0?{timeoutMs:s.timeoutMs}:{}}):l({...s?.timeoutMs!==void 0?{timeoutMs:s.timeoutMs}:{},onColdSocket:a(async()=>{y()},"onColdSocket"),coldStartDiagnostic:D,coldStartPollWindowMs:v})}a(h,"cliClient");const E=2e3;class x{static{a(this,"ApiCanvasSource")}client;rosterCache=null;rosterInFlight=null;constructor(t=h()){this.client=t}async roster(){const t=Date.now();return this.rosterCache!==null&&t-this.rosterCache.at<E?this.rosterCache.index:this.rosterInFlight!==null?this.rosterInFlight:(this.rosterInFlight=this.client.canvasRoster().then(e=>{const i={subscriptions:new Map,subscribers:new Map};for(const n of e.edges){const r={node_id:n.to_id,active:n.active,created:n.created},o={node_id:n.from_id,active:n.active,created:n.created},c=i.subscriptions.get(n.from_id);c===void 0?i.subscriptions.set(n.from_id,[r]):c.push(r);const d=i.subscribers.get(n.to_id);d===void 0?i.subscribers.set(n.to_id,[o]):d.push(o)}return this.rosterCache={at:Date.now(),index:i},i}).finally(()=>{this.rosterInFlight=null}),this.rosterInFlight)}async orNull(t){try{return await t()}catch(e){if(e instanceof u&&e.status===404)return null;throw e}}async getNode(t){const e=await this.orNull(()=>this.client.getNode(t));return e===null?null:f(e)}async getRow(t){const e=await this.orNull(()=>this.client.getNode(t));return e===null?null:f(e)}async listNodes(t){const e=t?.status;let i;if(Array.isArray(e)){const n=new Set(e);i=(await this.client.listNodes()).filter(o=>n.has(o.status))}else e!==void 0?i=await this.client.listNodes({status:e}):i=await this.client.listNodes();return i.map(n=>f(n))}async subscriptionsOf(t){return this.roster().then(e=>e.subscriptions.get(t)??[])}async subscribersOf(t){return this.roster().then(e=>e.subscribers.get(t)??[])}async view(t){const e=new Set([t]),i=[],n=(await this.subscriptionsOf(t)).map(r=>r.node_id);for(;n.length>0;){const r=n.shift();if(!e.has(r)){e.add(r),i.push(r);for(const o of await this.subscriptionsOf(r))e.has(o.node_id)||n.push(o.node_id)}}return i}async ticketCountsForNodes(t){return(await this.client.attentionCounts([...t])).counts}async ticketCountsForView(t){return this.ticketCountsForNodes([t,...await this.view(t)])}async hasActiveLiveSubscription(t){const e=(await this.subscriptionsOf(t)).filter(i=>i.active);for(const i of e){const n=await this.getRow(i.node_id);if(n&&(n.status==="active"||n.status==="idle"))return!0}return!1}}function V(s){const t=s?.scope??"user",e=s?.canvasName??N(t).activeCanvas??null;if(!e)return new x;const{previewEndpoint:i,relayToken:n}=T(e,t);return new A(i,n)}a(V,"cliCanvasSource");export{x as ApiCanvasSource,O as COLD_START_DIAGNOSTIC_TAIL_BYTES,V as cliCanvasSource,h as cliClient,U as getNodeOrNull,D as readColdStartDiagnostic,I as rethrowAsCliError};
+${o}`}catch{return}finally{if(s!==void 0)try{p(s)}catch{}}}a(D,"readColdStartDiagnostic");function h(s){return process.env.CRTR_API_SOCKET?l({autostart:!1,...s?.timeoutMs!==void 0?{timeoutMs:s.timeoutMs}:{}}):y()?l({autostart:!1,...s?.timeoutMs!==void 0?{timeoutMs:s.timeoutMs}:{}}):l({...s?.timeoutMs!==void 0?{timeoutMs:s.timeoutMs}:{},onColdSocket:a(async()=>{S()},"onColdSocket"),coldStartDiagnostic:D,coldStartPollWindowMs:v})}a(h,"cliClient");const E=2e3;class x{static{a(this,"ApiCanvasSource")}client;rosterCache=null;rosterInFlight=null;constructor(t=h()){this.client=t}async roster(){const t=Date.now();return this.rosterCache!==null&&t-this.rosterCache.at<E?this.rosterCache.index:this.rosterInFlight!==null?this.rosterInFlight:(this.rosterInFlight=this.client.canvasRoster().then(e=>{const i={subscriptions:new Map,subscribers:new Map};for(const n of e.edges){const r={node_id:n.to_id,active:n.active,created:n.created},o={node_id:n.from_id,active:n.active,created:n.created},c=i.subscriptions.get(n.from_id);c===void 0?i.subscriptions.set(n.from_id,[r]):c.push(r);const d=i.subscribers.get(n.to_id);d===void 0?i.subscribers.set(n.to_id,[o]):d.push(o)}return this.rosterCache={at:Date.now(),index:i},i}).finally(()=>{this.rosterInFlight=null}),this.rosterInFlight)}async orNull(t){try{return await t()}catch(e){if(e instanceof u&&e.status===404)return null;throw e}}async getNode(t){const e=await this.orNull(()=>this.client.getNode(t));return e===null?null:f(e)}async getRow(t){const e=await this.orNull(()=>this.client.getNode(t));return e===null?null:f(e)}async listNodes(t){const e=t?.status;let i;if(Array.isArray(e)){const n=new Set(e);i=(await this.client.listNodes()).filter(o=>n.has(o.status))}else e!==void 0?i=await this.client.listNodes({status:e}):i=await this.client.listNodes();return i.map(n=>f(n))}async subscriptionsOf(t){return this.roster().then(e=>e.subscriptions.get(t)??[])}async subscribersOf(t){return this.roster().then(e=>e.subscribers.get(t)??[])}async view(t){const e=new Set([t]),i=[],n=(await this.subscriptionsOf(t)).map(r=>r.node_id);for(;n.length>0;){const r=n.shift();if(!e.has(r)){e.add(r),i.push(r);for(const o of await this.subscriptionsOf(r))e.has(o.node_id)||n.push(o.node_id)}}return i}async ticketCountsForNodes(t){return(await this.client.attentionCounts([...t])).counts}async ticketCountsForView(t){return this.ticketCountsForNodes([t,...await this.view(t)])}async newestReport(t){return(await this.client.getReports(t,{limit:1}))[0]??null}async hasActiveLiveSubscription(t){const e=(await this.subscriptionsOf(t)).filter(i=>i.active);for(const i of e){const n=await this.getRow(i.node_id);if(n&&(n.status==="active"||n.status==="idle"))return!0}return!1}}function V(s){const t=s?.scope??"user",e=s?.canvasName??N(t).activeCanvas??null;if(!e)return new x;const{previewEndpoint:i,relayToken:n}=T(e,t);return new A(i,n)}a(V,"cliCanvasSource");export{x as ApiCanvasSource,R as COLD_START_DIAGNOSTIC_TAIL_BYTES,V as cliCanvasSource,h as cliClient,U as getNodeOrNull,D as readColdStartDiagnostic,I as rethrowAsCliError};

package/dist/commands/canvas/edges.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const edgesLeaf: LeafDef;

package/dist/commands/canvas/edges.js

@@ -0,0 +1,2 @@
+var r=Object.defineProperty;var o=(e,n)=>r(e,"name",{value:n,configurable:!0});import{defineLeaf as s}from"../../core/command.js";import{cliClient as a,rethrowAsCliError as i}from"../api-client.js";import{REF_CONSTRAINT as c}from"./read.js";const d=["acted-on","links-to","watches"],g=s({name:"edges",description:"list the edges of an object: acted-on, links-to, watches",whenToUse:"you need what a document links to or what links to it, who acted on an object, or who watches it. Records nothing.",help:{name:"canvas edges",summary:"list an object\u2019s acted-on, links-to and watches edges; records nothing",params:[{kind:"positional",name:"ref",required:!0,constraint:c},{kind:"flag",name:"type",type:"enum",choices:d,required:!1,constraint:"Only edges of this type. acted-on: an actor changed or wrote the object. links-to: a body names the object as `[[name]]`. watches: a watcher of the object."},{kind:"flag",name:"direction",type:"enum",choices:["out","in"],required:!1,constraint:"out: edges from this object; in: edges to it. Omit for both."}],output:[{name:"items",type:"string[]",required:!0,constraint:"One row per edge you can read both ends of: type, source and destination as id and `[[name]]`, and for links-to the name as the body wrote it."}],outputKind:"object",effects:["None. Listing edges records no watch."]},run:o(async e=>{const n={...e.type?{type:e.type}:{},...e.direction?{direction:e.direction}:{}};try{return{...await a().objects.edges(e.ref,n)}}catch(t){i(t)}},"run"),render:o(e=>{const{items:n}=e;return n.length===0?"No edges.":n.map(t=>`- ${t.type}: ${t.src.id} [[${t.src.name}]] \u2192 ${t.dst.id} [[${t.dst.name}]]${t.written_as?` (written as [[${t.written_as}]])`:""}`).join(`
+`)},"render")});export{g as edgesLeaf};

package/dist/commands/canvas/list.d.ts

@@ -0,0 +1,4 @@
+import type { LeafDef } from '../../core/command.js';
+import type { ObjectListItemDTO } from '../../api/dto/objects.js';
+export declare function listItemRow(item: ObjectListItemDTO): string;
+export declare const listLeaf: LeafDef;

package/dist/commands/canvas/list.js

@@ -0,0 +1,3 @@
+var s=Object.defineProperty;var n=(e,r)=>s(e,"name",{value:r,configurable:!0});import{defineLeaf as a}from"../../core/command.js";import{OBJECT_TYPES as i,PRIVACY_LEVELS_DTO as c}from"../../api/dto/objects.js";import{cliClient as d,rethrowAsCliError as l}from"../api-client.js";import{objectRow as m}from"./read.js";function f(e){const r=m(e);if(e.type!=="document")return r;const t=[`privacy=${e.privacy}`,e.rules!==void 0?`rules=${e.rules}`:""].filter(Boolean).join(" ");return`${r}
+  ${t}${e.summary?` \u2014 ${e.summary}`:""}`}n(f,"listItemRow");const w=a({name:"list",description:"list objects by type, kind, owner, privacy or name prefix",whenToUse:"browsing what exists without reading it \u2014 the documents an owner holds, a node\u2019s reports, every job of a node. Records nothing, so listing does not make you a watcher.",help:{name:"canvas list",summary:"list the objects you can read, filtered; records nothing",params:[{kind:"flag",name:"type",type:"enum",choices:[...i],required:!1,constraint:"Only objects of this type."},{kind:"flag",name:"kind",type:"string",required:!1,constraint:"Only objects of this kind: for documents knowledge, preference or report; for nodes the node kind."},{kind:"flag",name:"owner",type:"string",required:!1,constraint:"Only objects this owner owns directly: a node id, a handle, or any name `crtr canvas read` accepts."},{kind:"flag",name:"privacy",type:"enum",choices:[...c],required:!1,constraint:"Only objects at this privacy level."},{kind:"flag",name:"name",type:"string",required:!1,constraint:"Only objects whose name starts with this prefix."},{kind:"flag",name:"deleted",type:"bool",required:!1,constraint:"When present, lists deleted objects instead of live ones."},{kind:"flag",name:"limit",type:"int",required:!1,default:50,constraint:"Page size, 1 to 100."},{kind:"flag",name:"cursor",type:"string",required:!1,constraint:"The `next_cursor` of the previous page."}],output:[{name:"items",type:"string[]",required:!0,constraint:"One row per object: id, `[[name]]`, type/kind, owner handle and preview. A document row adds its privacy, its rule count and its summary."},{name:"next_cursor",type:"string",required:!1,constraint:"Pass as `--cursor` for the next page; absent on the last page."}],outputKind:"object",effects:["None. Listing records no watch."]},run:n(async e=>{const r={...e.type?{type:e.type}:{},...e.kind?{kind:e.kind}:{},...e.owner?{owner:e.owner}:{},...e.privacy?{privacy:e.privacy}:{},...e.name?{name:e.name}:{},...e.deleted===!0?{deleted:!0}:{},limit:e.limit??50,...e.cursor?{cursor:e.cursor}:{}};try{return{...await d().objects.list(r)}}catch(t){l(t)}},"run"),render:n(e=>{const{items:r,next_cursor:t}=e;if(r.length===0)return"No objects match.";const o=r.map(f);return t&&o.push("",`More: \`crtr canvas list \u2026 --cursor ${t}\`.`),o.join(`
+`)},"render")});export{f as listItemRow,w as listLeaf};

package/dist/commands/canvas/read.d.ts

@@ -0,0 +1,8 @@
+import type { LeafDef } from '../../core/command.js';
+import type { ObjectDTO, ObjectReadDTO } from '../../api/dto/objects.js';
+export declare const REF_CONSTRAINT = "A name (the `[[ ]]` brackets are optional) or a raw object id. A name is `<owner-handle>/<path>`; a node or other owner is also named by its id or handle.";
+export declare function attr(name: string, value: string | number | null | undefined): string;
+/** One line per object: id, name, type/kind, owner handle and preview. */
+export declare function objectRow(o: ObjectDTO): string;
+export declare function renderRead(result: ObjectReadDTO): string;
+export declare const readLeaf: LeafDef;

package/dist/commands/canvas/read.js

@@ -0,0 +1,5 @@
+var c=Object.defineProperty;var o=(e,n)=>c(e,"name",{value:n,configurable:!0});import{defineLeaf as h}from"../../core/command.js";import{cliClient as m,rethrowAsCliError as u}from"../api-client.js";const p="A name (the `[[ ]]` brackets are optional) or a raw object id. A name is `<owner-handle>/<path>`; a node or other owner is also named by its id or handle.";function a(e,n){return n==null||n===""?"":` ${e}="${String(n).replace(/"/g,"&quot;")}"`}o(a,"attr");function b(e){const n=e.kind?`${e.type}/${e.kind}`:e.type,t=e.owner?` owner=${e.owner.handle}`:"",i=e.deleted_at?" (deleted)":"";return`- ${e.id} [[${e.name}]] ${n}${t}${i} \u2014 ${e.preview}`}o(b,"objectRow");function d(e,n,t=""){return`<${e}${a("type",n.type)}${a("kind",n.kind)}${a("id",n.id)}${a("name",n.name)}${a("owner",n.owner?.handle)}${t}>`}o(d,"header");function r(e,n){return n.length===0?[]:[`${e}:`,...n.map(b)]}o(r,"section");function l(e){if(e.state==="remote")return`No object named ${e.remote} on this runtime. It may be on another runtime, or the name may be misspelled.`;if(e.state==="deleted"){const i=e.deleted;return[`${d("deleted",i,a("deleted_at",i.deleted_at))}`,`Last preview: ${i.preview}`,"</deleted>"].join(`
+`)}const n=e.object,t=[];switch(e.type){case"document":{e.attachments&&t.push(e.attachments,""),t.push(d("object",n,a("privacy",n.privacy)+a("revision",e.revision))),t.push(`Preview: ${n.preview}`),e.summary&&t.push(`Summary: ${e.summary}`),e.fields!==void 0&&t.push(`<fields>
+${JSON.stringify(e.fields,null,2)}
+</fields>`),e.needs_merge?(e.heads.forEach((i,s)=>{t.push(`<head${a("rev",i.rev_id)}${a("number",i.number)}${a("author",i.author_id)}>`,e.bodies[s]??"","</head>")}),t.push(`This document has ${e.heads.length} heads. Your next \`crtr doc edit\` writes the merged body and joins them into one revision.`)):t.push("",e.bodies[0]??""),e.listing&&e.listing.length>0&&t.push("",...r(`Names under ${n.name}/`,e.listing));break}case"node":t.push(d("object",n,a("status",e.status))),t.push(`Mandate: ${e.mandate_first_line}`),t.push(...r("Children",e.children),...r("Owns",e.owned),...r("Jobs",e.jobs));break;case"job":t.push(d("object",n,a("status",e.status)+a("exit_code",e.exit_code))),t.push(`Command: ${e.command}`,`Log: ${e.log_path}`);break;default:t.push(d("object",n)),t.push(`Handle: ${e.handle}`,`Display name: ${e.display_name}`,`Identity: ${e.identity.scheme}:${e.identity.external_id}`)}return t.push("</object>"),t.join(`
+`)}o(l,"renderRead");const $=h({name:"read",description:"read one object \u2014 a document, node, job or owner \u2014 by name or id",whenToUse:"you need the content or state of an object you can name: a document\u2019s body, a node\u2019s status and what it owns, a job\u2019s result. Reading makes you a watcher of the object. Find the name first with `crtr canvas search` or `crtr canvas list` when you do not know it.",help:{name:"canvas read",summary:"read one object by name or id and become a watcher of it",params:[{kind:"positional",name:"ref",required:!0,constraint:p},{kind:"flag",name:"fields",type:"bool",required:!1,constraint:"When present, a document read also returns its delivery rules, why-it-exists, unlisted, lint-ignore and plugin extension fields."}],output:[{name:"object",type:"string",required:!0,constraint:"`<object type kind id name owner \u2026>` header. A document adds privacy and revision, then its preview, summary and body; several heads show one `<head rev number author>` block each, and your next `crtr doc edit` merges them. A document with names under it lists them. It may be preceded by one `<auto-loaded-context>` block carrying the document\u2019s enclosing listings and the documents its `document-read` rules deliver; in a node, each is delivered once per context. A node shows its status, the first line of its mandate, its children, what it owns and its jobs; a job its command, status, exit code and log path; an owner its handle and identity."},{name:"deleted",type:"string",required:!1,constraint:"`<deleted \u2026>` with the last preview when the object was deleted."},{name:"remote",type:"string",required:!1,constraint:"A line saying no object has that name on this runtime: it may be on another runtime, or the name may be misspelled."}],outputKind:"object",effects:["A live read records a watch on the object for you (every event subject) and publishes a read event to its other watchers. A deleted or remote answer records nothing."]},run:o(async e=>{try{return{...await m().objects.read(e.ref,e.fields===!0?{fields:!0}:void 0)}}catch(n){u(n)}},"run"),render:o(e=>l(e),"render")});export{p as REF_CONSTRAINT,a as attr,b as objectRow,$ as readLeaf,l as renderRead};

package/dist/commands/canvas/search.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const searchLeaf: LeafDef;

package/dist/commands/canvas/search.js

@@ -0,0 +1,3 @@
+var o=Object.defineProperty;var r=(e,t)=>o(e,"name",{value:t,configurable:!0});import{defineLeaf as i}from"../../core/command.js";import{OBJECT_TYPES as s}from"../../api/dto/objects.js";import{cliClient as c,rethrowAsCliError as d}from"../api-client.js";import{listItemRow as m}from"./list.js";const p=i({name:"search",description:"search objects by name, preview or body text",whenToUse:"finding an object when you do not know its name \u2014 a document on a topic, a report that mentions something, the exact line a regex matches. Records nothing; read a hit with `crtr canvas read`.",help:{name:"canvas search",summary:"find the objects you can read by text; records nothing",params:[{kind:"positional",name:"text",required:!0,constraint:"Words matched against names, previews and summaries (and document bodies with --body)."},{kind:"flag",name:"body",type:"bool",required:!1,constraint:"When present, also matches document bodies."},{kind:"flag",name:"grep",type:"string",required:!1,constraint:"An ECMAScript regex matched against document body lines; each hit lists its matching lines with line numbers."},{kind:"flag",name:"type",type:"enum",choices:[...s],required:!1,constraint:"Only objects of this type."},{kind:"flag",name:"kind",type:"string",required:!1,constraint:"Only objects of this kind."},{kind:"flag",name:"owner",type:"string",required:!1,constraint:"Only objects this owner owns directly: a node id, a handle, or any name `crtr canvas read` accepts."},{kind:"flag",name:"limit",type:"int",required:!1,constraint:"Most hits returned, 1 to 100."}],output:[{name:"items",type:"string[]",required:!0,constraint:"One row per hit, as `crtr canvas list` shows it, followed by the matching body lines when --grep is set."}],outputKind:"object",effects:["None. Searching records no watch."]},run:r(async e=>{const t={text:e.text,...e.body===!0?{body:!0}:{},...e.grep?{grep:e.grep}:{},...e.type?{type:e.type}:{},...e.kind?{kind:e.kind}:{},...e.owner?{owner:e.owner}:{},...e.limit?{limit:e.limit}:{}};try{return{...await c().objects.search(t)}}catch(n){d(n)}},"run"),render:r(e=>{const{items:t}=e;return t.length===0?"No objects match.":t.map(n=>[m(n.object),...(n.matches??[]).map(a=>`    ${a.line}: ${a.text}`)].join(`
+`)).join(`
+`)},"render")});export{p as searchLeaf};

package/dist/commands/canvas/unwatch.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const unwatchLeaf: LeafDef;

package/dist/commands/canvas/unwatch.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var n=(e,t)=>o(e,"name",{value:t,configurable:!0});import{defineLeaf as a}from"../../core/command.js";import{cliClient as c,rethrowAsCliError as s}from"../api-client.js";import{REF_CONSTRAINT as i}from"./read.js";import{PATTERN_CONSTRAINT as m}from"./watch.js";const y=a({name:"unwatch",description:"stop watching an object",whenToUse:"you no longer want an object\u2019s events \u2014 a document you read once, a node whose work no longer concerns you.",help:{name:"canvas unwatch",summary:"remove your watch on an object, or one pattern of it",params:[{kind:"positional",name:"ref",required:!0,constraint:i},{kind:"flag",name:"pattern",type:"string",required:!1,constraint:`Remove only this pattern. ${m} Omit to remove every pattern.`}],output:[{name:"unwatched",type:"string",required:!0,constraint:"The object and how many watch patterns were removed."}],outputKind:"object",effects:["Removes your watch patterns on the object; its events stop reaching you. Watches that keep a spawned node in your tree are removed the same way."]},run:n(async e=>{try{return{...await c().objects.unwatch(e.ref,e.pattern?{pattern:e.pattern}:void 0)}}catch(t){s(t)}},"run"),render:n(e=>{const{object:t,removed:r}=e;return`<unwatched id="${t.id}" name="${t.name}" removed="${r}">`},"render")});export{y as unwatchLeaf};

package/dist/commands/canvas/watch.d.ts

@@ -0,0 +1,3 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const PATTERN_CONSTRAINT = "An event subject pattern: dot-separated segments, where `*` matches exactly one segment and `>` matches one or more trailing segments. `>` alone matches every event.";
+export declare const watchLeaf: LeafDef;

package/dist/commands/canvas/watch.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var r=(e,t)=>s(e,"name",{value:t,configurable:!0});import{defineLeaf as c}from"../../core/command.js";import{usage as u}from"../../core/errors.js";import{cliClient as d,rethrowAsCliError as l}from"../api-client.js";import{REF_CONSTRAINT as h}from"./read.js";const f="An event subject pattern: dot-separated segments, where `*` matches exactly one segment and `>` matches one or more trailing segments. `>` alone matches every event.";function a(e,t){if(t===void 0)return;let n;try{n=JSON.parse(t)}catch{n=void 0}if(n===null||typeof n!="object"||Array.isArray(n))throw u(`--${e} must be a JSON object`,{field:e,received:t,next:`Run \`crtr canvas watch -h\` for the --${e} shape.`});return n}r(a,"parseJsonObject");const v=c({name:"watch",description:"watch an object so its events are delivered to you",whenToUse:"you want to hear when an object changes or acts \u2014 a document you depend on is edited, a node you did not spawn reports \u2014 without reading it now. Reading already makes you a watcher; use this for patterns or a listening configuration.",help:{name:"canvas watch",summary:"become a watcher of an object, optionally for chosen events only",params:[{kind:"positional",name:"ref",required:!0,constraint:h},{kind:"flag",name:"pattern",type:"string",required:!1,repeatable:!0,constraint:`${f} Default \`>\`.`},{kind:"flag",name:"listen",type:"string",required:!1,constraint:'JSON object mapping an event level (1\u201310) to how it reaches you: `{"<level>":"interrupt|steer|after-turn|next-turn"}`. Levels you leave out follow your node\u2019s listening configuration.'},{kind:"flag",name:"filter",type:"string",required:!1,constraint:"JSON object of event fields an event must match to be delivered."}],output:[{name:"watching",type:"string",required:!0,constraint:"The object and the patterns you now watch it for."}],outputKind:"object",effects:["Records a watch on the object; its matching events are delivered to you by your listening configuration, and the object\u2019s other watchers see a watched event."]},run:r(async e=>{const t=a("listen",e.listen),n=a("filter",e.filter),o={...Array.isArray(e.pattern)?{patterns:e.pattern}:{},...t?{config:t}:{},...n?{filter:n}:{}};try{return{...await d().objects.watch(e.ref,o)}}catch(i){l(i)}},"run"),render:r(e=>{const{object:t,patterns:n}=e;return`<watching id="${t.id}" name="${t.name}" patterns="${n.join(" ")}">`},"render")});export{f as PATTERN_CONSTRAINT,v as watchLeaf};

package/dist/commands/canvas-analytics.js

@@ -1 +1 @@
-var n=Object.defineProperty;var a=(e,t)=>n(e,"name",{value:t,configurable:!0});import{defineLeaf as s}from"../core/command.js";const o=s({name:"analytics",description:"open the interactive Analytics page",whenToUse:"the user wants to see how agents worked in the last 24 hours or 7 days \u2014 graph sizes and spawned kinds, created \u2192 final report times, memory documents read, and where the API-price estimate and tokens went. It is a person-facing page for the tmux popup (prefix menu, shift+a); it has no non-interactive output for agents",help:{name:"canvas analytics",summary:"open the read-only Analytics page \u2014 Overview, Graphs, Time, Memory, and Usage tabs over the last 24h or 7d",params:[{kind:"flag",name:"pane",type:"string",required:!1,constraint:"tmux pane id that `o` opens a conversation beside (the prefix menu passes the pane it was opened from). Default: $TMUX_PANE."}],output:[],outputKind:"object",effects:["Opens a pi-tui page; crtrd computes every number (`GET /v1/canvas/analytics`, person only). The page opens no database or transcript file.","Read-only. The one exception is `o` in graph detail, which closes the page and opens that agent\u2019s conversation and may wake it.","Does not start crtrd: with the daemon unreachable the page shows the error and `R` retries.","Requires an interactive terminal. Without one it prints one line to stderr and exits 1."]},run:a(async e=>{await(await import("./canvas-analytics/shell.js")).runAnalytics(e.pane)},"run"),render:a(()=>"","render")});export{o as analyticsLeaf};
+var n=Object.defineProperty;var a=(e,t)=>n(e,"name",{value:t,configurable:!0});import{defineLeaf as s}from"../core/command.js";const o=s({name:"analytics",description:"open the interactive Analytics page",whenToUse:"the user wants to see how agents worked in the last 24 hours or 7 days \u2014 graph sizes and spawned kinds, created \u2192 final report times, memory documents read, and where the API-price estimate and tokens went. It is a person-facing page for the tmux popup (prefix menu, shift+a); it has no non-interactive output for agents",help:{name:"canvas analytics",summary:"open the read-only Analytics page \u2014 Overview, Graphs, Time, Memory, and Usage tabs over the last 24h or 7d",params:[{kind:"flag",name:"pane",type:"string",required:!1,constraint:"tmux pane id that `o` opens a conversation beside (the prefix menu passes the pane it was opened from). Default: $TMUX_PANE."}],output:[],outputKind:"object",effects:["Opens a pi-tui page; crtrd computes every number (`GET /v1/canvas/analytics`). The page opens no database or transcript file.","Read-only. The one exception is `o` in graph detail, which closes the page and opens that agent\u2019s conversation and may wake it.","Does not start crtrd: with the daemon unreachable the page shows the error and `R` retries.","Requires an interactive terminal. Without one it prints one line to stderr and exits 1."]},run:a(async e=>{await(await import("./canvas-analytics/shell.js")).runAnalytics(e.pane)},"run"),render:a(()=>"","render")});export{o as analyticsLeaf};

package/dist/commands/canvas-history/grep.js

@@ -1,7 +1,7 @@
-var u=Object.defineProperty;var s=(e,t)=>u(e,"name",{value:t,configurable:!0});import{defineLeaf as f}from"../../core/command.js";import{usage as c}from"../../core/errors.js";import{cliClient as m,rethrowAsCliError as g}from"../api-client.js";import{applyFilters as y,filterParams as x,parseFilters as w}from"./shared.js";const j=f({name:"grep",description:"exact regex line search across the cwd's node history",whenToUse:"you know the exact string or pattern you're looking for \u2014 an error message, a literal identifier, a code fragment \u2014 and want every matching body LINE across every node that ran in this cwd, not a relevance ranking. The pattern is required (an ECMAScript regex, case-insensitive). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node. Want ranked/browse search instead? Use `canvas history search` \u2014 a distinct leaf, not a flag here. Use `canvas history read <ref>` to read a hit's full body, `node inspect artifacts <node-id>` to list one node's artifacts, and `node lifecycle revive <id>` to reopen a node you found.",help:{name:"canvas history grep",summary:"required-pattern regex line search over the per-cwd episodic record (reports + context docs + meta; transcripts and inbox opt-in)",params:[{kind:"positional",name:"pattern",required:!0,constraint:"An ECMAScript regex, matched case-insensitively against each body line. One hit per matching line."},...x,{kind:"flag",name:"limit",type:"int",required:!1,default:20,constraint:"Page size. Default 20, hard max 100."},{kind:"flag",name:"cursor",type:"string",required:!1,constraint:"Opaque token from a prior next_cursor; omit on the first call."}],output:[{name:"hits",type:"object[]",required:!0,constraint:"{ref, node, ts, line, text} per matching body line, sorted by ref then line. ref is the <node-id>:<relpath> handle passed verbatim to `canvas history read`."},{name:"next_cursor",type:"string|null",required:!0,constraint:"Token for the next page; null is the only end-of-list signal."},{name:"total",type:"int",required:!0,constraint:"Total matching lines (exact)."},{name:"follow_up",type:"string",required:!0,constraint:"Concrete next commands."}],outputKind:"object",effects:["None. Read-only."]},run:s(async e=>{const t=(e.pattern??"").trim(),o=Math.min(100,Math.max(1,e.limit??20)),i=e.cursor;if(t==="")throw c("pattern is required \u2014 the regex to match against body lines.");try{const r=new RegExp(t)}catch{throw c(`invalid regex pattern: ${t}`)}const n=w(e),a={pattern:t,limit:o};y(a,n),i!==void 0&&(a.cursor=i);try{const r=await m().historyGrep(a);return{hits:r.hits,next_cursor:r.next_cursor,total:r.total,follow_up:"Read a hit with `crtr canvas history read <ref>`; narrow with `crtr canvas history grep -h`."}}catch(r){g(r)}},"run"),render:s(e=>v(e),"render")});function v(e){const t=e.hits,o=e.total,i=e.next_cursor,n=[];if(t.length===0)n.push("0 hits.");else{n.push(`${t.length} of ${o} hits:`);const a=Object.keys(t[0]),r=`| ${a.join(" | ")} |`,l=`| ${a.map(()=>"---").join(" | ")} |`,d=t.map(h=>`| ${a.map(p=>String(h[p]??"").replace(/\|/g,"\\|").replace(/\n/g," ")).join(" | ")} |`).join(`
+var u=Object.defineProperty;var o=(e,t)=>u(e,"name",{value:t,configurable:!0});import{defineLeaf as m}from"../../core/command.js";import{usage as c}from"../../core/errors.js";import{cliClient as f,rethrowAsCliError as g}from"../api-client.js";import{applyFilters as y,filterParams as w,parseFilters as x}from"./shared.js";const j=m({name:"grep",description:"exact regex line search across the cwd's node history",whenToUse:"you know the exact string or pattern you're looking for \u2014 an error message, a literal identifier, a code fragment \u2014 and want every matching body LINE across every node that ran in this cwd, not a relevance ranking. The pattern is required (an ECMAScript regex, case-insensitive). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node. Want ranked/browse search instead? Use `canvas history search` \u2014 a distinct leaf, not a flag here. Use `canvas history read <ref>` to read a hit's full body. Reports and documents are `crtr canvas search --grep`, not this.",help:{name:"canvas history grep",summary:"required-pattern regex line search over past inboxes (default) and conversation transcripts in a cwd",params:[{kind:"positional",name:"pattern",required:!0,constraint:"An ECMAScript regex, matched case-insensitively against each body line. One hit per matching line."},...w,{kind:"flag",name:"limit",type:"int",required:!1,default:20,constraint:"Page size. Default 20, hard max 100."},{kind:"flag",name:"cursor",type:"string",required:!1,constraint:"Opaque token from a prior next_cursor; omit on the first call."}],output:[{name:"hits",type:"object[]",required:!0,constraint:"{ref, node, ts, line, text} per matching body line, sorted by ref then line. ref is the <node-id>:<relpath> handle passed verbatim to `canvas history read`."},{name:"next_cursor",type:"string|null",required:!0,constraint:"Token for the next page; null is the only end-of-list signal."},{name:"total",type:"int",required:!0,constraint:"Total matching lines (exact)."},{name:"follow_up",type:"string",required:!0,constraint:"Concrete next commands."}],outputKind:"object",effects:["None. Read-only."]},run:o(async e=>{const t=(e.pattern??"").trim(),s=Math.min(100,Math.max(1,e.limit??20)),i=e.cursor;if(t==="")throw c("pattern is required \u2014 the regex to match against body lines.");try{const r=new RegExp(t)}catch{throw c(`invalid regex pattern: ${t}`)}const n=x(e),a={pattern:t,limit:s};y(a,n),i!==void 0&&(a.cursor=i);try{const r=await f().historyGrep(a);return{hits:r.hits,next_cursor:r.next_cursor,total:r.total,follow_up:"Read a hit with `crtr canvas history read <ref>`; narrow with `crtr canvas history grep -h`."}}catch(r){g(r)}},"run"),render:o(e=>v(e),"render")});function v(e){const t=e.hits,s=e.total,i=e.next_cursor,n=[];if(t.length===0)n.push("0 hits.");else{n.push(`${t.length} of ${s} hits:`);const a=Object.keys(t[0]),r=`| ${a.join(" | ")} |`,l=`| ${a.map(()=>"---").join(" | ")} |`,h=t.map(d=>`| ${a.map(p=>String(d[p]??"").replace(/\|/g,"\\|").replace(/\n/g," ")).join(" | ")} |`).join(`
 `);n.push(`${r}
 ${l}
-${d}`)}return n.push(`- next_cursor: ${i??"null"}
-- total: ${o}`),n.push(String(e.follow_up)),n.join(`
+${h}`)}return n.push(`- next_cursor: ${i??"null"}
+- total: ${s}`),n.push(String(e.follow_up)),n.join(`
 
-`)}s(v,"renderGrep");export{j as grepLeaf};
+`)}o(v,"renderGrep");export{j as grepLeaf};

package/dist/commands/canvas-history/read.js

@@ -1,3 +1,3 @@
-var s=Object.defineProperty;var n=(e,r)=>s(e,"name",{value:r,configurable:!0});import{defineLeaf as i}from"../../core/command.js";import{usage as d}from"../../core/errors.js";import{cliClient as c,rethrowAsCliError as f}from"../api-client.js";const p=i({name:"read",description:"read one search hit's full body by its ref",whenToUse:"you picked a hit from `canvas history search` (or `node inspect artifacts`) and want its full content \u2014 pass the `<node-id>:<relpath>` ref verbatim. Strips frontmatter by default; add --frontmatter to keep the YAML header.",help:{name:"canvas history read",summary:"resolve a <node-id>:<relpath> ref to its full artifact body",params:[{kind:"positional",name:"ref",required:!0,constraint:"The <node-id>:<relpath> handle from `canvas history search` (e.g. mq186ky0-c754531c:reports/20260607T075536-final.md, or <node-id>:meta for a node's identity). <node-id>:session addresses a node's whole conversation; <node-id>:session/<index> one message in it."},{kind:"flag",name:"frontmatter",type:"bool",required:!1,constraint:"Include the artifact's YAML frontmatter. Stripped by default."},{kind:"flag",name:"format",type:"enum",choices:["rendered","raw"],required:!1,default:"rendered",constraint:"raw returns the verbatim bytes behind the ref \u2014 the session .jsonl for a bare session ref, the single persisted jsonl entry for one message, the unparsed file for a report or doc. Use it when the rendered view may be hiding what you are chasing."}],output:[{name:"ref",type:"string",required:!0,constraint:"Echo of the resolved ref."},{name:"node",type:"string",required:!0,constraint:"Node name + id."},{name:"source",type:"string",required:!0,constraint:"report | doc | roadmap | meta | inbox | transcript (+ report-kind for reports)."},{name:"ts",type:"string",required:!0,constraint:"Artifact timestamp."},{name:"content",type:"string",required:!0,constraint:"Full body. Frontmatter stripped unless --frontmatter."}],outputKind:"object",effects:["None. Read-only."]},run:n(async e=>{const r=e.ref.trim(),o=e.frontmatter===!0,a=e.format??"rendered";if(!r.includes(":"))throw d(`ref must be <node-id>:<relpath>; received: ${r}`,{received:r,next:"Get a valid ref from `crtr canvas history search` or `crtr node inspect artifacts <node-id>`."});try{const t=await c().historyRead({ref:r,frontmatter:o,format:a});return{ref:t.ref,node:t.node,source:t.source,ts:t.ts,content:t.content}}catch(t){f(t)}},"run"),render:n(e=>`${`${e.node}  |  source: ${e.source}  |  ts: ${e.ts}  |  ref: ${e.ref}`}
+var s=Object.defineProperty;var t=(e,r)=>s(e,"name",{value:r,configurable:!0});import{defineLeaf as a}from"../../core/command.js";import{usage as i}from"../../core/errors.js";import{cliClient as d,rethrowAsCliError as c}from"../api-client.js";const y=a({name:"read",description:"read one inbox entry or conversation message in full by its ref",whenToUse:"you picked a hit from `canvas history search` or `grep` and want its full content \u2014 pass the ref verbatim. Reports and documents are `crtr canvas read <name>`, not this.",help:{name:"canvas history read",summary:"resolve an inbox or conversation ref to its full body",params:[{kind:"positional",name:"ref",required:!0,constraint:"A ref from `canvas history search`: <node-id>:inbox/<n> for one inbox entry, <node-id>:session for a node's whole conversation, <node-id>:session/<n> for one message in it."},{kind:"flag",name:"format",type:"enum",choices:["rendered","raw"],required:!1,default:"rendered",constraint:"raw returns the verbatim bytes behind a conversation ref \u2014 the session .jsonl for <node-id>:session, the single persisted jsonl entry for one message. Use it when the rendered view may be hiding what you are chasing."}],output:[{name:"ref",type:"string",required:!0,constraint:"Echo of the resolved ref."},{name:"node",type:"string",required:!0,constraint:"Node name + id."},{name:"source",type:"string",required:!0,constraint:"inbox | transcript."},{name:"ts",type:"string",required:!0,constraint:"Entry or message timestamp."},{name:"content",type:"string",required:!0,constraint:"Full body."}],outputKind:"object",effects:["None. Read-only."]},run:t(async e=>{const r=e.ref.trim(),o=e.format??"rendered";if(!r.includes(":"))throw i(`ref must be <node-id>:inbox/<n>, <node-id>:session, or <node-id>:session/<n>; received: ${r}`,{received:r,next:"Get a valid ref from `crtr canvas history search`. Reports and documents are `crtr canvas read <name>`."});try{const n=await d().historyRead({ref:r,format:o});return{ref:n.ref,node:n.node,source:n.source,ts:n.ts,content:n.content}}catch(n){c(n)}},"run"),render:t(e=>`${`${e.node}  |  source: ${e.source}  |  ts: ${e.ts}  |  ref: ${e.ref}`}
 
-${String(e.content).trim()}`,"render")});export{p as readLeaf};
+${String(e.content).trim()}`,"render")});export{y as readLeaf};

package/dist/commands/canvas-history/search.js

@@ -1,10 +1,10 @@
-var u=Object.defineProperty;var c=(e,t)=>u(e,"name",{value:t,configurable:!0});import{defineLeaf as p}from"../../core/command.js";import{cliClient as y,rethrowAsCliError as m}from"../api-client.js";import{applyFilters as g,filterParams as w,parseFilters as b}from"./shared.js";const k=["relevance","recency","oldest"],j=p({name:"search",description:"ranked content search across the cwd's node history",whenToUse:'you want to find past work by what it SAYS \u2014 a design, a final report, a roadmap, a finding \u2014 across every node that ran in this cwd, ranked by relevance. Omit the query to browse the record by recency ("what happened here lately"). Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node. Need an exact regex over bodies instead of ranking? Use `canvas history grep` \u2014 a distinct leaf, not a flag here. Use `canvas history read <ref>` to read a hit in full, `node inspect artifacts <node-id>` to list one node\'s artifacts, and `node lifecycle revive <id>` to reopen a node you found.',help:{name:"canvas history search",summary:"ranked/filtered/sorted content search over the per-cwd episodic record (reports + context docs + meta; transcripts and inbox opt-in)",params:[{kind:"positional",name:"query",required:!1,constraint:"Whitespace-separated terms, matched case-insensitively and weighted across node name/description, report titles, and doc headings (and full bodies with --body); artifacts matching more/stronger fields rank higher. Omit to browse by recency (no relevance ranking; --sort still applies)."},...w,{kind:"flag",name:"body",type:"bool",required:!1,constraint:"Also weigh full body text in the ranking (default weighs name/title/heading only)."},{kind:"flag",name:"sort",type:"enum",choices:k,required:!1,constraint:"relevance (default with a query) ranks by score; recency (default without a query) / oldest order by artifact timestamp."},{kind:"flag",name:"snippet-lines",type:"int",required:!1,default:1,constraint:"Context lines per hit. Default 1."},{kind:"flag",name:"full",type:"bool",required:!1,constraint:"Inline each hit's full body. Off by default; pair with a small --limit."},{kind:"flag",name:"limit",type:"int",required:!1,default:20,constraint:"Page size. Default 20, hard max 100."},{kind:"flag",name:"cursor",type:"string",required:!1,constraint:"Opaque token from a prior next_cursor; omit on the first call."}],output:[{name:"hits",type:"object[]",required:!0,constraint:"Ranked/sorted hits, each: {ref, node, kind, source, ts, score?, snippet}. ref is the <node-id>:<relpath> handle passed verbatim to `canvas history read`."},{name:"next_cursor",type:"string|null",required:!0,constraint:"Token for the next page; null is the only end-of-list signal."},{name:"total",type:"int",required:!0,constraint:"Total matching artifacts (exact)."},{name:"follow_up",type:"string",required:!0,constraint:"Concrete next commands."}],outputKind:"object",effects:["None. Read-only."]},run:c(async e=>{const t=(e.query??"").trim(),a=e.body===!0,l=e.full===!0,d=Math.max(1,e.snippetLines??1),n=Math.min(100,Math.max(1,e.limit??20)),r=e.cursor,i=b(e),h=t.toLowerCase().split(/\s+/).filter(o=>o.length>0),f=e.sort??(h.length>0?"relevance":"recency"),s={snippet_lines:d,limit:n,sort:f};t!==""&&(s.query=t),g(s,i),a&&(s.weigh_body=!0),l&&(s.full=!0),r!==void 0&&(s.cursor=r);try{const o=await y().historySearch(s);return{hits:o.hits,next_cursor:o.next_cursor,total:o.total,follow_up:"Read a hit with `crtr canvas history read <ref>`; narrow with `crtr canvas history search -h`."}}catch(o){m(o)}},"run"),render:c(e=>q(e),"render")});function q(e){const t=e.hits,a=e.total,l=e.next_cursor,d=t.length>0&&Object.prototype.hasOwnProperty.call(t[0],"body"),n=[];if(t.length===0)n.push("0 hits.");else if(d){n.push(`${t.length} of ${a} hits:`);for(const r of t){const i=`### ${r.ref}
-- node: ${r.node}  |  kind: ${r.kind}  |  source: ${r.source}  |  ts: ${r.ts}`;n.push(`${i}
+var f=Object.defineProperty;var c=(e,t)=>f(e,"name",{value:t,configurable:!0});import{defineLeaf as p}from"../../core/command.js";import{cliClient as y,rethrowAsCliError as m}from"../api-client.js";import{applyFilters as g,filterParams as w,parseFilters as b}from"./shared.js";const k=["relevance","recency","oldest"],j=p({name:"search",description:"ranked search over past inboxes and conversations in a cwd",whenToUse:"you want to find what was SAID to or by nodes that ran in this cwd \u2014 a message a node received, a turn in its conversation \u2014 ranked by relevance. Omit the query to browse by recency. Narrow with --type/--kind/--status/--since, scope elsewhere with --cwd/--all-cwds/--under/--node. Need an exact regex over bodies instead? Use `canvas history grep`. Reports and documents are `crtr canvas search`, not this.",help:{name:"canvas history search",summary:"ranked/filtered/sorted search over past inboxes (default) and conversation transcripts in a cwd",params:[{kind:"positional",name:"query",required:!1,constraint:"Whitespace-separated terms, matched case-insensitively and weighted across node name/description and each entry's or message's lead line (and full bodies with --body); artifacts matching more/stronger fields rank higher. Omit to browse by recency (no relevance ranking; --sort still applies)."},...w,{kind:"flag",name:"body",type:"bool",required:!1,constraint:"Also weigh full body text in the ranking (default weighs node name/description and the lead line only)."},{kind:"flag",name:"sort",type:"enum",choices:k,required:!1,constraint:"relevance (default with a query) ranks by score; recency (default without a query) / oldest order by artifact timestamp."},{kind:"flag",name:"snippet-lines",type:"int",required:!1,default:1,constraint:"Context lines per hit. Default 1."},{kind:"flag",name:"full",type:"bool",required:!1,constraint:"Inline each hit's full body. Off by default; pair with a small --limit."},{kind:"flag",name:"limit",type:"int",required:!1,default:20,constraint:"Page size. Default 20, hard max 100."},{kind:"flag",name:"cursor",type:"string",required:!1,constraint:"Opaque token from a prior next_cursor; omit on the first call."}],output:[{name:"hits",type:"object[]",required:!0,constraint:"Ranked/sorted hits, each: {ref, node, kind, source, ts, score?, snippet}. ref is the <node-id>:inbox/<n> or <node-id>:session/<n> handle passed verbatim to `canvas history read`."},{name:"next_cursor",type:"string|null",required:!0,constraint:"Token for the next page; null is the only end-of-list signal."},{name:"total",type:"int",required:!0,constraint:"Total matching entries and messages (exact)."},{name:"follow_up",type:"string",required:!0,constraint:"Concrete next commands."}],outputKind:"object",effects:["None. Read-only."]},run:c(async e=>{const t=(e.query??"").trim(),o=e.body===!0,l=e.full===!0,d=Math.max(1,e.snippetLines??1),r=Math.min(100,Math.max(1,e.limit??20)),n=e.cursor,i=b(e),h=t.toLowerCase().split(/\s+/).filter(a=>a.length>0),u=e.sort??(h.length>0?"relevance":"recency"),s={snippet_lines:d,limit:r,sort:u};t!==""&&(s.query=t),g(s,i),o&&(s.weigh_body=!0),l&&(s.full=!0),n!==void 0&&(s.cursor=n);try{const a=await y().historySearch(s);return{hits:a.hits,next_cursor:a.next_cursor,total:a.total,follow_up:"Read a hit with `crtr canvas history read <ref>`; narrow with `crtr canvas history search -h`."}}catch(a){m(a)}},"run"),render:c(e=>x(e),"render")});function x(e){const t=e.hits,o=e.total,l=e.next_cursor,d=t.length>0&&Object.prototype.hasOwnProperty.call(t[0],"body"),r=[];if(t.length===0)r.push("0 hits.");else if(d){r.push(`${t.length} of ${o} hits:`);for(const n of t){const i=`### ${n.ref}
+- node: ${n.node}  |  kind: ${n.kind}  |  source: ${n.source}  |  ts: ${n.ts}`;r.push(`${i}
 
-${String(r.body??"").trim()}`)}}else{n.push(`${t.length} of ${a} hits:`);const r=Object.keys(t[0]).filter(s=>s!=="body"),i=`| ${r.join(" | ")} |`,h=`| ${r.map(()=>"---").join(" | ")} |`,f=t.map(s=>`| ${r.map(o=>String(s[o]??"").replace(/\|/g,"\\|").replace(/\n/g," ")).join(" | ")} |`).join(`
-`);n.push(`${i}
+${String(n.body??"").trim()}`)}}else{r.push(`${t.length} of ${o} hits:`);const n=Object.keys(t[0]).filter(s=>s!=="body"),i=`| ${n.join(" | ")} |`,h=`| ${n.map(()=>"---").join(" | ")} |`,u=t.map(s=>`| ${n.map(a=>String(s[a]??"").replace(/\|/g,"\\|").replace(/\n/g," ")).join(" | ")} |`).join(`
+`);r.push(`${i}
 ${h}
-${f}`)}return n.push(`- next_cursor: ${l??"null"}
-- total: ${a}`),n.push(String(e.follow_up)),n.join(`
+${u}`)}return r.push(`- next_cursor: ${l??"null"}
+- total: ${o}`),r.push(String(e.follow_up)),r.join(`
 
-`)}c(q,"renderSearch");export{j as searchLeaf};
+`)}c(x,"renderSearch");export{j as searchLeaf};

package/dist/commands/canvas-history/shared.d.ts

@@ -18,7 +18,6 @@ export interface ParsedFilters {
     under: string | undefined;
     nodes: string[] | undefined;
     types: string[] | undefined;
-    reportKind: string | undefined;
     kinds: string[] | undefined;
     statuses: string[] | undefined;
     sinceMs: number | undefined;

package/dist/commands/canvas-history/shared.js

@@ -1 +1 @@
-var g=Object.defineProperty;var d=(e,n)=>g(e,"name",{value:n,configurable:!0});import{usage as s}from"../../core/errors.js";const u=["report","doc","roadmap","meta","inbox","transcript"],f=["human","inbox","wake","revive","restart-continuation","stop-guard","park","recovery","context-nudge","kickoff","unknown"],p=["user","assistant","toolResult"],w=["advisor","developer","spec","design","review","explore","plan","general"],y=["active","idle","done","dead","canceled"],h={s:1e3,m:6e4,h:36e5,d:864e5,w:6048e5,mo:2592e6,y:31536e6};function m(e,n){const t=n.match(/^(\d+)(mo|[smhdwy])$/);if(t!==null)return Date.now()-Number(t[1])*h[t[2]];const i=Date.parse(n);if(!Number.isNaN(i))return i;throw s(`--${e} must be ISO 8601 (2026-06-01) or relative (7d, 2w, 1mo); received: ${n}`)}d(m,"parseWhen");function o(e){if(!(e===void 0||e===""))return e.split(",").map(n=>n.trim()).filter(n=>n!=="")}d(o,"splitCsv");const b=[{kind:"flag",name:"cwd",type:"path",required:!1,constraint:"Search another project's record. Default: the calling node's cwd (process cwd when not a node). Mutually exclusive with --all-cwds."},{kind:"flag",name:"all-cwds",type:"bool",required:!1,constraint:"Search every cwd on the canvas. Mutually exclusive with --cwd."},{kind:"flag",name:"under",type:"string",required:!1,constraint:"Restrict to a node and its subscription descendants (one initiative / sub-DAG)."},{kind:"flag",name:"node",type:"string",required:!1,constraint:"Restrict to specific node ids. Comma-separated for several."},{kind:"flag",name:"type",type:"string",required:!1,constraint:`Corpus to search; comma-separated for several. One of: ${u.join(", ")}. report = push history; doc = context artifacts; roadmap = roadmap.md specifically; meta = node name/description/kind; inbox = inbox history including full un-clipped direct-message bodies (diagnostic, not curated work). Default: report, doc, roadmap, meta \u2014 inbox is opt-in only, pass --type inbox explicitly.`},{kind:"flag",name:"report-kind",type:"enum",choices:["final","update"],required:!1,constraint:"Narrow reports to outcome summaries (final) or progress (update). Implies --type report."},{kind:"flag",name:"kind",type:"string",required:!1,constraint:`Node kind; comma-separated for several. One of: ${w.join(", ")}.`},{kind:"flag",name:"status",type:"string",required:!1,constraint:`Node lifecycle status; comma-separated for several. One of: ${y.join(", ")} (e.g. done = completed work only).`},{kind:"flag",name:"since",type:"string",required:!1,constraint:"Lower bound on artifact timestamp. ISO 8601 (2026-06-01) or relative (7d, 2w, 1mo)."},{kind:"flag",name:"until",type:"string",required:!1,constraint:"Upper bound on artifact timestamp. ISO 8601 or relative."},{kind:"flag",name:"origin",type:"string",required:!1,constraint:`What drove a message to arrive; comma-separated for several. One of: ${f.join(", ")}. Applies to transcript + inbox artifacts, which are the only ones that arrive \u2014 passing it therefore excludes every generated turn on its own. \`unknown\` is a message carrying no stamp, and is its own bucket rather than a fallback.`},{kind:"flag",name:"role",type:"string",required:!1,constraint:`Transcript message role; comma-separated for several. One of: ${p.join(", ")}.`},{kind:"flag",name:"from",type:"string",required:!1,constraint:"Case-insensitive substring against sender attribution \u2014 the node that sent a delivery. Applies to transcript + inbox artifacts."}];function x(e){const n=e.cwd,t=e.allCwds===!0;if(n!==void 0&&t)throw s("--cwd and --all-cwds are mutually exclusive.");const i=o(e.type);if(i!==void 0){const r=i.find(a=>!u.includes(a));if(r!==void 0)throw s(`--type must be one of: ${u.join(", ")}; received: ${r}`)}const c=o(e.origin);if(c!==void 0){const r=c.find(a=>!f.includes(a));if(r!==void 0)throw s(`--origin must be one of: ${f.join(", ")}; received: ${r}`)}const l=o(e.role);if(l!==void 0){const r=l.find(a=>!p.includes(a));if(r!==void 0)throw s(`--role must be one of: ${p.join(", ")}; received: ${r}`)}if(i!==void 0&&i.includes("transcript")&&!(e.node!==void 0||e.under!==void 0||e.since!==void 0))throw s("--type transcript needs a narrowing flag: pass --node, --under, or --since.",{next:"Transcripts are the full conversation corpus \u2014 scanning every node in a cwd reads every session file. Narrow first."});return{cwd:n,allCwds:t,under:e.under,nodes:o(e.node),types:i,reportKind:e.reportKind,kinds:o(e.kind),statuses:o(e.status),sinceMs:e.since!==void 0?m("since",e.since):void 0,untilMs:e.until!==void 0?m("until",e.until):void 0,origins:c,roles:l,from:e.from}}d(x,"parseFilters");function _(e,n){n.cwd!==void 0&&(e.cwd=n.cwd),n.allCwds&&(e.all_cwds=!0),n.under!==void 0&&(e.under=n.under),n.nodes!==void 0&&(e.nodes=n.nodes),n.types!==void 0&&(e.types=n.types),n.reportKind!==void 0&&(e.report_kind=n.reportKind),n.kinds!==void 0&&(e.kinds=n.kinds),n.statuses!==void 0&&(e.statuses=n.statuses),n.sinceMs!==void 0&&(e.since_ms=n.sinceMs),n.untilMs!==void 0&&(e.until_ms=n.untilMs),n.origins!==void 0&&(e.origins=n.origins),n.roles!==void 0&&(e.roles=n.roles),n.from!==void 0&&(e.from=n.from)}d(_,"applyFilters");export{w as NODE_KINDS,f as ORIGINS,p as ROLES,y as STATUSES,u as TYPES,_ as applyFilters,b as filterParams,x as parseFilters,m as parseWhen,o as splitCsv};
+var g=Object.defineProperty;var d=(e,n)=>g(e,"name",{value:n,configurable:!0});import{usage as t}from"../../core/errors.js";const u=["transcript","inbox"],f=["human","inbox","wake","revive","restart-continuation","stop-guard","park","recovery","context-nudge","kickoff","unknown"],m=["user","assistant","toolResult"],w=["advisor","developer","spec","design","review","explore","plan","general"],y=["active","idle","done","dead","canceled"],v={s:1e3,m:6e4,h:36e5,d:864e5,w:6048e5,mo:2592e6,y:31536e6};function p(e,n){const r=n.match(/^(\d+)(mo|[smhdwy])$/);if(r!==null)return Date.now()-Number(r[1])*v[r[2]];const s=Date.parse(n);if(!Number.isNaN(s))return s;throw t(`--${e} must be ISO 8601 (2026-06-01) or relative (7d, 2w, 1mo); received: ${n}`)}d(p,"parseWhen");function a(e){if(!(e===void 0||e===""))return e.split(",").map(n=>n.trim()).filter(n=>n!=="")}d(a,"splitCsv");const k=[{kind:"flag",name:"cwd",type:"path",required:!1,constraint:"Search another project's record. Default: the calling node's cwd (process cwd when not a node). Mutually exclusive with --all-cwds."},{kind:"flag",name:"all-cwds",type:"bool",required:!1,constraint:"Search every cwd on the canvas. Mutually exclusive with --cwd."},{kind:"flag",name:"under",type:"string",required:!1,constraint:"Restrict to a node and its subscription descendants (one initiative / sub-DAG)."},{kind:"flag",name:"node",type:"string",required:!1,constraint:"Restrict to specific node ids. Comma-separated for several."},{kind:"flag",name:"type",type:"string",required:!1,constraint:`Corpus to search; comma-separated for both. One of: ${u.join(", ")}. inbox = every delivery a node received, with un-clipped message bodies; transcript = the conversation itself, message by message. Default: inbox.`},{kind:"flag",name:"kind",type:"string",required:!1,constraint:`Node kind; comma-separated for several. One of: ${w.join(", ")}.`},{kind:"flag",name:"status",type:"string",required:!1,constraint:`Node lifecycle status; comma-separated for several. One of: ${y.join(", ")} (e.g. done = completed work only).`},{kind:"flag",name:"since",type:"string",required:!1,constraint:"Lower bound on artifact timestamp. ISO 8601 (2026-06-01) or relative (7d, 2w, 1mo)."},{kind:"flag",name:"until",type:"string",required:!1,constraint:"Upper bound on artifact timestamp. ISO 8601 or relative."},{kind:"flag",name:"origin",type:"string",required:!1,constraint:`What drove a message to arrive; comma-separated for several. One of: ${f.join(", ")}. Applies to transcript + inbox artifacts, which are the only ones that arrive \u2014 passing it therefore excludes every generated turn on its own. \`unknown\` is a message carrying no stamp, and is its own bucket rather than a fallback.`},{kind:"flag",name:"role",type:"string",required:!1,constraint:`Transcript message role; comma-separated for several. One of: ${m.join(", ")}.`},{kind:"flag",name:"from",type:"string",required:!1,constraint:"Case-insensitive substring against sender attribution \u2014 the node that sent a delivery. Applies to transcript + inbox artifacts."}];function x(e){const n=e.cwd,r=e.allCwds===!0;if(n!==void 0&&r)throw t("--cwd and --all-cwds are mutually exclusive.");const s=a(e.type);if(s!==void 0){const i=s.find(o=>!u.includes(o));if(i!==void 0)throw t(`--type must be one of: ${u.join(", ")}; received: ${i}`)}const c=a(e.origin);if(c!==void 0){const i=c.find(o=>!f.includes(o));if(i!==void 0)throw t(`--origin must be one of: ${f.join(", ")}; received: ${i}`)}const l=a(e.role);if(l!==void 0){const i=l.find(o=>!m.includes(o));if(i!==void 0)throw t(`--role must be one of: ${m.join(", ")}; received: ${i}`)}if(s!==void 0&&s.includes("transcript")&&!(e.node!==void 0||e.under!==void 0||e.since!==void 0))throw t("--type transcript needs a narrowing flag: pass --node, --under, or --since.",{next:"Transcripts are the full conversation corpus \u2014 scanning every node in a cwd reads every session file. Narrow first."});return{cwd:n,allCwds:r,under:e.under,nodes:a(e.node),types:s,kinds:a(e.kind),statuses:a(e.status),sinceMs:e.since!==void 0?p("since",e.since):void 0,untilMs:e.until!==void 0?p("until",e.until):void 0,origins:c,roles:l,from:e.from}}d(x,"parseFilters");function _(e,n){n.cwd!==void 0&&(e.cwd=n.cwd),n.allCwds&&(e.all_cwds=!0),n.under!==void 0&&(e.under=n.under),n.nodes!==void 0&&(e.nodes=n.nodes),n.types!==void 0&&(e.types=n.types),n.kinds!==void 0&&(e.kinds=n.kinds),n.statuses!==void 0&&(e.statuses=n.statuses),n.sinceMs!==void 0&&(e.since_ms=n.sinceMs),n.untilMs!==void 0&&(e.until_ms=n.untilMs),n.origins!==void 0&&(e.origins=n.origins),n.roles!==void 0&&(e.roles=n.roles),n.from!==void 0&&(e.from=n.from)}d(_,"applyFilters");export{w as NODE_KINDS,f as ORIGINS,m as ROLES,y as STATUSES,u as TYPES,_ as applyFilters,k as filterParams,x as parseFilters,p as parseWhen,a as splitCsv};

package/dist/commands/canvas-history/stats.js

@@ -1,5 +1,5 @@
-var h=Object.defineProperty;var s=(o,e)=>h(o,"name",{value:e,configurable:!0});import{defineLeaf as m}from"../../core/command.js";import{usage as g}from"../../core/errors.js";import{cliClient as l,rethrowAsCliError as f}from"../api-client.js";import{applyFilters as b,filterParams as w,parseFilters as v}from"./shared.js";const i=["origin","node","kind","day","type","role"],_=m({name:"stats",description:"grouped counts over the cwd's node history \u2014 the projection view",whenToUse:"you want the SHAPE of the record rather than individual hits \u2014 how much of it came from where, who produced it, or when it happened. Group by origin to census what drove agents to run (cron wakes, inbox deliveries, recovery re-drives, people), by node/kind to see who produced the work, by day for volume over time, by type for corpus composition. Takes every scope and filter `canvas history search` takes, so any query you can search you can also count. Want the matching artifacts themselves? Use `canvas history search` or `canvas history grep`.",help:{name:"canvas history stats",summary:"counts by one dimension over the per-cwd episodic record \u2014 origin census, per-node volume, activity by day",params:[{kind:"flag",name:"group-by",type:"enum",choices:i,required:!1,default:"type",constraint:"The dimension to count by. origin = what drove an inbound message (transcript + inbox only); role = transcript message role; node / kind = who produced it; day = artifact date; type = corpus composition."},...w],output:[{name:"group_by",type:"string",required:!0,constraint:"The dimension counted."},{name:"groups",type:"object[]",required:!0,constraint:"{key, count}, descending by count then key."},{name:"total",type:"int",required:!0,constraint:"Artifacts that carried the grouped dimension. Lower than `scanned` when grouping by one not every artifact has (origin, role)."},{name:"scanned",type:"int",required:!0,constraint:"Artifacts matched by the filters before grouping."}],outputKind:"object",effects:["None. Read-only."]},run:s(async o=>{const e=o.groupBy??"type";if(!i.includes(e))throw g(`--group-by must be one of: ${i.join(", ")}; received: ${e}`);const n=v(o),r={group_by:e};b(r,n);try{const t=await l().historyStats(r);return{group_by:t.group_by,groups:t.groups,total:t.total,scanned:t.scanned}}catch(t){f(t)}},"run"),render:s(o=>{const e=o.groups,n=String(o.group_by),r=o.total,t=o.scanned;if(e.length===0)return`0 artifacts carried \`${n}\` (${t} scanned).`;const c=Math.max(...e.map(a=>a.key.length)),d=e[0].count,u=e.map(a=>{const y="\u2588".repeat(Math.max(1,Math.round(a.count/d*24)));return`  ${a.key.padEnd(c)}  ${String(a.count).padStart(6)}  ${y}`}).join(`
-`),p=r===t?`${r} artifacts`:`${r} of ${t} scanned carried \`${n}\``;return`by ${n}:
+var h=Object.defineProperty;var s=(o,e)=>h(o,"name",{value:e,configurable:!0});import{defineLeaf as m}from"../../core/command.js";import{usage as g}from"../../core/errors.js";import{cliClient as l,rethrowAsCliError as f}from"../api-client.js";import{applyFilters as b,filterParams as v,parseFilters as w}from"./shared.js";const i=["origin","node","kind","day","type","role"],_=m({name:"stats",description:"grouped counts over the cwd's node history \u2014 the projection view",whenToUse:"you want the SHAPE of the record rather than individual hits \u2014 how much of it came from where, who produced it, or when it happened. Group by origin to census what drove agents to run (cron wakes, inbox deliveries, recovery re-drives, people), by node/kind to see who produced the work, by day for volume over time, by type for corpus composition. Takes every scope and filter `canvas history search` takes, so any query you can search you can also count. Want the matching artifacts themselves? Use `canvas history search` or `canvas history grep`.",help:{name:"canvas history stats",summary:"counts by one dimension over past inboxes and conversations \u2014 origin census, per-node volume, activity by day",params:[{kind:"flag",name:"group-by",type:"enum",choices:i,required:!1,default:"type",constraint:"The dimension to count by. origin = what drove an inbound message (transcript + inbox only); role = transcript message role; node / kind = who produced it; day = artifact date; type = corpus composition."},...v],output:[{name:"group_by",type:"string",required:!0,constraint:"The dimension counted."},{name:"groups",type:"object[]",required:!0,constraint:"{key, count}, descending by count then key."},{name:"total",type:"int",required:!0,constraint:"Artifacts that carried the grouped dimension. Lower than `scanned` when grouping by one not every artifact has (origin, role)."},{name:"scanned",type:"int",required:!0,constraint:"Artifacts matched by the filters before grouping."}],outputKind:"object",effects:["None. Read-only."]},run:s(async o=>{const e=o.groupBy??"type";if(!i.includes(e))throw g(`--group-by must be one of: ${i.join(", ")}; received: ${e}`);const r=w(o),n={group_by:e};b(n,r);try{const t=await l().historyStats(n);return{group_by:t.group_by,groups:t.groups,total:t.total,scanned:t.scanned}}catch(t){f(t)}},"run"),render:s(o=>{const e=o.groups,r=String(o.group_by),n=o.total,t=o.scanned;if(e.length===0)return`0 artifacts carried \`${r}\` (${t} scanned).`;const c=Math.max(...e.map(a=>a.key.length)),d=e[0].count,u=e.map(a=>{const y="\u2588".repeat(Math.max(1,Math.round(a.count/d*24)));return`  ${a.key.padEnd(c)}  ${String(a.count).padStart(6)}  ${y}`}).join(`
+`),p=n===t?`${n} artifacts`:`${n} of ${t} scanned carried \`${r}\``;return`by ${r}:
 
 ${u}
 

package/dist/commands/canvas-history.js

@@ -1 +1 @@
-var n=Object.defineProperty;var t=(e,r)=>n(e,"name",{value:r,configurable:!0});import{envNodeCwd as o}from"../shared/env.js";import{defineBranch as a}from"../core/command.js";import{searchLeaf as s}from"./canvas-history/search.js";import{grepLeaf as i}from"./canvas-history/grep.js";import{readLeaf as d}from"./canvas-history/read.js";import{statsLeaf as c}from"./canvas-history/stats.js";function h(){return`<corpus cwd="${o()??process.cwd()}"/>`}t(h,"corpusBlock");const g=a({name:"history",description:"search and recall the cwd-wide content corpus \u2014 every node's reports, context docs, and conversations",whenToUse:'you want to find or re-read what was DONE in a cwd \u2014 a past design, a final report, a roadmap, a finding \u2014 across every node that ran there, WITHOUT already knowing which node. Use it when picking up prior work ("that caching work from last week"), recovering an artifact, or surveying a project\'s history. Already have the node id and just want everything IT left behind? Use `node inspect artifacts <id>` instead \u2014 this branch is the cwd-wide search corpus, not a per-node listing. Distinct from `crtr memory` (curated semantic knowledge, not episodes) and from `canvas dashboard`/`node inspect` (graph topology, not content).',help:{name:"canvas history",summary:"search and recall the cwd-wide content corpus \u2014 every node's reports and context docs in this cwd",model:"The accumulated record of every node that ran in a cwd and the artifacts it left \u2014 its reports (final/update outcome summaries), context docs (specs, designs, roadmaps, findings), and the conversations themselves. `search` finds by content (ranked, filtered, sorted; omit the query to browse by recency); `grep` finds by an exact ECMAScript regex over body lines (pattern required, one hit per matching line \u2014 use this over `search` when you know the literal string/pattern, not just the topic); `read` pulls one hit's full body by its <node-id>:<relpath> ref, `--format raw` for the verbatim bytes; `stats` counts the same filtered corpus by one dimension instead of listing hits. Corpus is a DIMENSION here, not a location: `--type` selects which record you search, and every leaf takes the same scope and filters. This is the episodic record of what was DONE \u2014 distinct from `crtr memory`, which is curated semantic knowledge. Already have a node id and want everything IT left behind (not a cwd-wide search)? Use `node inspect artifacts <node-id>` instead. Two corpora are opt-in diagnostics rather than curated work: `--type inbox` is one node's full inbox history including un-clipped message bodies, and `--type transcript` is the conversation itself, message by message, each inbound turn carrying the origin that drove it (`--origin`, `--role`, `--from`, and `stats --group-by origin` for the census). Transcripts require a narrowing flag because there is no index. To reopen a node you found, use `node lifecycle revive`; for its place in the graph, `node inspect show`.",dynamicState:h},children:[s,i,d,c]});export{g as historyBranch};
+var s=Object.defineProperty;var r=(e,a)=>s(e,"name",{value:a,configurable:!0});import{envNodeCwd as n}from"../shared/env.js";import{defineBranch as o}from"../core/command.js";import{searchLeaf as t}from"./canvas-history/search.js";import{grepLeaf as i}from"./canvas-history/grep.js";import{readLeaf as c}from"./canvas-history/read.js";import{statsLeaf as d}from"./canvas-history/stats.js";function h(){return`<corpus cwd="${n()??process.cwd()}"/>`}r(h,"corpusBlock");const g=o({name:"history",description:"past conversations and inboxes \u2014 search, grep, count, and read what nodes were told and said",whenToUse:"you want what was SAID in a cwd's past runs \u2014 a message a node received, a turn of its conversation, what drove it to wake \u2014 without already knowing which node. Reports and documents are `crtr canvas search` / `crtr canvas read`, not this.",help:{name:"canvas history",summary:"past conversations and inboxes; reports and documents are `crtr canvas search`/`read`",model:"Two corpora, selected with `--type`: `inbox` (default) is every delivery a node received, with un-clipped message bodies; `transcript` is the conversation itself, message by message, each inbound turn carrying the origin that drove it (`--origin`, `--role`, `--from`, and `stats --group-by origin` for the census). Transcripts require a narrowing flag because there is no index. `search` ranks or browses; `grep` matches an exact ECMAScript regex per body line; `read` pulls one hit by its ref (`<node-id>:inbox/<n>`, `<node-id>:session`, `<node-id>:session/<n>`); `stats` counts the same filtered corpus by one dimension. Every leaf takes the same scope and filters. Reports and documents are graph objects: find them with `crtr canvas search`, read them with `crtr canvas read`.",dynamicState:h},children:[t,i,c,d]});export{g as historyBranch};

package/dist/commands/canvas.js

@@ -1 +1 @@
-var o=Object.defineProperty;var e=(a,t)=>o(a,"name",{value:t,configurable:!0});import{defineBranch as r}from"../core/command.js";import{dashboardLeaf as n}from"./dashboard.js";import{canvasSnapshotLeaf as s}from"./canvas-snapshot.js";import{canvasRosterLeaf as i}from"./canvas-roster.js";import{browseLeaf as c}from"./canvas-browse.js";import{reviveLeaf as d}from"./revive.js";import{attentionBranch as p}from"./attention.js";import{chordLeaf as h}from"./chord.js";import{canvasPruneLeaf as m}from"./canvas-prune.js";import{historyBranch as u}from"./canvas-history.js";import{issueNewLeaf as f}from"./canvas-issue.js";import{canvasConfigBranch as l}from"./canvas-config.js";import{canvasUseLeaf as g}from"./canvas-use.js";import{analyticsLeaf as v}from"./canvas-analytics.js";const b=r({name:"issue",description:"capture a quick todo/idea/bug into a GitHub issue (or a .todos/ note)",whenToUse:"the alt+c \u2192 i chord uses this; capture a passing thought without leaving your pane",tier:"hidden",help:{name:"canvas issue",summary:"capture a quick todo/idea/bug into a GitHub issue",model:"Quick brain-dump capture, bound to the alt+c \u2192 i \u2192 (idea|bug) prefix chord. `new` reads a free-text note, auto-generates the title via a headless pi call, and files it with `gh issue create --label <type>` when the pane\u2019s cwd is a GitHub repo, else writes `<git-root>/.todos/<slug>.md`. Meant for the chord/popup, not hand-running."},children:[f]});function U(){return r({name:"canvas",rootEntry:{concept:"the whole agent graph at a glance \u2014 render it, see who is blocked, mass-revive disconnected nodes, and find or re-read prior node reports/context artifacts",desc:"bird's-eye view, supervision, and report/artifact history for the entire canvas",useWhen:"surveying the full graph, finding blocked agents, mass-reviving every disconnected node, or finding/re-reading prior reports/artifacts; run `crtr canvas -h`"},help:{name:"canvas",summary:"observe and supervise the whole agent graph",model:"Canvas-wide operations, distinct from per-node work (`node`) and a node's own spine write verb (`push`). `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator (tabs/tree/search) over the whole canvas and resumes the chosen node; `attention` aggregates pending replies from the user across the graph; `revive --all` mass-reconnects every disconnected node (bringing back ONE named node is `node lifecycle revive <id>` instead); `history` searches and recalls the content record (reports + context docs) of past work in a cwd; `prune` bounds growth by deleting terminal nodes past a TTL; `analytics` opens the read-only Analytics page (graph sizes, agent time, memory reads, API-price estimate) for a person. `config` registers/lists remote canvas targets (preview endpoint + relay token); `use` switches remote-capable read commands such as `node inspect` onto a configured target or back to local."},children:[n,s,i,c,p,d,u,h,b,m,l,g,v]})}e(U,"registerCanvas");export{b as issueBranch,U as registerCanvas};
+var r=Object.defineProperty;var e=(o,t)=>r(o,"name",{value:t,configurable:!0});import{defineBranch as a}from"../core/command.js";import{dashboardLeaf as n}from"./dashboard.js";import{canvasSnapshotLeaf as s}from"./canvas-snapshot.js";import{canvasRosterLeaf as i}from"./canvas-roster.js";import{browseLeaf as d}from"./canvas-browse.js";import{reviveLeaf as c}from"./revive.js";import{attentionBranch as h}from"./attention.js";import{chordLeaf as m}from"./chord.js";import{canvasPruneLeaf as p}from"./canvas-prune.js";import{historyBranch as u}from"./canvas-history.js";import{issueNewLeaf as f}from"./canvas-issue.js";import{canvasConfigBranch as l}from"./canvas-config.js";import{canvasUseLeaf as g}from"./canvas-use.js";import{readLeaf as w}from"./canvas/read.js";import{listLeaf as v}from"./canvas/list.js";import{searchLeaf as b}from"./canvas/search.js";import{watchLeaf as y}from"./canvas/watch.js";import{unwatchLeaf as L}from"./canvas/unwatch.js";import{edgesLeaf as k}from"./canvas/edges.js";import{analyticsLeaf as j}from"./canvas-analytics.js";const x=a({name:"issue",description:"capture a quick todo/idea/bug into a GitHub issue (or a .todos/ note)",whenToUse:"the alt+c \u2192 i chord uses this; capture a passing thought without leaving your pane",tier:"hidden",help:{name:"canvas issue",summary:"capture a quick todo/idea/bug into a GitHub issue",model:"Quick brain-dump capture, bound to the alt+c \u2192 i \u2192 (idea|bug) prefix chord. `new` reads a free-text note, auto-generates the title via a headless pi call, and files it with `gh issue create --label <type>` when the pane\u2019s cwd is a GitHub repo, else writes `<git-root>/.todos/<slug>.md`. Meant for the chord/popup, not hand-running."},children:[f]});function J(){return a({name:"canvas",rootEntry:{concept:"every object in the agent graph \u2014 documents, nodes, jobs and their owners \u2014 read, listed, searched and watched by name, plus the whole-graph views: render it, see who is blocked, mass-revive disconnected nodes",desc:"read, list, search and watch objects; whole-graph views and supervision",useWhen:"reading a document, node or job by name, finding one you cannot name, watching an object for changes, surveying the full graph, finding blocked agents, or mass-reviving every disconnected node; documents are written with `crtr doc`; run `crtr canvas -h`"},help:{name:"canvas",summary:"read, find and watch objects; observe and supervise the whole agent graph",model:"Every document, node, bash job and owner (person, app, repo, plugin, profile) is an object with an id and a name, and the same verbs work on all of them. `read` returns one object by name or id and makes you a watcher of it; `list` filters objects by type, kind, owner, privacy or name prefix; `search` finds them by text; `edges` shows what an object links to, who acted on it and who watches it; `watch`/`unwatch` add or remove your watch without reading. `list`, `search` and `edges` record nothing. Documents are written, edited and moved with `crtr doc`, and pointed at as `[[name]]`. Canvas-wide views, distinct from per-node work (`node`) and a node's own spine write verb (`push`): `dashboard` renders the subscription forest as a tree; `browse` opens an interactive full-screen navigator over the whole canvas and resumes the chosen node; `attention` aggregates pending replies from the user across the graph; `revive --all` mass-reconnects every disconnected node (bringing back ONE named node is `node lifecycle revive <id>` instead); `history` searches past node conversations; `prune` bounds growth by deleting terminal nodes past a TTL; `analytics` opens the read-only Analytics page (graph sizes, agent time, document reads, API-price estimate) for a person. `config` registers/lists remote canvas targets (preview endpoint + relay token); `use` switches remote-capable read commands such as `node inspect` onto a configured target or back to local."},children:[w,v,b,y,L,k,n,s,i,d,h,c,u,m,x,p,l,g,j]})}e(J,"registerCanvas");export{x as issueBranch,J as registerCanvas};

package/dist/commands/doc/delete.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const deleteLeaf: LeafDef;

package/dist/commands/doc/delete.js

@@ -0,0 +1 @@
+var n=Object.defineProperty;var r=(e,t)=>n(e,"name",{value:t,configurable:!0});import{defineLeaf as o}from"../../core/command.js";import{cliClient as i,rethrowAsCliError as d}from"../api-client.js";import{REF_CONSTRAINT as a}from"./shared.js";const u=o({name:"delete",description:"delete a document",whenToUse:"a document is wrong or obsolete",help:{name:"doc delete",summary:"delete a document",params:[{kind:"positional",name:"ref",required:!0,constraint:a}],output:[{name:"name",type:"string",required:!0,constraint:"The deleted document's full name."},{name:"id",type:"string",required:!0,constraint:"Object id."}],outputKind:"object",effects:["Deletes the document and pushes the deletion to its watchers; links to it resolve to deleted, showing its last preview."]},run:r(async e=>{try{return{...await i().docs.delete(e.ref)}}catch(t){d(t)}},"run"),render:r(e=>`<deleted name="${String(e.name)}" id="${String(e.id)}">`,"render")});export{u as deleteLeaf};

package/dist/commands/doc/edit.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const editLeaf: LeafDef;

package/dist/commands/doc/edit.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var s=(e,n)=>m(e,"name",{value:n,configurable:!0});import{defineLeaf as h}from"../../core/command.js";import{usage as l}from"../../core/errors.js";import{DOC_UNSET_FIELDS as u}from"../../api/dto/docs.js";import{cliClient as f}from"../api-client.js";import{FIELD_FLAGS as t,REF_CONSTRAINT as y,fieldsFromInput as p,rethrowDocError as w,renderLinkReport as b,ruleParam as g}from"./shared.js";const T=h({name:"edit",description:"revise a document you have read",whenToUse:"a document you read needs a change to its body or fields",help:{name:"doc edit",summary:"revise a document you have read",guide:"The edit is made from the revision you last read (`crtr canvas read`); pass no revision. If someone edited it after your read, the edit is refused and nothing is overwritten. Change the body with a whole new body on stdin, or with --replace; give exactly one of the two, or neither for a fields-only edit. A field flag replaces that field; omitted fields stay as they are.",params:[{kind:"positional",name:"ref",required:!0,constraint:y},{kind:"flag",name:"rationale",type:"string",required:!0,constraint:"Why this revision is made; recorded on the revision, never in the body."},{kind:"stdin",name:"body",required:!1,constraint:"The whole new body, saved byte for byte."},{kind:"flag",name:"replace",type:"string",required:!1,constraint:'JSON list `[{"old": "\u2026", "new": "\u2026"}]` of exact-text replacements; each `old` must match exactly once in the body you read.'},{kind:"flag",name:"verbatim",type:"bool",required:!1,constraint:"The body is the person's own text relayed unchanged; recorded on the revision."},t.preview("New one-line preview."),t.summary,t.privacy("Who beyond the owner may read it."),g("Replaces the whole rule list."),t.whyItExists,t.unlisted("Sets unlisted; remove it with `--unset unlisted`."),t.lintIgnore,t.extension,{kind:"flag",name:"unset",type:"enum",choices:[...u],required:!1,repeatable:!0,constraint:"Clear one optional field."}],output:[{name:"revision",type:"number",required:!0,constraint:"The new revision number."},{name:"unresolved_links",type:"string[]",required:!1,constraint:"`[[links]]` in the new body that name no document yet."},{name:"remote_links",type:"string[]",required:!1,constraint:"`[[links]]` whose first segment is no owner on this runtime: on another runtime, or misspelled."}],outputKind:"object",effects:["Commits a new revision based on your last read and pushes the edit to the document's watchers."]},run:s(async e=>{const n=e.ref,i=typeof e.body=="string"&&e.body!==""?e.body:void 0;let a;if(typeof e.replace=="string"){if(i!==void 0)throw l("give a stdin body or --replace, not both",{field:"replace",next:"Drop one of them and rerun."});try{const r=JSON.parse(e.replace);if(!Array.isArray(r)||r.length===0||r.some(o=>typeof o!="object"||o===null||typeof o.old!="string"||typeof o.new!="string"))throw new Error;a=r}catch{throw l('--replace must be a non-empty JSON list of {"old": string, "new": string}',{field:"replace",next:"Fix the JSON and rerun."})}}const d=e.unset===void 0?[]:[].concat(e.unset),c={rationale:e.rationale,...i!==void 0?{body:i}:{},...a!==void 0?{replace:a}:{},...e.verbatim===!0?{verbatim:!0}:{},...p(e),...d.length>0?{unset:d}:{}};try{return{...await f().docs.edit(n,c)}}catch(r){w(r,n)}},"run"),render:s(e=>`<edited name="${String(e.name)}" revision=${String(e.revision)}>${b(e)}`,"render")});export{T as editLeaf};

package/dist/commands/doc/history.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const historyLeaf: LeafDef;

package/dist/commands/doc/history.js

@@ -0,0 +1,2 @@
+var s=Object.defineProperty;var i=(t,e)=>s(t,"name",{value:e,configurable:!0});import{defineLeaf as a}from"../../core/command.js";import{cliClient as d,rethrowAsCliError as f}from"../api-client.js";import{REF_CONSTRAINT as m}from"./shared.js";const y=a({name:"history",description:"list the revisions of a document",whenToUse:"you need how or why a document reached its current state, or who wrote it first",help:{name:"doc history",summary:"list the revisions of a document",params:[{kind:"positional",name:"ref",required:!0,constraint:m},{kind:"flag",name:"diff",type:"int",required:!1,constraint:"A revision number; adds that revision's body diff against the revision it was made from."}],output:[{name:"revisions",type:"object[]",required:!0,constraint:"Each {number, rev_id, author_id, rationale, verbatim, created_at, parents}; oldest first. The first revision's author wrote the document."},{name:"diff",type:"string",required:!1,constraint:"Present with --diff."}],outputKind:"object",effects:["None."]},run:i(async t=>{try{return{...await d().docs.history(t.ref,typeof t.diff=="number"?{diff:t.diff}:void 0)}}catch(e){f(e)}},"run"),render:i(t=>{const e=t,n=e.revisions.map(r=>`<revision number=${r.number} rev="${r.rev_id}" author="${r.author_id??"unknown"}" at="${r.created_at}"${r.verbatim?" verbatim":""}${r.parents.length>1?` merges="${r.parents.join(",")}"`:""}>${r.rationale??""}</revision>`),o=[`<history name="${e.object.name}" id="${e.object.id}">`,...n,"</history>"];return e.diff!==void 0&&o.push("","```diff",e.diff,"```"),o.join(`
+`)},"render")});export{y as historyLeaf};

package/dist/commands/doc/lint.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const lintLeaf: LeafDef;

package/dist/commands/doc/lint.js

@@ -0,0 +1,2 @@
+var o=Object.defineProperty;var t=(n,e)=>o(n,"name",{value:e,configurable:!0});import{defineLeaf as i}from"../../core/command.js";import{cliClient as s,rethrowAsCliError as a}from"../api-client.js";import{ownerFromInput as c}from"./shared.js";const p=i({name:"lint",description:"check documents for authoring problems",whenToUse:"checking the documents you can change for bodies too long for their delivery, badly shaped previews, or links to nothing",help:{name:"doc lint",summary:"check documents for authoring problems",guide:'Checks the documents you can change: body length against how the document is delivered; the "When \u2026, read this because \u2026" preview shape where a rule delivers at preview; `[[links]]` that name no document; more than one workspace-open content document per repo your profile manages. A document skips a check named in its lint-ignore field.',params:[{kind:"flag",name:"owner",type:"string",required:!1,constraint:"Check only this owner's documents: node | user | profile | profile:<name> | app | repo | repo:<handle>."}],output:[{name:"findings",type:"object[]",required:!0,constraint:"Each {name, severity, rule, message}; empty when clean."}],outputKind:"object",effects:["None."]},run:t(async n=>{try{return{...await s().docs.lint({...c(n),cwd:process.cwd()})}}catch(e){a(e)}},"run"),render:t(n=>{const{findings:e}=n;return e.length===0?"No findings.":e.map(r=>`<finding name="${r.name}" severity="${r.severity}" rule="${r.rule}">${r.message}</finding>`).join(`
+`)+"\nFix each with `crtr doc edit`, or add the rule to the document's lint-ignore field when it does not apply."},"render")});export{p as lintLeaf};

package/dist/commands/doc/list.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const listLeaf: LeafDef;

package/dist/commands/doc/list.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var t=(e,n)=>o(e,"name",{value:n,configurable:!0});import{defineLeaf as r}from"../../core/command.js";import{CrtrError as s}from"../../core/errors.js";const m=r({name:"list",description:"documents are listed with crtr canvas list --type document",whenToUse:"never; this path exists only to name the canvas command",tier:"hidden",help:{name:"doc list",summary:"documents are listed with crtr canvas list --type document",params:[],output:[],outputKind:"object",effects:["None."]},run:t(async()=>{throw new s("wrong_command","crtr doc list does not exist; documents are listed with crtr canvas list --type document")},"run")});export{m as listLeaf};

package/dist/commands/doc/move.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const moveLeaf: LeafDef;

package/dist/commands/doc/move.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var r=(e,n)=>i(e,"name",{value:n,configurable:!0});import{defineLeaf as a}from"../../core/command.js";import{usage as m}from"../../core/errors.js";import{cliClient as d,rethrowAsCliError as s}from"../api-client.js";import{REF_CONSTRAINT as w,ownerFromInput as u,ownerParam as c}from"./shared.js";const v=a({name:"move",description:"rename a document or give it a new owner",whenToUse:"a document belongs under another name, or must outlive its node under another owner",help:{name:"doc move",summary:"rename a document or give it a new owner",params:[{kind:"positional",name:"ref",required:!0,constraint:w},{kind:"positional",name:"new-name",required:!1,constraint:"New name under its owner. Give it, --owner, or both."},c("New owner.")],output:[{name:"name",type:"string",required:!0,constraint:"The new full name."},{name:"id",type:"string",required:!0,constraint:"Object id, unchanged."}],outputKind:"object",effects:["Renames or re-owns the document; its id stays, links to it keep pointing at it, and no document body is rewritten."]},run:r(async e=>{const n=e.newName,o=u(e);if(n===void 0&&o.owner===void 0)throw m("give a new name, --owner, or both",{next:"Rerun with the new name after the document, or with --owner."});try{return{...await d().docs.move(e.ref,{...n!==void 0?{new_name:n}:{},...o,cwd:process.cwd()})}}catch(t){s(t)}},"run"),render:r(e=>`<moved name="${String(e.name)}" id="${String(e.id)}">`,"render")});export{v as moveLeaf};

package/dist/commands/doc/read.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const readLeaf: LeafDef;

package/dist/commands/doc/read.js

@@ -0,0 +1 @@
+var t=Object.defineProperty;var e=(r,a)=>t(r,"name",{value:a,configurable:!0});import{defineLeaf as n}from"../../core/command.js";import{CrtrError as o}from"../../core/errors.js";const i=n({name:"read",description:"documents are read with crtr canvas read",whenToUse:"never; this path exists only to name the canvas command",tier:"hidden",help:{name:"doc read",summary:"documents are read with crtr canvas read",params:[{kind:"positional",name:"ref",required:!1,constraint:"Ignored; read documents with crtr canvas read."}],output:[],outputKind:"object",effects:["None."]},run:e(async()=>{throw new o("wrong_command","crtr doc read does not exist; documents are read with crtr canvas read <name>")},"run")});export{i as readLeaf};

package/dist/commands/doc/shared.d.ts

@@ -0,0 +1,25 @@
+import type { FlagParam } from '../../core/help.js';
+import type { DocOwnerFlag } from '../../api/dto/docs.js';
+export declare const REF_CONSTRAINT = "A document name (with or without [[ ]]) or a raw object id.";
+export declare const OWNER_VALUES = "node | user | profile | profile:<name> | app | repo | repo:<handle>";
+export declare function ownerParam(constraint: string): FlagParam;
+export declare function ruleParam(constraint: string): FlagParam;
+export declare const FIELD_FLAGS: {
+    preview: (constraint: string) => FlagParam;
+    kind: FlagParam;
+    summary: FlagParam;
+    privacy: (constraint: string) => FlagParam;
+    whyItExists: FlagParam;
+    unlisted: (constraint: string) => FlagParam;
+    lintIgnore: FlagParam;
+    extension: FlagParam;
+};
+/** Parse every field flag shared by write and edit; reports every bad value in one error. */
+export declare function fieldsFromInput(input: Record<string, unknown>): Record<string, unknown>;
+export declare function ownerFromInput(input: Record<string, unknown>): {
+    owner?: DocOwnerFlag;
+};
+/** Rethrow an API failure with the next step its code implies for `ref`. */
+export declare function rethrowDocError(err: unknown, ref: string): never;
+/** The link lines under a write or edit result. */
+export declare function renderLinkReport(r: Record<string, unknown>): string;

package/dist/commands/doc/shared.js

@@ -0,0 +1,2 @@
+var f=Object.defineProperty;var o=(e,t)=>f(e,"name",{value:t,configurable:!0});import{usage as m}from"../../core/errors.js";import{ApiError as w}from"../../api/errors.js";import{rethrowAsCliError as c}from"../api-client.js";import{RULE_ON as v,RULE_DELIVER as y,DOC_KINDS as g}from"../../api/dto/docs.js";import{PRIVACY_LEVELS_DTO as b}from"../../api/dto/objects.js";const O="A document name (with or without [[ ]]) or a raw object id.",p="node | user | profile | profile:<name> | app | repo | repo:<handle>";function j(e){return{kind:"flag",name:"owner",type:"string",required:!1,constraint:e,focusedHelp:{whenToUse:"Omit it for a document only this node and the nodes it points at need: the writing node owns it and it is deleted with the node, unless a kept document links to it. Give another owner when the document must outlive this node or reach other nodes by itself. A document worth another owner carries reusable current truth: a non-obvious procedure, a gotcha, a lasting preference, a convention across repos. Task notes, conversation summaries and facts the repo already records stay with the node or are not written. Before writing one, search for a document that already covers it (`crtr canvas search`) and revise that one with `crtr doc edit` instead of adding a near copy. When one document grows long, keep the most important content in it and move separate subjects into documents named under it (`topic/part`), each pointed at with a `[[link]]`. Choose the narrowest owner that still reaches the next agent who needs it.",value:`One of ${p}. \`node\` \u2014 the writing node; only this node loads it by rule, other nodes read it when pointed at it; deleted with the node. \`profile\` \u2014 the node's profile, or \`profile:<name>\`; loads for nodes running in that profile; stays on this runtime. \`app\` \u2014 the app that runs the node; kept until deleted; readable by that app's nodes. \`repo\` \u2014 the repo the node works in (from its working directory), or \`repo:<handle>\`; every clone and worktree of the repo shares it, and it syncs to collaborators over the repo's \`refs/crtr/docs\`. A repo owns only public documents: a private or friends document that should load in one repo is owned by \`user\` and carries a rule with \`if: {"repo": "<handle>"}\`. \`user\` \u2014 you, the person; loads for every node by its rules; readable by apps by privacy level. Default: the writing node; a person's own run (not a node) defaults to \`user\`. The owner becomes the start of the document's full name (\`<owner-handle>/<name>\`); \`crtr doc move --owner\` changes it later and keeps the id and every link.`,effects:["Decides who may read and change the document, where it syncs, and what deleting takes it with."]}}}o(j,"ownerParam");const k="`if` is a condition on the receiving node. Fields: `kind`, `mode`, `lifecycle`, `cwd`, `repo` (the handle of a repo the node works in), `profile`, `depth`. A field map is ANDed across fields; dotted fields resolve nested values. A scalar matches by equality (a list value matches when any element is equal); a list matcher matches by membership or overlap; an object matcher takes `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, `lte`. `all`, `any` and `not` combine conditions; field matchers beside them are ANDed in. An empty condition always matches; an unknown operator never matches. `match_frontmatter` uses the same language against the read file's YAML frontmatter.";function S(e){return{kind:"flag",name:"rule",type:"string",required:!1,repeatable:!0,constraint:e,focusedHelp:{whenToUse:"Omit it for most documents: a document with no rule is read when a node is pointed at it (`[[name]]`), finds it with `crtr canvas search`, or sees it in a listing. Add a rule only when the document must load on its own because of what a node is doing; every rule costs context in every node it fires on. Prefer the narrowest trigger: a `file-read` rule with a real glob over `boot` for knowledge about specific code; `boot` for knowledge about a person or process with no file boundary. When the whole document is one sentence, deliver `content` \u2014 a preview line would be longer than the document.",value:`One JSON object per occurrence: \`{"on": \u2026, "match"?: [globs], "match_frontmatter"?: {\u2026}, "if"?: {\u2026}, "deliver": \u2026}\`. \`on\` is the node's activity: ${v.join(" | ")}. \`boot\` \u2014 every session start of the node. \`workspace-open\` \u2014 the node's first message when it works in the document's repo. \`file-read\` \u2014 the node reads a file whose absolute path or basename matches a \`match\` glob, or whose frontmatter matches \`match_frontmatter\`. \`document-read\` \u2014 another document whose name matches is delivered at content, including an explicit read. \`command\` \u2014 a shell segment of a bash command matches (segments split on \`&&\`, \`||\`, \`;\`, \`|\` and newlines outside quotes, leading \`VAR=value\` dropped; \`*\` spans whole whitespace-separated tokens, \`?\` one character, quoted text is opaque). \`pre-command\` \u2014 as \`command\`, but runs before the command: when the node has not read the document, the command does not run and the document is returned instead; the node re-issues the command. \`slash-command\` \u2014 the document is a \`/<name>\` slash command whose body is the injected prompt. \`match\` is required on \`file-read\` (unless \`match_frontmatter\` is given), \`document-read\`, \`command\` and \`pre-command\`, and not allowed on \`boot\`, \`workspace-open\` and \`slash-command\`. `+k+` \`deliver\` is ${y.join(" | ")}: the bare name, the preview line, or the whole body. The flag set replaces the document's whole rule list; on \`crtr doc edit\`, \`--unset rules\` removes every rule.`,effects:["When several rules deliver one document to a node, the highest delivery wins: content over preview over name; content already in the node's context is not delivered again.","A document delivered at content is a read: it records the node as a watcher, so the node is pushed later edits.","The profile's delivery limit per owner caps what `boot` and `workspace-open` rules deliver for that owner.",'A rule that delivers at `preview` requires the preview in the shape "When <situation in the reader\'s work>, read this because <what the reader gains>"; `crtr doc lint` checks it. There the line alone decides whether a node that did not ask for the document opens it.']}}}o(S,"ruleParam");const N={preview:o(e=>({kind:"flag",name:"preview",type:"string",required:!1,constraint:e}),"preview"),kind:{kind:"flag",name:"kind",type:"enum",choices:[...g],required:!1,constraint:"knowledge is consulted for facts or procedures; preference directs behavior. Default knowledge."},summary:{kind:"flag",name:"summary",type:"string",required:!1,constraint:"A very short version of the content, shown in `crtr canvas list`."},privacy:o(e=>({kind:"flag",name:"privacy",type:"enum",choices:[...b],required:!1,constraint:e}),"privacy"),whyItExists:{kind:"flag",name:"why-it-exists",type:"string",required:!1,constraint:"The observed failure this document exists to prevent; shown only with `crtr canvas read --fields`."},unlisted:o(e=>({kind:"flag",name:"unlisted",type:"bool",required:!1,constraint:e}),"unlisted"),lintIgnore:{kind:"flag",name:"lint-ignore",type:"string",required:!1,repeatable:!0,constraint:"A `crtr doc lint` rule name to skip for this document."},extension:{kind:"flag",name:"extension",type:"string",required:!1,repeatable:!0,constraint:"One declared plugin field as `<plugin>.<field>=<json value>`."}};function h(e){return e===void 0?[]:Array.isArray(e)?e.map(String):[String(e)]}o(h,"list");function T(e){const t=[],n={};for(const[r,a]of[["preview","preview"],["kind","kind"],["summary","summary"],["privacy","privacy"],["why-it-exists","why_it_exists"]])typeof e[r]=="string"&&(n[a]=e[r]);typeof n.preview=="string"&&/[\r\n]/.test(n.preview)&&t.push("--preview must be one line"),e.unlisted===!0&&(n.unlisted=!0);const s=h(e["lint-ignore"]);s.length>0&&(n.lint_ignore=s);const i=h(e.rule);if(i.length>0){const r=[];i.forEach((a,u)=>{try{const d=JSON.parse(a);typeof d!="object"||d===null||Array.isArray(d)?t.push(`--rule #${u+1} must be a JSON object`):r.push(d)}catch{t.push(`--rule #${u+1} is not valid JSON: ${a}`)}}),n.rules=r}const l={};for(const r of h(e.extension)){const a=/^([^.=]+)\.([^=]+)=(.*)$/s.exec(r);if(!a){t.push(`--extension ${r} is not <plugin>.<field>=<json value>`);continue}try{(l[a[1]]??={})[a[2]]=JSON.parse(a[3])}catch{t.push(`--extension ${r}: the value after = is not valid JSON`)}}if(Object.keys(l).length>0&&(n.extensions=l),t.length>0)throw m(t.join("; "),{next:"Fix every value above and rerun; `--rule -h` gives the rule grammar."});return n}o(T,"fieldsFromInput");function D(e){const t=e.owner;if(t===void 0)return{};const n=String(t);if(!/^(node|user|profile|app|repo)$|^(profile|repo):.+$/.test(n))throw m(`invalid --owner ${n}`,{field:"owner",next:`Pass one of ${p}.`});return{owner:n}}o(D,"ownerFromInput");function R(e,t){e instanceof w&&(e.code==="read_first"&&c(e,`Read it first with \`crtr canvas read ${t}\`, then rerun the edit.`),e.code==="stale_revision"&&c(e,`Someone edited it after your read. Read it again with \`crtr canvas read ${t}\`, make your change on the current text, and rerun the edit.`)),c(e)}o(R,"rethrowDocError");function I(e){const t=[],n=e.unresolved_links,s=e.remote_links;return n?.length&&t.push(`Unresolved links (no document by these names yet): ${n.map(i=>`[[${i}]]`).join(", ")}`),s?.length&&t.push(`Not on this runtime: ${s.map(i=>`[[${i}]]`).join(", ")} \u2014 each may be on another runtime, or the name may be misspelled.`),t.map(i=>`
+${i}`).join("")}o(I,"renderLinkReport");export{N as FIELD_FLAGS,p as OWNER_VALUES,O as REF_CONSTRAINT,T as fieldsFromInput,D as ownerFromInput,j as ownerParam,I as renderLinkReport,R as rethrowDocError,S as ruleParam};

package/dist/commands/doc/write.d.ts

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../../core/command.js';
+export declare const writeLeaf: LeafDef;

package/dist/commands/doc/write.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var r=(e,n)=>o(e,"name",{value:n,configurable:!0});import{defineLeaf as a}from"../../core/command.js";import{cliClient as s,rethrowAsCliError as d}from"../api-client.js";import{FIELD_FLAGS as t,fieldsFromInput as m,ownerFromInput as u,ownerParam as l,renderLinkReport as c,ruleParam as h}from"./shared.js";const b=a({name:"write",description:"write a new document from a stdin body",whenToUse:"a spec, plan, map, finding, knowledge or preference should exist as a document other nodes can read; creation only \u2014 revise an existing one with `crtr doc edit`",help:{name:"doc write",summary:"write a new document from a stdin body",guide:"Most documents need only a name, a preview and a body: the writing node owns it, it has no delivery rules, and other nodes read it when pointed at it as `[[<name printed below>]]`. Give --owner or --rule only when the document must outlive this node or load on its own; each has focused help. Read, list and search documents with `crtr canvas read|list|search`.",params:[{kind:"positional",name:"name",required:!0,constraint:"Name under its owner: segments of letters, digits, `_` and `-`, joined by `/`. Must be free under that owner."},{kind:"stdin",name:"body",required:!0,constraint:"Document body (markdown), piped on stdin and saved byte for byte."},{...t.preview("One line shown wherever the document is listed or delivered without its body, telling a reader whether to open it."),required:!0},t.kind,t.summary,t.privacy("Who beyond the owner may read it; default public. A repo-owned document must be public."),l("Whose document it is; default the writing node."),h("A delivery rule that loads the document into nodes by their activity."),t.whyItExists,t.unlisted("Keep it out of listings; reads, links and rules still work."),t.lintIgnore,t.extension],output:[{name:"name",type:"string",required:!0,constraint:"Full name, `<owner-handle>/<name>`; point at it as `[[name]]`."},{name:"id",type:"string",required:!0,constraint:"Object id."},{name:"unresolved_links",type:"string[]",required:!1,constraint:"`[[links]]` in the body that name no document yet; absent when every link resolves."},{name:"remote_links",type:"string[]",required:!1,constraint:"`[[links]]` whose first segment is no owner on this runtime: on another runtime, or misspelled."}],outputKind:"object",effects:["Creates the document at revision 1 and makes the writer a watcher, so it is pushed later edits."]},run:r(async e=>{const n={name:e.name,body:e.body,...m(e),...u(e),cwd:process.cwd()};try{return{...await s().docs.write(n)}}catch(i){d(i)}},"run"),render:r(e=>`<written name="${String(e.name)}" id="${String(e.id)}">${c(e)}`,"render")});export{b as writeLeaf};

package/dist/commands/{memory.d.ts → doc.d.ts}

@@ -1,2 +1,2 @@
 import type { BranchDef } from '../core/command.js';
-export declare function registerMemory(): BranchDef;
+export declare function registerDoc(): BranchDef;

package/dist/commands/doc.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var e=(r,t)=>o(r,"name",{value:t,configurable:!0});import{defineBranch as n}from"../core/command.js";import{writeLeaf as a}from"./doc/write.js";import{editLeaf as i}from"./doc/edit.js";import{moveLeaf as m}from"./doc/move.js";import{historyLeaf as d}from"./doc/history.js";import{deleteLeaf as c}from"./doc/delete.js";import{lintLeaf as s}from"./doc/lint.js";import{readLeaf as f}from"./doc/read.js";import{listLeaf as p}from"./doc/list.js";function A(){return n({name:"doc",rootEntry:{concept:"a document \u2014 markdown written for readers: knowledge, preferences, specs, plans, maps",desc:"write, edit, move, delete and lint documents",useWhen:"writing or revising a document; read, list and search documents with `crtr canvas`"},help:{name:"doc",summary:"write, edit, move, delete and lint documents",model:"Reading, listing and searching documents are `crtr canvas read`, `crtr canvas list --type document` and `crtr canvas search`. A document is pointed at as `[[name]]`."},children:[a,i,m,d,c,s,f,p]})}e(A,"registerDoc");export{A as registerDoc};