@bugb-technologies/bravos 1.0.1 → 1.0.3

package/dist/cli.js

@@ -11,7 +11,7 @@ import { writeOmpExtension } from './omp.js';
 import { homeOf, installGlobal } from './global.js';
 import { uninstall } from './uninstall.js';
 import { checkKind, newToken, readAllAnswers, readDraft, renderReview, summarize, writePage } from './review.js';
-import { spawn as spawnChild } from 'node:child_process';
+import { spawn as spawnChild, spawnSync } from 'node:child_process';
 import { createServer as netServer } from 'node:net';
 import { dirname as pathDirname, join as pathJoin } from 'node:path';
 import { OPENCODE_CONFIG, writeOpencode } from './opencode.js';
@@ -485,6 +485,23 @@ export function buildProgram(io, result) {
         }
         lines.push(JSON.stringify(opts.json ? a : a.result, null, 2));
     }));
+    // @comment -- "bravos hook <name> runs one of the hook scripts this install ships (session-start, pre-pr, autopilot) with the given arguments, stdin passed through: what a plugin's skills call where the repository has no .bravos/hooks/ copy. Only those three names run; the script's own exit code is returned."
+    program
+        .command('hook <name> [args...]')
+        .description('Run one of bravos\'s hook scripts from this install (session-start, pre-pr, autopilot), e.g. `bravos hook session-start --briefing` or `bravos hook pre-pr --check`: what plugin installs use where the repository has no .bravos/hooks/.')
+        .allowUnknownOption()
+        .helpOption(false)
+        .action((name, args) => guarded((lines) => {
+        const known = ['session-start', 'pre-pr', 'autopilot'];
+        if (!known.includes(name))
+            throw new BravosError(`unknown hook '${name}'; use ${known.join(', ')}`);
+        const r = spawnSync(process.execPath, [pathJoin(hooksDir(), `${name}.mjs`), ...args], { env: io.env, encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'], maxBuffer: 16 * 1024 * 1024 });
+        if (r.stdout)
+            lines.push(r.stdout.replace(/\n$/, ''));
+        if (r.stderr)
+            io.stderr(r.stderr.replace(/\n$/, ''));
+        result.code = r.status ?? 1;
+    }));
     program
         .command('doctor [dir]')
         .description('Read-only check of the tools, licence, skills and hooks bravos relies on.')
@@ -859,9 +876,9 @@ export function buildProgram(io, result) {
         }
         const row = (f) => `  ${(f.severity ?? '').toLowerCase().padEnd(8)} ${f.rule ?? '?'}  ${f.file ?? '?'}:${f.line ?? '?'}${f.route ? `  ${f.route}` : f.entryPoint ? `  via ${f.entryPoint}` : ''}`;
         lines.push(`SAST run ${c.run}${c.sha ? ` at ${String(c.sha).slice(0, 9)}` : ''}${opts.all ? '' : ' (reachable only; --all for the rest)'}`);
-        lines.push('', `Joined to a claim (${c.joined.length}) — taint evidence for bravos-templatize and bravos-prove:`, ...c.joined.map((f) => `${row(f)}  [${f.claimState}]`));
+        lines.push('', `Joined to a claim (${c.joined.length}) — taint evidence for bravos-templatize and bravos-prove:`, ...c.joined.map((f) => `${row(f)}  [${lib.claimLabel(f.claimState)}]`));
         lines.push('', `Not in the threat model yet (${c.unjoined.length}) — leads for bravos-annotate:`, ...c.unjoined.map(row));
-        lines.push('', `Dependencies (${c.dependencies.length}):`, ...c.dependencies.map((f) => `${row(f)}  vulnerable function reached: ${String(f.vulnerableFunctionReached ?? 'unknown')}`));
+        lines.push('', `Dependencies (${c.dependencies.length}):`, ...c.dependencies.map((f) => `${row(f)}  vulnerable function reached: ${lib.reachLabel(f.vulnerableFunctionReached)}`));
         lines.push('', `Secrets (${c.secrets.length}) — rotate; never pentest candidates:`, ...c.secrets.map((f) => `  ${f.rule ?? '?'}  ${f.file ?? '?'}:${f.line ?? '?'}${f.inHistory ? '  (in git history)' : ''}`));
     }));
     program

package/dist/guide.js

@@ -120,7 +120,7 @@ export const GUIDE_TOPICS = [
             { name: 'Is this exposure real?', skills: ['bravos-templatize', 'bravos-env', 'bravos-prove'], body: ['Template → authorized target → run. Only a reproduced run confirms; reading code never does.'] },
             { name: 'I fixed a finding', skills: ['bravos-recheck'], body: ['Re-verifies stale claims, replays the retest kit, and checks the fix added no new exposure.'] },
             { name: 'I am about to open a PR', skills: ['bravos-ship'], body: ['The no-mistakes gate: validate, lint since the merge base, disclose new exposure, block confirmed exploits on changed paths.'] },
-            { name: 'Find the routes, callers or blast radius', skills: ['bravos-codegraph'], body: ['One bounded question to the code graph instead of grepping. Needs codegraph-mcp (pip install bravos; licence-free). With it, other skills get sharper on their own: bravos-templatize targets the route and auth that actually reach each sink, bravos-recheck follows a fix\'s callers and blast radius into other files, bravos-context drafts the real public surface, and bravos-prove tests the most reachable exposures first. Without it they read the code and say so.'] },
+            { name: 'Find the routes, callers or blast radius', skills: ['bravos-codegraph'], body: ['One bounded question to the code graph instead of grepping. Team plan: bravos setup --codegraph stages codegraph-mcp, then bravos graph build . indexes the repository. With it, other skills get sharper on their own: bravos-templatize targets the route and auth that actually reach each sink, bravos-recheck follows a fix\'s callers and blast radius into other files, bravos-context drafts the real public surface, and bravos-prove tests the most reachable exposures first. Without it they read the code and say so.'] },
             { name: 'Scan for dependency CVEs, secrets, IaC', skills: ['bravos-sast'], body: ['Licensed bravos-cli: Semgrep rules, request-to-sink taint over the code graph, dependency CVEs with whether the vulnerable function is reached, secrets (git history too) and IaC. It reads the GuardLink threat model as input, so annotate first. Says plainly when it is unavailable.'] },
             { name: 'What did SAST find, and what happens to it', skills: ['bravos-sast', 'bravos-annotate', 'bravos-templatize', 'bravos-prove', 'bravos-recheck'], body: ['bravos sast candidates (free, no model) reads the newest run in .bravos/sast/: reachable findings joined to a claim feed bravos-templatize and bravos-prove (the route and taint path to target, tested first); reachable findings not in the threat model are leads for bravos-annotate; bravos-recheck rescans the changed files after a fix. A static finding is a lead, never a confirmation; only a run confirms. The briefing\'s SAST line shows the latest run, or that SAST is unavailable.'] },
             { name: 'Keep it fresh while I work, or nightly', skills: ['bravos-schedule'], body: ['An in-session /loop from .claude/loop.md, the nightly workflow, or a cloud task you create. Loops never send test traffic.'] },

package/dist/plugin-release.js

@@ -0,0 +1,212 @@
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { SERVERS } from './mcp.js';
+import { hooksDir, packageRoot, version } from './paths.js';
+import { listBundledSkills, renderPluginSkillFile, renderPortableSkillFile, viaCliHooks } from './skills.js';
+// @comment -- "The public plugin repository (Bugb-Technologies/bravos-plugins): one generated tree that every harness installs from. The repository root is the Gemini CLI extension and the Antigravity plugin; claude/, codex/, copilot/ and cursor/ are the other harnesses' plugins, each listed by that harness's own marketplace file at the root. It carries the skills, the session hook scripts and the guardlink MCP entry, never the CLI's source, the analyzer or the code graph, and the Bravos licence."
+export const RELEASE_REPO = 'Bugb-Technologies/bravos-plugins';
+const NAME = 'bravos';
+const DESCRIPTION = 'Bravos makes your coding agent work the threat model (guardlink), authorized pentests (cxg), the code graph and SAST, with the evidence kept in your repository. Needs the bravos CLI: npm install -g @bugb-technologies/bravos.';
+const SHORT = 'Threat model, pentests, code graph and SAST for your coding agent.';
+const AUTHOR = { name: 'BugB Technologies', url: 'https://www.bugb.io' };
+const HOMEPAGE = 'https://docs.bugb.io/bravos/';
+const REPOSITORY = `https://github.com/${RELEASE_REPO}`;
+const LICENSE_ID = 'LicenseRef-Bravos-Software-Licence';
+const KEYWORDS = ['security', 'threat-modeling', 'guardlink', 'pentest', 'cxg', 'sast', 'code-graph', 'skills'];
+const SESSION_MATCHER = 'startup|resume|clear|compact';
+const json = (v) => Buffer.from(JSON.stringify(v, null, 2) + '\n');
+const text = (s) => Buffer.from(s.endsWith('\n') ? s : s + '\n');
+function walk(dir) {
+    const out = [];
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+        const abs = join(dir, e.name);
+        if (e.isDirectory())
+            out.push(...walk(abs));
+        else if (e.isFile())
+            out.push(abs);
+    }
+    return out;
+}
+const guardlinkServer = () => ({ type: 'stdio', command: SERVERS.guardlink.command, args: [...SERVERS.guardlink.args] });
+// @comment -- "Every file of the public plugin repository, computed and not written. Skills: Claude Code's copy uses ${CLAUDE_SKILL_DIR} and ${CLAUDE_PLUGIN_ROOT}, which it substitutes; every other copy uses the portable SKILL_DIR wording. In every copy a skill's `node .bravos/hooks/<hook>.mjs` is `bravos hook <hook>`, because a plugin install has no .bravos/hooks/. Session hooks are registered where the harness's plugin format and SessionStart output are known: Claude Code, Codex, Gemini CLI and Antigravity. Copilot, VS Code and Cursor get the skills and MCP, and the bravos skill loads the briefing itself."
+export function releaseFiles(opts = {}) {
+    const v = version();
+    const files = [];
+    const add = (path, content) => files.push({ path, content });
+    const skills = listBundledSkills(opts.skillsDir);
+    const hooks = opts.hooksDir ?? hooksDir();
+    const hookFiles = walk(hooks).sort();
+    const licence = opts.licence ?? readFileSync(join(packageRoot(), 'LICENSE'));
+    const addSkills = (prefix, render) => {
+        for (const skill of skills) {
+            for (const f of skill.files) {
+                const md = f.rel.endsWith('.md');
+                add(`${prefix}skills/${skill.name}/${f.rel}`, md ? Buffer.from(render(f.content.toString('utf8'), f.rel)) : f.content);
+            }
+        }
+    };
+    const addHookScripts = (prefix) => {
+        for (const abs of hookFiles)
+            add(`${prefix}hooks/${relative(hooks, abs).split('\\').join('/')}`, readFileSync(abs));
+    };
+    const sessionGroup = (command) => ({ matcher: SESSION_MATCHER, hooks: [{ type: 'command', command, timeout: 30 }] });
+    const base = { name: NAME, version: v, description: DESCRIPTION, author: AUTHOR, homepage: HOMEPAGE, repository: REPOSITORY, license: LICENSE_ID, keywords: KEYWORDS };
+    // Claude Code: claude/, listed by .claude-plugin/marketplace.json.
+    addSkills('claude/', (c, rel) => viaCliHooks(renderPluginSkillFile(c, rel)));
+    addHookScripts('claude/');
+    add('claude/hooks/hooks.json', json({ hooks: { SessionStart: [sessionGroup('node "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs" --harness claude')] } }));
+    add('claude/.mcp.json', json({ mcpServers: { guardlink: SERVERS.guardlink } }));
+    add('claude/.claude-plugin/plugin.json', json(base));
+    add('claude/LICENSE', licence);
+    add('.claude-plugin/marketplace.json', json({
+        name: NAME,
+        owner: AUTHOR,
+        description: SHORT,
+        plugins: [{ name: NAME, source: './claude', description: DESCRIPTION, version: v, category: 'security', homepage: HOMEPAGE }],
+    }));
+    // Codex: codex/, listed by .agents/plugins/marketplace.json. Hooks at the plugin root, as Codex's own plugins keep them.
+    addSkills('codex/', renderPortableSkillFile);
+    addHookScripts('codex/');
+    add('codex/hooks.json', json({ hooks: { SessionStart: [sessionGroup('node "${PLUGIN_ROOT}/hooks/session-start.mjs" --harness codex')] } }));
+    add('codex/.mcp.json', json({ mcpServers: { guardlink: guardlinkServer() } }));
+    add('codex/.codex-plugin/plugin.json', json({
+        ...base,
+        skills: './skills/',
+        mcpServers: './.mcp.json',
+        interface: {
+            displayName: 'Bravos',
+            shortDescription: SHORT,
+            longDescription: DESCRIPTION,
+            developerName: AUTHOR.name,
+            category: 'Security',
+            capabilities: ['Read', 'Write'],
+            websiteURL: HOMEPAGE,
+            defaultPrompt: ['Where do I start on security here?', 'Threat-model this repository', 'Is this PR safe to open?'],
+        },
+    }));
+    add('codex/LICENSE', licence);
+    add('.agents/plugins/marketplace.json', json({
+        name: NAME,
+        interface: { displayName: 'Bravos' },
+        plugins: [{ name: NAME, source: { source: 'local', path: './codex' }, policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' }, category: 'Security' }],
+    }));
+    // GitHub Copilot CLI and VS Code: copilot/, an Agent Plugins 1.0 plugin, listed by .github/plugin/marketplace.json.
+    addSkills('copilot/', renderPortableSkillFile);
+    add('copilot/mcp.json', json({ mcpServers: { guardlink: guardlinkServer() } }));
+    add('copilot/plugin.json', json({ $schema: 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json', ...base }));
+    add('copilot/LICENSE', licence);
+    add('.github/plugin/marketplace.json', json({
+        name: NAME,
+        owner: AUTHOR,
+        description: SHORT,
+        plugins: [{ name: NAME, source: './copilot', description: DESCRIPTION, version: v }],
+    }));
+    // Cursor (team marketplaces): cursor/, listed by .cursor-plugin/marketplace.json.
+    addSkills('cursor/', renderPortableSkillFile);
+    add('cursor/mcp.json', json({ mcpServers: { guardlink: guardlinkServer() } }));
+    add('cursor/.cursor-plugin/plugin.json', json(base));
+    add('cursor/LICENSE', licence);
+    add('.cursor-plugin/marketplace.json', json({
+        name: NAME,
+        owner: AUTHOR,
+        description: SHORT,
+        plugins: [{ name: NAME, source: './cursor', description: DESCRIPTION, version: v }],
+    }));
+    // The repository root: the Gemini CLI extension and the Antigravity plugin share skills/ and hooks/.
+    addSkills('', renderPortableSkillFile);
+    addHookScripts('');
+    add('gemini-extension.json', json({
+        name: NAME,
+        version: v,
+        description: DESCRIPTION,
+        contextFileName: 'GEMINI.md',
+        mcpServers: { guardlink: { command: SERVERS.guardlink.command, args: [...SERVERS.guardlink.args] } },
+    }));
+    add('GEMINI.md', text(GEMINI_CONTEXT));
+    add('hooks/hooks.json', json({ hooks: { SessionStart: [sessionGroup('node "${extensionPath}${/}hooks${/}session-start.mjs" --harness gemini')] } }));
+    // Antigravity runs a plugin's hooks with the plugin root as the working directory; SessionStart takes a flat list.
+    add('.antigravity-plugin/plugin.json', json({
+        ...base,
+        displayName: 'Bravos',
+        suggestedPrompts: ['Where do I start on security here?', 'Threat-model this repository', 'Is this PR safe to open?'],
+    }));
+    add('hooks.json', json({ bravos: { SessionStart: [{ type: 'command', command: 'node hooks/session-start.mjs --harness agy', timeout: 30 }] } }));
+    // Antigravity loads a plugin's context only from rules/; GEMINI.md is Gemini CLI's.
+    add('rules/bravos.md', text(GEMINI_CONTEXT));
+    add('mcp_config.json', json({ mcpServers: { guardlink: { command: SERVERS.guardlink.command, args: [...SERVERS.guardlink.args] } } }));
+    add('LICENSE', licence);
+    add('README.md', text(readme(v)));
+    return files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+const GEMINI_CONTEXT = `# Bravos
+
+This extension adds the Bravos skills: the threat model as guardlink annotations,
+authorized pentests with cxg, the code graph and SAST. Start with the \`bravos\`
+skill. If no briefing is in context, run \`bravos hook session-start --briefing\`
+once to print the repository's security picture.
+
+The skills drive the \`bravos\` CLI (\`npm install -g @bugb-technologies/bravos\`),
+\`guardlink\` and \`cxg\`. Never send a request to a host other than loopback
+without a committed, reviewed \`.guardlink/scope.yaml\` and the user's own typed
+authorization naming the target.`;
+function readme(v) {
+    return `# Bravos plugins
+
+Bravos ${v} for the coding agent you already use. Each plugin carries the same 14
+skills and the guardlink MCP server; the session-start briefing loads by itself
+where the agent supports it.
+
+**First, install the CLI** (Node 20 or newer). The skills drive it:
+
+\`\`\`bash
+npm install -g @bugb-technologies/bravos
+\`\`\`
+
+Then install the plugin for your agent:
+
+| Agent | Install |
+| --- | --- |
+| Claude Code | \`claude plugin marketplace add ${RELEASE_REPO}\` then \`claude plugin install bravos@bravos\` |
+| Codex | \`codex plugin marketplace add ${RELEASE_REPO}\` then \`/plugins\` in Codex and install Bravos |
+| GitHub Copilot CLI | \`copilot plugin marketplace add ${RELEASE_REPO}\` then \`copilot plugin install bravos@bravos\` |
+| VS Code (agent plugins) | add \`${RELEASE_REPO}\` to \`chat.plugins.marketplaces\`, then install Bravos from the Agent Customizations view |
+| Gemini CLI | \`gemini extensions install ${REPOSITORY}\` |
+| Antigravity | \`agy plugin install ${REPOSITORY}\` |
+| Cursor (Teams and Enterprise) | Dashboard → Plugins → Import from Repo → \`${REPOSITORY}\` |
+
+You do not need a plugin: \`bravos init\` in a repository installs the same skills,
+hooks and MCP wiring for every agent it finds, and commits them with the code.
+
+## Plans
+
+The research loop is free for one researcher in one repository. The pre-PR gate
+and autopilot, CI and nightly workflows, scheduled upkeep, workspaces, campaigns,
+SAST and the code graph are on the Team plan: \`bravos account activate\` starts a
+30-day trial with no card. See [how licensing works](https://docs.bugb.io/bravos/concepts/how-licensing-works/).
+
+## Docs
+
+[docs.bugb.io/bravos](${HOMEPAGE})
+
+## Licence
+
+Bravos Software Licence: see [LICENSE](LICENSE). This repository is generated from
+the Bravos release; changes go into Bravos itself, not here.
+`;
+}
+// @comment -- "Writes the public plugin repository's tree into out: removes every tracked path the previous build wrote except .git/, then writes releaseFiles(). Returns the paths written."
+export function writeRelease(out, opts = {}) {
+    const files = releaseFiles(opts);
+    mkdirSync(out, { recursive: true });
+    for (const e of readdirSync(out)) {
+        if (e === '.git')
+            continue;
+        rmSync(join(out, e), { recursive: true, force: true });
+    }
+    for (const f of files) {
+        const abs = join(out, f.path);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, f.content);
+    }
+    return files.map((f) => f.path);
+}

package/dist/report/data.js

@@ -182,7 +182,7 @@ export async function gatherEvidence(root, env, opts) {
                 id: `SAST-${s}`,
                 kind: 'sast',
                 supports: reached ? ['code-review'] : [],
-                summary: `${group}: ${f.rule ?? '?'} ${f.severity ?? ''} ${f.file ?? '?'}:${f.line ?? '?'}${f.route ? ` (${f.route})` : ''}${group === 'dependency' ? ` vulnerable function reached: ${String(f.vulnerableFunctionReached ?? 'unknown')}` : ''}`,
+                summary: `${group}: ${f.rule ?? '?'} ${f.severity ?? ''} ${f.file ?? '?'}:${f.line ?? '?'}${f.route ? ` (${f.route})` : ''}${group === 'dependency' ? ` vulnerable function reached: ${sastLib.reachLabel(f.vulnerableFunctionReached)}` : ''}`,
                 file: f.file,
                 line: num(f.line),
             });

package/dist/setup.js

@@ -74,14 +74,16 @@ export async function runSetup(env, opts, io) {
     }
     return lines;
 }
-// @comment -- "A staged bundle proves it runs: codegraph-build --ladder, bravos-cli --version, each under the bundle's own environment. A bundle that verifies but does not run is reported, not hidden."
+// @comment -- "A staged bundle proves it runs: codegraph-build --version, bravos-cli --version, codegraph-mcp --help (it has no --version and answers with its usage), each under the bundle's own environment. A bundle that verifies but does not run is reported, not hidden."
 export function selfTest(kind, dir, env) {
     const out = [];
-    const bins = kind === 'analyzer' ? [['bravos-cli', ['--version']]] : [['codegraph-build', ['--ladder']], ['codegraph-mcp', ['--help']]];
+    const bins = kind === 'analyzer' ? [['bravos-cli', ['--version']]] : [['codegraph-build', ['--version']], ['codegraph-mcp', ['--help']]];
     for (const [name, args] of bins) {
         const r = spawnSync(join(dir, name), args, { env: bundleEnvironment(dir, env), encoding: 'utf8', timeout: 60000, stdio: ['ignore', 'pipe', 'pipe'] });
-        const ok = r.status === 0 || (name === 'codegraph-mcp' && (r.stdout + r.stderr).includes('usage'));
-        out.push(`  ${ok ? '✔' : '✘'} ${name}${ok ? ` ${(r.stdout || r.stderr).trim().split('\n')[0].slice(0, 80)}` : ` did not run: ${(r.stderr || r.error?.message || '').trim().split('\n')[0]}`}`);
+        const isMcp = name === 'codegraph-mcp';
+        const ok = r.status === 0 || (isMcp && (r.stdout + r.stderr).includes('usage'));
+        const said = isMcp ? 'runs' : (r.stdout || r.stderr).trim().split('\n')[0].slice(0, 80);
+        out.push(`  ${ok ? '✔' : '✘'} ${name}${ok ? ` ${said}` : ` did not run: ${(r.stderr || r.error?.message || '').trim().split('\n')[0]}`}`);
     }
     return out;
 }
@@ -105,8 +107,8 @@ export async function runSast(root, env, opts = {}) {
         const a = ['analyze', root, '--ci', '--fail-on', 'never', '--allow-incomplete-analysis', '--codegraph', graph, '--scip', opts.scip ?? 'off', '-f', 'json,sarif', '-o', join(runDir, 'report')];
         if (opts.scope?.length)
             a.push('--scope', opts.scope.join(','));
-        if (opts.exclude?.length)
-            a.push('--exclude', opts.exclude.join(','));
+        // @comment -- ".bravos/ is always excluded: it holds the hooks bravos init copied into the repository and the SAST runs themselves, which are bravos's code, not the customer's, and would otherwise surface as findings 'not in the threat model'."
+        a.push('--exclude', ['.bravos', ...(opts.exclude ?? []).filter((p) => p !== '.bravos')].join(','));
         if (opts.minSeverity)
             a.push('--min-severity', opts.minSeverity);
         if (opts.timeoutS)

package/dist/skills.js

@@ -68,6 +68,30 @@ export function renderPluginSkillFile(content, rel = 'SKILL.md') {
         .split('{{SKILLS_ROOT}}')
         .join('.claude/skills');
 }
+// @comment -- "A plugin has no .bravos/hooks/ in the repository, so a skill's `node .bravos/hooks/<hook>.mjs` becomes `bravos hook <hook>`, which runs the same script from the installed CLI."
+export function viaCliHooks(content) {
+    return content.replace(/node \.bravos\/hooks\/([\w-]+)\.mjs/g, 'bravos hook $1');
+}
+/** The line a portable SKILL.md carries after its frontmatter, saying what SKILL_DIR means. */
+export const SKILL_DIR_NOTE = '> Paths that start with `SKILL_DIR/` are files in this skill\'s own folder, the folder that holds this SKILL.md.';
+// @comment -- "Portable plugin render, for harnesses that substitute no variable inside SKILL.md (Codex, Copilot, VS Code, Cursor, Gemini, Antigravity): {{SKILL_DIR}} becomes the literal SKILL_DIR with a note saying it is this skill's folder; {{SKILLS_ROOT}}/bravos* becomes SKILL_DIR/../bravos*, a sibling in the same plugin; any other {{SKILLS_ROOT}} (guardlink's generated skills) stays at the repo's .claude/skills; hook scripts run through the CLI."
+export function renderPortableSkillFile(content, rel = 'SKILL.md') {
+    const needsNote = rel === 'SKILL.md' && (content.includes('{{SKILL_DIR}}') || content.includes('{{SKILLS_ROOT}}/bravos'));
+    let out = viaCliHooks(withMarker(content, rel))
+        .split('{{SKILL_DIR}}')
+        .join('SKILL_DIR')
+        .split('{{SKILLS_ROOT}}/bravos')
+        .join('SKILL_DIR/../bravos')
+        .split('{{SKILLS_ROOT}}')
+        .join('.claude/skills');
+    if (needsNote) {
+        const lines = out.split('\n');
+        const at = lines.indexOf(MARKER);
+        lines.splice(at === -1 ? 0 : at + 1, 0, '', SKILL_DIR_NOTE);
+        out = lines.join('\n');
+    }
+    return out;
+}
 // @comment -- "User-level render (bravos init --global): bravos's own paths become absolute under the home folder (skills in ~/.claude/skills, hook scripts in ~/.bravos/hooks), while {{SKILLS_ROOT}} for guardlink's generated skills stays at the repo's .claude/skills."
 export function renderGlobalSkillFile(home) {
     return (content, _harness, name, rel = 'SKILL.md') => withMarker(content, rel)

package/docs/GUIDE.md

@@ -144,7 +144,7 @@ The no-mistakes gate: validate, lint since the merge base, disclose new exposure
 
 Skills: `/bravos-codegraph`
 
-One bounded question to the code graph instead of grepping. Needs codegraph-mcp (pip install bravos; licence-free). With it, other skills get sharper on their own: bravos-templatize targets the route and auth that actually reach each sink, bravos-recheck follows a fix's callers and blast radius into other files, bravos-context drafts the real public surface, and bravos-prove tests the most reachable exposures first. Without it they read the code and say so.
+One bounded question to the code graph instead of grepping. Team plan: bravos setup --codegraph stages codegraph-mcp, then bravos graph build . indexes the repository. With it, other skills get sharper on their own: bravos-templatize targets the route and auth that actually reach each sink, bravos-recheck follows a fix's callers and blast radius into other files, bravos-context drafts the real public surface, and bravos-prove tests the most reachable exposures first. Without it they read the code and say so.
 
 ### Scan for dependency CVEs, secrets, IaC
 

package/hooks/lib/sast.mjs

@@ -111,6 +111,22 @@ export function sastCandidates(root, { all = false } = {}) {
   return out;
 }
 
+// @comment -- "One line for the claim a SAST finding joined: the analyzer's guardlink_join is an object ({asset, threat, declared_at, …}) in current reports and was a plain state string in older ones; both read as text, never as [object Object]."
+export function claimLabel(cs) {
+  if (cs == null) return 'claim';
+  if (typeof cs !== 'object') return String(cs);
+  const what = cs.asset && cs.threat ? `#${cs.asset} → #${cs.threat}` : cs.threat ? `#${cs.threat}` : 'claim';
+  return cs.declared_at ? `${what} at ${cs.declared_at}` : what;
+}
+
+// @comment -- "One phrase for whether a dependency advisory's vulnerable function is reached: the analyzer reports {state, reason, …}; older reports carried a boolean or nothing."
+export function reachLabel(v) {
+  if (v == null) return 'unknown';
+  if (typeof v !== 'object') return String(v);
+  const state = v.state ?? 'unknown';
+  return v.reason ? `${state} (${String(v.reason).replace(/_/g, ' ')})` : state;
+}
+
 // @comment -- "The Python bravos CLI (siete) on PATH, as `bravos` or renamed to `bravos-py`, and never this package's own `bravos` bin: an npm shim is a script that execs node on dist/cli.js, and skipping it keeps the hooks pointed at the Python install's analyzer and graph until phase 3 makes this CLI carry them."
 export function pythonBravos(env = process.env) {
   // Its own name first, then bravos-py: the name it keeps once it is renamed so `bravos` means this CLI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bugb-technologies/bravos",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Skills pack and installer that make Claude Code and Codex power users of guardlink (threat-model-as-code) and cert-x-gen (pentest-as-code).",
   "keywords": [
     "security",
@@ -37,7 +37,8 @@
     "test": "vitest run",
     "capture-help": "bash scripts/capture-help.sh",
     "prepublishOnly": "npm run build && npm test",
-    "build:plugin": "npm run build && node scripts/build-plugin.mjs"
+    "build:plugin": "npm run build && node scripts/build-plugin.mjs",
+    "build:plugin-release": "node scripts/build-plugin-release.mjs"
   },
   "dependencies": {
     "commander": "^15.0.0",