@lastboy/pai 0.2.0 → 0.4.0

package/README.md

@@ -58,7 +58,8 @@ pai review
 
 Shows your guidelines from the CLAUDE.md files that apply to the current
 folder — global (`~/.claude/CLAUDE.md`) and project (`CLAUDE.md`,
-`CLAUDE.local.md`) — grouped by their markdown headings.
+`CLAUDE.local.md`) — plus the PAI-managed `CLAUDE.pai.md` next to each, all
+grouped by their markdown headings. Managed files are labeled `PAI managed`.
 
 | Option | Effect |
 |---|---|
@@ -77,7 +78,23 @@ Search matches word starts, so `--search ask` finds "Ask me before…" but not
 
 ### `pai export`
 
-Exports PAI's own rule store as portable, versioned JSON.
+Exports the same rules `pai rules` shows — from `CLAUDE.md` and
+`CLAUDE.pai.md`, global then project — as portable, versioned JSON.
+`CLAUDE.local.md` is per-machine and is not exported.
+
+```json
+{
+  "version": 2,
+  "pai": "0.3.1",
+  "exportedAt": "2026-08-29T12:00:00.000Z",
+  "rules": [ { "rule": "…", "category": "…", "scope": "global" } ]
+}
+```
+
+`version` is the export format (for compatibility checks), `pai` is the PAI
+version that produced the file, and `exportedAt` is when it was written;
+files from a newer format than this `pai` supports are rejected with an
+upgrade hint.
 
 | Option | Effect |
 |---|---|
@@ -92,30 +109,46 @@ pai export --scope global --out mine.json   # only user-level rules
 ### `pai import <file>`
 
 Merges a previously exported file into this machine. Rules carry their own
-scope, so global rules land in the global store and project rules in the
-current project's store — no flag needed.
-
-The merge is **non-destructive**: new rules are added, rules you already have
-gain any new evidence, and nothing is overwritten or removed. Re-importing the
-same file changes nothing.
+scope: global rules go to `~/.claude/CLAUDE.pai.md`, project rules to
+`<project>/CLAUDE.pai.md` — no flag needed. For each scope PAI:
+
+1. makes sure `CLAUDE.md` exists and contains the import line `@CLAUDE.pai.md`
+   (created with only that line if missing; the line is appended in place if
+   absent, so a symlinked CLAUDE.md stays a symlink; nothing else in the file
+   is touched);
+2. adds the rules that `CLAUDE.pai.md` does not have yet, under their category
+   headings, keeping everything already there exactly as it is.
+
+The merge is **non-destructive** and idempotent: nothing is overwritten or
+removed, and re-importing the same file adds nothing. Rule identity is the
+normalized text (case, punctuation, whitespace and line endings ignored).
+Hand-written `CLAUDE.md` rules are never used for deduplication — only
+`CLAUDE.pai.md` is. Files from the older `version: 1` store format are accepted.
 
 | Option | Effect |
 |---|---|
-| `--dry-run` | report what would change without writing |
+| `--dry-run` | report what would change ("would add …") without writing |
+| `--validate` | check the file only — parse, migrate, validate — and print a summary; writes nothing |
 
 ```bash
 pai import mine.json --dry-run
 pai import mine.json
+pai import mine.json --validate
 ```
 
 Invalid or unsupported files fail with a clear message and a non-zero exit code.
+Files from an older export format are migrated automatically; files from a
+newer format than this `pai` supports are rejected with an upgrade hint. See
+[the export format contract](docs/export-format.md) for the full JSON shape,
+field constraints, and migration/compatibility rules.
 
-**Cross-platform.** A store exported on macOS or Linux imports on Windows and
-back. Stores contain no filesystem paths, so nothing is machine-specific, and
+**Cross-platform.** A file exported on macOS or Linux imports on Windows and
+back. Exports contain no filesystem paths, so nothing is machine-specific, and
 import accepts the encodings Windows tooling produces: UTF-8, UTF-8 with a BOM
 (Notepad, `Set-Content`) and UTF-16 with a BOM (PowerShell 5.1's `>` redirect).
 Line endings are normalized, so the same rule written on Windows and on
-macOS/Linux merges as one instead of duplicating.
+macOS/Linux counts as one instead of duplicating; `CLAUDE.pai.md` is always
+written as UTF-8 with LF line endings.
 
 ### `pai experiment …`
 
@@ -134,26 +167,29 @@ Default model: `qwen2.5:14b`.
 
 ## Where PAI stores things
 
-| Path | Contents |
-|---|---|
-| `~/.pai/rules.json` | your user-level rules |
-| `<project>/.pai/rules.json` | rules scoped to that project |
+Your rules have one source of truth: the CLAUDE.md family of files the coding
+agent already reads.
 
-The store is agent-neutral, versioned (`version: 1`), and portable: rule
-identity comes from the rule text, so the same rule learned on two machines
-merges cleanly instead of duplicating. Each rule keeps its category, scope,
-source (`learned` or `manual`) and evidence — your actual words, with session id
-and timestamp.
+| Path | Contents | Who writes it |
+|---|---|---|
+| `~/.claude/CLAUDE.md` | your hand-written global rules | you |
+| `~/.claude/CLAUDE.pai.md` | global rules PAI added | PAI |
+| `<project>/CLAUDE.md` | hand-written project rules | you |
+| `<project>/CLAUDE.pai.md` | project rules PAI added | PAI |
+| `~/.pai/`, `<project>/.pai/` | reserved for PAI metadata (future) | PAI |
 
-PAI **never writes** to `~/.claude/` or to any CLAUDE.md file.
+PAI never merges into a hand-written CLAUDE.md. The only change it makes there
+is adding the single line `@CLAUDE.pai.md` — Claude Code's native import — so
+the agent reads the managed file too. Rule identity comes from the rule text,
+so the same rule imported twice, or written on two machines, counts once.
 
 ## What PAI reads
 
 | Path | Used for |
 |---|---|
 | `~/.claude/projects/<encoded-cwd>/*.jsonl` | session transcripts (read-only) |
-| `~/.claude/CLAUDE.md` | global guidelines |
-| `<project>/CLAUDE.md`, `CLAUDE.local.md` | project guidelines |
+| `~/.claude/CLAUDE.md`, `CLAUDE.pai.md` | global guidelines |
+| `<project>/CLAUDE.md`, `CLAUDE.local.md`, `CLAUDE.pai.md` | project guidelines |
 
 The encoded folder name is the project path with every non-alphanumeric
 character replaced by `-`.
@@ -163,7 +199,7 @@ character replaced by `-`.
 ```
 src/core/          agent-independent logic (sessions, corrections, rules, review)
 src/adapters/      per-agent integration — currently only claude/
-src/persistence/   PAI's own store on disk
+src/persistence/   file I/O — CLAUDE.pai.md, text decoding, the .pai/ store
 src/experiments/   local-LLM experiments (Ollama, optional)
 src/cli/           command wiring and rendering
 tests/             vitest suites and sanitized fixtures
@@ -191,6 +227,17 @@ repository.
 Working today: `status`, `review`, `rules`, `export`, `import`, and the two
 experiments.
 
-Next: `pai learn` — scan sessions, distill candidate rules, approve or reject
-them interactively, and store the approved ones. Then auditing sessions against
-stored rules (which rules the agent actually violated, with evidence).
+Next: see [Roadmap](#roadmap).
+
+## Roadmap
+
+- **`pai learn`** — scan sessions, distill candidate rules with a local model, approve/reject/edit interactively, write approved rules to `CLAUDE.pai.md`.
+- **Compliance audit** — check sessions against your rules and report violations with evidence (which rule, how often, your own words) — the "is the agent following my guidance" measure.
+- **Trends** — violations over time, before/after a rule was added, and comparison across models/configurations.
+- **Cross-project promotion** — rules that keep appearing in several projects get proposed as global rules.
+- **Better session review** — active time instead of wall-clock duration, filtering out headless/automation sessions.
+- **Long-list UX** — category summaries with counts, `--category`, an interactive picker.
+- **More agents** — Codex CLI adapter (`AGENTS.md`); the core stays agent-independent.
+- **Optional integrations, only if needed** — Claude Code hooks for real-time capture; MCP so the agent can ask PAI about rules.
+
+Order is not a commitment; each item ships as its own small, tested step.

package/dist/adapters/claude/guidelines.js

@@ -1,33 +1,44 @@
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
+import { parseGuidelines } from '../../core/guidelines.js';
+export { parseGuidelines };
+/** PAI's own guidance file, next to the hand-written CLAUDE.md. */
+export const MANAGED_FILE_NAME = 'CLAUDE.pai.md';
+/** Claude Code's native import line; added once to CLAUDE.md so it reads ours. */
+export const POINTER_LINE = `@${MANAGED_FILE_NAME}`;
+const LOCAL_FILE_NAME = 'CLAUDE.local.md';
+/** Directory that holds a scope's CLAUDE.md family of files. */
+export function guidelineDir(scope, cwd, home = homedir()) {
+    return scope === 'global' ? join(home, '.claude') : cwd;
+}
+export function managedGuidelinePath(dir) {
+    return join(dir, MANAGED_FILE_NAME);
+}
+/** Everything `pai import` needs to know about one scope's directory. */
+export function managedImportTarget(dir) {
+    return {
+        claudeMdPath: join(dir, 'CLAUDE.md'),
+        managedPath: managedGuidelinePath(dir),
+        pointer: POINTER_LINE,
+    };
+}
 // Claude Code guidance locations: ~/.claude/CLAUDE.md (global) and
-// CLAUDE.md / CLAUDE.local.md at the project root. Parent-directory
-// traversal is not implemented yet.
+// CLAUDE.md / CLAUDE.local.md at the project root, each followed by the
+// PAI-managed sibling. Parent-directory traversal is not implemented yet.
 export function findGuidelineFiles(cwd, home = homedir()) {
+    const global = guidelineDir('global', cwd, home);
+    const project = guidelineDir('project', cwd, home);
     const candidates = [
-        { path: join(home, '.claude', 'CLAUDE.md'), scope: 'global' },
-        { path: join(cwd, 'CLAUDE.md'), scope: 'project' },
-        { path: join(cwd, 'CLAUDE.local.md'), scope: 'project' },
+        { path: join(global, 'CLAUDE.md'), scope: 'global', managed: false },
+        { path: managedGuidelinePath(global), scope: 'global', managed: true },
+        { path: join(project, 'CLAUDE.md'), scope: 'project', managed: false },
+        { path: join(project, LOCAL_FILE_NAME), scope: 'project', managed: false },
+        { path: managedGuidelinePath(project), scope: 'project', managed: true },
     ];
     return candidates.filter((candidate) => existsSync(candidate.path));
 }
-const HEADING = /^#{1,6}\s+(.+?)\s*$/;
-const BULLET = /^\s*[-*]\s+(.+?)\s*$/;
-export function parseGuidelines(markdown) {
-    const guidelines = [];
-    let category = 'General';
-    // A BOM (Windows editors) would otherwise hide the first heading.
-    for (const line of markdown.replace(/^/, '').split('\n')) {
-        const heading = HEADING.exec(line);
-        if (heading?.[1]) {
-            category = heading[1];
-            continue;
-        }
-        const bullet = BULLET.exec(line);
-        if (bullet?.[1]) {
-            guidelines.push({ category, text: bullet[1] });
-        }
-    }
-    return guidelines;
+/** Files that travel between machines: CLAUDE.local.md is per-machine and stays out. */
+export function findExportableGuidelineFiles(cwd, home = homedir()) {
+    return findGuidelineFiles(cwd, home).filter((file) => basename(file.path) !== LOCAL_FILE_NAME);
 }

package/dist/cli/program.js

@@ -12,10 +12,11 @@ import { detectPossibleCorrections } from '../core/corrections.js';
 import { analyzeWithOllama, buildCorrectionContext, buildPrompt, } from '../experiments/correction-analysis.js';
 import { ollamaGenerate } from '../experiments/ollama.js';
 import { buildDistillPrompt, parseDistillResponse } from '../experiments/rule-distillation.js';
-import { findGuidelineFiles, parseGuidelines } from '../adapters/claude/guidelines.js';
+import { findExportableGuidelineFiles, findGuidelineFiles, guidelineDir, managedImportTarget, } from '../adapters/claude/guidelines.js';
 import { filterGuidelineGroups } from '../core/guidelines.js';
-import { emptyStore, mergeStores, parseRuleStore, serializeRuleStore, } from '../core/rule-store.js';
-import { globalStorePath, projectStorePath, readStore, writeStore, } from '../persistence/rule-store-files.js';
+import { parseExportDocument, serializeExportDocument, toExportRules, } from '../core/managed-guidelines.js';
+import { CURRENT_EXPORT_FORMAT } from '../core/export-migrations.js';
+import { importManagedGuidelines, readGuidelineGroups, } from '../persistence/managed-guideline-files.js';
 import { decodeTextFile } from '../persistence/text-file.js';
 import { parseSelection, renderGuidelines, renderReview, renderSessionList } from './render.js';
 async function ask(question) {
@@ -53,8 +54,25 @@ async function chooseSession(out) {
 function describeError(error) {
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * Best-effort read of the file's own `pai`/`exportedAt` fields for the
+ * `--validate` summary. Only called after `parseExportDocument` has already
+ * succeeded on the same text, so this re-parse cannot fail in practice.
+ */
+function readExportMeta(text) {
+    try {
+        const parsed = JSON.parse(text.replace(/^/, ''));
+        return {
+            ...(typeof parsed['pai'] === 'string' ? { pai: parsed['pai'] } : {}),
+            ...(typeof parsed['exportedAt'] === 'string' ? { exportedAt: parsed['exportedAt'] } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
 // Same relative depth from src/cli and dist/cli.
-function packageVersion() {
+export function packageVersion() {
     const pkg = JSON.parse(readFileSync(join(import.meta.dirname, '..', '..', 'package.json'), 'utf8'));
     return pkg.version ?? '0.0.0';
 }
@@ -88,16 +106,11 @@ export function createProgram(out) {
     program
         .command('rules')
         .description('Show your guidelines from CLAUDE.md files, categorized')
-        .option('--global', 'only global rules (~/.claude/CLAUDE.md)')
-        .option('--project', 'only project rules (CLAUDE.md, CLAUDE.local.md)')
+        .option('--global', 'only global rules (~/.claude/CLAUDE.md, CLAUDE.pai.md)')
+        .option('--project', 'only project rules (CLAUDE.md, CLAUDE.local.md, CLAUDE.pai.md)')
         .option('--search <text>', 'only rules whose text or category starts a word with <text>')
-        .action(async (options) => {
-        const files = findGuidelineFiles(process.cwd());
-        const groups = await Promise.all(files.map(async (file) => ({
-            scope: file.scope,
-            path: file.path,
-            guidelines: parseGuidelines(decodeTextFile(await readFile(file.path))),
-        })));
+        .action((options) => {
+        const groups = readGuidelineGroups(findGuidelineFiles(process.cwd()));
         // --global and --project together = no scope filter (same as neither).
         const scope = options.global && !options.project
             ? 'global'
@@ -114,7 +127,7 @@ export function createProgram(out) {
     });
     program
         .command('export')
-        .description('Export PAI rules to a portable JSON file (or stdout)')
+        .description('Export your rules (CLAUDE.md + CLAUDE.pai.md) to a portable JSON file (or stdout)')
         .option('--out <file>', 'write to this file instead of stdout')
         .option('--scope <scope>', 'export only "global" or "project" rules')
         .action((options) => {
@@ -124,19 +137,19 @@ export function createProgram(out) {
             return;
         }
         try {
-            const global = readStore(globalStorePath());
-            const project = readStore(projectStorePath(process.cwd()));
-            const combined = {
-                ...emptyStore(),
-                rules: [...global.rules, ...project.rules].filter((rule) => options.scope === undefined || rule.scope === options.scope),
-            };
-            const json = serializeRuleStore(combined);
+            // Global files come first, so the output order is global → project.
+            const files = findExportableGuidelineFiles(process.cwd()).filter((file) => options.scope === undefined || file.scope === options.scope);
+            const rules = toExportRules(readGuidelineGroups(files));
+            const json = serializeExportDocument(rules, {
+                pai: packageVersion(),
+                exportedAt: new Date().toISOString(),
+            });
             if (options.out === undefined) {
                 out(json.trimEnd());
                 return;
             }
             writeFileSync(options.out, json, 'utf8');
-            out(`Exported ${combined.rules.length} rule(s) to ${options.out}`);
+            out(`Exported ${rules.length} rule(s) to ${options.out}`);
         }
         catch (error) {
             out(`Export failed: ${describeError(error)}`);
@@ -146,31 +159,61 @@ export function createProgram(out) {
     program
         .command('import')
         .argument('<file>', 'JSON file previously produced by "pai export"')
-        .description('Merge rules from a file into this machine (never overwrites)')
+        .description('Merge rules from a file into CLAUDE.pai.md on this machine (never overwrites)')
         .option('--dry-run', 'show what would change without writing')
+        .option('--validate', 'check the file only; print a summary and exit without writing')
         .action(async (file, options) => {
+        const text = decodeTextFile(await readFile(file));
         let incoming;
         try {
-            incoming = parseRuleStore(decodeTextFile(await readFile(file)));
+            incoming = parseExportDocument(text, { currentPaiVersion: packageVersion() });
         }
         catch (error) {
-            out(`Could not read ${file}: ${describeError(error)}`);
+            if (options.validate) {
+                for (const line of describeError(error).split('\n'))
+                    out(line);
+            }
+            else {
+                out(`Could not read ${file}: ${describeError(error)}`);
+            }
             process.exitCode = 1;
             return;
         }
-        const targets = [
-            { scope: 'global', path: globalStorePath() },
-            { scope: 'project', path: projectStorePath(process.cwd()) },
-        ];
+        if (options.validate) {
+            const meta = readExportMeta(text);
+            const paiPart = meta.pai !== undefined ? `pai ${meta.pai}` : 'pai unknown';
+            const exportedPart = meta.exportedAt !== undefined ? `, exported ${meta.exportedAt}` : '';
+            out(`Valid PAI export (format ${CURRENT_EXPORT_FORMAT}, ${paiPart}${exportedPart})`);
+            const global = incoming.rules.filter((rule) => rule.scope === 'global').length;
+            const project = incoming.rules.filter((rule) => rule.scope === 'project').length;
+            out(`Rules: ${incoming.rules.length} (global ${global}, project ${project})`);
+            if (incoming.migratedFrom !== undefined) {
+                out(`Migrated from format ${incoming.migratedFrom} (would be imported as format ${CURRENT_EXPORT_FORMAT})`);
+            }
+            return;
+        }
         try {
-            for (const target of targets) {
-                const rules = incoming.rules.filter((rule) => rule.scope === target.scope);
+            if (incoming.migratedFrom !== undefined) {
+                out(`Migrated from format ${incoming.migratedFrom}.`);
+            }
+            for (const scope of ['global', 'project']) {
+                const rules = incoming.rules.filter((rule) => rule.scope === scope);
                 if (rules.length === 0)
                     continue;
-                const result = mergeStores(readStore(target.path), { ...emptyStore(), rules });
-                if (!options.dryRun)
-                    writeStore(target.path, result.store);
-                out(`${target.scope}: ${result.added} added, ${result.merged} updated with new evidence, ${result.store.rules.length} total → ${target.path}`);
+                const dir = guidelineDir(scope, process.cwd());
+                out(`Target (${scope}): ${dir}`);
+                const result = importManagedGuidelines(managedImportTarget(dir), rules, {
+                    dryRun: options.dryRun,
+                });
+                const dry = options.dryRun === true;
+                if (result.pointer === 'created') {
+                    out(dry ? '  would create CLAUDE.md with pointer' : '  created CLAUDE.md with pointer');
+                }
+                if (result.pointer === 'appended') {
+                    out(dry ? '  would add pointer line to CLAUDE.md' : '  added pointer line to CLAUDE.md');
+                }
+                const added = dry ? `would add ${result.added} rule(s)` : `${result.added} added`;
+                out(`${scope}: ${added}, ${result.existing} already present → ${result.managedPath}`);
             }
         }
         catch (error) {

package/dist/cli/render.js

@@ -2,7 +2,8 @@ export function renderGuidelines(groups) {
     const lines = ['PAI — Guidelines'];
     for (const group of groups) {
         lines.push('');
-        lines.push(`${group.scope === 'global' ? 'Global' : 'Project'} (${group.path})`);
+        const scope = group.scope === 'global' ? 'Global' : 'Project';
+        lines.push(`${group.managed ? `${scope} — PAI managed` : scope} (${group.path})`);
         if (group.guidelines.length === 0) {
             lines.push('  (no guidelines found)');
             continue;

package/dist/core/export-migrations.js

@@ -0,0 +1,41 @@
+// Migration chain that brings an older PAI export up to the current format.
+// Pure: no I/O, no filesystem, no process access.
+import { parseRuleStore } from './rule-store.js';
+export const CURRENT_EXPORT_FORMAT = 2;
+/** Older `.pai/rules.json` stores carry the same three fields an export needs. */
+function v1ToV2(doc) {
+    const store = parseRuleStore(JSON.stringify(doc));
+    return {
+        version: 2,
+        rules: store.rules.map((r) => ({ rule: r.rule, category: r.category, scope: r.scope })),
+    };
+}
+// Adding a future migration is one new entry here: key N migrates format N to N+1.
+const MIGRATIONS = {
+    1: v1ToV2,
+};
+export function migrateExport(raw, options) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('Invalid PAI export: file is not a JSON object');
+    }
+    const record = raw;
+    const version = record['version'];
+    if (typeof version !== 'number' || !Number.isInteger(version) || version < 1) {
+        throw new Error('Invalid PAI export: "version" must be a positive integer');
+    }
+    if (version > CURRENT_EXPORT_FORMAT) {
+        const producer = typeof record['pai'] === 'string' && record['pai'].trim() !== '' ? record['pai'] : 'unknown';
+        throw new Error(`Invalid PAI export: format ${version} was produced by pai ${producer}; this pai (${options.currentPaiVersion}) supports up to format ${CURRENT_EXPORT_FORMAT} — upgrade pai`);
+    }
+    let document = record;
+    let from = version;
+    while (from < CURRENT_EXPORT_FORMAT) {
+        const migrate = MIGRATIONS[from];
+        if (!migrate) {
+            throw new Error(`Invalid PAI export: no migration path from format ${from}`);
+        }
+        document = migrate(document);
+        from += 1;
+    }
+    return { document, ...(version !== CURRENT_EXPORT_FORMAT ? { migratedFrom: version } : {}) };
+}

package/dist/core/guidelines.js

@@ -1,3 +1,22 @@
+export const HEADING = /^#{1,6}\s+(.+?)\s*$/;
+export const BULLET = /^\s*[-*]\s+(.+?)\s*$/;
+export function parseGuidelines(markdown) {
+    const guidelines = [];
+    let category = 'General';
+    // A BOM (Windows editors) would otherwise hide the first heading.
+    for (const line of markdown.replace(/^/, '').split('\n')) {
+        const heading = HEADING.exec(line);
+        if (heading?.[1]) {
+            category = heading[1];
+            continue;
+        }
+        const bullet = BULLET.exec(line);
+        if (bullet?.[1]) {
+            guidelines.push({ category, text: bullet[1] });
+        }
+    }
+    return guidelines;
+}
 export function filterGuidelineGroups(groups, filters) {
     const query = filters.search?.trim();
     // Word-start match: "ask" hits "Ask"/"asking" but not "tasks".

package/dist/core/managed-guidelines.js

@@ -0,0 +1,220 @@
+// PAI's rules live in markdown the coding agent already reads. Hand-written
+// guidance files are never edited; PAI owns one sibling file per scope and
+// merges into it. Everything here is pure — paths and I/O live elsewhere.
+import { HEADING, parseGuidelines } from './guidelines.js';
+import { ruleId } from './rule-store.js';
+import { CURRENT_EXPORT_FORMAT, migrateExport } from './export-migrations.js';
+export const MANAGED_HEADER = '<!-- Managed by PAI. Hand-written rules belong in CLAUDE.md; PAI adds rules here via `pai import` / `pai learn`. -->';
+function toLf(text) {
+    return text.replace(/\r\n?/g, '\n');
+}
+/** Flatten groups into export order: caller supplies global before project. */
+export function toExportRules(groups) {
+    return groups.flatMap((group) => group.guidelines.map((g) => ({ rule: g.text, category: g.category, scope: group.scope })));
+}
+export function serializeExportDocument(rules, meta) {
+    const document = {
+        version: CURRENT_EXPORT_FORMAT,
+        pai: meta.pai,
+        exportedAt: meta.exportedAt,
+        rules,
+    };
+    return `${JSON.stringify(document, null, 2)}\n`;
+}
+const MAX_RULE_LENGTH = 500;
+const MAX_CATEGORY_LENGTH = 80;
+const MAX_PROBLEMS_SHOWN = 20;
+/**
+ * Strict validation of a format-2 document (after migration). Collects every
+ * problem instead of stopping at the first one; each message is prefixed
+ * with a JSON-path so multiple problems in one file can be fixed at once.
+ * Unknown extra fields, top-level or per-rule, are ignored for forward
+ * compatibility.
+ */
+export function validateExportDocument(doc) {
+    const problems = [];
+    if (doc['version'] !== CURRENT_EXPORT_FORMAT) {
+        problems.push(`version: expected ${CURRENT_EXPORT_FORMAT}`);
+    }
+    if (doc['pai'] !== undefined && typeof doc['pai'] !== 'string') {
+        problems.push('pai: expected string');
+    }
+    if (doc['exportedAt'] !== undefined) {
+        const exportedAt = doc['exportedAt'];
+        if (typeof exportedAt !== 'string' || Number.isNaN(Date.parse(exportedAt))) {
+            problems.push('exportedAt: expected ISO-8601 timestamp');
+        }
+    }
+    const rawRules = doc['rules'];
+    if (!Array.isArray(rawRules)) {
+        problems.push('rules: expected array');
+        return { ok: false, problems };
+    }
+    const rules = [];
+    rawRules.forEach((entry, index) => {
+        const path = `rules[${index}]`;
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            problems.push(`${path}: expected object`);
+            return;
+        }
+        const record = entry;
+        const rawText = record['rule'];
+        // A bullet is one line; line breaks inside a rule would split it.
+        const normalizedText = typeof rawText === 'string' ? toLf(rawText).replace(/\n/g, ' ').trim() : undefined;
+        const ruleValid = normalizedText !== undefined && normalizedText !== '' && normalizedText.length <= MAX_RULE_LENGTH;
+        if (!ruleValid) {
+            problems.push(`${path}.rule: expected non-empty string (max ${MAX_RULE_LENGTH} chars)`);
+        }
+        let category = 'General';
+        let categoryValid = true;
+        const rawCategory = record['category'];
+        if (rawCategory !== undefined) {
+            if (typeof rawCategory !== 'string' || rawCategory.trim().length > MAX_CATEGORY_LENGTH) {
+                categoryValid = false;
+                problems.push(`${path}.category: expected string (max ${MAX_CATEGORY_LENGTH} chars)`);
+            }
+            else {
+                category = rawCategory.trim() === '' ? 'General' : rawCategory.trim();
+            }
+        }
+        const scope = record['scope'];
+        const scopeValid = scope === 'global' || scope === 'project';
+        if (!scopeValid) {
+            problems.push(`${path}.scope: expected "global" or "project"`);
+        }
+        if (ruleValid && categoryValid && scopeValid) {
+            rules.push({ rule: normalizedText, category, scope: scope });
+        }
+    });
+    if (problems.length > 0)
+        return { ok: false, problems };
+    return { ok: true, document: { version: CURRENT_EXPORT_FORMAT, rules } };
+}
+export function parseExportDocument(json, options) {
+    let parsed;
+    try {
+        // Tolerate a byte-order mark left by Windows editors.
+        parsed = JSON.parse(json.replace(/^/, ''));
+    }
+    catch {
+        return failParse('file is not valid JSON');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return failParse('file is not a JSON object');
+    }
+    const { document, migratedFrom } = migrateExport(parsed, {
+        currentPaiVersion: options.currentPaiVersion,
+    });
+    const result = validateExportDocument(document);
+    if (!result.ok)
+        failValidation(result.problems);
+    return { ...result.document, ...(migratedFrom !== undefined ? { migratedFrom } : {}) };
+}
+function failParse(reason) {
+    throw new Error(`Invalid PAI export: ${reason}`);
+}
+function failValidation(problems) {
+    const shown = problems.slice(0, MAX_PROBLEMS_SHOWN);
+    const remaining = problems.length - shown.length;
+    const lines = [
+        `Invalid PAI export: ${problems.length} problem(s)`,
+        ...shown.map((problem) => `  - ${problem}`),
+        ...(remaining > 0 ? [`  - … and ${remaining} more`] : []),
+    ];
+    throw new Error(lines.join('\n'));
+}
+/**
+ * Make sure the hand-written file references the managed one. Only a suffix
+ * is ever produced — the caller appends it in place, so a symlinked CLAUDE.md
+ * keeps pointing at its target and existing bytes are never rewritten.
+ */
+export function ensurePointer(claudeMd, pointer) {
+    if (claudeMd === undefined) {
+        return { suffix: `${pointer}\n`, action: 'created' };
+    }
+    const hasPointer = toLf(claudeMd)
+        .split('\n')
+        .some((line) => line.trim() === pointer);
+    if (hasPointer)
+        return { suffix: '', action: 'unchanged' };
+    const trailing = /\s*$/.exec(claudeMd)?.[0] ?? '';
+    if (trailing.length === claudeMd.length) {
+        // Empty or whitespace-only: the pointer is the first real line.
+        const needsBreak = claudeMd !== '' && !claudeMd.endsWith('\n');
+        return { suffix: `${needsBreak ? '\n' : ''}${pointer}\n`, action: 'appended' };
+    }
+    // Exactly one blank line before the pointer, given what is already there.
+    const newlines = trailing.split('\n').length - 1;
+    const separator = newlines >= 2 ? '' : newlines === 1 ? '\n' : '\n\n';
+    return { suffix: `${separator}${pointer}\n`, action: 'appended' };
+}
+/**
+ * Merge rules into PAI's managed markdown. Identity is the normalized rule
+ * text (`ruleId`), so wording that differs only in case, punctuation,
+ * whitespace or line endings counts as already present. Existing content,
+ * order and prose are preserved; new bullets go under their category heading,
+ * and missing headings are appended at the end.
+ */
+export function mergeManagedMarkdown(existingMarkdown, rules) {
+    const isNew = existingMarkdown === undefined || existingMarkdown.trim() === '';
+    const source = isNew ? MANAGED_HEADER : toLf(existingMarkdown);
+    const seen = new Set(parseGuidelines(source).map((g) => ruleId(g.text)));
+    // Category → new bullets, in first-appearance order.
+    const additions = new Map();
+    let added = 0;
+    let existing = 0;
+    for (const incoming of rules) {
+        const id = ruleId(incoming.rule);
+        if (seen.has(id)) {
+            existing += 1;
+            continue;
+        }
+        seen.add(id);
+        added += 1;
+        const bullets = additions.get(incoming.category) ?? [];
+        bullets.push(`- ${toLf(incoming.rule).replace(/\n/g, ' ').trim()}`);
+        additions.set(incoming.category, bullets);
+    }
+    if (added === 0) {
+        return { markdown: existingMarkdown ?? '', added, existing };
+    }
+    // Each existing heading's section ends at its last non-blank line; new
+    // bullets for that category are inserted right after it.
+    const lines = source.split('\n');
+    const sectionEnd = new Map();
+    let current;
+    for (const [index, line] of lines.entries()) {
+        const heading = HEADING.exec(line);
+        if (heading?.[1]) {
+            current = sectionEnd.has(heading[1]) ? undefined : heading[1];
+            if (current !== undefined)
+                sectionEnd.set(current, index);
+            continue;
+        }
+        if (current !== undefined && line.trim() !== '')
+            sectionEnd.set(current, index);
+    }
+    const insertAfter = new Map();
+    const missing = [];
+    for (const [category, bullets] of additions) {
+        const end = sectionEnd.get(category);
+        if (end === undefined) {
+            missing.push(category);
+            continue;
+        }
+        insertAfter.set(end, bullets);
+    }
+    const output = [];
+    for (const [index, line] of lines.entries()) {
+        output.push(line);
+        const bullets = insertAfter.get(index);
+        if (bullets)
+            output.push(...bullets);
+    }
+    while (output.length > 0 && output[output.length - 1]?.trim() === '')
+        output.pop();
+    for (const category of missing) {
+        output.push('', `## ${category}`, ...(additions.get(category) ?? []));
+    }
+    return { markdown: `${output.join('\n')}\n`, added, existing };
+}

package/dist/persistence/managed-guideline-files.js

@@ -0,0 +1,88 @@
+import { appendFileSync, lstatSync, mkdirSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { parseGuidelines } from '../core/guidelines.js';
+import { ensurePointer, mergeManagedMarkdown, } from '../core/managed-guidelines.js';
+import { readTextFile } from './text-file.js';
+export function readGuidelineGroups(files) {
+    return files.map((file) => ({
+        scope: file.scope,
+        path: file.path,
+        managed: file.managed,
+        guidelines: parseGuidelines(readTextFile(file.path)),
+    }));
+}
+/** A missing file is `undefined`; any other read error propagates. */
+function readOptionalTextFile(path) {
+    try {
+        return readTextFile(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Written via a temporary file and renamed into place, so an interrupted
+ * write cannot leave a half-written file behind. A symlink is written through
+ * instead — renaming over it would replace the link with a plain file.
+ * UTF-8, no BOM.
+ */
+function writeTextFileAtomic(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    if (isSymlink(path)) {
+        writeFileSync(path, content, 'utf8');
+        return;
+    }
+    const temporary = `${path}.tmp`;
+    try {
+        writeFileSync(temporary, content, 'utf8');
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // Nothing to clean up.
+        }
+        throw error;
+    }
+}
+/**
+ * Bring one scope's directory up to date: CLAUDE.md gets the pointer line if
+ * it lacks one, CLAUDE.pai.md gets the rules it does not have yet. The
+ * hand-written file is only ever appended to in place (never renamed over,
+ * so symlinks into a dotfiles repo survive) and is not read for deduplication.
+ */
+export function importManagedGuidelines(target, rules, options = {}) {
+    const { claudeMdPath, managedPath } = target;
+    const pointer = ensurePointer(readOptionalTextFile(claudeMdPath), target.pointer);
+    const merge = mergeManagedMarkdown(readOptionalTextFile(managedPath), rules);
+    if (!options.dryRun) {
+        if (pointer.action === 'created') {
+            mkdirSync(dirname(claudeMdPath), { recursive: true });
+            writeFileSync(claudeMdPath, pointer.suffix, 'utf8');
+        }
+        else if (pointer.action === 'appended') {
+            appendFileSync(claudeMdPath, pointer.suffix, 'utf8');
+        }
+        if (merge.added > 0)
+            writeTextFileAtomic(managedPath, merge.markdown);
+    }
+    return {
+        claudeMdPath,
+        managedPath,
+        pointer: pointer.action,
+        added: merge.added,
+        existing: merge.existing,
+    };
+}

package/docs/export-format.md

@@ -0,0 +1,83 @@
+# PAI export format
+
+The contract for the JSON file `pai export` writes and `pai import` reads.
+It exists so a file exported by one version of PAI, on one machine, imports
+safely — or fails clearly — on another.
+
+## Format 2 (current)
+
+```json
+{
+  "version": 2,
+  "pai": "0.3.1",
+  "exportedAt": "2026-08-29T12:00:00.000Z",
+  "rules": [
+    { "rule": "Keep answers short.", "category": "Communication", "scope": "global" },
+    { "rule": "Never force-push.", "category": "Git", "scope": "project" }
+  ]
+}
+```
+
+| Field | Type | Required | Constraint |
+|---|---|---|---|
+| `version` | number | yes | must be `2` |
+| `pai` | string | no | PAI version that produced the file |
+| `exportedAt` | string | no | ISO-8601 timestamp, parseable by `Date` |
+| `rules` | array | yes | array of rule objects (may be empty) |
+| `rules[].rule` | string | yes | non-empty after trim, max 500 chars |
+| `rules[].category` | string | no | max 80 chars; defaults to `"General"` |
+| `rules[].scope` | string | yes | `"global"` or `"project"` |
+
+Unknown extra fields — at the top level or inside a rule object — are
+ignored, both by validation and on import. This is what lets a newer PAI add
+fields to the format without breaking an older one that only understands the
+fields above.
+
+## Normalization
+
+On import, each rule is normalized before it is compared or written:
+
+- CRLF and lone CR are converted to LF
+- newlines inside `rule` become a single space (a rule is one bullet, one line)
+- the result is trimmed
+- an empty or missing `category` becomes `"General"`
+
+## Compatibility policy
+
+- **Same format** (`version: 2`) — always safe to import, on any PAI version
+  that supports format 2.
+- **Older format** — migrated automatically. Migrations applied so far:
+  - **1 → 2**: reads the old `.pai/rules.json` store shape
+    (`rules[].{rule,category,scope}`, plus `id`, `evidence`, `source`,
+    `createdAt`/`updatedAt`). Only `rule`, `category` and `scope` survive;
+    `id`, `evidence`, `source` and the timestamps are dropped — none of them
+    are part of the export format.
+- **Newer format** — rejected with an exact, upgrade-pointing message:
+
+  ```
+  Invalid PAI export: format <N> was produced by pai <pai or "unknown">; this pai (<current>) supports up to format 2 — upgrade pai
+  ```
+
+## Validation errors
+
+An invalid file (right format, wrong contents) is rejected with every
+problem found, not just the first one:
+
+```
+Invalid PAI export: 2 problem(s)
+  - rules[0].rule: expected non-empty string (max 500 chars)
+  - rules[0].scope: expected "global" or "project"
+```
+
+Each line is prefixed with a JSON path to the offending field. At most 20
+problems are listed; beyond that, a final line reads `  - … and N more`.
+
+Run `pai import <file> --validate` to check a file against this contract —
+parse, migrate, and validate — without writing anything.
+
+## Encodings accepted
+
+`pai import` decodes, in order of likelihood: UTF-8, UTF-8 with a BOM
+(as written by Notepad or PowerShell's `Set-Content`), and UTF-16 with a BOM
+(as written by PowerShell 5.1's `>` redirect). `pai export` always writes
+UTF-8 with LF line endings and no BOM.

package/docs/principles.md

@@ -3,9 +3,10 @@
 ## Principles
 
 1. **Read-only toward agents' data.** PAI never modifies coding-agent files
-   (transcripts, configs, CLAUDE.md). PAI writes only to its own store
-   (`.pai/` in a project) — and to agent guidance files only as an explicit,
-   user-approved sync feature (future).
+   (transcripts, configs, CLAUDE.md). PAI writes only its own `CLAUDE.pai.md`
+   next to each CLAUDE.md, plus a single pointer line (`@CLAUDE.pai.md`) in
+   CLAUDE.md so the agent reads it — it never edits hand-written rules.
+   `.pai/` is reserved for PAI's own metadata.
 2. **Approval gates knowledge.** Nothing becomes a stored rule without the
    user approving it. Every stored or reported item carries evidence: the
    user's actual words, session id, timestamp.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lastboy/pai",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "PAI — Personal AI Supervisor: a local-first CLI that observes how you work with AI coding agents and turns it into knowledge you own",
   "keywords": [
     "cli",