pi-canon 0.2.4 → 0.3.1

package/extensions/lib/tool.ts

@@ -1,9 +1,10 @@
-/* The pi_canon tool: one tool, five verbs. Read and update over create; the journal
+/* The canon tool: one tool, five verbs. Read and update over create; the journal
    for events; map to orient; search when the agent asks. */
 
 import { existsSync } from "node:fs";
 import { basename, join } from "node:path";
-import { advise, unretained } from "./lint.ts";
+import { advise, orphaned, unretained } from "./lint.ts";
+import { checkArticle, loadSchema, outgoingOf, READ_ONLY, SCHEMA_FILE } from "./schema.ts";
 import { contained, normalize, type CanonStore } from "./store.ts";
 import { type Candidate, LexicalRetriever, RULE_SCOPE } from "./retrieval.ts";
 import type { Mount, Surfacer } from "./surfacing.ts";
@@ -33,6 +34,13 @@ export const CANON_TOOL_PARAMETERS = {
     },
     capsule: { type: "string", description: "write: one dense line injected when the asset is touched." },
     query: { type: "string", description: "search: words to look for, across articles and the journal." },
+    journal: {
+      type: "boolean",
+      description:
+        "search: true to include journal entries in the results. Off by default because " +
+        "events are history, not current truth; the result names how many entries matched " +
+        "so you can opt in when the history is the point.",
+    },
     scope: {
       type: "string",
       enum: ["rule", "asset"],
@@ -99,8 +107,8 @@ function settle(mount: Mount, raw: string, cwd: string): string {
 
 export function buildCanonTool(ready: (ctx: unknown) => CanonRuntime, retrieval = "none") {
   return {
-    name: "pi_canon",
-    label: "pi-canon",
+    name: "canon",
+    label: "canon",
     description: canonToolDescription(retrieval),
     parameters: CANON_TOOL_PARAMETERS,
     async execute(
@@ -156,10 +164,19 @@ function filingTail(retrieval: string): string {
    named. Neither is decoration.
 
    Ranking reuses LexicalRetriever rather than growing a second notion of relevance, so search
-   and recommendation cannot drift apart. */
+   and recommendation cannot drift apart.
+
+   The journal is opt-in (Shane, 2026-08-20): events are history, not current truth,
+   and R1 measured what including them by default cost, journal entries about an
+   event crowding out the article that carries its current truth for 8 to 20 points
+   of governing-article recall at realistic query lengths. Default search ranks
+   articles alone, never reads a journal body, and says the journal exists; with
+   journal true the window is split, articles up to half, journal the rest,
+   whichever side runs short ceding its slots. Current truth first, always. */
 const SEARCH_RESULTS = 10;
+const ARTICLE_SLOTS = 5;
 
-function search(store: CanonStore, query: string): string {
+function search(store: CanonStore, query: string, includeJournal: boolean): string {
   if (!query.trim()) return "search needs a query.";
   const articles: Candidate[] = [];
   for (const path of store.list()) {
@@ -175,20 +192,26 @@ function search(store: CanonStore, query: string): string {
     }
   }
   /* Journal entries enter the same index under a `journal/` key so one ranking covers both.
-     The key is an index handle, never an address: it is not something `read` accepts. */
-  const entries = store.journalEntries();
+     The key is an index handle, never an address: it is not something `read` accepts.
+     Built only on opt-in, so a default search never pays for reading every entry body. */
   const byKey = new Map<string, { logged: string; subjects: string[]; body: string }>();
-  const journal: Candidate[] = entries.map((entry) => {
-    const key = `journal/${entry.name.replace(/\.md$/, "")}`;
-    byKey.set(key, entry);
-    return {
-      path: key,
-      capsule: entry.subjects.join(", "),
-      body: entry.body,
-      updated: entry.logged,
-      declared: false,
-    };
-  });
+  const journal: Candidate[] = !includeJournal
+    ? []
+    : store.journalEntries().map((entry) => {
+        const key = `journal/${entry.name.replace(/\.md$/, "")}`;
+        byKey.set(key, entry);
+        return {
+          path: key,
+          capsule: entry.subjects.join(", "),
+          body: entry.body,
+          updated: entry.logged,
+          declared: false,
+        };
+      });
+  const invitation =
+    !includeJournal && store.journalCount() > 0
+      ? "The journal was not searched; pass journal true to search events too."
+      : "";
 
   const all = [...articles, ...journal];
   if (!all.length) return "Nothing in the canon yet.";
@@ -196,9 +219,18 @@ function search(store: CanonStore, query: string): string {
   retriever.index(all);
   const scored = retriever.score(query, all);
   const ranked = [...scored.entries()].sort((a, b) => b[1] - a[1]);
-  if (!ranked.length) return `Nothing matches "${query}".`;
+  if (!ranked.length) return [`Nothing matches "${query}".`, invitation].filter(Boolean).join(" ");
+
+  const articleRanked = ranked.filter(([key]) => !byKey.has(key));
+  const journalRanked = ranked.filter(([key]) => byKey.has(key));
+  const articleQuota = Math.min(
+    articleRanked.length,
+    Math.max(ARTICLE_SLOTS, SEARCH_RESULTS - journalRanked.length),
+  );
+  const journalQuota = Math.min(journalRanked.length, SEARCH_RESULTS - articleQuota);
+  const chosen = [...articleRanked.slice(0, articleQuota), ...journalRanked.slice(0, journalQuota)];
 
-  const lines = ranked.slice(0, SEARCH_RESULTS).map(([key]) => {
+  const lines = chosen.map(([key]) => {
     const entry = byKey.get(key);
     if (entry) {
       const subjects = entry.subjects.length ? ` (${entry.subjects.join(", ")})` : "";
@@ -208,9 +240,10 @@ function search(store: CanonStore, query: string): string {
     return `${key}: ${article?.capsule || excerpt(article?.body ?? "")}`;
   });
   /* Say what was dropped. A silent cap reads as "that is everything". */
-  if (ranked.length > SEARCH_RESULTS) {
-    lines.push(`... ${ranked.length - SEARCH_RESULTS} more matched; narrow the query to see them.`);
+  if (ranked.length > chosen.length) {
+    lines.push(`... ${ranked.length - chosen.length} more matched; narrow the query to see them.`);
   }
+  if (invitation) lines.push(invitation);
   return lines.join("\n");
 }
 
@@ -253,7 +286,18 @@ export function runCanon(runtime: CanonRuntime, params: Record<string, unknown>)
       const index = recent.length
         ? `\n\njournal: ${recent.join(", ")}${earlier ? ` and ${earlier} earlier` : ""}`
         : "";
-      return `${title}\n${head}\n\n${article.body}`.trim() + index;
+      /* Reads never reject, but they do report: an agent holding a noncompliant
+         article is the one agent positioned to heal it, and silence here is how a
+         store drifts out of its own contract one read at a time. */
+      const { schema, problems } = loadSchema(store.root);
+      const standing = schema ? checkArticle(article, schema, READ_ONLY) : { rejections: [], warnings: [] };
+      const issues = [...standing.warnings, ...problems];
+      const report = issues.length
+        ? `\n\nschema (${SCHEMA_FILE}): ${issues.join(" ")} This article can be healed with a write.`
+        : "";
+      const missing = orphaned(mount.dir, article);
+      const orphan = missing ? `\n\n${missing}` : "";
+      return `${title}\n${head}\n\n${article.body}`.trim() + index + report + orphan;
     }
     case "write": {
       if (!path) return "write needs a path.";
@@ -266,7 +310,7 @@ export function runCanon(runtime: CanonRuntime, params: Record<string, unknown>)
          prior state; which fields this call happened to set is a separate question and is
          answered separately below. */
       const prior = store.read(path);
-      const article = store.write(path, {
+      const fields = {
         capsule: params.capsule ? String(params.capsule) : undefined,
         body: params.body ? String(params.body) : undefined,
         /* "asset" is the way back. The enum is the only vocabulary the model has, so
@@ -274,16 +318,93 @@ export function runCanon(runtime: CanonRuntime, params: Record<string, unknown>)
            one: every other input falls through to undefined, which means untouched. It
            stores empty, which is the default state, the address being the claim. */
         scope: params.scope === "asset" ? "" : params.scope ? String(params.scope) : undefined,
-      });
+      };
+      /* The store's declared contract, held against the article this write WOULD
+         store, before anything touches disk. Only a required rule the write itself
+         touched (or a brand new article) rejects; everything else warns, so the write
+         still lands and the agent still learns. */
+      const { schema, problems } = loadSchema(store.root);
+      const composed = store.compose(path, fields);
+      const verdict = schema
+        ? checkArticle(composed, schema, {
+            capsule: fields.capsule !== undefined,
+            body: fields.body !== undefined,
+            /* Touched means the reference SET changed, not that a body was sent: a
+               body edit that keeps its citations must not re-litigate them. */
+            refs: outgoingOf(prior ? prior.body : "").join("\n") !== outgoingOf(composed.body).join("\n"),
+            created: !prior,
+          })
+        : { rejections: [], warnings: [] };
+      if (verdict.rejections.length) {
+        return [
+          `Write rejected by this store's ${SCHEMA_FILE}:`,
+          ...verdict.rejections.map((line) => `- ${line}`),
+          "Nothing was written. Fix the listed fields and write again.",
+        ].join("\n");
+      }
+      /* A write that changes nothing is a restatement, not a change. Measured (W1j):
+         restating the current state through the write path was the one store
+         corruption no content rule could catch, because no field differs; the only
+         thing it changed was the freshness stamp, which then lied. So equality is
+         checked here, mechanically, and `updated` keeps meaning what it says. */
+      if (
+        prior &&
+        composed.capsule === prior.capsule &&
+        composed.scope === prior.scope &&
+        composed.body.trimEnd() === prior.body.trimEnd()
+      ) {
+        surfacer.markUpdated(
+          qualify(composed.path),
+          [params.capsule, params.body].filter(Boolean).map(String).join("\n"),
+        );
+        return [
+          `${qualify(composed.path)} is already current: this write matches the stored article, ` +
+            `so nothing was rewritten and updated stays ${prior.updated}.`,
+          ...verdict.warnings.map((line) => `schema: ${line}`),
+          ...problems,
+        ].join("\n");
+      }
+      const article = store.write(path, fields);
+      /* When a rewrite grows the body, the result says so and restates the split.
+         Measured over three captures, two arms each, on byte-identical
+         eight-session lineages: writers narrate history into articles until the
+         store outgrows the raw transcripts it distills, and prompt-side guidance
+         does not change the habit. The arm that got this line ended with fewer
+         standing superseded values in all three, 51 and 45 and 71 of 96 against
+         88 and 87 and 85. Take the DIRECTION and not the size. The third capture
+         counterbalanced the arm order and kept the direction while losing most of
+         the magnitude, and re-running a matched untreated cell moved its median
+         store 39 percent, so this instrument does not measure its own magnitudes
+         reliably. Two readers in 96 sessions were harmed by a stale value, one
+         from each arm, so this line is not known to protect readers. It is also
+         not one exposure: it fired after 117, 99, and 126 of that arm's 198, 184,
+         and 207 writes. Any growth fires; that exact behavior is what was
+         measured. Creation is not growth, and a capsule-only write never grows
+         the stored body. */
+      const priorBytes = prior ? Buffer.byteLength(prior.body.trimEnd()) : null;
+      const nextBytes = Buffer.byteLength(composed.body.trimEnd());
+      const growth =
+        priorBytes !== null && nextBytes > priorBytes
+          ? [
+              `Body grew ${priorBytes} -> ${nextBytes} bytes. An article carries current ` +
+                `state; if this growth is narrated history (old values, transitions), move ` +
+                `it to the journal and keep the article at what is true now.`,
+            ]
+          : [];
       /* What this write put in the window, which is what the agent supplied, not the
          merged article: a capsule-only write does not deliver the stored body. */
       surfacer.markUpdated(
         qualify(article.path),
         [params.capsule, params.body].filter(Boolean).map(String).join("\n"),
       );
+      const missingAsset = orphaned(mount.dir, article);
       return [
         `Wrote ${qualify(article.path)}.`,
-        ...advise(article, store, prior?.body, { dir: mount.dir, retrieval: runtime.retrieval }),
+        ...growth,
+        ...verdict.warnings.map((line) => `schema: ${line}`),
+        ...problems,
+        ...advise(article, store, prior?.body, { dir: mount.dir, retrieval: runtime.retrieval }, schema),
+        ...(missingAsset ? [missingAsset] : []),
       ].join("\n");
     }
     case "journal": {
@@ -330,7 +451,7 @@ export function runCanon(runtime: CanonRuntime, params: Record<string, unknown>)
     case "map":
       return store.map(path);
     case "search":
-      return search(store, String(params.query ?? ""));
+      return search(store, String(params.query ?? ""), params.journal === true);
     default:
       return `Unknown action "${action}". Actions: read, write, journal, map, search.`;
   }

package/extensions/settings.ts

@@ -0,0 +1,328 @@
+/* /canon-settings: user-facing configuration for the behavior options that are
+   otherwise code. The storage stays exactly what registerPiCanon accepts; this
+   module only changes the experience: one validation path, an in-TUI editor over
+   a JSON file, and every state that reaches disk already passed validation.
+
+   root and mounts deliberately have no row here: they are per-project topology,
+   and a global file overriding them would be wrong. The editor carries the four
+   behavior options a user might legitimately flip session to session.
+
+   The editor is built from pi-tui's own SettingsList and Input so it looks and
+   behaves like Pi's native /settings screen, and ALL key handling goes through
+   matchesKey: raw byte matching freezes on terminals in application cursor mode,
+   where arrows arrive as SS3 rather than CSI.
+
+   This file must stay loadable by PLAIN NODE (the entry-point gate imports it
+   without jiti), so it uses none of the TypeScript that requires a transform:
+   no parameter properties and no accessibility modifiers, only erasable
+   annotations. */
+
+import { homedir } from "node:os";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Container, Input, Key, matchesKey, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
+
+export const DEFAULT_CANON_SETTINGS_PATH = join(
+  homedir(),
+  ".config",
+  "pi-canon",
+  "settings.json",
+);
+
+export interface CanonUserSettings {
+  surface?: boolean;
+  resurface?: boolean;
+  retrieval?: "none" | "lexical";
+  standout?: number;
+}
+
+const SETTING_IDS = ["surface", "resurface", "retrieval", "standout"] as const;
+export type CanonSettingId = (typeof SETTING_IDS)[number];
+
+const RETRIEVAL_CHOICES = ["none", "lexical"];
+/* The standout lattice, stepped by left/right and clamped at the ends. 1 is no
+   cutoff; the default 1.4 is the operating point the 120-cell study priced. */
+const STANDOUT_LATTICE = [1, 1.2, 1.4, 1.6, 1.8, 2, 2.5, 3];
+
+export function applyCanonSettingsEdit(
+  draft: CanonUserSettings,
+  id: CanonSettingId,
+  rawValue: string,
+): { ok: true; draft: CanonUserSettings } | { ok: false; error: string } {
+  const text = rawValue.trim();
+  if (id === "surface" || id === "resurface") {
+    if (text !== "on" && text !== "off") {
+      return { ok: false, error: `${id} must be on or off` };
+    }
+    return { ok: true, draft: { ...draft, [id]: text === "on" } };
+  }
+  if (id === "retrieval") {
+    if (!RETRIEVAL_CHOICES.includes(text)) {
+      return { ok: false, error: 'retrieval must be "none" or "lexical"' };
+    }
+    return { ok: true, draft: { ...draft, retrieval: text as "none" | "lexical" } };
+  }
+  const value = Number(text);
+  if (!Number.isFinite(value) || value < 1) {
+    return { ok: false, error: "standout must be a number of at least 1 (1 is no cutoff)" };
+  }
+  return { ok: true, draft: { ...draft, standout: value } };
+}
+
+export function loadCanonSettingsFile(path: string = DEFAULT_CANON_SETTINGS_PATH): CanonUserSettings {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error: any) {
+    if (error?.code === "ENOENT") return {};
+    throw error;
+  }
+  const parsed = JSON.parse(raw) as Record<string, unknown>;
+  for (const key of Object.keys(parsed)) {
+    if (!SETTING_IDS.includes(key as CanonSettingId)) {
+      throw new Error(`canon settings file has no ${key} field: the surface is surface, resurface, retrieval, standout`);
+    }
+  }
+  let draft: CanonUserSettings = {};
+  for (const id of SETTING_IDS) {
+    if (parsed[id] === undefined) continue;
+    const raw =
+      typeof parsed[id] === "boolean" ? (parsed[id] ? "on" : "off") : String(parsed[id]);
+    const result = applyCanonSettingsEdit(draft, id, raw);
+    if (!result.ok) throw new Error(result.error);
+    draft = result.draft;
+  }
+  return draft;
+}
+
+export function saveCanonSettingsFile(path: string, settings: CanonUserSettings): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(settings, null, 2)}\n`);
+  renameSync(temporary, path);
+}
+
+interface EditorRow {
+  id: CanonSettingId;
+  label: string;
+  description: string;
+}
+
+const EDITOR_ROWS: readonly EditorRow[] = [
+  { id: "surface", label: "Surfacing on touch", description: "Govern articles surface as tool calls touch their assets" },
+  { id: "resurface", label: "Resurface after folding", description: "A surfaced article surfaces again once it leaves the context window" },
+  { id: "retrieval", label: "Retrieval ranking", description: "How off-spine articles are ranked against what the agent is doing" },
+  { id: "standout", label: "Standout cutoff", description: "How far the best rank must stand out before it rides; ignored while retrieval is none" },
+];
+
+function rowRawValue(settings: CanonUserSettings, id: CanonSettingId): string {
+  if (id === "surface" || id === "resurface") return settings[id] === false ? "off" : "on";
+  if (id === "retrieval") return settings.retrieval ?? "none";
+  return String(settings.standout ?? 1.4);
+}
+
+function rowDisplayValue(settings: CanonUserSettings, id: CanonSettingId): string {
+  const raw = rowRawValue(settings, id);
+  if (id === "standout" && (settings.retrieval ?? "none") === "none") return `${raw} (unused)`;
+  return raw;
+}
+
+// The frame Pi's own /settings screen draws around its list. Implemented locally
+// rather than imported because jiti keeps a separate module cache: the border's
+// default color closure would bind to a different theme instance than the one the
+// editor receives, so the color always arrives explicitly.
+class SettingsBorder {
+  color: (text: string) => string;
+
+  constructor(color: (text: string) => string) {
+    this.color = color;
+  }
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    return [this.color("─".repeat(Math.max(1, width)))];
+  }
+}
+
+// The exact-value editor behind the standout row's submenu: an Input prefilled
+// with the raw value; Enter applies through applyCanonSettingsEdit and only a
+// valid result calls done, so an invalid state can never reach the list, the
+// file, or registration. Composition mirrors the native SelectSubmenu.
+class StandoutEditor extends Container {
+  input: Input;
+  errorText: Text;
+  themeLike: any;
+  apply: (raw: string) => { ok: true; display: string } | { ok: false; error: string };
+  done: (displayValue?: string) => void;
+
+  constructor(themeLike: any, initialValue: string, apply: any, done: (displayValue?: string) => void) {
+    super();
+    this.themeLike = themeLike;
+    this.apply = apply;
+    this.done = done;
+    const theme = this.themeLike;
+    this.input = new Input();
+    this.errorText = new Text("", 0, 0);
+    this.addChild(new Text(theme.bold(theme.fg("accent", "Standout cutoff")), 0, 0));
+    this.addChild(new Text(theme.fg("muted", "How far the best-ranked article must outscore the rest before it rides. 1 is no cutoff."), 0, 0));
+    this.addChild(new Spacer(1));
+    this.input.setValue(initialValue);
+    // setValue parks the cursor at 0; a prefilled editor must start at the end,
+    // or typing inserts at the front and backspace deletes nothing.
+    (this.input as any).cursor = initialValue.length;
+    this.input.onSubmit = () => this.submit();
+    this.input.onEscape = () => this.done();
+    this.addChild(this.input);
+    this.addChild(new Spacer(1));
+    this.addChild(this.errorText);
+    this.addChild(new Text(theme.fg("dim", "  Enter to apply · Esc to go back"), 0, 0));
+  }
+
+  submit(): void {
+    const result = this.apply(this.input.getValue());
+    if (!result.ok) {
+      this.errorText.setText(this.themeLike.fg("error", `  ${result.error}`));
+      return;
+    }
+    this.done(result.display);
+  }
+
+  handleInput(data: string): void {
+    this.input.handleInput(data);
+  }
+}
+
+// The /canon-settings screen itself. Boolean and retrieval rows CYCLE through
+// their values natively; the standout row STEPS along its lattice with left/right
+// (clamped at the ends) and takes an exact value on Enter.
+export class CanonSettingsEditor extends Container {
+  draft: CanonUserSettings;
+  settingsPath: string;
+  themeLike: any;
+  done: (saved: boolean) => void;
+  settingsList: SettingsList;
+
+  constructor(draft: CanonUserSettings, settingsPath: string, themeLike: any, done: (saved: boolean) => void) {
+    super();
+    this.draft = draft;
+    this.settingsPath = settingsPath;
+    this.themeLike = themeLike;
+    this.done = done;
+    const theme = this.themeLike;
+    this.addChild(new SettingsBorder((text: string) => theme.fg("border", text)));
+    this.addChild(new Text(theme.bold(theme.fg("accent", "pi-canon settings")), 0, 0));
+    this.addChild(new Text(theme.fg("muted", "Edits save immediately. ←→ steps the cutoff · Enter changes or types a value."), 0, 0));
+    this.addChild(new Spacer(1));
+    // SettingsList takes its own theme shape; adapt it off the live theme.
+    const listTheme = {
+      label: (text: string, selected: boolean) => (selected ? theme.fg("accent", text) : text),
+      value: (text: string, selected: boolean) => (selected ? theme.fg("accent", text) : theme.fg("muted", text)),
+      description: (text: string) => theme.fg("dim", text),
+      cursor: theme.fg("accent", "→ "),
+      hint: (text: string) => theme.fg("dim", text),
+    };
+    this.settingsList = new SettingsList(
+      EDITOR_ROWS.map((row) => ({
+        id: row.id,
+        label: row.label,
+        description: row.description,
+        currentValue: rowDisplayValue(this.draft, row.id),
+        values: row.id === "surface" || row.id === "resurface"
+          ? ["on", "off"]
+          : row.id === "retrieval"
+            ? [...RETRIEVAL_CHOICES]
+            : undefined,
+        submenu: row.id === "standout"
+          ? (_current: string, submenuDone: (displayValue?: string) => void) =>
+            new StandoutEditor(
+              themeLike,
+              rowRawValue(this.draft, row.id),
+              (raw: string) => this.applyAndSave(row.id, raw),
+              submenuDone,
+            )
+          : undefined,
+      })),
+      EDITOR_ROWS.length + 2,
+      listTheme,
+      (id: string, newValue: string) => this.applyCycled(id as CanonSettingId, newValue),
+      () => this.done(true),
+    );
+    this.addChild(this.settingsList);
+    this.addChild(new Spacer(1));
+    this.addChild(new Text(theme.fg("dim", "  ←→ to step the cutoff · Enter to change · Esc to close"), 0, 0));
+    this.addChild(new SettingsBorder((text: string) => theme.fg("border", text)));
+  }
+
+  applyAndSave(id: CanonSettingId, raw: string): { ok: true; display: string } | { ok: false; error: string } {
+    const result = applyCanonSettingsEdit(this.draft, id, raw);
+    if (!result.ok) return result;
+    this.draft = result.draft;
+    saveCanonSettingsFile(this.settingsPath, this.draft);
+    for (const row of EDITOR_ROWS) {
+      const item = (this.settingsList as any).items.find((candidate: any) => candidate.id === row.id);
+      if (item) item.currentValue = rowDisplayValue(this.draft, row.id);
+    }
+    return { ok: true, display: rowDisplayValue(this.draft, id) };
+  }
+
+  /* Cycling rows reach this handler from SettingsList itself. The standout row
+     reaches it too when its submenu closes: SettingsList re-fires onChange with
+     the DISPLAY string, which is not a number, so the handler ignores that row
+     entirely; the submit path already applied and saved it. */
+  applyCycled(id: CanonSettingId, newValue: string): void {
+    if (id === "standout") return;
+    this.applyAndSave(id, newValue);
+  }
+
+  // One step along the standout lattice, clamped at its ends. Stepping is inert
+  // while retrieval is none, because the value is ignored there anyway.
+  stepStandout(direction: number): void {
+    if ((this.draft.retrieval ?? "none") === "none") return;
+    const current = Number(rowRawValue(this.draft, "standout"));
+    const target = direction > 0
+      ? STANDOUT_LATTICE.find((candidate) => candidate > current + 1e-9)
+      : [...STANDOUT_LATTICE].reverse().find((candidate) => candidate < current - 1e-9);
+    if (target === undefined) return;
+    this.applyAndSave("standout", String(target));
+  }
+
+  handleInput(data: string): void {
+    // An open submenu owns everything until it closes.
+    if (this.settingsList.submenuComponent) {
+      this.settingsList.handleInput(data);
+      return;
+    }
+    if (matchesKey(data, Key.left)) {
+      this.stepStandout(-1);
+      return;
+    }
+    if (matchesKey(data, Key.right)) {
+      this.stepStandout(+1);
+      return;
+    }
+    if (matchesKey(data, Key.escape)) {
+      this.done(true);
+      return;
+    }
+    this.settingsList.handleInput(data);
+  }
+}
+
+export function registerCanonSettings(
+  pi: any,
+  options: { settingsPath?: string } = {},
+): void {
+  const settingsPath = options.settingsPath ?? DEFAULT_CANON_SETTINGS_PATH;
+  pi.registerCommand("canon-settings", {
+    description: "Configure pi-canon: surfacing, resurfacing, retrieval ranking, standout cutoff",
+    handler: async (_args: string, ctx: any) => {
+      if (typeof ctx.ui?.custom !== "function") {
+        throw new Error("/canon-settings needs an interactive UI; set the options in the settings file instead");
+      }
+      const draft = loadCanonSettingsFile(settingsPath);
+      await ctx.ui.custom((_tui: unknown, theme: any, _keybindings: unknown, done: (saved: boolean) => void) =>
+        new CanonSettingsEditor(draft, settingsPath, theme, done));
+    },
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-canon",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "Canonical project memory for the Pi coding agent: one article per asset at a knowable address, an append-only journal beneath it.",
   "type": "module",
   "exports": {
@@ -21,7 +21,8 @@
     "node": ">=22.18"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.83.0 <1"
+    "@earendil-works/pi-coding-agent": ">=0.83.0 <2",
+    "@earendil-works/pi-tui": "*"
   },
   "scripts": {
     "test": "node tests/verify.mjs"
@@ -43,10 +44,10 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/shaneconner/pi-canon.git"
+    "url": "git+https://github.com/shaneconner/canon.git"
   },
-  "bugs": "https://github.com/shaneconner/pi-canon/issues",
-  "homepage": "https://github.com/shaneconner/pi-canon#readme",
+  "bugs": "https://github.com/shaneconner/canon/issues",
+  "homepage": "https://github.com/shaneconner/canon#readme",
   "devDependencies": {
     "jiti": "^2.7.0"
   }