@lastboy/pai 0.1.0 → 0.3.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,13 @@ 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, "rules": [ { "rule": "…", "category": "…", "scope": "global" } ] }
+```
 
 | Option | Effect |
 |---|---|
@@ -92,16 +99,25 @@ 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 |
 
 ```bash
 pai import mine.json --dry-run
@@ -110,6 +126,14 @@ pai import mine.json
 
 Invalid or unsupported files fail with a clear message and a non-zero exit code.
 
+**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 counts as one instead of duplicating; `CLAUDE.pai.md` is always
+written as UTF-8 with LF line endings.
+
 ### `pai experiment …`
 
 Experimental commands. They may change or disappear, and they are the only
@@ -127,26 +151,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 `-`.
@@ -156,7 +183,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

package/dist/adapters/claude/guidelines.js

@@ -1,32 +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';
-    for (const line of markdown.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 { 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) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -48,6 +49,10 @@ async function chooseSession(out) {
     out('');
     return sessions[index];
 }
+/** Node's fs errors are readable already; anything else gets stringified. */
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 // Same relative depth from src/cli and dist/cli.
 function packageVersion() {
     const pkg = JSON.parse(readFileSync(join(import.meta.dirname, '..', '..', 'package.json'), 'utf8'));
@@ -74,7 +79,7 @@ export function createProgram(out) {
             process.exitCode = 1;
             return;
         }
-        const transcript = await readFile(chosen.path, 'utf8');
+        const transcript = decodeTextFile(await readFile(chosen.path));
         const session = parseTranscript(transcript, chosen.id);
         for (const line of renderReview(buildReview(session))) {
             out(line);
@@ -83,16 +88,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(await readFile(file.path, 'utf8')),
-        })));
+        .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'
@@ -109,7 +109,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) => {
@@ -118,47 +118,64 @@ export function createProgram(out) {
             process.exitCode = 1;
             return;
         }
-        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);
-        if (options.out === undefined) {
-            out(json.trimEnd());
-            return;
+        try {
+            // 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);
+            if (options.out === undefined) {
+                out(json.trimEnd());
+                return;
+            }
+            writeFileSync(options.out, json, 'utf8');
+            out(`Exported ${rules.length} rule(s) to ${options.out}`);
+        }
+        catch (error) {
+            out(`Export failed: ${describeError(error)}`);
+            process.exitCode = 1;
         }
-        writeFileSync(options.out, json, 'utf8');
-        out(`Exported ${combined.rules.length} rule(s) to ${options.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')
         .action(async (file, options) => {
         let incoming;
         try {
-            incoming = parseRuleStore(await readFile(file, 'utf8'));
+            incoming = parseExportDocument(decodeTextFile(await readFile(file)));
         }
         catch (error) {
-            out(error instanceof Error ? error.message : String(error));
+            out(`Could not read ${file}: ${describeError(error)}`);
             process.exitCode = 1;
             return;
         }
-        const targets = [
-            { scope: 'global', path: globalStorePath() },
-            { scope: 'project', path: projectStorePath(process.cwd()) },
-        ];
-        for (const target of targets) {
-            const rules = incoming.rules.filter((rule) => rule.scope === target.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}`);
+        try {
+            for (const scope of ['global', 'project']) {
+                const rules = incoming.rules.filter((rule) => rule.scope === scope);
+                if (rules.length === 0)
+                    continue;
+                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) {
+            out(`Import failed: ${describeError(error)}`);
+            out('Nothing was changed for the scope that failed.');
+            process.exitCode = 1;
+            return;
         }
         if (incoming.rules.length === 0)
             out('Nothing to import — the file contains no rules.');
@@ -179,7 +196,7 @@ export function createProgram(out) {
             process.exitCode = 1;
             return;
         }
-        const transcript = await readFile(chosen.path, 'utf8');
+        const transcript = decodeTextFile(await readFile(chosen.path));
         const events = parseEvents(transcript);
         const candidates = events
             .map((event, index) => ({ event, index }))
@@ -265,7 +282,7 @@ export function createProgram(out) {
             process.exitCode = 1;
             return;
         }
-        const transcript = await readFile(chosen.path, 'utf8');
+        const transcript = decodeTextFile(await readFile(chosen.path));
         const messages = parseEvents(transcript).filter((e) => e.kind === 'user');
         const limit = Math.max(1, Number(options.limit) || 10);
         const sample = messages.slice(-limit);

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/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,173 @@
+// 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 { parseRuleStore, ruleId } from './rule-store.js';
+const EXPORT_VERSION = 2;
+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) {
+    const document = { version: EXPORT_VERSION, rules };
+    return `${JSON.stringify(document, null, 2)}\n`;
+}
+export function parseExportDocument(json) {
+    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 raw = parsed;
+    if (raw['version'] === 1) {
+        // Older `.pai/rules.json` stores carry the same three fields we need.
+        return {
+            version: EXPORT_VERSION,
+            rules: parseRuleStore(json).rules.map((r) => ({
+                rule: r.rule,
+                category: r.category,
+                scope: r.scope,
+            })),
+        };
+    }
+    if (raw['version'] !== EXPORT_VERSION) {
+        return failParse(`unsupported version: ${String(raw['version'])} (expected ${EXPORT_VERSION})`);
+    }
+    if (!Array.isArray(raw['rules'])) {
+        return failParse('"rules" must be an array');
+    }
+    const rules = [];
+    for (const [index, entry] of raw['rules'].entries()) {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            return failParse(`rule ${index + 1} is not an object`);
+        }
+        const record = entry;
+        const text = record['rule'];
+        if (typeof text !== 'string' || text.trim() === '') {
+            return failParse(`rule ${index + 1} is missing a non-empty "rule" field`);
+        }
+        const category = record['category'];
+        if (category !== undefined && typeof category !== 'string') {
+            return failParse(`rule ${index + 1} has a non-string "category"`);
+        }
+        const scope = record['scope'];
+        if (scope !== 'global' && scope !== 'project') {
+            return failParse(`rule ${index + 1} has an invalid "scope" (expected "global" or "project")`);
+        }
+        rules.push({
+            // A bullet is one line; line breaks inside a rule would split it.
+            rule: toLf(text).replace(/\n/g, ' ').trim(),
+            category: category === undefined || category.trim() === '' ? 'General' : category.trim(),
+            scope,
+        });
+    }
+    return { version: EXPORT_VERSION, rules };
+}
+function failParse(reason) {
+    throw new Error(`Invalid PAI export: ${reason}`);
+}
+/**
+ * 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/dist/persistence/rule-store-files.js

@@ -1,7 +1,8 @@
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { emptyStore, parseRuleStore, serializeRuleStore } from '../core/rule-store.js';
+import { readTextFile } from './text-file.js';
 // PAI writes only to its own agent-neutral `.pai/` directories.
 export function globalStorePath(home = homedir()) {
     return join(home, '.pai', 'rules.json');
@@ -9,17 +10,40 @@ export function globalStorePath(home = homedir()) {
 export function projectStorePath(cwd) {
     return join(cwd, '.pai', 'rules.json');
 }
+/** A missing store is empty; a corrupt one is an error naming the file. */
 export function readStore(path) {
     let contents;
     try {
-        contents = readFileSync(path, 'utf8');
+        contents = readTextFile(path);
     }
     catch {
         return emptyStore();
     }
-    return parseRuleStore(contents);
+    try {
+        return parseRuleStore(contents);
+    }
+    catch (error) {
+        throw new Error(`${error instanceof Error ? error.message : String(error)} — ${path}`);
+    }
 }
+/**
+ * Written via a temporary file and renamed into place, so an interrupted
+ * write cannot leave a half-written store behind.
+ */
 export function writeStore(path, store) {
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, serializeRuleStore(store), 'utf8');
+    const temporary = `${path}.tmp`;
+    try {
+        writeFileSync(temporary, serializeRuleStore(store), 'utf8');
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // Nothing to clean up.
+        }
+        throw error;
+    }
 }

package/dist/persistence/text-file.js

@@ -0,0 +1,23 @@
+import { readFileSync } from 'node:fs';
+// Files exported on one platform are routinely imported on another. Windows
+// tooling adds byte-order marks and PowerShell 5.1's `>` redirect writes
+// UTF-16LE, both of which break a plain UTF-8 read.
+export function decodeTextFile(bytes) {
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        return bytes.subarray(3).toString('utf8');
+    }
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) {
+        return bytes.subarray(2).toString('utf16le');
+    }
+    if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
+        const body = bytes.subarray(2);
+        if (body.length % 2 !== 0)
+            return body.toString('utf8');
+        // swap16 mutates, so work on a copy of the caller's buffer.
+        return Buffer.from(body).swap16().toString('utf16le');
+    }
+    return bytes.toString('utf8');
+}
+export function readTextFile(path) {
+    return decodeTextFile(readFileSync(path));
+}

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.1.0",
+  "version": "0.3.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",