@symbols-cli/cli 0.0.1

package/dist/commands/mcp.js

@@ -0,0 +1,33 @@
+// 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.
+// `symbols mcp` — run the Symbols MCP server on stdio.
+//
+// Not invoked by hand. Claude Code launches it from a plugin-shipped `.mcp.json`:
+//
+//     { "mcpServers": { "symbols": { "command": "symbols", "args": ["mcp"] } } }
+//
+// The P0 spike confirmed a plugin may ship its own `.mcp.json` (verified live —
+// the vercel and supabase plugins do), so nothing here needs to write
+// `~/.claude.json`. Tools then appear to the agent as
+// `mcp__plugin_<plugin>_<serverKey>__<tool>` — e.g. `mcp__plugin_odin_symbols__get_quote`.
+//
+// ⚠ This process owns stdout for JSON-RPC. Anything printed there breaks the
+// protocol, so every message this command emits goes to stderr.
+import { serve } from "../mcp/server.js";
+import { eprint } from "../util/log.js";
+export async function run(argv) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        eprint("usage: symbols mcp\n\n" +
+            "Runs the Symbols MCP server on stdio. Launched by Claude Code via the\n" +
+            "plugin's .mcp.json — you do not normally run this yourself.\n");
+        return 2;
+    }
+    if (argv.length > 0) {
+        eprint(`symbols mcp: unexpected argument '${argv[0]}'\n`);
+        return 2;
+    }
+    await serve();
+    return 0;
+}

package/dist/commands/project.js

@@ -0,0 +1,145 @@
+// 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.
+// `symbols project` — new · ls · rm · detach.
+//
+// The replacement for the container's `nb` helper, and the semantics DIFFER in a
+// way that matters: `notebook-workspace/SKILL.md` currently teaches that the
+// project folders are SYMLINKS and that `rm -rf` is silently undone by the next
+// materialize. On a laptop both are false. Projects are real directories and
+// `rm -rf` is genuinely destructive, so the confirm-before-delete rule gets
+// STRONGER here, not weaker.
+//
+// ## `rm` and `detach` are different operations and must never be confused
+//
+//   `rm`      deletes the NOTEBOOK, server-side, for every device. Irreversible.
+//   `detach`  stops syncing this directory. The notebook and the files both
+//             survive; only this machine forgets the binding.
+//
+// A user who means the second and gets the first has lost work in a way no
+// amount of local backup helps. So `rm` requires the project's name typed back,
+// and `detach` never touches the server.
+import { promises as fs } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { Ledger } from "../sync/ledger.js";
+import { ensureProjects, projectJsonPath, rootGate } from "../sync/reconcile.js";
+import { listProjects, createNotebook, deleteNotebook } from "../sync/api.js";
+import { workspaceRoot } from "../util/platform.js";
+import { eprint, print } from "../util/log.js";
+async function confirm(question, expect) {
+    if (!process.stdin.isTTY) {
+        eprint(`refusing without a terminal to confirm on. Re-run interactively, or pass --yes if you are certain.\n`);
+        return false;
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await rl.question(question);
+        return answer.trim() === expect;
+    }
+    finally {
+        rl.close();
+    }
+}
+async function cmdLs(ledger) {
+    const server = await listProjects();
+    const bound = new Map(ledger.projects().map((p) => [p.notebookId, p]));
+    if (server.length === 0) {
+        print("no projects on the server\n");
+        return 0;
+    }
+    for (const p of server) {
+        const local = bound.get(p.id);
+        const where = local ? local.root : `(not synced — run \`symbols up\`)`;
+        const problem = local ? await rootGate(local) : null;
+        const flag = local?.frozenReason ? "FROZEN " : problem ? "OFFLINE" : local ? "ok     " : "       ";
+        print(`${flag} ${p.name}\n         ${where}\n`);
+    }
+    return 0;
+}
+async function cmdNew(ledger, name) {
+    if (!name) {
+        eprint("usage: symbols project new <name>\n");
+        return 2;
+    }
+    const created = await createNotebook(name);
+    print(`created notebook ${created.id}\n`);
+    // Re-materialize so the directory, `project.json` and the ledger binding all
+    // exist before the user's next command — the server computes the dirname, and
+    // the dedupe is positional, so the only correct answer comes from a fresh list.
+    const ensured = await ensureProjects(ledger, await listProjects(), workspaceRoot());
+    const mine = ensured.find((e) => e.notebookId === created.id);
+    if (mine?.project)
+        print(`${mine.project.root}\n`);
+    return 0;
+}
+async function cmdDetach(ledger, name) {
+    const target = ledger
+        .projects()
+        .find((p) => p.name === name || p.dirname === name || p.notebookId === name);
+    if (!target) {
+        eprint(`no synced project named '${name}'\n`);
+        return 1;
+    }
+    // The ledger has no "forget" verb by design — dropping rows is how a base is
+    // lost, and a lost base re-conflicts every path. Freezing achieves the goal
+    // (nothing is synced) without discarding what we knew.
+    ledger.freezeProject(target.id, `detached by \`symbols project detach\` — no file is synced until you run \`symbols up\` here again`);
+    // The identity anchor goes, so a later `up` in this directory does not silently
+    // re-adopt it. The files stay: detach is not a delete.
+    await fs.rm(projectJsonPath(target.root), { force: true });
+    print(`detached ${target.name} — ${target.root} is no longer synced\n`);
+    print(`your files were NOT touched.\n`);
+    return 0;
+}
+async function cmdRm(ledger, name, yes) {
+    const server = await listProjects();
+    const target = server.find((p) => p.name === name || p.dirname === name || p.id === name);
+    if (!target) {
+        eprint(`no project named '${name}'\n`);
+        return 1;
+    }
+    eprint(`\n⚠ This DELETES the notebook '${target.name}' and every file in it, for every device.\n` +
+        `  It is not undoable. To stop syncing this machine only, use \`symbols project detach\`.\n\n`);
+    if (!yes && !(await confirm(`Type the project name to confirm: `, target.name))) {
+        eprint("aborted — nothing was deleted\n");
+        return 1;
+    }
+    await deleteNotebook(target.id);
+    const local = ledger.project(target.id);
+    if (local) {
+        ledger.freezeProject(local.id, `the notebook was deleted with \`symbols project rm\``);
+        // The local directory is NOT removed. The server row is gone and the files
+        // here are now the only copy — deleting them on the strength of a successful
+        // API call would turn one confirmed action into two, and the second one was
+        // never confirmed.
+        print(`the local directory ${local.root} was kept — delete it yourself if you meant to.\n`);
+    }
+    print(`deleted ${target.name}\n`);
+    return 0;
+}
+export async function run(argv) {
+    const [sub, ...rest] = argv;
+    const yes = rest.includes("--yes");
+    const name = rest.filter((a) => !a.startsWith("--")).join(" ");
+    const ledger = await Ledger.open();
+    try {
+        switch (sub) {
+            case "ls":
+            case undefined:
+                return await cmdLs(ledger);
+            case "new":
+                return await cmdNew(ledger, name);
+            case "detach":
+                return await cmdDetach(ledger, name);
+            case "rm":
+                return await cmdRm(ledger, name, yes);
+            default:
+                eprint(`usage: symbols project [ls|new <name>|rm <name>|detach <name>]\n`);
+                return 2;
+        }
+    }
+    finally {
+        ledger.close();
+    }
+}

package/dist/commands/status.js

@@ -0,0 +1,78 @@
+// 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.
+// `symbols status` — what sync is holding, and why.
+//
+// ## Frozen is a FIRST-CLASS state, not an error to be swept up
+//
+// The three-way table's answer to every ambiguous case is "freeze and report",
+// which is only a safe design if the report is somewhere the user actually
+// looks. A conflict that keeps the local file and writes a sidecar has lost
+// nothing — but if nobody ever learns the path stopped syncing, the server copy
+// diverges silently for weeks and the eventual merge is a research project.
+//
+// So this command reads the LEDGER, not the network: it works offline, it is
+// instant, and it never itself changes anything. `--json` exists because
+// `symbols doctor` and the conformance harness parse it, and a human-formatted
+// table parsed with a regex is the substring-grep failure in a different hat.
+import { Ledger } from "../sync/ledger.js";
+import { rootGate } from "../sync/reconcile.js";
+import { print } from "../util/log.js";
+export async function run(argv) {
+    const json = argv.includes("--json");
+    const ledger = await Ledger.open();
+    try {
+        const out = [];
+        for (const p of ledger.projects()) {
+            const problem = await rootGate(p);
+            const frozenFiles = ledger.frozen(p.id);
+            out.push({
+                name: p.name,
+                notebook_id: p.notebookId,
+                root: p.root,
+                present: problem === null,
+                // The project-level freeze and the "is it there right now" check are
+                // separate facts: a project can be frozen for an ambiguity that has
+                // nothing to do with the directory being absent.
+                frozen_reason: p.frozenReason ?? problem,
+                tracked: ledger.files(p.id).length,
+                frozen_paths: frozenFiles.map((f) => ({
+                    path: f.path,
+                    reason: f.frozenReason ?? "frozen",
+                })),
+                queued: ledger.pending(p.id).length,
+            });
+        }
+        if (json) {
+            print(`${JSON.stringify({ projects: out }, null, 2)}\n`);
+        }
+        else if (out.length === 0) {
+            print("no projects are being synced — run `symbols up`\n");
+        }
+        else {
+            for (const p of out) {
+                const flag = p.frozen_reason ? "FROZEN" : p.present ? "ok" : "OFFLINE";
+                print(`${flag}  ${p.name}\n`);
+                print(`       ${p.root}\n`);
+                print(`       ${p.tracked} tracked file(s)`);
+                if (p.queued > 0)
+                    print(`, ${p.queued} queued`);
+                print("\n");
+                if (p.frozen_reason)
+                    print(`       ⚠ ${p.frozen_reason}\n`);
+                for (const f of p.frozen_paths) {
+                    print(`       ! ${f.path}\n         ${f.reason}\n`);
+                }
+                print("\n");
+            }
+        }
+        // Non-zero when anything is frozen. `status` is the surface a script polls,
+        // and "everything is fine" must be a code, not a paragraph.
+        const bad = out.filter((p) => p.frozen_reason || p.frozen_paths.length > 0).length;
+        return bad > 0 ? 1 : 0;
+    }
+    finally {
+        ledger.close();
+    }
+}

package/dist/commands/sync.js

@@ -0,0 +1,94 @@
+// 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.
+// `symbols sync` — one full sweep, then exit.
+//
+// The same engine `watch` runs on a timer; there is deliberately no second code
+// path. A "quick sync" that skipped a guard would be the drift the whole design
+// is built to prevent.
+import { Ledger } from "../sync/ledger.js";
+import { ensureProjects, syncProject } from "../sync/reconcile.js";
+import { listProjects } from "../sync/api.js";
+import { workspaceRoot } from "../util/platform.js";
+import { eprint, print } from "../util/log.js";
+export function renderResult(r) {
+    const lines = [];
+    if (r.offline) {
+        lines.push(`  ${r.project}: OFFLINE — ${r.offlineReason}`);
+        return lines.join("\n");
+    }
+    const moved = r.pulled + r.pushed + r.localDeletes + r.serverDeletes + r.conflicts + r.frozen.length;
+    const parts = [];
+    if (r.pulled)
+        parts.push(`${r.pulled} pulled`);
+    if (r.pushed)
+        parts.push(`${r.pushed} pushed`);
+    if (r.localDeletes)
+        parts.push(`${r.localDeletes} deleted locally`);
+    if (r.serverDeletes)
+        parts.push(`${r.serverDeletes} deleted on the server`);
+    if (r.conflicts)
+        parts.push(`${r.conflicts} CONFLICT`);
+    if (r.frozen.length)
+        parts.push(`${r.frozen.length} frozen`);
+    lines.push(`  ${r.project}: ${moved === 0 ? "up to date" : parts.join(", ")}`);
+    if (r.deletesBlocked) {
+        lines.push(`    ⚠ ${r.deletesBlocked}`);
+    }
+    for (const f of r.frozen) {
+        lines.push(`    ! ${f.path} — ${f.reason}`);
+    }
+    return lines.join("\n");
+}
+export async function run(argv) {
+    const confirmDeletes = argv.includes("--confirm-deletes");
+    const dryRun = argv.includes("--dry-run") || argv.includes("-n");
+    const only = argv.find((a) => a.startsWith("--project="))?.slice("--project=".length);
+    const ledger = await Ledger.open();
+    try {
+        // The server list is the authority for which notebooks exist and what each
+        // one's directory is called. A failure here is NOT a reason to sweep the
+        // ledger's cached projects anyway: if we cannot list, we cannot tell a
+        // deleted notebook from an unreachable server, and the second one must never
+        // produce deletes.
+        const projects = await listProjects();
+        const ensured = await ensureProjects(ledger, projects, workspaceRoot());
+        const results = [];
+        let problems = 0;
+        for (const e of ensured) {
+            if (e.dirnameDrift) {
+                eprint(`symbols: ${e.name}: ${e.dirnameDrift}\n`);
+            }
+            if (e.problem || !e.project) {
+                eprint(`symbols: ${e.name}: ${e.problem ?? "could not be bound"}\n`);
+                problems += 1;
+                continue;
+            }
+            if (only && e.project.name !== only && e.project.dirname !== only)
+                continue;
+            results.push(await syncProject({
+                ledger,
+                project: e.project,
+                confirmDeletes,
+                ...(dryRun ? { dryRun: true } : {}),
+                log: (l) => print(`${l}\n`),
+            }));
+        }
+        print(`${dryRun ? "would sync" : "synced"} ${results.length} project(s)\n`);
+        for (const r of results)
+            print(`${renderResult(r)}\n`);
+        // ⚠ The exit code is a contract, and a frozen path is NOT success. A sync
+        // that silently returns 0 while three files are frozen trains the user (and
+        // any script) to stop reading the output, which is how the one conflict that
+        // mattered goes unnoticed.
+        const frozen = results.reduce((n, r) => n + r.frozen.length, 0);
+        const offline = results.filter((r) => r.offline).length;
+        if (problems > 0 || frozen > 0 || offline > 0)
+            return 1;
+        return 0;
+    }
+    finally {
+        ledger.close();
+    }
+}

package/dist/commands/uninstall.js

@@ -0,0 +1,149 @@
+// 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.
+// `symbols uninstall` — remove what this CLI installed, and NOTHING ELSE.
+//
+// # ⚠ THE ONE RULE: THIS COMMAND NEVER DELETES A PROJECT
+//
+// `~/Symbols/<Project>/` holds the user's work. Some of it is synced and some
+// of it — anything over 1 MB, anything non-UTF-8, every plot and CSV and
+// parquet the agent produced — EXISTS NOWHERE ELSE. The server-side notebook is
+// not a backup of it.
+//
+// So an uninstall that "tidies up the workspace" is unrecoverable data loss
+// dressed as housekeeping, and no confirmation prompt makes that acceptable:
+// the person typing `uninstall` is thinking about the tool, not about the four
+// months of notebooks under it. This command therefore has no flag that deletes
+// projects. Not `--all`, not `--purge`. If the user wants the directory gone
+// they can delete it themselves, having seen it.
+//
+// What it DOES remove, all of it re-creatable:
+//   ~/.symbols/plugins/     the skills bundle       (re-fetch: symbols update)
+//   ~/.symbols/manifest.json                        (same)
+//   ~/.symbols/state.db     the sync ledger         (rebuilt on next sync)
+//   the credential          keychain or 0600 file   (re-created: symbols login)
+//
+// The ledger is worth a note: dropping it is safe precisely BECAUSE the sync is
+// three-way. With no recorded base every path re-diffs as "no common ancestor",
+// which the table resolves to CONFLICT — keep local, write the server copy
+// beside it, freeze. Noisy, never destructive. A last-writer-wins design could
+// not offer this command at all.
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { load, clear, credentialsPath, storeKind } from "../auth/credentials.js";
+import { requestAnonymous, forgetAccessToken } from "../auth/client.js";
+import { symbolsHome, workspaceRoot, bundleRoot, installedManifestPath } from "../util/platform.js";
+import { print, eprint } from "../util/log.js";
+function usage() {
+    eprint(`usage: symbols uninstall [--keep-credential] [--yes]\n\n` +
+        `Removes the skills bundle, the sync ledger and this device's credential.\n\n` +
+        `  --keep-credential   leave the login in place (skills + ledger only)\n` +
+        `  --yes               do not prompt\n\n` +
+        `⚠ Your projects under ~/Symbols are NEVER touched. Delete them yourself if\n` +
+        `  you want them gone — some files there exist nowhere else.\n\n` +
+        `This does not remove the npm package: npm rm -g @symbols-cli/cli\n`);
+    return 2;
+}
+async function rm(path) {
+    try {
+        await fs.rm(path, { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Prompt on a TTY. Anywhere else, refuse rather than assume consent. */
+async function confirm(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    process.stderr.write(question);
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = (await rl.question("")).trim().toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function run(argv) {
+    if (argv.includes("-h") || argv.includes("--help"))
+        return usage();
+    const keepCredential = argv.includes("--keep-credential");
+    const assumeYes = argv.includes("--yes");
+    const home = symbolsHome();
+    const ledger = join(home, "state.db");
+    // Say exactly what will go, and exactly what will not, BEFORE asking.
+    print(`This will remove:\n` +
+        `  ${bundleRoot()}            (skills bundle — re-fetch with \`symbols update\`)\n` +
+        `  ${installedManifestPath()}\n` +
+        `  ${ledger}                  (sync ledger — rebuilt on the next sync)\n` +
+        (keepCredential
+            ? ``
+            : `  this device's credential   (${storeKind() === "keychain" ? "keychain" : credentialsPath()})\n`) +
+        `\nIt will NOT touch your projects in ${workspaceRoot()}.\n` +
+        `Some files there — anything over 1 MB, anything not UTF-8 — exist nowhere else.\n\n`);
+    if (!assumeYes && !(await confirm("Continue? [y/N] "))) {
+        // A non-TTY lands here too: a piped or CI invocation must pass --yes
+        // explicitly rather than have consent inferred from an absent terminal.
+        eprint("\nNothing was removed. Pass --yes to skip this prompt.\n");
+        return 1;
+    }
+    // ── the credential goes FIRST, and server-side before local ────────────────
+    //
+    // Same ordering as `logout`, for the same reason: clearing locally first and
+    // then failing to reach the server leaves a live credential on the account
+    // with nothing on this machine able to revoke it. The user believes the
+    // laptop is disconnected; it is not.
+    if (!keepCredential) {
+        const cred = await load();
+        if (cred) {
+            try {
+                await requestAnonymous("/api/auth/cli/logout", {
+                    method: "POST",
+                    body: JSON.stringify({ refresh_token: cred.refreshToken }),
+                });
+                print("Device revoked server-side.\n");
+            }
+            catch (err) {
+                eprint(`\n⚠ Could not revoke this device server-side: ${err.message}\n` +
+                    `The local credential has NOT been removed, because deleting it now would\n` +
+                    `leave a working credential on your account that this machine can no longer\n` +
+                    `revoke. Re-run when you are online, or revoke the device in the app.\n`);
+                return 1;
+            }
+            await clear();
+            forgetAccessToken();
+            print("Local credential removed.\n");
+        }
+    }
+    let removed = 0;
+    for (const path of [bundleRoot(), installedManifestPath(), ledger]) {
+        if (await rm(path))
+            removed += 1;
+    }
+    print(`Removed ${removed} item(s).\n`);
+    // ⚠ `~/.symbols` itself is removed ONLY if it is now empty. It is the
+    // documented home for CLI state, and a future version may keep something
+    // there this build does not know about — `rm -rf` on a directory whose full
+    // contents you cannot enumerate is how the notebook-delete incident happened.
+    try {
+        const left = await fs.readdir(home);
+        if (left.length === 0) {
+            await fs.rmdir(home);
+            print(`Removed ${home}.\n`);
+        }
+        else {
+            print(`Left ${home} in place — it still holds: ${left.join(", ")}\n`);
+        }
+    }
+    catch {
+        // Already gone, or never existed.
+    }
+    print(`\nYour projects are untouched in ${workspaceRoot()}.\n` +
+        `To remove the command itself: npm rm -g @symbols-cli/cli\n`);
+    return 0;
+}

package/dist/commands/up.js

@@ -0,0 +1,176 @@
+// 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.
+// `symbols up` — turn an account into working directories.
+//
+// One command between `symbols login` and `claude`. It materialises every
+// notebook as a real directory under `~/Symbols/`, wires the project-scope
+// plugin install, merges (never overwrites) the project settings and `CLAUDE.md`,
+// and runs the first sync.
+//
+// ## The ownership rule, restated because this is the command that could break it
+//
+// > `symbols` owns `~/Symbols/**` and nothing else.
+//
+// Nothing here writes `~/.claude/CLAUDE.md`, `~/.claude/settings.json`,
+// `~/.claude.json`, or a shell rc. The container earned the right to own a
+// filesystem by BEING the filesystem; the CLI is a guest in someone's home
+// directory. Every file this command writes is inside a project root, and every
+// one of them is merged rather than replaced.
+//
+// ## ⚠ The `.mcp.json` question, answered by NOT writing one
+//
+// The plan's layout line for this file reads "CLAUDE.md, .mcp.json, plugins,
+// .gitignore", and the `.mcp.json` half is deliberately **not** implemented here.
+// The plan's own skills section settles it: *"a plugin can ship its own
+// `.mcp.json`, so we never write `~/.claude.json`"* — the MCP registration rides
+// in the bundle, which is signed. A `.mcp.json` written by this command would be
+// an UNSIGNED file that tells Claude Code what process to launch, sitting in a
+// directory the sync engine also writes to. That is the remote-code-execution
+// channel the plan calls the thing it got most wrong, re-opened by a convenience.
+// If the bundle ever stops shipping one, this is where it goes back — signed.
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { listProjects } from "../sync/api.js";
+import { Ledger } from "../sync/ledger.js";
+import { ensureProjects, syncProject } from "../sync/reconcile.js";
+import { fetchProtected, protectedPaths, applyReadOnly } from "../sync/protect.js";
+import { readInstalledManifest } from "../skills/bundle.js";
+import { installPlugins, ClaudeCliMissingError } from "../skills/install.js";
+import { mergeProjectSettings } from "../skills/settings-merge.js";
+import { writeManagedBlock, renderManagedBody, MarkerError } from "../skills/claude-md.js";
+import { workspaceRoot } from "../util/platform.js";
+import { renderResult } from "./sync.js";
+import { eprint, print } from "../util/log.js";
+/**
+ * What we add to a project's `.gitignore`, and nothing else.
+ *
+ * Appended between no markers because a `.gitignore` has no comment structure to
+ * hang them on — so it is APPEND-ONLY and idempotent by line membership. A user
+ * who deletes our line keeps it deleted only until the next `up`, which is the
+ * one behaviour here that is worse than the settings merge; it is accepted
+ * because a synced `.symbols/state.db` in someone's git history is worse.
+ */
+const GITIGNORE_LINES = [".symbols/", "*.server.*"];
+async function ensureGitignore(root) {
+    const path = join(root, ".gitignore");
+    let existing = "";
+    try {
+        existing = await fs.readFile(path, "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    const have = new Set(existing.split("\n").map((l) => l.trim()));
+    const missing = GITIGNORE_LINES.filter((l) => !have.has(l));
+    if (missing.length === 0)
+        return false;
+    const prefix = existing === "" ? "" : existing.endsWith("\n") ? "" : "\n";
+    await fs.writeFile(path, `${existing}${prefix}\n# Symbols CLI\n${missing.join("\n")}\n`, "utf8");
+    return true;
+}
+export async function run(argv) {
+    const skipSkills = argv.includes("--no-skills");
+    const skipSync = argv.includes("--no-sync");
+    const ledger = await Ledger.open();
+    try {
+        const projects = await listProjects();
+        if (projects.length === 0) {
+            print("no notebooks on this account yet — create one with `symbols project new <name>`\n");
+            return 0;
+        }
+        const ensured = await ensureProjects(ledger, projects, workspaceRoot());
+        const manifest = skipSkills ? null : await readInstalledManifest();
+        if (!skipSkills && manifest === null) {
+            // Not fatal: the directories and the sync are useful without the skills,
+            // and failing the whole bootstrap on a missing bundle would make a
+            // network blip look like a broken install.
+            eprint("symbols: no skills bundle is installed yet — run `symbols update` to fetch it\n");
+        }
+        let failures = 0;
+        for (const e of ensured) {
+            if (e.dirnameDrift)
+                eprint(`symbols: ${e.name}: ${e.dirnameDrift}\n`);
+            if (e.problem || !e.project) {
+                eprint(`symbols: ${e.name}: ${e.problem ?? "could not be bound"}\n`);
+                failures += 1;
+                continue;
+            }
+            const root = e.project.root;
+            print(`${e.name}\n  ${root}\n`);
+            await ensureGitignore(root);
+            // Which files a live regime or widget is reading. Fetched BEFORE the sync
+            // so the agent is told before it can form the intent to delete one — and
+            // so the read-only marks are already on when the first pull lands.
+            let protectedEntries = [];
+            try {
+                protectedEntries = await fetchProtected(e.notebookId);
+            }
+            catch (err) {
+                // ⚠ NOT an empty set. A failed read is not an affirmative "nothing is
+                // protected", and treating it as one would silently unmark every
+                // regime-backed file on a blip. The server's 409 still refuses.
+                eprint(`symbols: could not read protected files for ${e.name} (${err.message}) — ` +
+                    `existing read-only marks are left as they are\n`);
+            }
+            if (manifest) {
+                try {
+                    await mergeProjectSettings(root, manifest);
+                    await installPlugins(root, manifest);
+                }
+                catch (err) {
+                    if (err instanceof ClaudeCliMissingError) {
+                        eprint(`symbols: ${err.message}\n`);
+                    }
+                    else {
+                        eprint(`symbols: ${e.name}: ${err.message}\n`);
+                        failures += 1;
+                    }
+                }
+                try {
+                    await writeManagedBlock(root, renderManagedBody({
+                        projectName: e.name,
+                        notebookId: e.notebookId,
+                        plugins: manifest.plugins.map((p) => ({ name: p.name, version: p.version })),
+                        protectedPaths: protectedPaths(protectedEntries),
+                    }));
+                }
+                catch (err) {
+                    if (err instanceof MarkerError) {
+                        // Duplicate or unmatched markers mean we cannot tell which region is
+                        // ours. Freezing is right: rewriting the file would eat whatever the
+                        // user put between the stray markers.
+                        eprint(`symbols: ${e.name}: ${err.message}\n`);
+                        failures += 1;
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+            }
+            if (!skipSync) {
+                const res = await syncProject({
+                    ledger,
+                    project: e.project,
+                    log: (l) => print(`${l}\n`),
+                });
+                print(`${renderResult(res)}\n`);
+                if (res.offline || res.frozen.length > 0)
+                    failures += 1;
+            }
+            // Marks go on AFTER the pull, so a file that did not exist locally a
+            // moment ago is marked too.
+            for (const p of protectedPaths(protectedEntries)) {
+                await applyReadOnly(join(root, p), true);
+            }
+        }
+        print(`\nready. \`cd ${workspaceRoot()}/<project>\` and run \`claude\`.\n` +
+            `Keep \`symbols watch\` running in another terminal to stay in sync.\n`);
+        return failures > 0 ? 1 : 0;
+    }
+    finally {
+        ledger.close();
+    }
+}