phaedo-mcp 0.3.7 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phaedo-mcp",
-  "version": "0.3.7",
+  "version": "0.3.13",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",
@@ -50,6 +50,12 @@
     "receipts.js",
     "receipts-sync.js",
     "agreement.js",
+    "weekly.js",
+    "precedent.js",
+    "rules-files.js",
+    "learned.js",
+    "history-import.js",
+    "agent-hooks.js",
     "calibration.js",
     "health.js",
     "phone-source.js",
@@ -88,14 +94,16 @@
     "setup": "node install.mjs",
     "setup:pair": "node install.mjs --pair",
     "setup:code-hook": "node install.mjs --code-hook",
+    "setup:agent-hooks": "node install.mjs --agent-hooks",
     "setup:capture-model": "node install.mjs --capture-model",
     "unsetup": "node install.mjs --uninstall",
     "pair": "node pair.js",
     "pull": "node pull.js",
-    "test": "node test-smoke.mjs && node test-no-profile.mjs && node test-phone-boundary.mjs && node test-cache.mjs && node test-pairing.mjs && node test-revoke.mjs && node test-install.mjs && node test-consult.mjs && node test-consult-policy.mjs && node test-amount-bands.mjs && node test-resolver-revision.mjs && node test-ship-actions.mjs && node test-ship-hook.mjs && node test-ship-readout.mjs && node test-action-binding.mjs && node test-autonomy-promotion.mjs && node test-ap2.mjs && node test-delegation-sync.mjs && node test-delegation-relay.mjs && node test-capture-sync.mjs && node test-capture-hook.mjs && node test-stop-capture.mjs && node test-capture-local.mjs && node test-capture-a11y.mjs && node test-vendored-capture.mjs && node test-escalation.mjs && node test-domain.mjs && node test-receipts.mjs && node test-receipts-sync.mjs && node test-agreement.mjs && node test-calibration.mjs && node test-identity.mjs && node test-signing.mjs && node test-sign-request.mjs && node test-signing-audit.mjs && node test-delegation-domain-fragmentation.mjs && node test-stale-authority.mjs && node test-config-home-fold.mjs && node test-precedence-and-ceiling.mjs && node test-package-closure.mjs && node test-plugin.mjs",
+    "test": "node test-smoke.mjs && node test-no-profile.mjs && node test-phone-boundary.mjs && node test-cache.mjs && node test-pairing.mjs && node test-revoke.mjs && node test-install.mjs && node test-consult.mjs && node test-consult-policy.mjs && node test-amount-bands.mjs && node test-resolver-revision.mjs && node test-ship-actions.mjs && node test-ship-hook.mjs && node test-ship-readout.mjs && node test-action-binding.mjs && node test-autonomy-promotion.mjs && node test-ap2.mjs && node test-delegation-sync.mjs && node test-delegation-relay.mjs && node test-capture-sync.mjs && node test-capture-hook.mjs && node test-stop-capture.mjs && node test-capture-local.mjs && node test-capture-a11y.mjs && node test-vendored-capture.mjs && node test-escalation.mjs && node test-domain.mjs && node test-receipts.mjs && node test-receipts-sync.mjs && node test-agreement.mjs && node test-weekly.mjs && node test-precedent.mjs && node test-rules-files.mjs && node test-agent-hook.mjs && node test-learned.mjs && node test-history-import.mjs && node test-calibration.mjs && node test-identity.mjs && node test-signing.mjs && node test-sign-request.mjs && node test-signing-audit.mjs && node test-delegation-domain-fragmentation.mjs && node test-stale-authority.mjs && node test-config-home-fold.mjs && node test-precedence-and-ceiling.mjs && node test-package-closure.mjs && node test-plugin.mjs",
     "receipts": "node receipts.js list",
     "agreement": "node agreement.js",
     "ship-readout": "node ship-readout.js",
+    "precedent": "node precedent.js",
     "calibration": "node calibration.js",
     "health": "node health.js",
     "validate": "node ../spec/validate-fingerprint.mjs sample-fingerprint.json",
@@ -113,7 +121,11 @@
     "smoke:calibration": "node test-calibration.mjs",
     "smoke:binding": "node test-action-binding.mjs",
     "smoke:autonomy": "node test-autonomy-promotion.mjs",
-    "smoke:ap2": "node test-ap2.mjs"
+    "smoke:ap2": "node test-ap2.mjs",
+    "week": "node weekly.js",
+    "rules": "node rules-files.js",
+    "learned": "node learned.js",
+    "import": "node history-import.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/precedent.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// Phaedo — situational precedent, Phase 2 (proposal 0009, design doc §9 / G8 B4).
+//
+// A §10 consultation answers dispositionally ("this subject favors caution"). An agent can act
+// on a precedent: "you have faced this shape 6 times; approved 5, edited 1." This module is the
+// derived view that would say so — over the §10.6 receipt store, never a stored artifact.
+//
+// PURE: (receipts, opts) -> report. No I/O, `now` injected — the agreement.js discipline.
+// NOT WIRED into consult: 0009 is a draft, and its rail 4 says precedent informs and never
+// authorizes. Dev-only readout: `npm run precedent`.
+//
+// The SHAPE is the situation key — banded features only, a closed vocabulary per field, so
+// nothing a receipt holds on-device (summary, exact amount, counterparty, ids, previews) can
+// leave through it (0009 rail 1):
+//
+//   domain       canonical §10.2 term when there is one, else the normalized free-text domain
+//   kind         merge | deploy | push to main | publish | message | payment | … | other
+//   reversible   true | false | null
+//   magnitude    low | medium | high | null            (as the agent described it)
+//   amount_band  none | low | medium | high            (against the subject's own edges, G8 B1)
+//   size         normal | large | null                 (the diff, when GitHub was read)
+//   touched      ordinary | sensitive | null           (the paths, when GitHub was read)
+//   binding      shell | connected_app | agent_tool | none   (what would carry the action out)
+//
+// Rails enforced here (0009 "Rails proposed for normative status"):
+//   1. banded features only — shapeOf() reads nothing else into the key;
+//   2. minimum support — below MIN_SUPPORT observations the answer is null, never a guess;
+//   3. subject-authored outcomes only — a burst of marks (BATCH_MIN within BATCH_WINDOW_MS)
+//      is bookkeeping, not consent, and is excluded (the §10.7 batch gate, per receipt);
+//   5. pre-flight receipts (via phaedo_check_authorization) are counted apart, never mixed in.
+// Rails 4 and 6 are about use, not computation: nothing here produces a signal.
+
+import { actionKind } from './ship-readout.js';
+import { canonicalDomain, normalizeDomain } from './lib/domain.js';
+import { DECISIVE } from './agreement.js';
+import { BATCH_WINDOW_MS } from './autonomy-promotion.js';
+import { isMainModule } from './lib/is-main.js';
+
+export const SHAPE_REVISION = '2026-10-27.v0';
+export const SHAPE_FIELDS = Object.freeze(['domain', 'kind', 'reversible', 'magnitude', 'amount_band', 'size', 'touched', 'binding']);
+export const DEFAULT_WINDOW_DAYS = 180;
+export const MIN_SUPPORT = 5;
+export const BATCH_MIN = 3;                 // this many marks inside BATCH_WINDOW_MS = a burst
+export const PREFLIGHT_VIA = 'phaedo_check_authorization';
+
+const DAY = 24 * 60 * 60 * 1000;
+const OUTCOMES = new Set(['approved', 'rejected', 'modified']);
+const MAGNITUDES = new Set(['low', 'medium', 'high']);
+
+const driver = (r, cue) => (Array.isArray(r?.drivers) ? r.drivers.find((d) => d && d.cue === cue) : null)?.value ?? null;
+
+function domainOf(raw) {
+  if (typeof raw !== 'string' || !raw.trim()) return '(none)';
+  return canonicalDomain(raw) || normalizeDomain(raw) || '(none)';
+}
+
+function amountBandOf(r) {
+  const a = r?.request?.action_descriptor?.amount;
+  if (typeof a !== 'number' || !Number.isFinite(a) || a <= 0) return 'none';
+  // consult-core only writes amountBand when the amount raised the stakes; a positive
+  // amount without one sat below the subject's low edge.
+  const b = driver(r, 'amountBand');
+  return b === 'medium' || b === 'high' ? b : 'low';
+}
+
+function bindingOf(r) {
+  const t = r?.request?.action_binding?.tool_name;
+  if (typeof t !== 'string' || !t) return 'none';
+  if (t === 'Bash') return 'shell';
+  if (t.startsWith('mcp__')) return 'connected_app';
+  return 'agent_tool';
+}
+
+/** The situation a receipt was about, as banded features. Never throws. */
+export function shapeOf(r) {
+  const ad = r?.request?.action_descriptor || {};
+  const stakes = driver(r, 'diffStakes');        // normal | large | sensitive | large+sensitive | unknown
+  const read = typeof stakes === 'string' && stakes !== 'unknown';
+  return {
+    domain: domainOf(ad.domain),
+    kind: actionKind(ad.summary),
+    reversible: typeof ad.reversible === 'boolean' ? ad.reversible : null,
+    magnitude: MAGNITUDES.has(ad.magnitude) ? ad.magnitude : null,
+    amount_band: amountBandOf(r),
+    size: read ? (stakes.includes('large') ? 'large' : 'normal') : null,
+    touched: read ? (stakes.includes('sensitive') ? 'sensitive' : 'ordinary') : null,
+    binding: bindingOf(r),
+  };
+}
+
+/** A stable string for a shape over `fields` (a coarser key = fewer fields). */
+export function shapeKey(shape, fields = SHAPE_FIELDS) {
+  return fields.map((f) => `${f}=${shape?.[f] ?? 'null'}`).join('|');
+}
+
+/** Only the requested fields of a shape — what may cross the boundary. */
+export function projectShape(shape, fields = SHAPE_FIELDS) {
+  return Object.fromEntries(fields.map((f) => [f, shape?.[f] ?? null]));
+}
+
+/**
+ * Receipt ids whose outcome was marked in a burst: BATCH_MIN or more marks inside one
+ * windowMs span. Receipts without a mark time are never batch (absence of evidence).
+ */
+export function batchMarkedIds(receipts, { windowMs = BATCH_WINDOW_MS, batchMin = BATCH_MIN } = {}) {
+  const marked = (Array.isArray(receipts) ? receipts : [])
+    .map((r) => ({ id: r?.receipt_id, t: Date.parse(r?.user_action_at) }))
+    .filter((x) => x.id && Number.isFinite(x.t))
+    .sort((a, b) => a.t - b.t);
+  const out = new Set();
+  let i = 0;
+  for (let j = 0; j < marked.length; j++) {
+    while (marked[j].t - marked[i].t > windowMs) i++;
+    if (j - i + 1 >= batchMin) for (let k = i; k <= j; k++) out.add(marked[k].id);
+  }
+  return out;
+}
+
+function agrees(signal, action) {
+  if (action === 'approved') return signal === 'proceed' || signal === 'proceed_with_note';
+  if (action === 'rejected') return signal === 'decline';
+  return false;   // modified: not accepted as-judged (agreement.js v0, conservative)
+}
+
+// The receipts that may count as evidence at all: in the window, subject-marked, not in a burst.
+function evidence(receipts, { now, windowDays, windowMs, batchMin }) {
+  const since = now - windowDays * DAY;
+  const list = Array.isArray(receipts) ? receipts : [];
+  const batch = batchMarkedIds(list, { windowMs, batchMin });
+  const out = { usable: [], excluded_batch: 0 };
+  for (const r of list) {
+    const t = Date.parse(r?.created_at);
+    if (!Number.isFinite(t) || t < since || t > now) continue;
+    if (!OUTCOMES.has(r?.user_action)) continue;
+    if (batch.has(r.receipt_id)) { out.excluded_batch++; continue; }
+    out.usable.push({ r, t });
+  }
+  return out;
+}
+
+function tally(items, now) {
+  const user_actions = { approved: 0, rejected: 0, modified: 0 };
+  let scored = 0, agreed = 0, lastDivergence = null;
+  for (const { r, t } of items) {
+    user_actions[r.user_action]++;
+    const signal = r?.response?.signal;
+    if (!DECISIVE.includes(signal)) continue;
+    scored++;
+    if (agrees(signal, r.user_action)) agreed++;
+    else if (lastDivergence === null || t > lastDivergence) lastDivergence = t;
+  }
+  return {
+    observed: items.length,
+    user_actions,
+    oracle_agreement: scored ? Math.round((agreed / scored) * 100) / 100 : null,
+    most_recent_divergence_days_ago: lastDivergence === null ? null : Math.floor((now - lastDivergence) / DAY),
+  };
+}
+
+/**
+ * The precedent for one situation, or null below minimum support (rail 2 — never a guess).
+ * `shape` may be a receipt's shapeOf() or any object with the SHAPE_FIELDS; `fields` picks
+ * how coarse the match is. The result carries banded features and counts only (rail 1).
+ */
+export function precedentFor(receipts, shape, {
+  now = Date.now(), windowDays = DEFAULT_WINDOW_DAYS, minSupport = MIN_SUPPORT,
+  fields = SHAPE_FIELDS, windowMs = BATCH_WINDOW_MS, batchMin = BATCH_MIN,
+} = {}) {
+  const want = shapeKey(shape, fields);
+  const { usable } = evidence(receipts, { now, windowDays, windowMs, batchMin });
+  const match = usable.filter(({ r }) => shapeKey(shapeOf(r), fields) === want);
+  const main = match.filter(({ r }) => r.via !== PREFLIGHT_VIA);
+  if (main.length < minSupport) return null;
+  const pre = match.filter(({ r }) => r.via === PREFLIGHT_VIA);
+  const { observed, user_actions, oracle_agreement, most_recent_divergence_days_ago } = tally(main, now);
+  return {
+    shape: projectShape(shape, fields),
+    shape_revision: SHAPE_REVISION,
+    observed,
+    user_actions,
+    oracle_agreement,
+    window_days: windowDays,
+    most_recent_divergence_days_ago,
+    preflight: { observed: pre.length, user_actions: tally(pre, now).user_actions },
+  };
+}
+
+/**
+ * The divergence episodes — the only thing 0009's principle says is worth keeping: receipts
+ * where a decisive prediction did not match what the subject did. Banded, newest first.
+ */
+export function divergenceEpisodes(receipts, {
+  now = Date.now(), windowDays = DEFAULT_WINDOW_DAYS, fields = SHAPE_FIELDS,
+  windowMs = BATCH_WINDOW_MS, batchMin = BATCH_MIN,
+} = {}) {
+  const { usable } = evidence(receipts, { now, windowDays, windowMs, batchMin });
+  return usable
+    .filter(({ r }) => DECISIVE.includes(r?.response?.signal) && !agrees(r.response.signal, r.user_action))
+    .sort((a, b) => b.t - a.t)
+    .map(({ r, t }) => ({
+      shape: projectShape(shapeOf(r), fields),
+      predicted: r.response.signal,
+      user_action: r.user_action,
+      days_ago: Math.floor((now - t) / DAY),
+      preflight: r.via === PREFLIGHT_VIA,
+    }));
+}
+
+/**
+ * Every shape seen in the window with its support — the readout's table, and the data for
+ * choosing N, the window and the coarseness of the key (0009 "Open").
+ */
+export function precedentTable(receipts, {
+  now = Date.now(), windowDays = DEFAULT_WINDOW_DAYS, minSupport = MIN_SUPPORT,
+  fields = SHAPE_FIELDS, windowMs = BATCH_WINDOW_MS, batchMin = BATCH_MIN,
+} = {}) {
+  const { usable, excluded_batch } = evidence(receipts, { now, windowDays, windowMs, batchMin });
+  const groups = new Map();
+  for (const item of usable) {
+    if (item.r.via === PREFLIGHT_VIA) continue;
+    const s = shapeOf(item.r);
+    const k = shapeKey(s, fields);
+    if (!groups.has(k)) groups.set(k, { shape: projectShape(s, fields), items: [] });
+    groups.get(k).items.push(item);
+  }
+  const shapes = [...groups.values()]
+    .map(({ shape, items }) => ({ shape, ...tally(items, now), supported: items.length >= minSupport }))
+    .sort((a, b) => b.observed - a.observed);
+  return {
+    window_days: windowDays,
+    min_support: minSupport,
+    fields: [...fields],
+    usable: usable.length,
+    excluded_batch,
+    shapes,
+  };
+}
+
+const show = (shape) => Object.entries(shape).filter(([, v]) => v !== null && v !== 'none' && v !== '(none)').map(([k, v]) => `${k}=${v}`).join(' ');
+
+export function formatTable(t) {
+  const lines = [
+    `Precedent — last ${t.window_days} days, ${t.usable} marked decision(s) usable` +
+      (t.excluded_batch ? `, ${t.excluded_batch} left out as marked in a burst` : '') + '.',
+    `Key: ${t.fields.join(' × ')}. A shape needs ${t.min_support} to answer.`,
+  ];
+  if (!t.shapes.length) lines.push('  No marked decisions yet — nothing to show.');
+  for (const s of t.shapes) {
+    const a = s.user_actions;
+    const agree = s.oracle_agreement === null ? 'no decisive calls' : `matched ${Math.round(s.oracle_agreement * 100)}%`;
+    const div = s.most_recent_divergence_days_ago === null ? '' : `, last miss ${s.most_recent_divergence_days_ago}d ago`;
+    lines.push(`  ${s.supported ? '✓' : '·'} ${s.observed}× ${show(s.shape)} — yes ${a.approved}, no ${a.rejected}, edited ${a.modified}; ${agree}${div}`);
+  }
+  return lines.join('\n');
+}
+
+if (isMainModule(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const num = (flag, d) => { const i = args.indexOf(flag); const n = i >= 0 ? Number(args[i + 1]) : NaN; return Number.isFinite(n) && n > 0 ? n : d; };
+  const fi = args.indexOf('--fields');
+  const fields = fi >= 0 ? String(args[fi + 1] || '').split(',').filter((f) => SHAPE_FIELDS.includes(f)) : SHAPE_FIELDS;
+  const { readReceipts } = await import('./receipts.js');
+  const { defaultStateDir } = await import('./cache.js');
+  const receipts = await readReceipts(defaultStateDir()).catch(() => []);
+  const t = precedentTable(receipts, { windowDays: num('--days', DEFAULT_WINDOW_DAYS), minSupport: num('--min', MIN_SUPPORT), fields: fields.length ? fields : SHAPE_FIELDS });
+  process.stdout.write(formatTable(t) + '\n');
+}

package/pull.js

@@ -8,9 +8,18 @@
 import { fileURLToPath } from 'url';
 import { dirname } from 'path';
 import { loadFingerprint, sourceOf, summarizeStarter } from './fingerprint-source.js';
+import { readReceipts } from './receipts.js';
+import { defaultStateDir } from './cache.js';
+import { weeklyHandled, formatWeekly } from './weekly.js';
+import { learnedItems, readLearnedState, reviewLine } from './learned.js';
 
 const BASE_DIR = dirname(fileURLToPath(import.meta.url));
 
+// Every outcome ends with what Phaedo did for the subject this week — the reason to have it.
+const week = async () => `  ${formatWeekly(weeklyHandled(await readReceipts(defaultStateDir()).catch(() => [])))}\n`;
+// …and, when there is any, what Phaedo learned that the subject hasn't looked at yet.
+const review = (vd) => { const line = reviewLine(learnedItems(vd), readLearnedState(defaultStateDir())); return line ? `  ${line}\n` : ''; };
+
 loadFingerprint(BASE_DIR)
   .then(async (vd) => {
     const fp = (vd && vd.phaedo_fingerprint) || {};
@@ -28,12 +37,14 @@ loadFingerprint(BASE_DIR)
         `  ${learned} thing(s) learned across ${areas} area(s)${sessions ? ` from ${sessions} session(s)` : ''} — ${stage}\n` +
         `  Pair the Phaedo phone app (npm run pair) to replace it with your full profile.\n`
       );
+      process.stdout.write(await week() + review(vd));
       process.exit(0);
     }
     if (src.live) {
       process.stdout.write(
         `✓ Read your profile from the phone — fingerprint ${fp.fingerprint_id || '(no id)'}, ${layers} layer(s).\n`
       );
+      process.stdout.write(await week() + review(vd));
       process.exit(0);
     }
     const hours = src.ageMs != null ? Math.round(src.ageMs / 3600000) : null;
@@ -43,9 +54,11 @@ loadFingerprint(BASE_DIR)
       `  Anything you changed since then — including a revoked authorization — is NOT reflected.\n` +
       `  Open Phaedo on your phone and approve the card, then run this again.\n`
     );
+    process.stdout.write(await week() + review(vd));
     process.exit(2);                       // distinct from 1 (hard failure) — stale, not broken
   })
-  .catch((err) => {
+  .catch(async (err) => {
     process.stderr.write(`✗ Couldn't read your profile: ${err.message}\n`);
+    process.stdout.write(await week());
     process.exit(1);
   });

package/receipts-sync.js

@@ -29,6 +29,7 @@
 import { Phaedo, b64uDec } from './lib/phaedo-crypto.js';
 import { readReceipts, markOutcome, USER_ACTIONS } from './receipts.js';
 import { agreementDigest } from './agreement.js';
+import { weeklyHandled, formatWeekly } from './weekly.js';
 
 const { Kdf, Envelope } = Phaedo;
 const DEFAULT_RELAY = 'https://phaedo-relay.fly.dev';
@@ -95,7 +96,11 @@ export async function buildReceiptsDeposit(pairKeyB64u, receipts, { cap = DIGEST
     pairKey.fill(0);
   }
   try {
-    const inner = { kind: 'receipts_digest', data: { receipts: head, agreement, generated_at: generatedAt } };
+    // The visible win: what Phaedo handled without interrupting the subject this week. Counts
+    // plus the sentence the MCP already shows in /phaedo:status, so both surfaces say the same.
+    const w = weeklyHandled(list, { now: Number.isFinite(agreementAt) ? agreementAt : Date.now() });
+    const week = { ...w, summary: formatWeekly(w) };
+    const inner = { kind: 'receipts_digest', data: { receipts: head, agreement, week, generated_at: generatedAt } };
     const plaintext = new TextEncoder().encode(JSON.stringify(inner));
     const envelope = await Envelope.wrap(plaintext, fpSyncKey, { artifact_kind: 'receipts_digest', created_at: now() });
     plaintext.fill(0);

package/rules-files.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+// Phaedo — write what Phaedo has learned into other agents' own instruction files.
+//
+// Claude Code gets the profile from the SessionStart hook. Codex, Copilot CLI, Gemini CLI and
+// Antigravity have no such hook, but each reads a user-level instructions file at the start of
+// every session. This writes a short version of the profile there, inside a marked block that
+// Phaedo owns and replaces; everything else in the file is left exactly as it was.
+//
+//   npm run rules                     # every agent found on this computer
+//   npm run rules -- --for codex,gemini
+//   npm run rules -- --project ~/code/app   # Cursor: .cursor/rules/phaedo.mdc, kept out of git
+//   npm run rules -- --remove         # take the block out again
+//   npm run rules -- --dry-run        # show what would be written
+//
+// User-level files only, by default: a profile in a repository's AGENTS.md would be committed
+// and shared. Cursor has no user-level rules file, so it takes an explicit project, and the
+// rule file is added to that repository's .git/info/exclude (local, never committed).
+//
+// Opt-in only. A file that already carries the block is how the subject said yes, so the
+// SessionStart hook refreshes those files (refreshExisting) and never adds new ones.
+
+import { homedir } from 'os';
+import { join, dirname, resolve } from 'path';
+import { promises as fs } from 'fs';
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { isMainModule } from './lib/is-main.js';
+
+export const BEGIN = '<!-- phaedo:begin — written by Phaedo and refreshed as it learns. Delete this whole block to stop. -->';
+export const END = '<!-- phaedo:end -->';
+export const MAX_CHARS = 6000;          // under Antigravity's ~12k per file and Codex's 32 KiB combined
+export const CURSOR_RULE = join('.cursor', 'rules', 'phaedo.mdc');
+
+// The sections an agent can act on, in the order they are worth keeping when space runs out.
+const KEEP = ['## Operating rules (user-confirmed)', '## How to respond to this user', '## How this user thinks'];
+
+/** The user-level instruction files Phaedo knows, for this home and environment. */
+export function targets({ home = homedir(), env = process.env } = {}) {
+  const codexHome = env.CODEX_HOME ? resolve(env.CODEX_HOME) : join(home, '.codex');
+  return {
+    codex:   { label: 'Codex', file: join(codexHome, 'AGENTS.md'), dir: codexHome },
+    copilot: { label: 'Copilot CLI', file: join(home, '.copilot', 'copilot-instructions.md'), dir: join(home, '.copilot') },
+    gemini:  { label: 'Gemini CLI and Antigravity', file: join(home, '.gemini', 'GEMINI.md'), dir: join(home, '.gemini') },
+    // Claude Code already gets the full profile from the SessionStart hook; only on request.
+    claude:  { label: 'Claude Code', file: join(home, '.claude', 'CLAUDE.md'), dir: join(home, '.claude'), onRequest: true },
+  };
+}
+
+function sections(projection) {
+  const body = String(projection || '').replace(/^\s*<phaedo_user_profile>\s*/, '').replace(/\s*<\/phaedo_user_profile>\s*$/, '');
+  const parts = body.split(/\n(?=## )/);
+  const preamble = parts[0].startsWith('## ') ? '' : parts.shift().trim();
+  const byHead = new Map(parts.map((p) => [p.split('\n', 1)[0].trim(), p.trim()]));
+  return { preamble, byHead };
+}
+
+/**
+ * The short profile for an instructions file, from the same projection Claude Code gets.
+ * PURE. Null when the projection has nothing an agent can act on.
+ */
+export function rulesText(projection, { now = Date.now(), maxChars = MAX_CHARS } = {}) {
+  const { preamble, byHead } = sections(projection);
+  const kept = KEEP.map((h) => byHead.get(h)).filter(Boolean);
+  if (!kept.length) return null;
+  const date = new Date(now).toISOString().slice(0, 10);
+  const head = [
+    '# How I like to work (from Phaedo)',
+    '',
+    `Learned by Phaedo and refreshed ${date}. ${preamble.replace(/\s+/g, ' ').trim()}`.trim(),
+  ].join('\n');
+  // Shed whole sections from the end first; cut inside one only if the first alone is too long.
+  while (kept.length > 1 && [head, ...kept].join('\n\n').length > maxChars) kept.pop();
+  let text = [head, ...kept].join('\n\n');
+  if (text.length > maxChars) text = text.slice(0, text.lastIndexOf('\n', maxChars)).trimEnd();
+  return text;
+}
+
+/** The managed block, markers included. */
+export function block(text) {
+  return `${BEGIN}\n${text}\n${END}`;
+}
+
+function findBlock(content) {
+  const b = content.indexOf('<!-- phaedo:begin');
+  const e = content.indexOf(END);
+  if (b < 0 && e < 0) return { state: 'absent' };
+  if (b < 0 || e < 0 || e < b || content.indexOf('<!-- phaedo:begin', b + 1) >= 0) return { state: 'broken' };
+  return { state: 'present', start: b, end: e + END.length };
+}
+
+/**
+ * The file's new content with the block put in (or replaced), everything else untouched.
+ * PURE. { content, changed } — or { error } when the markers are damaged, so a hand-edited
+ * file is never guessed at.
+ */
+export function upsertBlock(existing, text) {
+  const src = existing ?? '';
+  const f = findBlock(src);
+  if (f.state === 'broken') return { error: 'the Phaedo markers in this file are damaged — fix or delete them by hand' };
+  let content;
+  if (f.state === 'present') content = src.slice(0, f.start) + block(text) + src.slice(f.end);
+  else content = src.trim() ? `${src.replace(/\s*$/, '')}\n\n${block(text)}\n` : `${block(text)}\n`;
+  return { content, changed: content !== src };
+}
+
+/** The file's content with the block taken out. PURE. */
+export function removeBlock(existing) {
+  const src = existing ?? '';
+  const f = findBlock(src);
+  if (f.state === 'broken') return { error: 'the Phaedo markers in this file are damaged — fix or delete them by hand' };
+  if (f.state === 'absent') return { content: src, changed: false };
+  const before = src.slice(0, f.start).replace(/\s*$/, '');
+  const after = src.slice(f.end).replace(/^\s*/, '');
+  const content = before && after ? `${before}\n\n${after}` : before ? `${before}\n` : after;
+  return { content, changed: true };
+}
+
+export const hasBlock = (content) => findBlock(content ?? '').state === 'present';
+
+/** Cursor's project rule: a whole file Phaedo owns, always applied. PURE. */
+export function cursorRule(text) {
+  return [
+    '---',
+    'description: How I like to work, learned by Phaedo',
+    'alwaysApply: true',
+    '---',
+    '',
+    text,
+    '',
+  ].join('\n');
+}
+
+// ── I/O ───────────────────────────────────────────────────────────────────────
+
+const read = (file) => fs.readFile(file, 'utf8').catch((e) => (e.code === 'ENOENT' ? null : Promise.reject(e)));
+const exists = (p) => fs.stat(p).then(() => true, () => false);
+
+async function writeAtomic(file, content) {
+  await fs.mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.phaedo-${process.pid}.tmp`;
+  await fs.writeFile(tmp, content, 'utf8');
+  await fs.rename(tmp, file);
+}
+
+/** Put (or refresh) the block in one file. → { status: 'written'|'unchanged'|'error', error? } */
+export async function applyToFile(file, text, { dryRun = false } = {}) {
+  const r = upsertBlock(await read(file), text);
+  if (r.error) return { status: 'error', error: r.error };
+  if (!r.changed) return { status: 'unchanged' };
+  if (!dryRun) await writeAtomic(file, r.content);
+  return { status: 'written' };
+}
+
+export async function removeFromFile(file, { dryRun = false } = {}) {
+  const src = await read(file);
+  if (src === null) return { status: 'unchanged' };
+  const r = removeBlock(src);
+  if (r.error) return { status: 'error', error: r.error };
+  if (!r.changed) return { status: 'unchanged' };
+  if (!dryRun) await writeAtomic(file, r.content);
+  return { status: 'removed' };
+}
+
+/** Which agents to write for: those named, or every agent whose folder exists here. */
+export async function chooseTargets(all, names = null) {
+  if (names) return names.filter((n) => all[n]).map((n) => [n, all[n]]);
+  const out = [];
+  for (const [n, t] of Object.entries(all)) if (!t.onRequest && await exists(t.dir)) out.push([n, t]);
+  return out;
+}
+
+// Keep a project's Cursor rule out of git without touching its committed .gitignore.
+function excludeFromGit(projectDir) {
+  let excl;
+  try {
+    excl = execFileSync('git', ['-C', projectDir, 'rev-parse', '--git-path', 'info/exclude'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch { return false; }
+  return resolve(projectDir, excl);
+}
+
+export async function applyToCursorProject(projectDir, text, { dryRun = false } = {}) {
+  const file = join(projectDir, CURSOR_RULE);
+  const content = cursorRule(text);
+  const changed = (await read(file)) !== content;
+  const excl = excludeFromGit(projectDir);
+  const line = '/' + CURSOR_RULE.split('\\').join('/');
+  if (!dryRun) {
+    if (changed) await writeAtomic(file, content);
+    if (excl) {
+      const cur = (await read(excl)) || '';
+      if (!cur.split('\n').includes(line)) await writeAtomic(excl, `${cur.replace(/\s*$/, '')}${cur.trim() ? '\n' : ''}${line}\n`);
+    }
+  }
+  return { status: changed ? 'written' : 'unchanged', file, keptOutOfGit: Boolean(excl) };
+}
+
+/**
+ * Refresh only the files that already carry the block — the subject opted those in. Used by
+ * the SessionStart hook; never adds the block anywhere new, never throws.
+ */
+export async function refreshExisting(projection, { home, env, now } = {}) {
+  const text = rulesText(projection, { now });
+  if (!text) return [];
+  const out = [];
+  for (const [name, t] of Object.entries(targets({ home, env }))) {
+    try {
+      const src = await read(t.file);
+      if (!hasBlock(src)) continue;
+      out.push({ name, ...(await applyToFile(t.file, text)) });
+    } catch { /* one unreadable file never stops the rest */ }
+  }
+  return out;
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+const tilde = (p) => (p.startsWith(homedir()) ? '~' + p.slice(homedir().length) : p);
+
+async function main(argv) {
+  const flag = (f) => argv.includes(f);
+  const opt = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : null; };
+  const dryRun = flag('--dry-run');
+  const names = opt('--for') ? opt('--for').split(',').map((s) => s.trim().toLowerCase()).filter(Boolean) : null;
+  const project = opt('--project');
+  const all = targets();
+  if (names) {
+    const unknown = names.filter((n) => !all[n] && n !== 'cursor');
+    if (unknown.length) { process.stderr.write(`Unknown agent: ${unknown.join(', ')}. Known: ${Object.keys(all).join(', ')}, cursor (with --project).\n`); return 1; }
+  }
+  const chosen = await chooseTargets(all, names ? names.filter((n) => n !== 'cursor') : null);
+  const say = (s) => process.stdout.write(s + '\n');
+
+  if (flag('--remove')) {
+    for (const [, t] of names ? chosen : Object.entries(all)) {
+      const r = await removeFromFile(t.file, { dryRun });
+      if (r.status === 'removed') say(`✓ ${t.label}: took Phaedo's section out of ${tilde(t.file)}`);
+      else if (r.status === 'error') say(`✗ ${t.label}: ${r.error} (${tilde(t.file)})`);
+    }
+    if (project) {
+      const file = join(resolve(project), CURSOR_RULE);
+      if (await exists(file)) { if (!dryRun) await fs.rm(file); say(`✓ Cursor: removed ${tilde(file)}`); }
+    }
+    return 0;
+  }
+
+  const MCP_DIR = dirname(fileURLToPath(import.meta.url));
+  const { loadFingerprintPreferCache } = await import('./fingerprint-source.js');
+  const { buildInjectionResponse } = await import('./projection.js');
+  let text = null;
+  try {
+    const vd = await loadFingerprintPreferCache(MCP_DIR);
+    text = rulesText(buildInjectionResponse(vd, { requested_layers: ['all'], mode: 'standard' }).projection);
+  } catch { /* falls through to the message below */ }
+  if (!text) { say('Phaedo has no profile with rules or preferences yet, so nothing was written.'); return 0; }
+
+  if (dryRun) say(`Would write this (${text.length} characters):\n\n${text}\n`);
+  if (!chosen.length && !project) {
+    say('No other AI agents found on this computer (looked for Codex, Copilot CLI, Gemini CLI and Antigravity).');
+    say('Name one with --for codex,copilot,gemini,claude, or a Cursor project with --project <folder>.');
+    return 0;
+  }
+  let failed = false;
+  for (const [, t] of chosen) {
+    const r = await applyToFile(t.file, text, { dryRun });
+    if (r.status === 'error') { failed = true; say(`✗ ${t.label}: ${r.error} (${tilde(t.file)})`); }
+    else say(`✓ ${t.label}: ${r.status === 'written' ? (dryRun ? 'would update' : 'updated') : 'already up to date'} — ${tilde(t.file)}`);
+  }
+  if (project) {
+    const r = await applyToCursorProject(resolve(project), text, { dryRun });
+    say(`✓ Cursor: ${r.status === 'written' ? (dryRun ? 'would update' : 'updated') : 'already up to date'} — ${tilde(r.file)}${r.keptOutOfGit ? ' (kept out of git)' : ''}`);
+  }
+  if (!dryRun) say('Phaedo refreshes these whenever a Claude Code session starts with Phaedo on. To take them out: npm run rules -- --remove');
+  return failed ? 1 : 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => process.exit(code), (err) => { process.stderr.write(`✗ ${err.message}\n`); process.exit(1); });
+}