@bugb-technologies/bravos 0.0.0-stage → 1.0.1

package/dist/codegraph.js

@@ -0,0 +1,268 @@
+// @comment -- "The code graph, driven by this CLI: codegraph-build indexes a repository and codegraph-mcp answers questions about it over MCP on stdio. `bravos graph build` runs the builder; `bravos graph <question> [args] --json` starts the server for one call, speaks JSON-RPC to it (initialize, tools/list, tools/call) with no dependency, and prints the answer. The binaries come from the staged bundle under $BRAVOS_HOME/codegraph first, then PATH, then the Python CLI's wheel, so a machine that moved from the Python bravos keeps working. The graph store is BRAVOS_CODEGRAPH_DIR, else $BRAVOS_HOME/codegraph/store, else the Python launcher's own."
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { staged } from './artifacts.js';
+import { graphBin as legacyGraphBin, graphStoreDir as legacyStoreDir } from './graphbin.js';
+import { BravosError } from './types.js';
+// @comment -- "Resolution order for a graph binary: the staged bundle this CLI installed, PATH, the Python CLI's wheel payload. Null when none has it."
+export function graphBin(name, env = process.env) {
+    const dir = staged(env, 'codegraph');
+    if (dir)
+        return join(dir, name);
+    return legacyGraphBin(name, env);
+}
+/** Where graphs are kept: explicit, else this CLI's own store (created on demand), else the Python launcher's. */
+export function graphStore(env = process.env) {
+    if (env.BRAVOS_CODEGRAPH_DIR)
+        return env.BRAVOS_CODEGRAPH_DIR;
+    if (staged(env, 'codegraph')) {
+        const home = env.BRAVOS_HOME || (env.HOME ? join(env.HOME, '.bravos') : null);
+        if (home) {
+            const store = join(home, 'codegraph', 'store');
+            try {
+                mkdirSync(store, { recursive: true, mode: 0o700 });
+            }
+            catch {
+                /* reported at use */
+            }
+            return store;
+        }
+    }
+    return legacyStoreDir(env);
+}
+export const graphEnv = (env) => {
+    const store = graphStore(env);
+    return store ? { ...env, BRAVOS_CODEGRAPH_DIR: store } : { ...env };
+};
+export const SCIP_MODES = ['auto', 'trusted', 'no-exec', 'isolate', 'off'];
+// @comment -- "bravos graph build DIR [--scip MODE] [--mode auto|build|reuse] [--json]: runs codegraph-build --project-path DIR with the store in the environment. --scip auto/trusted runs the repository's own code (type checkers, build scripts), which is why the skills ask before using it; no-exec is the default here."
+export function build(root, env, opts = {}) {
+    const bin = graphBin('codegraph-build', env);
+    if (!bin)
+        throw new BravosError('codegraph-build is not installed: bravos setup --codegraph fetches it (on the Team plan)');
+    const scip = opts.scip ?? 'no-exec';
+    if (!SCIP_MODES.includes(scip))
+        throw new BravosError(`--scip must be one of ${SCIP_MODES.join(', ')}, got ${JSON.stringify(scip)}`);
+    const args = ['--project-path', root, '--scip', scip];
+    if (opts.mode)
+        args.push('--mode', opts.mode);
+    if (opts.json)
+        args.push('--json');
+    const r = spawnSync(bin, args, { cwd: root, env: graphEnv(env), encoding: 'utf8', timeout: opts.timeoutMs ?? 3 * 600 * 1000, maxBuffer: 64 * 1024 * 1024 });
+    return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+export class GraphUnavailable extends BravosError {
+    constructor(message) {
+        super(message);
+    }
+}
+// @comment -- "A minimal MCP stdio client: newline-delimited JSON-RPC 2.0 to a child codegraph-mcp --project-path ROOT. One session per question; the server is killed on close or timeout. stderr is kept for the error message; stdout is parsed line by line, with anything that is not a JSON-RPC message ignored."
+export class GraphSession {
+    child;
+    buf = '';
+    nextId = 1;
+    pending = new Map();
+    stderr = '';
+    closed = null;
+    constructor(bin, root, env) {
+        this.child = spawn(bin, ['--project-path', root], { cwd: root, env: graphEnv(env), stdio: ['pipe', 'pipe', 'pipe'] });
+        this.child.stdout.setEncoding('utf8');
+        this.child.stderr.setEncoding('utf8');
+        this.child.stdout.on('data', (chunk) => this.feed(chunk));
+        this.child.stderr.on('data', (chunk) => {
+            this.stderr = (this.stderr + chunk).slice(-8192);
+        });
+        const fail = (e) => {
+            this.closed = e;
+            for (const p of this.pending.values())
+                p.reject(e);
+            this.pending.clear();
+        };
+        this.child.on('error', (e) => fail(new GraphUnavailable(`codegraph-mcp could not start (${bin}): ${e.message}`)));
+        this.child.on('exit', (code) => fail(new GraphUnavailable(`codegraph-mcp exited (${code ?? 'signal'})${this.stderr.trim() ? `: ${this.stderr.trim().split('\n').pop()}` : ''}`)));
+    }
+    feed(chunk) {
+        this.buf += chunk;
+        let nl;
+        while ((nl = this.buf.indexOf('\n')) >= 0) {
+            const line = this.buf.slice(0, nl).trim();
+            this.buf = this.buf.slice(nl + 1);
+            if (!line.startsWith('{'))
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (typeof msg.id !== 'number')
+                continue;
+            const p = this.pending.get(msg.id);
+            if (!p)
+                continue;
+            this.pending.delete(msg.id);
+            if (msg.error)
+                p.reject(new BravosError(msg.error.message ?? 'the graph answered an error'));
+            else
+                p.resolve(msg.result);
+        }
+    }
+    request(method, params, timeoutMs) {
+        if (this.closed)
+            return Promise.reject(this.closed);
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const t = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new GraphUnavailable(`codegraph-mcp did not answer ${method} within ${Math.round(timeoutMs / 1000)}s`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (v) => {
+                    clearTimeout(t);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    clearTimeout(t);
+                    reject(e);
+                },
+            });
+            this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+        });
+    }
+    notify(method, params) {
+        if (!this.closed)
+            this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n');
+    }
+    async initialize(timeoutMs) {
+        await this.request('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'bravos', version: '1' } }, timeoutMs);
+        this.notify('notifications/initialized', {});
+    }
+    async tools(timeoutMs) {
+        const r = (await this.request('tools/list', {}, timeoutMs));
+        return Array.isArray(r?.tools) ? r.tools : [];
+    }
+    async call(name, args, timeoutMs) {
+        const r = (await this.request('tools/call', { name, arguments: args }, timeoutMs));
+        if (r?.structuredContent !== undefined)
+            return r.structuredContent;
+        const text = (r?.content ?? []).filter((c) => c.type === 'text' && typeof c.text === 'string').map((c) => c.text).join('\n');
+        if (r?.isError)
+            throw new BravosError(text || `the graph refused ${name}`);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return { text };
+        }
+    }
+    close() {
+        try {
+            this.child.stdin.end();
+            this.child.kill();
+        }
+        catch {
+            /* gone */
+        }
+    }
+}
+/** Opens a session for one repository; the caller closes it. */
+export function open(root, env) {
+    const bin = graphBin('codegraph-mcp', env);
+    if (!bin)
+        throw new GraphUnavailable('codegraph-mcp is not installed: bravos setup --codegraph fetches it (on the Team plan)');
+    return new GraphSession(bin, root, env);
+}
+// @comment -- "One question, in and out: `bravos graph attack-surface --json` becomes tools/call codegraph_attack_surface. Positional words fill the tool's first required string argument (symbol, query); --name value pairs fill the rest, parsed as JSON when they look like it. The tool list comes from the binary on this machine, never from a stored copy."
+export async function ask(root, env, question, argv, timeoutMs = 60000) {
+    const s = open(root, env);
+    try {
+        await s.initialize(Math.min(timeoutMs, 30000));
+        const tools = await s.tools(Math.min(timeoutMs, 30000));
+        const name = question.startsWith('codegraph_') ? question : `codegraph_${question.replace(/-/g, '_')}`;
+        const tool = tools.find((t) => t.name === name);
+        if (!tool)
+            throw new BravosError(`the graph has no question ${JSON.stringify(question)}; it answers: ${tools.map((t) => t.name.replace(/^codegraph_/, '').replace(/_/g, '-')).join(', ')}`);
+        return await s.call(name, bindArguments(tool, argv), timeoutMs);
+    }
+    finally {
+        s.close();
+    }
+}
+export async function listTools(root, env, timeoutMs = 30000) {
+    const s = open(root, env);
+    try {
+        await s.initialize(timeoutMs);
+        return await s.tools(timeoutMs);
+    }
+    finally {
+        s.close();
+    }
+}
+export function bindArguments(tool, argv) {
+    const props = tool.inputSchema?.properties ?? {};
+    const required = tool.inputSchema?.required ?? [];
+    const lead = required.find((n) => props[n]?.type === 'string') ?? '';
+    const out = {};
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            const key = (eq > 0 ? a.slice(2, eq) : a.slice(2)).replace(/-/g, '_');
+            const raw = eq > 0 ? a.slice(eq + 1) : i + 1 < argv.length && !argv[i + 1].startsWith('--') ? argv[++i] : 'true';
+            const type = props[key]?.type;
+            out[key] = type === 'string' ? raw : coerce(raw);
+        }
+        else
+            positional.push(a);
+    }
+    if (positional.length) {
+        if (!lead)
+            throw new BravosError(`${tool.name.replace(/^codegraph_/, '').replace(/_/g, '-')} takes no positional argument; its arguments are ${Object.keys(props).map((k) => `--${k.replace(/_/g, '-')}`).join(', ') || 'none'}`);
+        if (lead in out)
+            throw new BravosError(`${lead} was given twice — positionally and as --${lead.replace(/_/g, '-')}`);
+        out[lead] = positional.join(' ');
+    }
+    const missing = required.filter((n) => !(n in out));
+    if (missing.length)
+        throw new BravosError(`missing required argument${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`);
+    return out;
+}
+const coerce = (raw) => {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(raw))
+        return Number(raw);
+    if (/^[[{]/.test(raw)) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    return raw;
+};
+/** Whether this repository has a graph the server can load: a cheap probe through one call. */
+export async function probe(root, env, timeoutMs = 3000) {
+    if (!graphBin('codegraph-mcp', env))
+        return 'unavailable';
+    if (!existsSync(root))
+        return 'unavailable';
+    try {
+        await ask(root, env, 'acceptance-register', [], timeoutMs);
+        return 'current';
+    }
+    catch (e) {
+        const m = e.message ?? '';
+        if (/no graph|codegraph_unavailable|not built|no CodeGraph|nothing is there/i.test(m))
+            return 'not-built';
+        if (e instanceof GraphUnavailable && /within \d+s/.test(m))
+            return 'cli';
+        return 'cli';
+    }
+}

package/dist/cursor.js

@@ -0,0 +1,70 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { readLock, sha256, writeLock } from './lock.js';
+import { MARKER, skillsRoot } from './skills.js';
+// @comment -- "Where bravos's Cursor rule lives; Cursor reads project rules from .cursor/rules/*.mdc."
+export const CURSOR_RULE_PATH = '.cursor/rules/bravos.mdc';
+// @comment -- "The rule body for one skills root: a pointer to the bravos skills there plus the two rules that hold everywhere; no method is copied here, so it cannot drift from the skills."
+export const cursorRule = (root) => `---
+description: bravos security workflow skills for this repo (guardlink, cxg, code graph)
+globs:
+alwaysApply: true
+---
+${MARKER}
+# bravos
+
+This repo uses bravos's skills for security work. They live in \`${root}/bravos*/SKILL.md\`.
+Read \`${root}/bravos/SKILL.md\` first whenever a task touches security-relevant code
+(endpoints, authentication and authorization, validation, queries, file I/O, external calls,
+crypto, process spawning, configuration parsing) or before opening a pull request, and follow the
+skill it routes you to.
+
+Two rules hold everywhere:
+
+- Never run \`guardlink annotate\` or \`guardlink translate\` with an agent flag. You are the agent:
+  follow the method in this session.
+- Never write \`@accepts\`, \`@entitles\` or \`@confirmed\`. Acceptance and entitlement are a human's
+  decision, and only a reproduced run confirms an exposure.
+`;
+// @comment -- "The skills root the pointer names: .claude/skills when Claude Code's root was installed, else .agents/skills, else none."
+export function cursorSkillsRoot(harnesses) {
+    if (harnesses.includes('claude'))
+        return skillsRoot('claude');
+    if (harnesses.includes('agents'))
+        return skillsRoot('agents');
+    return null;
+}
+// @comment -- "Writes the Cursor pointer only when the repo already has a .cursor/ folder and a skills root was installed, naming that root's path; an existing file is replaced only if bravos wrote it (lock hash or marker) unless --force, and the lock records what was written."
+export function writeCursorPointer(root, harnesses, opts = {}) {
+    if (!existsSync(join(root, '.cursor')))
+        return { status: 'absent' };
+    const path = CURSOR_RULE_PATH;
+    const skills = cursorSkillsRoot(harnesses);
+    if (!skills)
+        return { status: 'no-skills', path };
+    const abs = join(root, path);
+    const content = Buffer.from(cursorRule(skills));
+    const hash = sha256(content);
+    const lock = readLock(root);
+    let status = 'written';
+    if (existsSync(abs)) {
+        const disk = readFileSync(abs);
+        const diskHash = sha256(disk);
+        if (diskHash === hash)
+            return { status: 'unchanged', path };
+        const locked = lock.files[path];
+        if (locked !== undefined && diskHash !== locked && !opts.force) {
+            return { status: 'skipped', path, reason: 'edited since last install (use --force to overwrite)' };
+        }
+        if (locked === undefined && !disk.toString('utf8').includes(MARKER) && !opts.force) {
+            return { status: 'skipped', path, reason: 'authored file, not managed by bravos (use --force to overwrite)' };
+        }
+        status = 'updated';
+    }
+    if (!opts.dryRun) {
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, content);
+        writeLock(root, { ...lock, files: { ...lock.files, [path]: hash } });
+    }
+    return { status, path };
+}

package/dist/detect.js

@@ -0,0 +1,26 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const CLAUDE_EVIDENCE = ['CLAUDE.md', '.claude/'];
+// .cursor/ counts as evidence for the shared root, so a Cursor-only repo gets .agents/skills for the Cursor rule to point at (it names .claude/skills instead when that root is installed).
+const AGENTS_EVIDENCE = ['AGENTS.md', 'GEMINI.md', '.agents/', '.codex/', '.cursor/'];
+const present = (root, rel) => existsSync(join(root, rel));
+/** Decides which skill locations to write for, from agent files already in the repo. */
+// @comment -- "Picks the skill roots to write (claude, agents or both) from agent files already in the repo; with no evidence it defaults to both and says so."
+export function detectHarnesses(root) {
+    const claude = CLAUDE_EVIDENCE.filter((p) => present(root, p));
+    const agents = AGENTS_EVIDENCE.filter((p) => present(root, p));
+    const evidence = [...claude, ...agents];
+    if (evidence.length === 0) {
+        return {
+            harnesses: ['claude', 'agents'],
+            evidence: ['(no agent files found — defaulting to both)'],
+            defaulted: true,
+        };
+    }
+    const harnesses = [];
+    if (claude.length)
+        harnesses.push('claude');
+    if (agents.length)
+        harnesses.push('agents');
+    return { harnesses, evidence, defaulted: false };
+}

package/dist/doctor.js

@@ -0,0 +1,99 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { installedGuardlinkSkills, whichBin } from './guardlink.js';
+import { graphBin } from './codegraph.js';
+import { findAnalyzer, findLicence } from './graphbin.js';
+import { AUTOPILOT_COMMAND, HOOK_COMMANDS, LEGACY_HOOK_COMMAND, PRE_PR_COMMAND } from './hooks.js';
+import { skillsRoot } from './skills.js';
+const TOOLS = [
+    { name: 'guardlink', hint: 'npm install -g guardlink' },
+    { name: 'cxg', hint: 'cargo install cert-x-gen  (or: brew tap bugb-technologies/cxg && brew install cxg)' },
+    { name: 'codegraph-mcp', hint: 'bravos setup --codegraph fetches codegraph-build and codegraph-mcp (Team plan); then bravos graph build .' },
+    { name: 'bravos-cli', hint: 'the SAST analyzer: bravos setup --analyzer fetches it (Team plan; bravos account activate starts a trial)' },
+];
+// @comment -- "Lists installed bravos* skill folders holding a SKILL.md; an unreadable skills root (absent, a file, no permission) yields [] so doctor never throws."
+function bravosSkills(root, harness) {
+    const dir = join(root, skillsRoot(harness));
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((n) => n.startsWith('bravos') && existsSync(join(dir, n, 'SKILL.md')))
+        .sort();
+}
+// @comment -- "guardlink's playbook skills (guardlink-annotate-*, guardlink-report-*) installed under a harness root; an unreadable root yields [] so doctor never throws."
+function guardlinkSkills(root, harness) {
+    try {
+        return installedGuardlinkSkills(root, skillsRoot(harness));
+    }
+    catch {
+        return [];
+    }
+}
+// @comment -- "True when a harness settings file registers one of bravos's commands under the given hook event (the per-harness SessionStart command or its pre-0.5.0 form); unreadable or malformed files read as not registered."
+function hookRegistered(file, event, commands) {
+    try {
+        const json = JSON.parse(readFileSync(file, 'utf8'));
+        const groups = json?.hooks?.[event];
+        if (!Array.isArray(groups))
+            return false;
+        return groups.some((g) => Array.isArray(g?.hooks) && g.hooks.some((h) => typeof h?.command === 'string' && commands.includes(h.command)));
+    }
+    catch {
+        return false;
+    }
+}
+/** Read-only environment check: PATH lookups and file reads only. */
+// @comment -- "Read-only environment check: looks up guardlink, cxg, codegraph-mcp and bravos-cli on PATH, the optional licence, guardlink initialisation, installed bravos and guardlink playbook skills per root, and hook registration; runs nothing."
+export function runDoctor(root, env = process.env) {
+    const tools = TOOLS.map(({ name, hint }) => {
+        // codegraph-mcp and bravos-cli also count when they sit inside the bravos install (bravos uses them from there).
+        const path = name === 'codegraph-mcp' ? graphBin('codegraph-mcp', env) : name === 'bravos-cli' ? findAnalyzer(env) : whichBin(name, env);
+        return path ? { name, found: true, path, hint } : { name, found: false, hint };
+    });
+    const found = findLicence({ ...env, HOME: env.HOME ?? homedir() });
+    const licence = found ? { present: true, source: found } : { present: false };
+    return {
+        tools,
+        licence,
+        guardlink_initialised: existsSync(join(root, '.guardlink')),
+        skills: { claude: bravosSkills(root, 'claude'), agents: bravosSkills(root, 'agents') },
+        guardlink_skills: { claude: guardlinkSkills(root, 'claude'), agents: guardlinkSkills(root, 'agents') },
+        hooks: {
+            claude: hookRegistered(join(root, '.claude', 'settings.json'), 'SessionStart', [HOOK_COMMANDS.claude, LEGACY_HOOK_COMMAND]),
+            codex: hookRegistered(join(root, '.codex', 'hooks.json'), 'SessionStart', [HOOK_COMMANDS.agents, LEGACY_HOOK_COMMAND]),
+        },
+        autopilot: {
+            claude: hookRegistered(join(root, '.claude', 'settings.json'), 'Stop', [AUTOPILOT_COMMAND]),
+            codex: hookRegistered(join(root, '.codex', 'hooks.json'), 'Stop', [AUTOPILOT_COMMAND]),
+        },
+        pre_pr: {
+            claude: hookRegistered(join(root, '.claude', 'settings.json'), 'PreToolUse', [PRE_PR_COMMAND]),
+            codex: hookRegistered(join(root, '.codex', 'hooks.json'), 'PreToolUse', [PRE_PR_COMMAND]),
+        },
+    };
+}
+// @comment -- "Renders a DoctorReport as one line per check, with an install hint for each missing tool and guardlink's playbook skills named per root."
+// @comment -- "Adds the verified licence status (plan line, licensed) to a report built synchronously; the verifier lives in the hook library, which the CLI loads asynchronously."
+export function withLicence(r, plan, licensed) {
+    return { ...r, licence: { ...r.licence, plan, licensed } };
+}
+export function formatDoctor(r) {
+    const yn = (b) => (b ? 'yes' : 'no');
+    const names = (l) => (l.length ? l.join(', ') : 'none');
+    return [
+        ...r.tools.map((t) => (t.found ? `✔ ${t.name}  ${t.path}` : `✘ ${t.name}  ${t.hint}`)),
+        r.licence.plan ? `${r.licence.licensed ? '✔' : '✘'} licence  ${r.licence.plan}` : r.licence.present ? `✔ licence  ${r.licence.source}` : '✘ licence  not found — Free (researcher) plan; bravos account activate starts a 30-day Team trial',
+        r.guardlink_initialised ? '✔ guardlink initialised (.guardlink/)' : '✘ guardlink not initialised — run bravos init',
+        `skills  claude: ${r.skills.claude.length}  agents: ${r.skills.agents.length}`,
+        `guardlink skills  claude: ${names(r.guardlink_skills.claude)}  agents: ${names(r.guardlink_skills.agents)}`,
+        `hooks   claude: ${yn(r.hooks.claude)}  codex: ${yn(r.hooks.codex)}`,
+        `pre-pr  claude: ${yn(r.pre_pr.claude)}  codex: ${yn(r.pre_pr.codex)}${r.pre_pr.claude || r.pre_pr.codex ? '' : '  (opt-in: bravos init --pre-pr-hook)'}`,
+        `autopilot  claude: ${yn(r.autopilot.claude)}  codex: ${yn(r.autopilot.codex)}${r.autopilot.claude || r.autopilot.codex ? '' : '  (opt-in: bravos init --autopilot)'}`,
+    ].join('\n');
+}

package/dist/global.js

@@ -0,0 +1,95 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { migrateFromOldName, reportMigration } from './migrate.js';
+import { dirname, join } from 'node:path';
+import { installHook } from './hooks.js';
+import { installSkills } from './install.js';
+import { readLock, sha256, writeLock } from './lock.js';
+import { mergeCodexConfig, selectServers } from './mcp.js';
+import { listBundledSkills, MARKER, renderGlobalSkillFile } from './skills.js';
+import { BravosError } from './types.js';
+// @comment -- "The home folder a user-level install writes into: HOME from the environment, else the OS home."
+export const homeOf = (env) => env.HOME || homedir();
+// @comment -- "Points ~/.agents/skills/<name> at ~/.claude/skills/<name> for one bravos skill, so Codex and other shared-root agents see it without a second copy; a real folder is replaced only when bravos wrote it (its SKILL.md carries the marker), anything else is left alone."
+function linkUserSkill(home, name, dryRun) {
+    const link = join(home, '.agents', 'skills', name);
+    const target = `../../.claude/skills/${name}`;
+    let st = null;
+    try {
+        st = lstatSync(link);
+    }
+    catch {
+        st = null;
+    }
+    if (st?.isSymbolicLink()) {
+        if (readlinkSync(link) === target)
+            return 'unchanged';
+        return 'skipped';
+    }
+    if (st?.isDirectory()) {
+        const md = join(link, 'SKILL.md');
+        if (!existsSync(md) || !readFileSync(md, 'utf8').includes(MARKER))
+            return 'skipped';
+        if (!dryRun)
+            rmSync(link, { recursive: true, force: true });
+    }
+    else if (st)
+        return 'skipped';
+    if (!dryRun) {
+        mkdirSync(dirname(link), { recursive: true });
+        symlinkSync(target, link, 'dir');
+    }
+    return 'linked';
+}
+// @comment -- "User-level install (bravos init --global / sync --global): skills once in ~/.claude/skills with absolute paths, a link per skill from ~/.agents/skills, the hook scripts in ~/.bravos/hooks registered as user SessionStart hooks for Claude Code (~/.claude/settings.json) and Codex (~/.codex/hooks.json) in --global mode, and guardlink in ~/.codex/config.toml. Touches nothing in any repo; the lock is ~/.bravos/skills.lock."
+export function installGlobal(env, lines, opts = {}) {
+    const home = homeOf(env);
+    const dryRun = !!opts.dryRun;
+    // Claude Code's sandbox can hold back writes under ~/.claude while ~/.bravos/skills.lock still lands,
+    // leaving a stale copy marked current; the user-level install runs only outside a Claude Code session.
+    if (env.CLAUDECODE && !dryRun && env.BRAVOS_ALLOW_SESSION_GLOBAL !== '1') {
+        throw new BravosError('the user-level install writes ~/.claude, which a Claude Code session may not reach; run bravos init --global / bravos sync --global in your own terminal (BRAVOS_ALLOW_SESSION_GLOBAL=1 overrides)');
+    }
+    if (dryRun)
+        lines.push('dry-run: nothing written');
+    lines.push(`User-level install into ${home}`);
+    reportMigration(migrateFromOldName(home, { dryRun, ownSkills: listBundledSkills(opts.skillsDir).map((s) => s.name) }), lines);
+    const skills = installSkills(home, ['claude'], { skillsDir: opts.skillsDir, force: opts.force, dryRun, render: renderGlobalSkillFile(home) });
+    lines.push(`Skills (~/.claude/skills): ${skills.written.length} written, ${skills.updated.length} updated, ${skills.unchanged.length} unchanged, ${skills.skipped.length} skipped`);
+    for (const s of skills.skipped)
+        lines.push(`  skipped ${s.path} — ${s.reason}`);
+    // ~/.agents/skills as a whole may hold other skills, so only bravos's entries become links.
+    const agentsRootLinked = (() => {
+        try {
+            return lstatSync(join(home, '.agents', 'skills')).isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    })();
+    if (agentsRootLinked)
+        lines.push('Skills (~/.agents/skills): a link already, nothing to do');
+    else {
+        const counts = { linked: [], unchanged: [], skipped: [] };
+        for (const s of listBundledSkills(opts.skillsDir))
+            counts[linkUserSkill(home, s.name, dryRun)].push(s.name);
+        lines.push(`Skills (~/.agents/skills): ${counts.linked.length} linked, ${counts.unchanged.length} unchanged, ${counts.skipped.length} skipped (links to ~/.claude/skills, one copy each)`);
+        for (const n of counts.skipped)
+            lines.push(`  skipped ~/.agents/skills/${n} — not a bravos copy; left as it is`);
+    }
+    const hook = installHook(home, ['claude', 'agents'], { hooksDir: opts.hooksDir, dryRun, globalHome: home });
+    if (!dryRun) {
+        const lock = readLock(home);
+        for (const rel of hook.copied)
+            lock.files[rel] = sha256(readFileSync(join(home, rel)));
+        writeLock(home, lock);
+    }
+    for (const r of hook.registered)
+        lines.push(`Hooks: ~/${r.file} ${r.changed ? 'registered' : 'already registered'} (user level, quiet where a repo has its own bravos hook or no threat model)`);
+    const { selected } = selectServers(env);
+    const m = mergeCodexConfig(home, selected, { dryRun });
+    lines.push(`MCP: ~/${m.path} added ${m.added.length ? m.added.join(', ') : 'none'}`);
+    lines.push(`MCP for Claude Code at user level: claude mcp add --scope user guardlink -- guardlink mcp`);
+    lines.push('In Codex run /hooks once to trust ~/.codex/hooks.json');
+    lines.push('Repos with bravos init keep their own skills and hooks; bravos init there is still how a team shares bravos through git.');
+}