pi-canon 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shane Conner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# pi-canon
+
+Canonical project memory for the [Pi coding agent](https://pi.dev). One article per asset at a knowable address, an append-only journal beneath it: pi-canon surfaces the governing article's capsule as the agent touches an asset, and reminds it to update the article after real changes.
+
+## Why
+
+Agent knowledge bases rot in two ways. Agents cannot tell which article is THE article for a topic, so they scatter near duplicates and cite stale ones. And they treat the knowledge base as a diary, so ground truth drowns in event logs.
+
+pi-canon answers both structurally:
+
+- The article address IS the asset path. `src/core/config.ts` is governed by `articles/src/core/config.md`; a data lake path like `lake/fundamentals/market_cap` works the same way. One place to look, nothing to search.
+- The journal is a separate, immutable tier. The source goes there as it happened, names and exact numbers included; articles hold only the current best understanding. An article can compress or drift, the journal entry underneath it cannot, so the original is always one hop away.
+
+## The store
+
+    .canon/
+      articles/
+        src/core/config.md        article governing src/core/config.*
+        lake/prices.md            articles are not limited to code
+      journal/
+        2026-08-10-inception.md   immutable, one file per entry
+
+Articles are markdown with a few owned lines of front matter, each with a job:
+
+    ---
+    capsule: Loads layered config; env beats file; secrets never land here.
+    updated: 2026-08-10
+    ---
+    The body: dense current understanding of this asset.
+
+`capsule` is the one dense line surfacing injects. `updated` is the date of the last write. Rename an asset by moving its article with it; lint names any wikilinks that go dead. Foreign front matter keys, such as Obsidian properties, ride through writes untouched.
+
+The tree is plain markdown and a valid Obsidian vault; if you think of it as a project wiki, that is the right instinct, with one rule added: every article has exactly one canonical address. Commit it with your repo: git is the history, diff, blame, and time machine. pi-canon never runs git itself. Journal entries are ordinary files too: pi_canon only appends them; read them with normal file tools.
+
+## Surfacing
+
+Each session opens with one orientation line: how many articles govern the project, or an invitation to write the first one. When a tool call touches an asset whose governing article has not been seen this session, pi-canon stages the capsule; each turn delivers everything staged as one bounded message, once per article per session, under a hard budget (pointers only once it is spent). Resolution walks up: the nearest existing ancestor article governs, so not every file needs an article. After the agent settles, touched but not updated articles draw a single reminder. `/pi-canon` prints a status line: articles, journal entries, and what surfacing has spent this session.
+
+## Tool
+
+One tool, `pi_canon`, four actions:
+
+| action | does |
+|---|---|
+| `read` | the article at an address; a miss points to the nearest governing ancestor |
+| `write` | create or update an article; returns advisory lint, never refuses |
+| `journal` | append an event entry, source details intact; pi_canon never rewrites one |
+| `map` | list articles with their capsules |
+
+Entries logged with `subject` addresses reappear as a one-line journal index when those articles are read, so event history is there to dig into without ever loading by default.
+
+## Options
+
+    import piCanon, { registerPiCanon } from "pi-canon"
+
+    piCanon(pi)                                      defaults
+    registerPiCanon(pi, { root, surface, mounts })   the whole surface
+
+Installed as a package, pi loads the default export with defaults; the named export is for an extension file of your own when you want options. `root` is where the project store lives (default `<project>/.canon`). `surface: false` disables nudging. `mounts` lists directories outside the project that carry their own `.canon` beside their assets: `mounts: ["/data/lake"]` serves articles as `lake:prices`, and two workspaces that mount the same directory share its knowledge, because the store lives with the assets it governs. Everything else is a constant on purpose.
+
+## Install
+
+    pi install npm:pi-canon    (not yet published)
+
+Or clone this repo into `~/.pi/agent/extensions/`. Node 22 or later, Pi 0.83 or later.
+
+MIT. pi-canon is the long-term half of a four-tier memory stack: the journal is the episodic tier, the canon the semantic tier. [pi-fold](https://github.com/shaneconner/pi-fold) is a separate, optional package serving the working tier; the two compose but neither requires the other.

package/extensions/canon.ts

@@ -0,0 +1,113 @@
+/* pi-canon: canonical project memory for Pi. Wiring only; mechanics live in lib/. */
+
+import { basename, isAbsolute, join } from "node:path";
+import { CanonStore } from "./lib/store.ts";
+import { SESSION_BUDGET_CHARS, Surfacer, type Mount } from "./lib/surfacing.ts";
+import { buildCanonTool, type CanonRuntime } from "./lib/tool.ts";
+
+export interface CanonOptions {
+  /* Where the project store lives. Default: <project>/.canon */
+  root?: string;
+  /* Surface governing articles as tool calls touch assets. Default: true. */
+  surface?: boolean;
+  /* Directories outside the project that carry their own .canon beside their
+     assets, addressed by basename: mounts: ["/data/lake"] serves lake:prices.
+     Workspaces that mount the same directory share its knowledge. */
+  mounts?: string[];
+}
+
+export function registerPiCanon(pi: any, options: CanonOptions = {}): void {
+  const unknown = Object.keys(options).find((key) => key !== "root" && key !== "surface" && key !== "mounts");
+  if (unknown) {
+    throw new Error(
+      `pi-canon: unknown option "${unknown}". The options are root, surface, and mounts; everything else is a constant on purpose.`,
+    );
+  }
+  const surface = options.surface !== false;
+
+  let runtime: CanonRuntime | undefined;
+
+  const ready = (ctx: any): CanonRuntime => {
+    if (!runtime) {
+      const cwd: string = ctx?.cwd ?? process.cwd();
+      const root = options.root
+        ? isAbsolute(options.root)
+          ? options.root
+          : join(cwd, options.root)
+        : join(cwd, ".canon");
+      const store = new CanonStore(root);
+      const mounts: Mount[] = [
+        { name: "", dir: cwd, store },
+        ...(options.mounts ?? []).map((dir) => {
+          const abs = isAbsolute(dir) ? dir : join(cwd, dir);
+          return { name: basename(abs), dir: abs, store: new CanonStore(join(abs, ".canon")) };
+        }),
+      ];
+      runtime = { store, surfacer: new Surfacer(mounts), cwd, mounts };
+    }
+    return runtime;
+  };
+
+  pi.registerTool(buildCanonTool(ready));
+
+  /* One orientation line per session, riding the first turn: without it a fresh
+     or headless session never hears the doctrine, and the write-after reminder
+     (nextTurn at settle) cannot reach a session that ends when the agent does. */
+  pi.on("session_start", (_event: unknown, ctx: any) => {
+    runtime = undefined;
+    const { store } = ready(ctx);
+    if (!surface) return;
+    const count = store.list().length;
+    const text = count
+      ? `[pi-canon] ${count} ${count === 1 ? "article governs" : "articles govern"} this project. Read the governing ` +
+        "article before working on an asset; after real changes update it and journal the " +
+        "source: names, exact numbers, who said what. Articles distill; the journal keeps the original."
+      : "[pi-canon] No articles yet in .canon/. When work teaches you something durable about an " +
+        "asset, write its article with pi_canon and journal the source as it happened: names, " +
+        "exact numbers, who said what. Articles distill; the journal keeps the original.";
+    deliver(pi, text, "nextTurn");
+  });
+
+  /* Touches stage; turns flush. One steered message per turn rides the provider
+     round trip that was happening anyway. */
+  pi.on("tool_call", (event: any, ctx: any) => {
+    if (!surface || event?.toolName === "pi_canon") return;
+    const { surfacer } = ready(ctx);
+    surfacer.collect(surfacer.pathsIn(event?.input));
+  });
+
+  pi.on("turn_end", (_event: unknown, ctx: any) => {
+    if (!surface) return;
+    const text = ready(ctx).surfacer.flush();
+    if (text) deliver(pi, text, "steer");
+  });
+
+  pi.on("agent_settled", (_event: unknown, ctx: any) => {
+    if (!surface) return;
+    const { surfacer } = ready(ctx);
+    const text = [surfacer.flush(), surfacer.settleNudge()].filter(Boolean).join("\n");
+    if (text) deliver(pi, text, "nextTurn");
+  });
+
+  pi.registerCommand("pi-canon", {
+    description: "pi-canon status: articles, journal entries, surfacing this session",
+    handler: async (_args: string, ctx: any) => {
+      const { store, surfacer, mounts } = ready(ctx);
+      const { surfaced, spent } = surfacer.stats;
+      const mounted = mounts.length > 1 ? `, ${mounts.length - 1} mounted` : "";
+      ctx.ui.notify(
+        `pi-canon at ${store.root}${mounted}: ${store.list().length} articles, ${store.journalCount()} journal ` +
+          `entries; ${surfaced} seen this session (${spent} of ${SESSION_BUDGET_CHARS} capsule chars).`,
+        "info",
+      );
+    },
+  });
+}
+
+function deliver(pi: any, content: string, deliverAs: "steer" | "nextTurn"): void {
+  try {
+    pi.sendMessage({ customType: "pi-canon", content, display: false }, { deliverAs });
+  } catch {
+    /* a lost nudge must never break the turn */
+  }
+}

package/extensions/index.js

@@ -0,0 +1,10 @@
+/* Package entry. Pi calls the default export with the extension API; embedders use
+   the named export to pass options. */
+
+import { registerPiCanon } from "./canon.ts";
+
+export { registerPiCanon };
+
+export default function piCanon(pi) {
+  return registerPiCanon(pi, {});
+}

package/extensions/lib/lint.ts

@@ -0,0 +1,80 @@
+/* Advisory only: advice strings, never a refusal. A blocked write teaches an agent
+   to stop writing; a warning teaches it what to do next. */
+
+import { normalize, type Article, type CanonStore } from "./store.ts";
+
+export const BODY_WARN_CHARS = 8000;
+export const BODY_LARGE_CHARS = 20000;
+export const CAPSULE_CHARS = 1000;
+const BODY_TINY_CHARS = 400;
+
+const JOURNALISH = /(^|\/)(logs?|journal|sessions?|standups?|meetings?)(\/|$)|\d{4}-\d{2}-\d{2}/i;
+const EVENTISH = /^(added|updated|fixed|changed|implemented|removed|refactored|renamed|migrated|verified)\b/i;
+
+const CONSTRAINT = /\b(must|never|always|require[sd]?|do not|don't)\b/i;
+
+export function advise(article: Article, store: CanonStore, priorBody?: string): string[] {
+  const advice: string[] = [];
+  const size = article.body.length;
+
+  /* The laundering guard: an agent that just violated a documented constraint will
+     faithfully update the article to describe the violation as current truth. Name
+     what disappeared; whether it still holds is the agent's call, stated out loud. */
+  if (priorBody !== undefined) {
+    const kept = article.body.replace(/\s+/g, " ");
+    const dropped = priorBody
+      .split(/\r?\n/)
+      .map((line) => line.replace(/^[-*\s]+/, "").trim())
+      .filter((line) => CONSTRAINT.test(line) && !kept.includes(line.replace(/\s+/g, " ")))
+      .slice(0, 2);
+    for (const line of dropped) {
+      advice.push(
+        `This write dropped constraint language: "${line.slice(0, 160)}". If it still holds, keep it; ` +
+          "if it genuinely changed, journal what changed it.",
+      );
+    }
+  }
+
+  if (size > BODY_LARGE_CHARS) {
+    advice.push(
+      `Body is ${size} chars (large past ${BODY_LARGE_CHARS}). Go hierarchical: keep this article ` +
+        `as the summary and router, and move detail into children under ${article.path}/ at chunks ` +
+        `worth loading separately.`,
+    );
+  } else if (size > BODY_WARN_CHARS) {
+    advice.push(`Body is ${size} chars (warn past ${BODY_WARN_CHARS}). Densify before it needs splitting.`);
+  } else if (size > 0 && size < BODY_TINY_CHARS) {
+    const parent = parentOf(article.path);
+    if (parent && store.read(parent)) {
+      advice.push(`Body is ${size} chars. Consider folding it into ${parent}; keep children only at real asset or chunk boundaries.`);
+    }
+  }
+
+  if (!article.capsule) {
+    advice.push("No capsule. Add one dense line of front matter; surfacing has nothing to inject without it.");
+  } else if (article.capsule.length > CAPSULE_CHARS) {
+    advice.push(
+      `Capsule is ${article.capsule.length} chars (cap ${CAPSULE_CHARS}). A capsule is one dense line, not a second body.`,
+    );
+  } else if (EVENTISH.test(article.capsule)) {
+    advice.push("The capsule reads like a change log. Capsules hold current truth; the event belongs in the journal.");
+  }
+
+  if (JOURNALISH.test(article.path)) {
+    advice.push(`The address ${article.path} reads like an event log. Articles hold current truth; the event belongs in the journal.`);
+  }
+
+  for (const match of article.body.matchAll(/\[\[([^\]|#]+)[^\]]*\]\]/g)) {
+    const target = match[1].trim().replace(/\.md$/, "");
+    if (!store.read(target) && !store.read(normalize(target))) {
+      advice.push(`Link [[${match[1]}]] resolves to no article.`);
+    }
+  }
+
+  return advice;
+}
+
+function parentOf(path: string): string {
+  const cut = path.lastIndexOf("/");
+  return cut === -1 ? "" : path.slice(0, cut);
+}

package/extensions/lib/store.ts

@@ -0,0 +1,245 @@
+/* Article and journal storage: a plain markdown tree under one root.
+   articles/<path>.md is the article governing asset <path>; journal/ holds immutable
+   entries. Front matter is a strict YAML subset (single line values, inline arrays)
+   so the tree stays hand editable and Obsidian readable with no parser dependency;
+   keys this package does not own are carried through writes untouched. */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface Article {
+  path: string;
+  capsule: string;
+  updated: string;
+  extra: string[];
+  body: string;
+}
+
+const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+const OWNED_KEYS = new Set(["capsule", "updated"]);
+
+/* Keep an address inside the tree: .. resolves against its own segments, so
+   a/b/../c means a/c, and clamps at the root, so nothing ever escapes. */
+function contain(path: string): string {
+  const parts: string[] = [];
+  for (const part of path.split("/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") parts.pop();
+    else parts.push(part);
+  }
+  return parts.join("/");
+}
+
+/* An asset address: relative to the project, contained, file extension dropped so
+   src/core/config.ts shares its article's address. The drop happens once, here at
+   the boundary; the store itself never drops again, or config.test would lose its
+   .test on the way to disk. */
+export function normalize(asset: string, cwd = ""): string {
+  let path = asset.trim().replace(/\\/g, "/");
+  if (cwd && (path === cwd || path.startsWith(`${cwd}/`))) path = path.slice(cwd.length);
+  path = contain(path);
+  /* Drop the extension only when something precedes the dot, so .env stays .env. */
+  const dot = path.lastIndexOf(".");
+  if (dot > path.lastIndexOf("/") + 1) path = path.slice(0, dot);
+  return path;
+}
+
+function parseFrontMatter(text: string): {
+  meta: Record<string, string | string[]>;
+  extra: string[];
+  body: string;
+} {
+  const match = FRONT_MATTER.exec(text);
+  if (!match) return { meta: {}, extra: [], body: text };
+  const meta: Record<string, string | string[]> = {};
+  const extra: string[] = [];
+  let keepingForeign = false;
+  for (const line of match[1].split(/\r?\n/)) {
+    const pair = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line);
+    if (!pair) {
+      if (keepingForeign) extra.push(line);
+      continue;
+    }
+    /* An owned key with an empty value is a block list (Obsidian's aliases shape).
+       Blocks are not ours to parse, so the whole thing rides along as foreign. */
+    keepingForeign = !OWNED_KEYS.has(pair[1]) || !pair[2].trim();
+    if (keepingForeign) {
+      extra.push(line);
+      continue;
+    }
+    meta[pair[1]] = unscalar(pair[2].trim());
+  }
+  return { meta, extra, body: text.slice(match[0].length) };
+}
+
+/* Owned values are quoted only when YAML would misread them plain, so the tree
+   stays hand editable and Obsidian keeps parsing it as a vault. */
+const NEEDS_QUOTES = /[:#[\]{}"'`,&*!|>%@\\]|^\s|\s$/;
+
+function scalar(value: string): string {
+  return NEEDS_QUOTES.test(value) ? JSON.stringify(value) : value;
+}
+
+function unscalar(value: string): string {
+  if (value.startsWith('"') && value.endsWith('"')) {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return value;
+    }
+  }
+  return value;
+}
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function serialize(article: Article): string {
+  const meta = [
+    article.capsule ? `capsule: ${scalar(article.capsule)}` : "",
+    `updated: ${article.updated}`,
+    ...article.extra,
+  ].filter(Boolean).join("\n");
+  return `---\n${meta}\n---\n${article.body.trimEnd()}\n`;
+}
+
+export class CanonStore {
+  readonly root: string;
+
+  constructor(root: string) {
+    this.root = root;
+  }
+
+  get articlesDir(): string {
+    return join(this.root, "articles");
+  }
+
+  get journalDir(): string {
+    return join(this.root, "journal");
+  }
+
+  private fileFor(path: string): string {
+    return join(this.articlesDir, `${path}.md`);
+  }
+
+  read(path: string): Article | undefined {
+    if (!path) return undefined;
+    const file = this.fileFor(path);
+    if (!existsSync(file)) return undefined;
+    const { meta, extra, body } = parseFrontMatter(readFileSync(file, "utf8"));
+    return {
+      path,
+      body,
+      extra,
+      capsule: typeof meta.capsule === "string" ? meta.capsule : "",
+      updated: typeof meta.updated === "string" ? meta.updated : "",
+    };
+  }
+
+  /* The closest existing article governs the asset: exact address, then the
+     nearest ancestor. */
+  resolve(asset: string, cwd = ""): Article | undefined {
+    let path = normalize(asset, cwd);
+    while (path) {
+      const article = this.read(path);
+      if (article) return article;
+      const cut = path.lastIndexOf("/");
+      path = cut === -1 ? "" : path.slice(0, cut);
+    }
+    return undefined;
+  }
+
+  list(): string[] {
+    const walk = (dir: string, prefix: string): string[] => {
+      if (!existsSync(dir)) return [];
+      const paths: string[] = [];
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) paths.push(...walk(join(dir, entry.name), `${prefix}${entry.name}/`));
+        else if (entry.name.endsWith(".md")) paths.push(`${prefix}${entry.name.slice(0, -3)}`);
+      }
+      return paths;
+    };
+    return walk(this.articlesDir, "").sort();
+  }
+
+  write(path: string, fields: { capsule?: string; body?: string }): Article {
+    path = contain(path);
+    const prior = this.read(path);
+    /* Agents sometimes paste a whole file as the body, front matter included; stored
+       verbatim that nests a second front matter block inside the article. Strip a
+       leading block only when its lines all look like front matter keys. */
+    let body = fields.body ?? prior?.body ?? "";
+    const block = FRONT_MATTER.exec(body);
+    if (block && block[1].split(/\r?\n/).every((line) => /^[\w-]+:\s|^\s*$/.test(line))) {
+      body = body.slice(block[0].length).trimStart();
+    }
+    const article: Article = {
+      path,
+      capsule: (fields.capsule ?? prior?.capsule ?? "").replace(/\s*\n\s*/g, " ").trim(),
+      updated: today(),
+      extra: prior?.extra ?? [],
+      body,
+    };
+    const file = this.fileFor(path);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, serialize(article));
+    return article;
+  }
+
+  /* Journal entries are immutable: a fresh dated file per entry, wx so nothing is
+     ever overwritten. EEXIST is the retry signal, so concurrent writers each land
+     on their own file instead of one losing its entry. */
+  journal(entry: { body: string; slug?: string; subject?: string[] }): string {
+    const slug =
+      (entry.slug ?? "entry").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "") || "entry";
+    mkdirSync(this.journalDir, { recursive: true });
+    const front = entry.subject?.length ? `---\nsubject: [${entry.subject.join(", ")}]\n---\n` : "";
+    const text = `${front}${entry.body.trimEnd()}\n`;
+    for (let n = 1; ; n += 1) {
+      const file = join(this.journalDir, `${today()}-${slug}${n > 1 ? `-${n}` : ""}.md`);
+      try {
+        writeFileSync(file, text, { flag: "wx" });
+        return file;
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      }
+    }
+  }
+
+  journalCount(): number {
+    try {
+      return readdirSync(this.journalDir).filter((name) => name.endsWith(".md")).length;
+    } catch {
+      return 0;
+    }
+  }
+
+  /* Journal entries whose subject names this address: the index a read surfaces
+     so the agent can dig into event history when it wants more than current truth. */
+  journalMentions(path: string): string[] {
+    try {
+      return readdirSync(this.journalDir)
+        .filter((name) => {
+          if (!name.endsWith(".md")) return false;
+          const subject = /^subject:\s*(.*)$/m.exec(readFileSync(join(this.journalDir, name), "utf8"))?.[1] ?? "";
+          return subject.replace(/^\[|\]$/g, "").split(",").some((s) => s.trim() === path);
+        })
+        .sort();
+    } catch {
+      return [];
+    }
+  }
+
+  map(under = ""): string {
+    const paths = this.list().filter((path) => !under || path === under || path.startsWith(`${under}/`));
+    if (!paths.length) return under ? `No articles under ${under}.` : "No articles yet.";
+    return paths
+      .map((path) => {
+        const capsule = this.read(path)?.capsule;
+        return capsule ? `${path}: ${capsule}` : path;
+      })
+      .join("\n");
+  }
+
+}

package/extensions/lib/surfacing.ts

@@ -0,0 +1,160 @@
+/* Surfacing: tool calls stage the articles governing what they touch; the staged
+   lines flush as ONE message per turn, once per article per session, under a hard
+   budget. Capsules first; when the budget is spent, pointers only. One message per
+   turn matters: pi's steering queue drains one message per provider round trip, so
+   a message per tool call would buy each nudge its own extra LLM call. */
+
+import { appendFileSync, existsSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import type { CanonStore } from "./store.ts";
+
+export const SESSION_BUDGET_CHARS = 4000;
+const MESSAGE_CHARS = 2000;
+
+/* Observability, env-gated and inert otherwise: PI_CANON_TRACE=<file> appends one
+   JSON line per surfacing decision, so a harness can audit the staged -> flushed ->
+   seen funnel instead of guessing at it. */
+function trace(kind: string, data: Record<string, unknown>): void {
+  const file = process.env.PI_CANON_TRACE;
+  if (!file) return;
+  try {
+    appendFileSync(file, JSON.stringify({ at: new Date().toISOString(), kind, ...data }) + "\n");
+  } catch {
+    /* tracing must never break surfacing */
+  }
+}
+
+const PATHLIKE = /(?:^|[\s"'`=:,([{])(\/?[\w.@-]+(?:\/[\w.@-]+)+)/g;
+
+/* A store and the directory whose assets it governs. The project is the first,
+   unnamed mount; named mounts are outside directories (a data lake, a shared
+   corpus) whose articles address as name:path. */
+export interface Mount {
+  name: string;
+  dir: string;
+  store: CanonStore;
+}
+
+export class Surfacer {
+  private mounts: Mount[];
+  private seen = new Set<string>();
+  private pendingUpdates = new Set<string>();
+  private staged = new Map<string, { capsule: string; stamp: string; asset: string }>();
+  private spent = 0;
+
+  constructor(mounts: Mount[]) {
+    this.mounts = mounts;
+  }
+
+  private get project(): Mount {
+    return this.mounts[0];
+  }
+
+  private mountFor(asset: string): Mount {
+    const path = asset.replace(/\\/g, "/");
+    const absolute = isAbsolute(path) ? path : join(this.project.dir, path);
+    for (const mount of this.mounts.slice(1)) {
+      if (absolute === mount.dir || absolute.startsWith(`${mount.dir}/`)) return mount;
+    }
+    return this.project;
+  }
+
+  markSeen(path: string): void {
+    if (this.staged.has(path)) trace("withdrawn", { path });
+    this.seen.add(path);
+    this.staged.delete(path);
+  }
+
+  markUpdated(path: string): void {
+    this.markSeen(path);
+    this.pendingUpdates.delete(path);
+  }
+
+  get stats(): { surfaced: number; spent: number } {
+    return { surfaced: this.seen.size, spent: this.spent };
+  }
+
+  /* Candidate asset paths in a tool call: string values that are paths, and path
+     shaped tokens inside them. A candidate needs to exist, or to have an existing
+     parent, so a file about to be created still surfaces its governing article. */
+  pathsIn(input: unknown): string[] {
+    const found = new Set<string>();
+    const consider = (candidate: string) => {
+      const path = candidate.replace(/\\/g, "/");
+      const absolute = isAbsolute(path) ? path : join(this.project.dir, path);
+      if (existsSync(absolute) || (path.includes("/") && existsSync(dirname(absolute)))) found.add(path);
+    };
+    const walk = (value: unknown): void => {
+      if (typeof value === "string") {
+        const whole = value.trim();
+        if (whole && whole.length < 512 && !whole.includes("\n")) consider(whole);
+        for (const match of value.matchAll(PATHLIKE)) consider(match[1]);
+      } else if (Array.isArray(value)) {
+        value.forEach(walk);
+      } else if (value && typeof value === "object") {
+        Object.values(value).forEach(walk);
+      }
+    };
+    walk(input);
+    return [...found];
+  }
+
+  /* Stage each newly touched governing article. Nothing is sent or spent here. */
+  collect(assets: string[]): void {
+    for (const asset of assets) {
+      const mount = this.mountFor(asset);
+      const article = mount.store.resolve(asset, mount.dir);
+      if (!article) continue;
+      const key = mount.name ? `${mount.name}:${article.path}` : article.path;
+      this.pendingUpdates.add(key);
+      if (this.seen.has(key) || this.staged.has(key)) continue;
+      const stamp = article.updated ? ` (updated ${article.updated})` : "";
+      this.staged.set(key, { capsule: article.capsule, stamp, asset });
+      trace("staged", { path: key, asset });
+    }
+  }
+
+  /* Everything staged since the last flush, as one bounded message. The budget is
+     charged here, not at staging, so a nudge withdrawn by markSeen costs nothing;
+     articles count as seen only once their line is part of a flushed message.
+     Overflow stays staged for the next turn. */
+  flush(): string | undefined {
+    if (!this.staged.size) return undefined;
+    const lines: string[] = [];
+    let size = 0;
+    for (const [path, entry] of this.staged) {
+      const useCapsule = entry.capsule && this.spent + entry.capsule.length <= SESSION_BUDGET_CHARS;
+      const line = useCapsule
+        ? `${path}${entry.stamp}: ${entry.capsule}`
+        : `${path}${entry.stamp}: article exists. Read it before relying on ${entry.asset}.`;
+      if (lines.length && size + line.length > MESSAGE_CHARS) {
+        lines.push(`${this.staged.size} more staged; they surface next turn.`);
+        break;
+      }
+      if (useCapsule) this.spent += entry.capsule.length;
+      size += line.length;
+      lines.push(line);
+      this.seen.add(path);
+      this.staged.delete(path);
+    }
+    const plural = lines.length > 1 ? "s" : "";
+    trace("flushed", { lines: lines.length, spent: this.spent });
+    return (
+      `[pi-canon] Governing article${plural} for what this turn touches. Read the full article with ` +
+      `pi_canon before depending on details; update it after real changes.\n${lines.join("\n")}`
+    );
+  }
+
+  /* The write-after half of the doctrine: every governing article touched since its
+     last update draws one reminder, then the slate clears for the next batch. */
+  settleNudge(): string | undefined {
+    const stale = [...this.pendingUpdates];
+    this.pendingUpdates.clear();
+    if (!stale.length) return undefined;
+    trace("settle-nudge", { paths: stale });
+    return (
+      `[pi-canon] Touched but not updated: ${stale.join(", ")}. If this work changed what is true, ` +
+      `update the article with pi_canon; if nothing durable changed, leave it.`
+    );
+  }
+}

package/extensions/lib/tool.ts

@@ -0,0 +1,147 @@
+/* The pi_canon tool: one tool, four verbs. Read and update over create; the journal
+   for events; map to orient. */
+
+import { basename } from "node:path";
+import { advise } from "./lint.ts";
+import { normalize, type CanonStore } from "./store.ts";
+import type { Mount, Surfacer } from "./surfacing.ts";
+
+export interface CanonRuntime {
+  store: CanonStore;
+  surfacer: Surfacer;
+  cwd: string;
+  mounts: Mount[];
+}
+
+/* A path routes to the mount it names (lake:prices), the mount whose directory
+   contains it, or the project. */
+function route(runtime: CanonRuntime, raw: string): { mount: Mount; path: string } {
+  const qualified = /^([\w.-]+):(.*)$/.exec(raw);
+  if (qualified) {
+    const mount = runtime.mounts.find((m) => m.name === qualified[1]);
+    if (mount) return { mount, path: normalize(qualified[2], mount.dir) };
+  }
+  const slashed = raw.replace(/\\/g, "/");
+  for (const mount of runtime.mounts) {
+    if (mount.name && (slashed === mount.dir || slashed.startsWith(`${mount.dir}/`))) {
+      return { mount, path: normalize(slashed, mount.dir) };
+    }
+  }
+  return { mount: runtime.mounts[0], path: normalize(raw, runtime.cwd) };
+}
+
+export function buildCanonTool(ready: (ctx: unknown) => CanonRuntime) {
+  return {
+    name: "pi_canon",
+    label: "pi-canon",
+    description:
+      "Canonical project memory. Every asset has at most one governing article at its own address " +
+      "(src/core/config, lake/prices). read the governing article before working on an asset; " +
+      "write it after real changes. journal appends an immutable event entry: record the source " +
+      "as it happened, names and exact numbers included, because articles distill and only the " +
+      "journal keeps the original. map lists articles with their capsules. " +
+      "Creation is rare: prefer updating the article that already governs. " +
+      "File a constraint at the asset it governs, or the shared parent when it spans assets, not " +
+      "the asset you happened to edit; knowledge filed off the asset path never surfaces.",
+    parameters: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["read", "write", "journal", "map"] },
+        path: {
+          type: "string",
+          description: "Article address, e.g. src/core/config. Required for read and write; optional filter for map.",
+        },
+        body: {
+          type: "string",
+          description:
+            "write: the full article body; specifics beat summaries (who consumes what, exact " +
+            "limits, what breaks). journal: the event text, source details intact.",
+        },
+        capsule: { type: "string", description: "write: one dense line injected when the asset is touched." },
+        subject: {
+          type: "array",
+          items: { type: "string" },
+          description: "journal: article addresses this event concerns.",
+        },
+        slug: { type: "string", description: "journal: short name for the entry file." },
+      },
+      required: ["action"],
+    },
+    async execute(
+      _toolCallId: string,
+      params: Record<string, unknown>,
+      _signal: unknown,
+      _onUpdate: unknown,
+      ctx: unknown,
+    ) {
+      const text = run(ready(ctx), params);
+      return { content: [{ type: "text", text }], details: {} };
+    },
+  };
+}
+
+function run(runtime: CanonRuntime, params: Record<string, unknown>): string {
+  const { surfacer } = runtime;
+  const action = String(params.action ?? "");
+  const { mount, path } = typeof params.path === "string" ? route(runtime, params.path) : { mount: runtime.mounts[0], path: "" };
+  const store = mount.store;
+  const qualify = (p: string) => (mount.name ? `${mount.name}:${p}` : p);
+
+  switch (action) {
+    case "read": {
+      if (!path) return "read needs a path.";
+      const article = store.resolve(path);
+      if (!article) {
+        return `No article governs ${path}. If you are working on this asset, create its article with write after the task.`;
+      }
+      surfacer.markSeen(qualify(article.path));
+      const title = article.path === path ? qualify(article.path) : `${qualify(article.path)} governs ${qualify(path)}`;
+      const head = [
+        article.capsule ? `capsule: ${article.capsule}` : "",
+        article.updated ? `updated: ${article.updated}` : "",
+      ].filter(Boolean).join("\n");
+      /* Filenames only, newest three: the index invites digging, it never pays for it. */
+      const mentions = runtime.mounts[0].store.journalMentions(qualify(article.path));
+      const recent = mentions.slice(-3).reverse();
+      const earlier = mentions.length - recent.length;
+      const index = recent.length
+        ? `\n\njournal: ${recent.join(", ")}${earlier ? ` and ${earlier} earlier` : ""}`
+        : "";
+      return `${title}\n${head}\n\n${article.body}`.trim() + index;
+    }
+    case "write": {
+      if (!path) return "write needs a path.";
+      /* Blank means untouched: models fill declared string fields with "" routinely,
+         and a "" here would silently erase stored content. */
+      const priorBody = params.body ? store.read(path)?.body : undefined;
+      const article = store.write(path, {
+        capsule: params.capsule ? String(params.capsule) : undefined,
+        body: params.body ? String(params.body) : undefined,
+      });
+      surfacer.markUpdated(qualify(article.path));
+      return [`Wrote ${qualify(article.path)}.`, ...advise(article, store, priorBody)].join("\n");
+    }
+    case "journal": {
+      const body = typeof params.body === "string" ? params.body.trim() : "";
+      if (!body) return "journal needs a body: what happened, densely.";
+      /* Events are project history; the journal always lives in the project store,
+         with subjects qualified so mounted articles index them too. */
+      const subject = Array.isArray(params.subject)
+        ? params.subject.map((s) => {
+            const routed = route(runtime, String(s));
+            return routed.mount.name ? `${routed.mount.name}:${routed.path}` : routed.path;
+          })
+        : undefined;
+      const file = runtime.mounts[0].store.journal({
+        body,
+        subject,
+        slug: typeof params.slug === "string" ? params.slug : undefined,
+      });
+      return `Logged ${basename(file)}.`;
+    }
+    case "map":
+      return store.map(path);
+    default:
+      return `Unknown action "${action}". Actions: read, write, journal, map.`;
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "pi-canon",
+  "version": "0.1.0",
+  "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": {
+    ".": "./extensions/index.js"
+  },
+  "pi": {
+    "extensions": ["./extensions"]
+  },
+  "files": ["extensions", "README.md", "LICENSE"],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.83.0 <1"
+  },
+  "scripts": {
+    "test": "node tests/verify.mjs"
+  },
+  "keywords": ["pi-package", "pi", "pi-extension", "memory", "knowledge", "agent", "wiki"],
+  "author": "Shane Conner",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shaneconner/pi-canon.git"
+  },
+  "bugs": "https://github.com/shaneconner/pi-canon/issues",
+  "homepage": "https://github.com/shaneconner/pi-canon#readme",
+  "devDependencies": {
+    "jiti": "^2.7.0"
+  }
+}