@crouton-kit/crouter 0.3.20 → 0.3.21

package/dist/core/substrate/render.js

@@ -5,8 +5,7 @@
 //     (renderPreferencesSection) — strings the D2 `before_agent_start` extension
 //     splices into the system prompt (built by a sibling AFTER this module);
 //   • the `<crtr-context>` half — `## References` (renderReferencesBlock) — the
-//     string wired into bearings.ts's session_start message, REPLACING the old
-//     `<memory>` block.
+//     string wired into bearings.ts's session_start message.
 //
 // Every doc flows through the same pipeline (design §4/§6/§9):
 //   MemoryDoc → parseSubstrateDoc → (null-filter non-substrate) →
@@ -54,10 +53,9 @@ function resolverDocs(subject, kind) {
  *  canvas home (`nodes/<id>/context/memory/`) and is OUTSIDE the scope resolver,
  *  so it is loaded directly here, its raw frontmatter run through
  *  parseSubstrateFrontmatter (mirroring the resolver pipeline), then gate-passed.
- *  Old-format / non-substrate files (incl. the MEMORY.md index, which has no
- *  `kind`) parse to null and drop out. Returned across ALL kinds — node-local is
- *  the catch-all this-node store and rides into the references block as the
- *  replacement for the old node-local `<memory>` stanza.
+ *  Non-substrate files (those with no `kind`) parse to null and drop out.
+ *  Returned across ALL kinds — node-local is the catch-all this-node store and
+ *  rides into the references block.
  *
  *  IMPORTANT: node-local docs are NOT filtered by `systemPromptVisibility` rung.
  *  A migrated node-local reference defaults to rung `none`, which would make it
@@ -122,8 +120,8 @@ function renderSubSection(d) {
  *  resolver-provided, NOT migrated — named-plugin skills at user/project scope;
  *  the SCOPE_SKILL_PLUGIN sentinel and builtin scope are EXCLUDED because they
  *  become substrate docs). Reuses skill/shared.ts's renderCatalogSection
- *  group-collapse so the boot catalog matches today's `<skills count=N>` shape.
- *  Returns '' when nothing is in the catalog. */
+ *  group-collapse for a compact, source-grouped catalog. Returns '' when nothing
+ *  is in the catalog. */
 function renderSkillCatalog(nameRungSkillDocs) {
     let pluginSkills;
     try {
@@ -138,8 +136,8 @@ function renderSkillCatalog(nameRungSkillDocs) {
     ];
     if (entries.length === 0)
         return '';
-    // Group by scope+plugin → forest-root names (drop nested children), mirroring
-    // buildSkillCatalog's source construction.
+    // Group by scope+plugin → forest-root names (drop nested children) so each
+    // source contributes only its top-level skills.
     const bySource = new Map();
     for (const e of entries) {
         const key = `${e.scope}\t${e.plugin}`;
@@ -225,8 +223,7 @@ export function renderPreferencesSection(nodeId) {
  *  drops it when ''). Holds every eligible `kind: reference` resolver doc at its
  *  `system-prompt-visibility` (reference boot default is `none`, so only
  *  author-promoted references show) PLUS the node-local memory docs (any kind),
- *  each a `###` sub-section. Replaces the old `<memory>` block. Returns '' when
- *  nothing is eligible.
+ *  each a `###` sub-section. Returns '' when nothing is eligible.
  *
  *  DEFENSIVE: each doc is rendered in its own try/catch so a single malformed
  *  doc drops only itself (with a loud stderr warning naming the offending path),

package/dist/core/substrate/schema.d.ts

@@ -21,15 +21,17 @@ export declare const KIND_DEFAULT_RUNGS: Record<DocKind, {
  *  `all`/`any`/`not` combinators (design §4). */
 export type GatePredicate = Record<string, unknown>;
 /** The frontmatter-derived schema of a substrate document, with kind-aware
- *  defaults applied. Required fields (`kind`/`when`/`why`) and optionals all
- *  resolved to concrete typed values. */
+ *  defaults applied. Required fields (`kind`/`when-and-why-to-read`) and
+ *  optionals all resolved to concrete typed values. */
 export interface SubstrateSchema {
     /** Which of the three semantic kinds. */
     kind: DocKind;
-    /** Routing condition — "When you are in a situation like X…" (design §4). */
-    when: string;
-    /** Payoff — "…because Z." Half of the generated preview line. */
-    why: string;
+    /** The read-routing line — a single sentence answering WHEN to read this doc
+     *  and WHY it is worth the read: "When <circumstance>, this <kind> should be
+     *  read <because <payoff>>." (design §4). This is read-routing — why an agent
+     *  should spend the read — NEVER justification of why the content should be
+     *  obeyed. It IS the preview verbatim. Frontmatter key `when-and-why-to-read`. */
+    whenAndWhyToRead: string;
     /** Human-facing abbreviation for `crtr memory list`. NEVER loaded into an
      *  agent's context (design §3). Empty string when absent. */
     shortForm: string;
@@ -62,15 +64,18 @@ export interface SubstrateDoc extends SubstrateSchema {
  *  resolver) into a typed schema with defaults applied. Returns `null` when the
  *  record is absent or carries no valid `kind` — i.e. it is not a substrate
  *  document and cannot be classified or defaulted. Tolerant of every other
- *  imperfection (missing `when`/`why` default to '', a bad rung falls back to
- *  the kind default), so a renderer mapping over many docs never throws. */
+ *  imperfection (a missing `when-and-why-to-read` defaults to '', a bad rung
+ *  falls back to the kind default), so a renderer mapping over many docs never
+ *  throws. Authoring-time enforcement of the field lives in `crtr memory lint`. */
 export declare function parseSubstrateFrontmatter(fm: Record<string, unknown> | null): SubstrateSchema | null;
 /** Parse a resolved MemoryDoc into a fully-typed SubstrateDoc (schema + the
  *  resolver's name/scope/path/body). Returns `null` for a non-substrate doc
  *  (no valid `kind`), so callers can `docs.map(parseSubstrateDoc).filter(...)`. */
 export declare function parseSubstrateDoc(doc: MemoryDoc): SubstrateDoc | null;
-/** The generated `preview`-rung routing line (design §4), composed from the two
- *  required prose fields and the kind: `"{when}, read this {kind}. {why}."`.
- *  Both boot and on-read render render this identical line, so it lives once
- *  here to prevent drift. Light cleanup avoids doubled punctuation. */
-export declare function previewLine(doc: Pick<SubstrateSchema, 'kind' | 'when' | 'why'>): string;
+/** The `preview`-rung routing line (design §4): the `when-and-why-to-read`
+ *  field rendered essentially verbatim — it is already authored as the complete
+ *  routing sentence ("When …, this <kind> should be read …"), so there is no
+ *  template to compose. Both boot and on-read render this identical line, so it
+ *  lives once here to prevent drift. Light cleanup normalizes the trailing
+ *  period. */
+export declare function previewLine(doc: Pick<SubstrateSchema, 'whenAndWhyToRead'>): string;

package/dist/core/substrate/schema.js

@@ -50,8 +50,9 @@ export const KIND_DEFAULT_RUNGS = {
  *  resolver) into a typed schema with defaults applied. Returns `null` when the
  *  record is absent or carries no valid `kind` — i.e. it is not a substrate
  *  document and cannot be classified or defaulted. Tolerant of every other
- *  imperfection (missing `when`/`why` default to '', a bad rung falls back to
- *  the kind default), so a renderer mapping over many docs never throws. */
+ *  imperfection (a missing `when-and-why-to-read` defaults to '', a bad rung
+ *  falls back to the kind default), so a renderer mapping over many docs never
+ *  throws. Authoring-time enforcement of the field lives in `crtr memory lint`. */
 export function parseSubstrateFrontmatter(fm) {
     if (fm === null)
         return null;
@@ -61,8 +62,7 @@ export function parseSubstrateFrontmatter(fm) {
     const defaults = KIND_DEFAULT_RUNGS[kind];
     return {
         kind,
-        when: strField(fm.when),
-        why: strField(fm.why),
+        whenAndWhyToRead: strField(fm['when-and-why-to-read']),
         shortForm: strField(fm['short-form']),
         systemPromptVisibility: parseRung(fm['system-prompt-visibility'], defaults.systemPrompt),
         fileReadVisibility: parseRung(fm['file-read-visibility'], defaults.fileRead),
@@ -79,14 +79,15 @@ export function parseSubstrateDoc(doc) {
         return null;
     return { ...schema, name: doc.name, scope: doc.scope, path: doc.path, body: doc.body };
 }
-/** The generated `preview`-rung routing line (design §4), composed from the two
- *  required prose fields and the kind: `"{when}, read this {kind}. {why}."`.
- *  Both boot and on-read render render this identical line, so it lives once
- *  here to prevent drift. Light cleanup avoids doubled punctuation. */
+/** The `preview`-rung routing line (design §4): the `when-and-why-to-read`
+ *  field rendered essentially verbatim — it is already authored as the complete
+ *  routing sentence ("When …, this <kind> should be read …"), so there is no
+ *  template to compose. Both boot and on-read render this identical line, so it
+ *  lives once here to prevent drift. Light cleanup normalizes the trailing
+ *  period. */
 export function previewLine(doc) {
-    const when = doc.when.trim().replace(/[.,]+$/, '');
-    const why = doc.why.trim().replace(/\.+$/, '');
-    return `${when}, read this ${doc.kind}. ${why}.`;
+    const line = doc.whenAndWhyToRead.trim().replace(/\.+$/, '');
+    return line === '' ? '' : `${line}.`;
 }
 // ---------------------------------------------------------------------------
 // Field coercion helpers (private).

package/dist/pi-extensions/canvas-context-intro.js

@@ -15,9 +15,11 @@
 //
 // The block carries: the path to the node's own context dir and the framing for
 // what belongs there (a shared document store for the other nodes). EVERY node
-// also gets a <memory> block merging the indexes of its three scoped memory
-// stores (user-global, project, node-local), each labeled with its dir — one
-// consistent surface, since every node is born with all three stores. An
+// also gets a `## References` block rendered from the document substrate —
+// eligible `reference` docs at their system-prompt visibility rung, plus the
+// node's own node-local substrate docs — so the bearings name what to read on
+// demand. (Skills and preferences surface as their own `## Skills` /
+// `## Preferences` sections of the system prompt, not in this block.) An
 // orchestrator additionally gets the across-refresh-cycles framing (the one
 // thing a terminal worker's bearings drop). The prose lives in
 // core/runtime/bearings.ts (shared with the promotion guidance dump).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.20",
+  "version": "0.3.21",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",