@symbols-cli/cli 0.0.1

package/dist/skills/bundle.js

@@ -0,0 +1,441 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// S1 — fetch, VERIFY, and atomically install the skills bundle.
+//
+// ## Why this file is a security boundary and not a downloader
+//
+// Skills are instructions the agent executes. They are delivered to every
+// laptop, persisted, and auto-refreshed. Server-side, one compromise hurt one
+// sandboxed container; client-side it is persistent code execution in every
+// user's home directory, simultaneously. The blast radius inverts, and deleting
+// gVisor is only acceptable if Symbols adds no attack surface beyond vanilla
+// Claude Code. An unsigned auto-updating instruction channel is exactly such
+// surface.
+//
+// Four controls, and the difference between them matters:
+//
+//   1. SIGNATURE (authenticity). Detached ed25519 over the manifest's exact
+//      bytes, against keys PINNED IN THIS FILE. This is the only control that
+//      survives a compromised API host.
+//   2. STAMP (integrity of what lands on disk). The signed manifest names the
+//      bundle's content hash; we recompute it from the EXTRACTED TREE and refuse
+//      on mismatch. Verifying after extraction means a bug in our own tar reader
+//      is caught too — verifying the archive's bytes would not catch that.
+//   3. SEQUENCE (freshness). A signature proves a bundle was ours, not that it
+//      is current. Without a monotonic floor, a correctly-signed OLD bundle
+//      replays a fixed skill defect back onto every laptop.
+//   4. sha256 of the tarball (TRANSPORT only). Catches truncation and a broken
+//      proxy. ⚠ It is NOT authenticity: a compromised server serves a matching
+//      hash for a malicious tarball trivially. Never describe it as more.
+//
+// ## Why raw ed25519 rather than minisign
+//
+// minisign's file format is ed25519 plus a framing convention. The framing buys
+// interoperability with the `minisign` tool — which would become a NEW runtime
+// prerequisite on every user's machine, against a plan whose distribution
+// section fought to keep the prerequisite list at "Node >= 20". Node's `crypto`
+// speaks ed25519 natively, so the raw form needs no dependency on either side,
+// and both ends are ours. We keep the one property the framing exists for by
+// signing the manifest's EXACT SERVED BYTES: no canonical-JSON step, so there is
+// no canonicalisation bug to have.
+import { promises as fs } from "node:fs";
+import { createHash, createPublicKey, verify as edVerify } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+import { join, dirname, relative, sep } from "node:path";
+import { randomBytes } from "node:crypto";
+import { requestBytes } from "../auth/client.js";
+import { readBundleSequence, recordBundleSequence } from "../auth/credentials.js";
+import { resolveInRoot } from "../sync/paths.js";
+import { bundleRoot, installedManifestPath, symbolsHome } from "../util/platform.js";
+/**
+ * ⚠ TWO KEYS: CURRENT AND NEXT. Shipping one means a key compromise bricks every
+ * installed client at once — they would all refuse the re-signed bundle, and the
+ * fix would require every user to upgrade the CLI before they could get skills
+ * again. With a next key already pinned, rotation is a re-publish.
+ *
+ * ⚠ AN EMPTY ARRAY REFUSES EVERY BUNDLE, and that was the correct state until
+ * the keys existed. It is no longer empty — but the rule that produced it still
+ * holds: **the private halves have never been in this tree and must never be.**
+ * These were generated ON THE REPO ADMIN'S MACHINE by
+ * `scripts/admin_provision_signing.sh`, and the private halves have never been
+ * anywhere else — not on a developer laptop, not in a chat, not in this repo.
+ * That is the point of the script: only the PUBLIC halves below travelled.
+ *
+ * The private key lives in CI as `SYMBOLS_BUNDLE_SIGNING_KEY`, gated behind the
+ * `plugin-signing` environment (`.github/workflows/plugin-bundle.yml:85`).
+ * Signing on the API host would be signed-by-the-thing-you-are-authenticating-
+ * against.
+ *
+ * What is below is the PUBLIC half only: 32 ed25519 bytes each. Publishing them
+ * is the point — a pinned public key is what lets a client refuse a bundle the
+ * server did not actually publish.
+ *
+ * ⚠ ROTATION IS A RE-PUBLISH, NOT AN UPGRADE, and that is why there are two.
+ * If `current` is ever compromised, re-sign with `next` and every installed CLI
+ * accepts it immediately, because it already pins both. With one key, a
+ * compromise would brick every client at once: they would all refuse the
+ * re-signed bundle, and the fix would require each user to upgrade the CLI
+ * before they could get skills again — during an incident.
+ *
+ * After rotating: mint a new `next`, pin it, and ship it BEFORE it is needed.
+ * A `next` that is only generated at rotation time is not a spare.
+ *
+ * To regenerate — the private half never touches this tree:
+ *
+ *     openssl genpkey -algorithm ed25519 -out ~/.symbols-signing/bundle.pem
+ *     chmod 600 ~/.symbols-signing/bundle.pem
+ *     scripts/publish_plugin_bundle.sh --print-pubkey ~/.symbols-signing/bundle.pem
+ */
+export const PINNED_KEYS = [
+    // current — signs today's bundles
+    { id: "29a7617f41749dbf", raw: "vpxVMHkQtIdGcR4s2WuGVcM4QNtUXx+R3INj0qUX1Is=" },
+    // next — the spare, pinned in advance so rotation needs no client upgrade
+    { id: "862ff69db775ec27", raw: "rQvWnNXMSVMGW7K+EK4YZPm/tkmbLVkUYStuzQoj2ik=" },
+];
+/** DER SPKI prefix for ed25519 — 12 bytes, then the 32 raw key bytes. */
+const SPKI_ED25519_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+export class BundleVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BundleVerificationError";
+    }
+}
+const SCHEMA = "symbols.skills-bundle/1";
+// ── signature ────────────────────────────────────────────────────────────────
+function keyObject(raw) {
+    const bytes = Buffer.from(raw, "base64");
+    if (bytes.length !== 32) {
+        throw new BundleVerificationError(`pinned key is ${bytes.length} bytes, expected 32`);
+    }
+    return createPublicKey({
+        key: Buffer.concat([SPKI_ED25519_PREFIX, bytes]),
+        format: "der",
+        type: "spki",
+    });
+}
+/**
+ * Verify a manifest envelope and return the manifest it carries.
+ *
+ * `keys` is a parameter ONLY so the security property is unit-testable without
+ * shipping a private key — the same reason `curl.ts` exports `resolveTarget`.
+ * Production callers use `PINNED_KEYS` and there is no env var, no flag, and no
+ * config file that can change them: a bypass switch on this check would hand the
+ * exact capability back to the adversary the check exists for.
+ */
+export function verifyManifestEnvelope(envelope, keys = PINNED_KEYS) {
+    if (keys.length === 0) {
+        throw new BundleVerificationError("no bundle signing keys are pinned in this build, so no bundle can be trusted. " +
+            "Skills are instructions the agent executes; installing them unverified would make " +
+            "one server compromise persistent code execution here. See PINNED_KEYS in skills/bundle.ts.");
+    }
+    if (!envelope || typeof envelope.manifest !== "string" || typeof envelope.signature !== "string") {
+        throw new BundleVerificationError("manifest response is not a signed envelope");
+    }
+    const bytes = Buffer.from(envelope.manifest, "base64");
+    const sig = Buffer.from(envelope.signature, "base64");
+    if (bytes.length === 0)
+        throw new BundleVerificationError("manifest is empty");
+    if (sig.length !== 64) {
+        // A missing signature arrives as an empty string, which is the "unsigned
+        // bundle" case the plan requires be refused. Same branch, same refusal.
+        throw new BundleVerificationError(`signature is ${sig.length} bytes, expected 64 — the bundle is unsigned or the signature is malformed`);
+    }
+    // TRY EVERY PINNED KEY. `key_id` in the envelope is a hint, and trusting a
+    // hint to choose the verifying key would let an attacker point us at whichever
+    // key they had.
+    const accepted = keys.some((k) => {
+        try {
+            return edVerify(null, bytes, keyObject(k.raw), sig);
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!accepted) {
+        throw new BundleVerificationError("the bundle manifest is not signed by any key this CLI pins. Refusing it. " +
+            "Either the server is serving something we did not publish, or this CLI predates a key rotation " +
+            "(`npm i -g @symbols-cli/cli`).");
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new BundleVerificationError("the signed manifest is not valid JSON");
+    }
+    if (manifest.schema !== SCHEMA) {
+        throw new BundleVerificationError(`manifest schema '${manifest.schema}' is not '${SCHEMA}' — this CLI cannot read it`);
+    }
+    if (!Number.isInteger(manifest.sequence) || manifest.sequence < 1) {
+        throw new BundleVerificationError("manifest carries no usable sequence number");
+    }
+    if (!/^[0-9a-f]{64}$/.test(manifest.stamp)) {
+        throw new BundleVerificationError("manifest carries no usable content stamp");
+    }
+    if (!Array.isArray(manifest.plugins) || manifest.plugins.length === 0) {
+        throw new BundleVerificationError("manifest names no plugins");
+    }
+    return manifest;
+}
+// ── the stamp ────────────────────────────────────────────────────────────────
+/**
+ * `stage_plugins.sh`'s content stamp, recomputed over an extracted tree.
+ *
+ * The shell is
+ *   find . -type f ! -name .stamp ! -name .gitkeep -print0 | LC_ALL=C sort -z
+ *     | xargs -0 sha256sum | sha256sum | cut -d' ' -f1
+ * so the digest is over `<hex>  <./path>\n` lines in byte order.
+ *
+ * ⚠ `.signing/` is excluded because the signed manifest is placed in the bundle
+ * dir on the API host AFTER staging stamped it. `publish_plugin_bundle.sh`
+ * recomputes the stamp with this same exclusion and fails the build if it stops
+ * matching `.stamp`, so the two implementations cannot drift silently — the
+ * build breaks before any client refuses.
+ */
+export async function computeBundleStamp(root) {
+    const files = [];
+    const walk = async (dir) => {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(abs);
+            else if (entry.isFile())
+                files.push(abs);
+            // Symlinks, sockets and fifos are skipped, matching `find -type f`. The
+            // extractor refuses to create them in the first place.
+        }
+    };
+    await walk(root);
+    const rows = files
+        .map((abs) => ["./" + relative(root, abs).split(sep).join("/"), abs])
+        .filter(([rel]) => rel !== "./.stamp" && rel !== "./.gitkeep" && !rel.startsWith("./.signing/"))
+        // LC_ALL=C sort is byte order. localeCompare is NOT byte order.
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    const outer = createHash("sha256");
+    for (const [rel, abs] of rows) {
+        const hex = createHash("sha256").update(await fs.readFile(abs)).digest("hex");
+        outer.update(`${hex}  ${rel}\n`);
+    }
+    return outer.digest("hex");
+}
+function octal(block, offset, length) {
+    const raw = block.subarray(offset, offset + length).toString("ascii").replace(/\0.*$/, "").trim();
+    if (raw === "")
+        return 0;
+    const n = Number.parseInt(raw, 8);
+    if (!Number.isFinite(n) || n < 0)
+        throw new BundleVerificationError("malformed tar header field");
+    return n;
+}
+function cstr(block, offset, length) {
+    const slice = block.subarray(offset, offset + length);
+    const end = slice.indexOf(0);
+    return slice.subarray(0, end === -1 ? slice.length : end).toString("utf8");
+}
+/** Every tar header carries its own checksum. A bad one is a corrupt archive. */
+function checksumOk(header) {
+    const declared = octal(header, 148, 8);
+    let signed = 0;
+    for (let i = 0; i < 512; i += 1) {
+        // The checksum field itself is summed as spaces.
+        signed += i >= 148 && i < 156 ? 0x20 : header[i];
+    }
+    return signed === declared;
+}
+export function readTar(buf) {
+    const out = [];
+    let offset = 0;
+    let pendingLongName = null;
+    while (offset + 512 <= buf.length) {
+        const header = buf.subarray(offset, offset + 512);
+        if (header.every((b) => b === 0))
+            break; // the end-of-archive marker
+        if (!checksumOk(header)) {
+            throw new BundleVerificationError(`tar header checksum mismatch at offset ${offset}`);
+        }
+        const size = octal(header, 124, 12);
+        const type = String.fromCharCode(header[156]);
+        const dataStart = offset + 512;
+        const dataEnd = dataStart + size;
+        if (dataEnd > buf.length)
+            throw new BundleVerificationError("tar entry runs past end of archive");
+        const data = buf.subarray(dataStart, dataEnd);
+        offset = dataStart + Math.ceil(size / 512) * 512;
+        // GNU long name: this entry's DATA is the next entry's path.
+        if (type === "L") {
+            pendingLongName = data.toString("utf8").replace(/\0+$/, "");
+            continue;
+        }
+        // PAX extended header. Only `path=` matters to us; `g` is global and ignored.
+        if (type === "x" || type === "g") {
+            if (type === "x") {
+                const text = data.toString("utf8");
+                const m = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(text);
+                if (m)
+                    pendingLongName = m[1];
+            }
+            continue;
+        }
+        const prefix = cstr(header, 345, 155);
+        const name = cstr(header, 0, 100);
+        const path = pendingLongName ?? (prefix ? `${prefix}/${name}` : name);
+        pendingLongName = null;
+        if (type === "5") {
+            out.push({ path, kind: "dir", mode: octal(header, 100, 8), data: Buffer.alloc(0) });
+            continue;
+        }
+        if (type === "0" || type === "\0") {
+            out.push({ path, kind: "file", mode: octal(header, 100, 8), data: Buffer.from(data) });
+            continue;
+        }
+        // ⚠ EVERYTHING ELSE IS REFUSED, LOUDLY. '1' and '2' are hard and symbolic
+        // links: a link named `.claude/settings.json` pointing at the user's real
+        // one would turn a bundle write into a config write, which is exactly the S2
+        // class. '3'/'4'/'6'/'7' are devices, fifos and contiguous files, none of
+        // which a skills bundle has any business containing.
+        throw new BundleVerificationError(`tar entry '${path}' has type '${type}'; only plain files and directories are accepted`);
+    }
+    return out;
+}
+/**
+ * Extract into `dest`, refusing anything that could escape it.
+ *
+ * Path safety reuses `sync/paths.ts::resolveInRoot` — ONE implementation of the
+ * arbitrary-local-write rules, not a second copy that drifts. It rejects `..`,
+ * absolute paths, NUL, control characters, Windows reserved device names, and
+ * anything resolving outside the root.
+ */
+export async function extractTarGz(targz, dest) {
+    const entries = readTar(gunzipSync(targz));
+    if (entries.length === 0)
+        throw new BundleVerificationError("the bundle archive is empty");
+    for (const entry of entries) {
+        // `append_dir_all(".", …)` produces "./" for the root itself.
+        const rel = entry.path.replace(/^\.\//, "").replace(/\/+$/, "");
+        if (rel === "" || rel === ".")
+            continue;
+        const resolved = resolveInRoot(dest, rel);
+        if (!resolved.ok || !resolved.abs) {
+            throw new BundleVerificationError(`bundle entry '${entry.path}' refused: ${resolved.reason}`);
+        }
+        if (entry.kind === "dir") {
+            await fs.mkdir(resolved.abs, { recursive: true, mode: 0o755 });
+            continue;
+        }
+        await fs.mkdir(dirname(resolved.abs), { recursive: true, mode: 0o755 });
+        // The archived exec bit is preserved but nothing else is: an archive cannot
+        // ask for setuid, setgid, or a world-writable file here.
+        const mode = (entry.mode & 0o111) !== 0 ? 0o755 : 0o644;
+        await fs.writeFile(resolved.abs, entry.data, { mode });
+    }
+}
+const defaultTransport = {
+    async manifest() {
+        const { bytes } = await requestBytes("/api/cli/bundle/manifest");
+        return JSON.parse(bytes.toString("utf8"));
+    },
+    async tarball() {
+        const { bytes } = await requestBytes("/api/cli/bundle.tgz");
+        return bytes;
+    },
+};
+/** The manifest of whatever is currently unpacked locally, if anything. */
+export async function readInstalledManifest() {
+    try {
+        return JSON.parse(await fs.readFile(installedManifestPath(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch, verify and install the bundle. Returns without writing when the local
+ * copy already carries the manifest's stamp.
+ *
+ * ORDER IS THE DESIGN:
+ *   manifest -> signature -> ROLLBACK FLOOR -> download -> transport hash ->
+ *   extract to a temp dir -> recompute the stamp -> ATOMIC RENAME -> raise floor
+ *
+ * The floor is checked BEFORE the download so a replayed old bundle costs
+ * nothing, and raised only AFTER the install lands so a crash mid-install cannot
+ * lock the machine out of the version it failed to install.
+ */
+export async function installBundle(opts = {}) {
+    const transport = opts.transport ?? defaultTransport;
+    // ONE fetch. An earlier draft fetched the envelope twice — once to verify and
+    // once for `tgz_sha256` — which would have let a server serve a signed
+    // manifest to the check and a different envelope to the download.
+    const envelope = await transport.manifest();
+    const manifest = verifyManifestEnvelope(envelope, opts.keys ?? PINNED_KEYS);
+    // 3. FRESHNESS. A signature says "we published this", never "this is current".
+    const floor = await readBundleSequence();
+    if (manifest.sequence < floor) {
+        throw new BundleVerificationError(`refusing a skills bundle at sequence ${manifest.sequence}; this machine has already ` +
+            `accepted ${floor}. A correctly-signed OLD bundle re-introduces every skill defect fixed since.`);
+    }
+    const root = bundleRoot();
+    const localStamp = await computeBundleStamp(root).catch(() => null);
+    if (localStamp === manifest.stamp) {
+        await recordBundleSequence(manifest.sequence);
+        await writeInstalledManifest(manifest);
+        return { manifest, root, changed: false };
+    }
+    const targz = await transport.tarball();
+    // 4. TRANSPORT ONLY. This catches a truncated download; it cannot catch a
+    //    hostile one, because whoever served the bytes also served this hash.
+    if (envelope.tgz_sha256) {
+        const got = createHash("sha256").update(targz).digest("hex");
+        if (got !== envelope.tgz_sha256) {
+            throw new BundleVerificationError(`bundle download is corrupt: sha256 ${got} != advertised ${envelope.tgz_sha256}`);
+        }
+    }
+    // Extract beside the destination, on the same filesystem, so the swap is a
+    // rename and not a copy.
+    await fs.mkdir(symbolsHome(), { recursive: true, mode: 0o700 });
+    const staging = `${root}.staging-${process.pid}-${randomBytes(4).toString("hex")}`;
+    await fs.rm(staging, { recursive: true, force: true });
+    await fs.mkdir(staging, { recursive: true, mode: 0o755 });
+    try {
+        await extractTarGz(targz, staging);
+        // 2. INTEGRITY OF WHAT LANDED. After extraction, deliberately.
+        const extracted = await computeBundleStamp(staging);
+        if (extracted !== manifest.stamp) {
+            throw new BundleVerificationError(`extracted bundle hashes to ${extracted}, but the signed manifest says ${manifest.stamp}`);
+        }
+        // ── the atomic rename, mirroring odin_skill_sync.rs:220-237 ──────────────
+        // A truncated SKILL.md is worse than a stale one, because stale still
+        // parses: the agent reads it, believes it, and acts on instructions that are
+        // merely out of date rather than obviously broken.
+        const old = `${root}.old`;
+        await fs.rm(old, { recursive: true, force: true });
+        if (await exists(root))
+            await fs.rename(root, old);
+        await fs.rename(staging, root);
+        await fs.rm(old, { recursive: true, force: true });
+    }
+    finally {
+        await fs.rm(staging, { recursive: true, force: true });
+    }
+    await writeInstalledManifest(manifest);
+    await recordBundleSequence(manifest.sequence);
+    return { manifest, root, changed: true };
+}
+async function writeInstalledManifest(manifest) {
+    const path = installedManifestPath();
+    await fs.mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(manifest, null, 2) + "\n", { mode: 0o644 });
+    await fs.rename(tmp, path);
+}
+async function exists(path) {
+    try {
+        await fs.stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/skills/claude-md.js

@@ -0,0 +1,135 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// `<project>/CLAUDE.md` — write ONLY between the managed markers.
+//
+// ## Why markers and not a file
+//
+// `CLAUDE.md` is the single most valuable file in a project directory: it is
+// where the user records the things they had to learn the hard way. It is also a
+// file Claude Code reads in EVERY directory, so it is the most attractive write
+// target in the tree. Two rules follow, and they point the same way:
+//
+//   * we own a marked region and nothing else, so a `symbols up` can never eat a
+//     paragraph the user wrote;
+//   * server content NEVER lands here at all (S2). `CLAUDE.md` is on
+//     `sync/paths.ts`'s deny-list by basename, at any depth. What this file
+//     writes is generated locally from the manifest — not fetched, not synced.
+//
+// ## Freeze on ambiguity, never guess
+//
+// Malformed markers — an end before a begin, two begins, a begin with no end —
+// are refused rather than repaired. "Repair" means choosing which of the user's
+// bytes are ours, and the only safe answer to that question is to stop and say
+// so. This is the same posture the sync engine takes on a path collision.
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+export const BEGIN = "<!-- symbols:begin managed -->";
+export const END = "<!-- symbols:end managed -->";
+export function projectClaudeMdPath(projectDir) {
+    return join(projectDir, "CLAUDE.md");
+}
+export class MarkerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MarkerError";
+    }
+}
+/**
+ * Replace the managed region of `text`, appending the block if it is absent.
+ *
+ * Pure and exported so the property — everything outside the markers survives
+ * byte for byte — is testable without a filesystem.
+ */
+export function applyManagedBlock(text, body) {
+    const begins = countOccurrences(text, BEGIN);
+    const ends = countOccurrences(text, END);
+    if (begins > 1 || ends > 1) {
+        throw new MarkerError(`CLAUDE.md contains ${begins} begin and ${ends} end markers. Refusing to guess which region is ours.`);
+    }
+    if (begins !== ends) {
+        throw new MarkerError(`CLAUDE.md has an unmatched symbols marker (${begins} begin, ${ends} end). ` +
+            `Fix or remove the stray marker and re-run.`);
+    }
+    const block = `${BEGIN}\n${body.replace(/\s+$/, "")}\n${END}`;
+    if (begins === 0) {
+        const separator = text.length === 0 ? "" : text.endsWith("\n\n") ? "" : text.endsWith("\n") ? "\n" : "\n\n";
+        return `${text}${separator}${block}\n`;
+    }
+    const start = text.indexOf(BEGIN);
+    const stop = text.indexOf(END);
+    if (stop < start) {
+        throw new MarkerError("CLAUDE.md's symbols end marker precedes its begin marker.");
+    }
+    return text.slice(0, start) + block + text.slice(stop + END.length);
+}
+export async function writeManagedBlock(projectDir, body) {
+    const path = projectClaudeMdPath(projectDir);
+    let before = "";
+    let created = false;
+    try {
+        before = await fs.readFile(path, "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        created = true;
+    }
+    const after = applyManagedBlock(before, body);
+    if (after === before) {
+        return { path, created: false, changed: false, preservedBytes: outsideBytes(before) };
+    }
+    // Write-then-rename. A half-written CLAUDE.md is read by the agent on its very
+    // next turn, and a truncated instruction file is worse than a stale one.
+    const tmp = `${path}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, after, { mode: 0o644 });
+    await fs.rename(tmp, path);
+    return { path, created, changed: true, preservedBytes: outsideBytes(after) };
+}
+function countOccurrences(haystack, needle) {
+    let n = 0;
+    let from = 0;
+    for (;;) {
+        const at = haystack.indexOf(needle, from);
+        if (at === -1)
+            return n;
+        n += 1;
+        from = at + needle.length;
+    }
+}
+function outsideBytes(text) {
+    const start = text.indexOf(BEGIN);
+    const stop = text.indexOf(END);
+    if (start === -1 || stop === -1)
+        return Buffer.byteLength(text, "utf8");
+    return Buffer.byteLength(text.slice(0, start) + text.slice(stop + END.length), "utf8");
+}
+/**
+ * The managed body itself: what the agent is told about this project.
+ *
+ * Deliberately short and factual. Anything that needs to be long belongs in a
+ * SKILL, which is versioned, signed and reviewed; `CLAUDE.md` is loaded into
+ * every single turn and its cost is paid on all of them.
+ */
+export function renderManagedBody(opts) {
+    const lines = [];
+    lines.push("## Symbols");
+    lines.push("");
+    lines.push(`This directory is the Symbols project **${opts.projectName}** (notebook \`${opts.notebookId}\`).`);
+    lines.push("Files here sync with the Symbols app. Edits land in the app; edits in the app land here.");
+    lines.push("");
+    lines.push("- `symbols status` — what is out of sync · `symbols sync` — reconcile now · `symbols doctor` — check the install");
+    lines.push("- Deleting a file here DELETES IT IN THE APP. There is no undo and no server-side copy afterwards.");
+    lines.push("- `.symbols/` is the CLI's own state. Do not edit it; changing `project.json` retargets sync at a different notebook.");
+    if (opts.protectedPaths && opts.protectedPaths.length > 0) {
+        lines.push("");
+        lines.push("**Regime-backed files — a deployed strategy reads these. Ask before changing or deleting one:**");
+        for (const p of opts.protectedPaths)
+            lines.push(`- \`${p}\``);
+    }
+    lines.push("");
+    lines.push(`Skills: ${opts.plugins.map((p) => `${p.name} ${p.version}`).join(" · ")}. ` +
+        "Managed by `symbols` — edit outside these markers only.");
+    return lines.join("\n");
+}