kirograph 0.16.1 → 0.19.0

package/dist/bin/installer/instructions.js

@@ -22,11 +22,66 @@ __export(instructions_exports, {
 });
 module.exports = __toCommonJS(instructions_exports);
 var import_caveman = require("./caveman");
-function buildAgentInstructions(cavemanMode) {
-  const content = `# KiroGraph
+const LEVEL_DESCRIPTIONS = {
+  normal: "Balanced: removes noise, keeps structure.",
+  aggressive: "Compact: groups by category, limits output.",
+  ultra: "Maximum compression: counts and summaries only."
+};
+const LEVEL_EXAMPLES = {
+  normal: `\`\`\`
+kirograph_exec(command: "git status")
+kirograph_exec(command: "npm test")
+kirograph_exec(command: "cargo build")
+kirograph_exec(command: "ls -la src/")
+\`\`\``,
+  aggressive: `\`\`\`
+kirograph_exec(command: "git status", level: "aggressive")
+kirograph_exec(command: "npm test", level: "aggressive")
+kirograph_exec(command: "eslint .", level: "aggressive")
+kirograph_exec(command: "find . -name '*.ts'", level: "aggressive")
+\`\`\``,
+  ultra: `\`\`\`
+kirograph_exec(command: "git status", level: "ultra")
+kirograph_exec(command: "npm test", level: "ultra")
+kirograph_exec(command: "docker ps", level: "ultra")
+kirograph_exec(command: "ls -la src/", level: "ultra")
+\`\`\``
+};
+function buildAgentInstructions(cavemanModeOrOpts) {
+  const opts = typeof cavemanModeOrOpts === "object" && cavemanModeOrOpts !== null ? cavemanModeOrOpts : { cavemanMode: cavemanModeOrOpts ?? void 0 };
+  const cavemanMode = opts.cavemanMode;
+  const enableCompression = opts.shellCompressionLevel && opts.shellCompressionLevel !== "off";
+  const shellCompressionLevel = opts.shellCompressionLevel ?? "normal";
+  const enableArchitecture = opts.enableArchitecture ?? false;
+  const enableMemory = opts.enableMemory ?? false;
+  const enableDocs = opts.enableDocs ?? false;
+  const enableData = opts.enableData ?? false;
+  const enableSecurity = opts.enableSecurity ?? false;
+  let content = `# KiroGraph
 
 KiroGraph builds a local semantic knowledge graph of this codebase. When the \`kirograph\` MCP server is available, prefer its tools over broad grep/glob/file-read exploration.
 
+## Quick decision guide
+
+| Question | Tool |
+|----------|------|
+| Where do I start on this task? | \`kirograph_context\` |
+| What is this symbol / show me its code | \`kirograph_node\` with \`includeCode: true\` |
+| Find a symbol by name | \`kirograph_search\` |
+| Who calls function X? | \`kirograph_callers\` |
+| What does function X call? | \`kirograph_callees\` |
+| What breaks if I change X? | \`kirograph_impact\` |
+| How are X and Y connected? | \`kirograph_path\` |
+| What extends / implements this type? | \`kirograph_type_hierarchy\` |
+| Which code is never called? | \`kirograph_dead_code\` |
+| Are there import cycles? | \`kirograph_circular_deps\` |
+| What files are indexed? | \`kirograph_files\` |
+| Is the index healthy? | \`kirograph_status\` |
+| What are the most critical symbols? | \`kirograph_hotspots\` |
+| Any unexpected cross-module coupling? | \`kirograph_surprising\` |
+| What changed since the last snapshot? | \`kirograph_diff\` |
+${enableArchitecture ? "| What packages/layers exist? | `kirograph_architecture` |\n| How coupled is package X? | `kirograph_coupling` |\n| What does package X depend on? | `kirograph_package` |\n" : ""}
+${enableCompression ? "| Run a command with token savings | `kirograph_exec` |\n| Check token savings stats | `kirograph_gain` |\n" : ""}${enableMemory ? "| Search past decisions/patterns | `kirograph_mem_search` |\n| Store an observation | `kirograph_mem_store` |\n" : ""}${enableDocs ? "| Find a doc section | `kirograph_docs_search` |\n| Get doc table of contents | `kirograph_docs_toc` |\n" : ""}${enableData ? "| What datasets are indexed? | `kirograph_data_list` |\n| Query rows with filters | `kirograph_data_query` |\n| Aggregate data server-side | `kirograph_data_aggregate` |\n" : ""}${enableSecurity ? "| Are there vulnerable dependencies? | `kirograph_security` |\n| Which CVEs affect my project? | `kirograph_vulns` |\n| Is this vulnerability reachable? | `kirograph_reachability` |\n| What licenses do my deps use? | `kirograph_licenses` |\n| Are dependencies outdated? | `kirograph_staleness` |\n" : ""}
 ## Tool selection
 
 - Start code tasks with \`kirograph_context\`.
@@ -50,8 +105,145 @@ KiroGraph builds a local semantic knowledge graph of this codebase. When the \`k
 
 If \`.kirograph/\` does not exist, ask whether to run \`kirograph init --index\`.
 `;
+  if (enableCompression) {
+    const level = shellCompressionLevel;
+    content += `
+## Shell Compression (\`kirograph_exec\`)
+
+When running shell commands, prefer \`kirograph_exec\` over raw shell execution for:
+- **git** operations (status, log, diff, push, pull, commit, add, fetch, branch)
+- **GitHub CLI** (gh pr list/view, gh issue list, gh run list)
+- **test runners** (jest, vitest, pytest, cargo test, go test, rspec, minitest, playwright)
+- **linters/build** (eslint, tsc, ruff, clippy, cargo build, prettier, biome, golangci-lint, rubocop, next build)
+- **file listings** (ls, find, tree)
+- **search** (grep, rg/ripgrep: grouped by file)
+- **diff** (diff file1 file2: condensed context)
+- **docker/k8s** (docker ps, images, logs, compose ps, kubectl pods, logs, services)
+- **package managers** (npm/pnpm install/list, pip list/install, bundle install, prisma generate)
+- **AWS CLI** (sts, ec2, lambda, logs, cloudformation, dynamodb, iam, s3, ecs, sqs, sns)
+- **network** (curl, wget: strip progress bars and headers)
+
+This saves 60-90% of tokens compared to raw output.
+
+Compression level: **${level}**: ${LEVEL_DESCRIPTIONS[level]}
+
+${LEVEL_EXAMPLES[level]}
+
+**Important:** Error details are always preserved. Failed commands show full diagnostic output regardless of level.
+
+**Do NOT re-run commands:** When \`kirograph_exec\` returns a result, treat it as the final answer. Never re-run the same command with raw shell execution to "get more details." The compressed output preserves all essential information. If you genuinely need something missing from the output, explain what's missing before making a second call.
+
+Use \`kirograph_gain\` to check token savings statistics.
+`;
+  }
+  if (enableMemory) {
+    content += `
+## Memory
+
+KiroGraph has persistent memory. Use \`kirograph_mem_search\` to recall past decisions,
+errors, and patterns before making changes. Use \`kirograph_mem_store\` to save important
+observations (architecture decisions, bug root causes, patterns discovered).
+
+Memory is searchable via hybrid FTS + vector search. Observations are automatically
+linked to code symbols in the graph and surface in \`kirograph_context\` and
+\`kirograph_impact\` results when relevant.
+
+**When to store:** After fixing a bug, making an architecture decision, discovering a pattern,
+encountering a non-obvious error, or learning something about the codebase that future sessions
+should know. Keep observations concise \u2014 one fact per store call.
+`;
+  }
+  if (enableArchitecture) {
+    content += `
+## Architecture
+
+KiroGraph analyzes the package structure and layer dependencies of the codebase.
+
+- \`kirograph_architecture\` \u2014 full package graph, detected layers (api/service/data/ui/shared), dependency edges
+- \`kirograph_coupling\` \u2014 Ca (afferent), Ce (efferent), instability per package; high Ca = load-bearing, high Ce = volatile
+- \`kirograph_package\` \u2014 drill into a single package: coupling metrics, deps, dependents, files
+
+Use \`kirograph_architecture\` for architectural questions instead of reading directory trees.
+High Ca + low instability = risky to change interface. High Ce + high instability = safe to refactor internals.
+`;
+  }
+  if (enableDocs) {
+    content += `
+## Documentation
+
+KiroGraph indexes project documentation by heading structure. Use \`kirograph_docs_search\`
+to find relevant sections instead of reading entire files.
+
+- \`kirograph_docs_toc\` \u2014 table of contents for a file or the whole project
+- \`kirograph_docs_search\` \u2014 search sections by query
+- \`kirograph_docs_section\` \u2014 retrieve full section content by ID
+- \`kirograph_docs_outline\` \u2014 heading hierarchy for a single file
+- \`kirograph_docs_refs\` \u2014 code \u2194 doc cross-references
+
+Before reading a doc file directly, try \`kirograph_docs_search\` or \`kirograph_docs_outline\` first.
+`;
+  }
+  if (enableData) {
+    content += `
+## Data
+
+KiroGraph indexes tabular data files (CSV, TSV, JSONL, JSON, Excel, Parquet).
+
+- \`kirograph_data_list\` \u2014 list all indexed datasets
+- \`kirograph_data_describe\` \u2014 schema profile: column names, types, cardinality, samples
+- \`kirograph_data_query\` \u2014 filtered row retrieval (eq, gt, contains, in, between)
+- \`kirograph_data_aggregate\` \u2014 server-side GROUP BY: count, sum, avg, min, max
+
+Use \`kirograph_data_describe\` before reading a data file. Use \`kirograph_data_query\` with
+filters instead of loading all rows. Use \`kirograph_data_aggregate\` for statistics.
+This saves 95-99% of tokens compared to reading raw data files.
+`;
+  }
+  if (enableSecurity) {
+    content += `
+## Security
+
+KiroGraph scans dependency manifests across 14 ecosystems for known vulnerabilities, performs
+call-graph reachability analysis, tracks EPSS exploitation probability, checks license
+compliance, and monitors dependency staleness.
+
+**Available tools:**
+- \`kirograph_security\` \u2014 overview: dep count, CVE count, verdict breakdown, stale warnings
+- \`kirograph_vulns\` \u2014 list CVEs with severity, EPSS score, reachability verdict, fix suggestion
+- \`kirograph_reachability\` \u2014 call paths, entry points, affected layers for one CVE or package
+- \`kirograph_licenses\` \u2014 list dependency licenses; flag policy violations
+- \`kirograph_staleness\` \u2014 identify outdated dependencies (staleness score 0.0\u20131.0)
+- \`kirograph_sbom\` / \`kirograph_vex\` \u2014 export CycloneDX 1.5 SBOM and VEX documents
+- \`kirograph_vuln_add\` \u2014 manually register a private/internal CVE
+
+**Proactive triggers:** Run \`kirograph_security\` when a dependency is added/updated, before a
+production deploy, or when the user asks about security/compliance.
+
+**Interpreting verdicts:**
+- \`affected\` \u2014 a call path exists from an entry point to the vulnerable code. Act on this.
+- \`not_affected\` \u2014 no reachable path found. Strong signal: likely safe.
+- \`under_investigation\` \u2014 unresolved symbols in traversal. Treat with caution.
+
+**EPSS scores:** >= 0.5 = patch immediately; 0.1\u20130.5 = elevated risk; < 0.1 = low probability.
+
+**Workflow:** \`kirograph_security\` \u2192 \`kirograph_vulns --verdict affected\` \u2192 \`kirograph_reachability <cve>\` \u2192 fix \u2192 \`kirograph_vulns --refresh\`
+`;
+  }
+  if (!opts.hasHooks) {
+    content += `
+## Session Hygiene
+
+This tool does not have automatic sync hooks. To keep the index fresh:
+- Run \`kirograph sync\` at the **start** of each session if files changed outside the agent.
+- Run \`kirograph sync\` at the **end** of each session after making changes.
+- If results from graph tools seem stale, run \`kirograph sync\` before retrying.
+${enableMemory ? "- Store important observations with `kirograph_mem_store` before ending your session.\n" : ""}`;
+  }
   const caveman = cavemanMode && cavemanMode !== "off" ? import_caveman.CAVEMAN_RULES[cavemanMode] : null;
-  return caveman ? content.trimEnd() + "\n\n" + caveman + "\n" : content;
+  if (caveman) {
+    content = content.trimEnd() + "\n\n" + caveman + "\n";
+  }
+  return content;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/bin/installer/instructions.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/bin/installer/instructions.ts"],
-  "sourcesContent": ["import { CAVEMAN_RULES, CavemanMode } from './caveman';\n\nexport function buildAgentInstructions(cavemanMode?: CavemanMode | 'off'): string {\n  const content = `# KiroGraph\n\nKiroGraph builds a local semantic knowledge graph of this codebase. When the \\`kirograph\\` MCP server is available, prefer its tools over broad grep/glob/file-read exploration.\n\n## Tool selection\n\n- Start code tasks with \\`kirograph_context\\`.\n- Find symbols by name with \\`kirograph_search\\`.\n- Inspect a symbol with \\`kirograph_node\\`; set \\`includeCode: true\\` only when source is needed.\n- Trace call flow with \\`kirograph_callers\\` and \\`kirograph_callees\\`.\n- Check blast radius before edits with \\`kirograph_impact\\`.\n- Use \\`kirograph_path\\` to explain how two symbols connect.\n- Use \\`kirograph_type_hierarchy\\` for inheritance/interface questions.\n- Use \\`kirograph_files\\` to inspect indexed file structure.\n- Use \\`kirograph_status\\` if results seem stale or incomplete.\n- Use \\`kirograph_architecture\\`, \\`kirograph_coupling\\`, and \\`kirograph_package\\` for package/layer questions when architecture analysis is enabled.\n- Use \\`kirograph_hotspots\\`, \\`kirograph_surprising\\`, and \\`kirograph_diff\\` for refactor planning and review.\n\n## Workflow\n\n1. Call \\`kirograph_context\\` for orientation.\n2. Drill into specific symbols with \\`kirograph_node\\`.\n3. Use graph traversal tools before reading unrelated files.\n4. Fall back to normal filesystem tools only when the graph is missing, stale, or lacks the needed detail.\n\nIf \\`.kirograph/\\` does not exist, ask whether to run \\`kirograph init --index\\`.\n`;\n\n  const caveman = cavemanMode && cavemanMode !== 'off' ? CAVEMAN_RULES[cavemanMode] : null;\n  return caveman ? content.trimEnd() + '\\n\\n' + caveman + '\\n' : content;\n}\n\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qBAA2C;AAEpC,SAAS,uBAAuB,aAA2C;AAChF,QAAM,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4BhB,QAAM,UAAU,eAAe,gBAAgB,QAAQ,6BAAc,WAAW,IAAI;AACpF,SAAO,UAAU,QAAQ,QAAQ,IAAI,SAAS,UAAU,OAAO;AACjE;",
+  "sourcesContent": ["import { CAVEMAN_RULES, CavemanMode } from './caveman';\n\nexport interface InstructionOptions {\n  cavemanMode?: CavemanMode | 'off';\n  shellCompressionLevel?: 'off' | 'normal' | 'aggressive' | 'ultra';\n  enableArchitecture?: boolean;\n  enableMemory?: boolean;\n  enableDocs?: boolean;\n  enableData?: boolean;\n  enableSecurity?: boolean;\n  hasHooks?: boolean;\n}\n\nconst LEVEL_DESCRIPTIONS: Record<string, string> = {\n  normal: 'Balanced: removes noise, keeps structure.',\n  aggressive: 'Compact: groups by category, limits output.',\n  ultra: 'Maximum compression: counts and summaries only.',\n};\n\nconst LEVEL_EXAMPLES: Record<string, string> = {\n  normal: `\\`\\`\\`\nkirograph_exec(command: \"git status\")\nkirograph_exec(command: \"npm test\")\nkirograph_exec(command: \"cargo build\")\nkirograph_exec(command: \"ls -la src/\")\n\\`\\`\\``,\n  aggressive: `\\`\\`\\`\nkirograph_exec(command: \"git status\", level: \"aggressive\")\nkirograph_exec(command: \"npm test\", level: \"aggressive\")\nkirograph_exec(command: \"eslint .\", level: \"aggressive\")\nkirograph_exec(command: \"find . -name '*.ts'\", level: \"aggressive\")\n\\`\\`\\``,\n  ultra: `\\`\\`\\`\nkirograph_exec(command: \"git status\", level: \"ultra\")\nkirograph_exec(command: \"npm test\", level: \"ultra\")\nkirograph_exec(command: \"docker ps\", level: \"ultra\")\nkirograph_exec(command: \"ls -la src/\", level: \"ultra\")\n\\`\\`\\``,\n};\n\nexport function buildAgentInstructions(cavemanModeOrOpts?: CavemanMode | 'off' | InstructionOptions): string {\n  // Support both old signature (cavemanMode string) and new signature (options object)\n  const opts: InstructionOptions = typeof cavemanModeOrOpts === 'object' && cavemanModeOrOpts !== null\n    ? cavemanModeOrOpts\n    : { cavemanMode: cavemanModeOrOpts ?? undefined };\n\n  const cavemanMode = opts.cavemanMode;\n  const enableCompression = opts.shellCompressionLevel && opts.shellCompressionLevel !== 'off';\n  const shellCompressionLevel = opts.shellCompressionLevel ?? 'normal';\n  const enableArchitecture = opts.enableArchitecture ?? false;\n  const enableMemory = opts.enableMemory ?? false;\n  const enableDocs = opts.enableDocs ?? false;\n  const enableData = opts.enableData ?? false;\n  const enableSecurity = opts.enableSecurity ?? false;\n\n  let content = `# KiroGraph\n\nKiroGraph builds a local semantic knowledge graph of this codebase. When the \\`kirograph\\` MCP server is available, prefer its tools over broad grep/glob/file-read exploration.\n\n## Quick decision guide\n\n| Question | Tool |\n|----------|------|\n| Where do I start on this task? | \\`kirograph_context\\` |\n| What is this symbol / show me its code | \\`kirograph_node\\` with \\`includeCode: true\\` |\n| Find a symbol by name | \\`kirograph_search\\` |\n| Who calls function X? | \\`kirograph_callers\\` |\n| What does function X call? | \\`kirograph_callees\\` |\n| What breaks if I change X? | \\`kirograph_impact\\` |\n| How are X and Y connected? | \\`kirograph_path\\` |\n| What extends / implements this type? | \\`kirograph_type_hierarchy\\` |\n| Which code is never called? | \\`kirograph_dead_code\\` |\n| Are there import cycles? | \\`kirograph_circular_deps\\` |\n| What files are indexed? | \\`kirograph_files\\` |\n| Is the index healthy? | \\`kirograph_status\\` |\n| What are the most critical symbols? | \\`kirograph_hotspots\\` |\n| Any unexpected cross-module coupling? | \\`kirograph_surprising\\` |\n| What changed since the last snapshot? | \\`kirograph_diff\\` |\n${enableArchitecture ? '| What packages/layers exist? | `kirograph_architecture` |\\n| How coupled is package X? | `kirograph_coupling` |\\n| What does package X depend on? | `kirograph_package` |\\n' : ''}\n${enableCompression ? '| Run a command with token savings | `kirograph_exec` |\\n| Check token savings stats | `kirograph_gain` |\\n' : ''}${enableMemory ? '| Search past decisions/patterns | `kirograph_mem_search` |\\n| Store an observation | `kirograph_mem_store` |\\n' : ''}${enableDocs ? '| Find a doc section | `kirograph_docs_search` |\\n| Get doc table of contents | `kirograph_docs_toc` |\\n' : ''}${enableData ? '| What datasets are indexed? | `kirograph_data_list` |\\n| Query rows with filters | `kirograph_data_query` |\\n| Aggregate data server-side | `kirograph_data_aggregate` |\\n' : ''}${enableSecurity ? '| Are there vulnerable dependencies? | `kirograph_security` |\\n| Which CVEs affect my project? | `kirograph_vulns` |\\n| Is this vulnerability reachable? | `kirograph_reachability` |\\n| What licenses do my deps use? | `kirograph_licenses` |\\n| Are dependencies outdated? | `kirograph_staleness` |\\n' : ''}\n## Tool selection\n\n- Start code tasks with \\`kirograph_context\\`.\n- Find symbols by name with \\`kirograph_search\\`.\n- Inspect a symbol with \\`kirograph_node\\`; set \\`includeCode: true\\` only when source is needed.\n- Trace call flow with \\`kirograph_callers\\` and \\`kirograph_callees\\`.\n- Check blast radius before edits with \\`kirograph_impact\\`.\n- Use \\`kirograph_path\\` to explain how two symbols connect.\n- Use \\`kirograph_type_hierarchy\\` for inheritance/interface questions.\n- Use \\`kirograph_files\\` to inspect indexed file structure.\n- Use \\`kirograph_status\\` if results seem stale or incomplete.\n- Use \\`kirograph_architecture\\`, \\`kirograph_coupling\\`, and \\`kirograph_package\\` for package/layer questions when architecture analysis is enabled.\n- Use \\`kirograph_hotspots\\`, \\`kirograph_surprising\\`, and \\`kirograph_diff\\` for refactor planning and review.\n\n## Workflow\n\n1. Call \\`kirograph_context\\` for orientation.\n2. Drill into specific symbols with \\`kirograph_node\\`.\n3. Use graph traversal tools before reading unrelated files.\n4. Fall back to normal filesystem tools only when the graph is missing, stale, or lacks the needed detail.\n\nIf \\`.kirograph/\\` does not exist, ask whether to run \\`kirograph init --index\\`.\n`;\n\n  // Shell compression section\n  if (enableCompression) {\n    const level = shellCompressionLevel as 'normal' | 'aggressive' | 'ultra';\n    content += `\n## Shell Compression (\\`kirograph_exec\\`)\n\nWhen running shell commands, prefer \\`kirograph_exec\\` over raw shell execution for:\n- **git** operations (status, log, diff, push, pull, commit, add, fetch, branch)\n- **GitHub CLI** (gh pr list/view, gh issue list, gh run list)\n- **test runners** (jest, vitest, pytest, cargo test, go test, rspec, minitest, playwright)\n- **linters/build** (eslint, tsc, ruff, clippy, cargo build, prettier, biome, golangci-lint, rubocop, next build)\n- **file listings** (ls, find, tree)\n- **search** (grep, rg/ripgrep: grouped by file)\n- **diff** (diff file1 file2: condensed context)\n- **docker/k8s** (docker ps, images, logs, compose ps, kubectl pods, logs, services)\n- **package managers** (npm/pnpm install/list, pip list/install, bundle install, prisma generate)\n- **AWS CLI** (sts, ec2, lambda, logs, cloudformation, dynamodb, iam, s3, ecs, sqs, sns)\n- **network** (curl, wget: strip progress bars and headers)\n\nThis saves 60-90% of tokens compared to raw output.\n\nCompression level: **${level}**: ${LEVEL_DESCRIPTIONS[level]}\n\n${LEVEL_EXAMPLES[level]}\n\n**Important:** Error details are always preserved. Failed commands show full diagnostic output regardless of level.\n\n**Do NOT re-run commands:** When \\`kirograph_exec\\` returns a result, treat it as the final answer. Never re-run the same command with raw shell execution to \"get more details.\" The compressed output preserves all essential information. If you genuinely need something missing from the output, explain what's missing before making a second call.\n\nUse \\`kirograph_gain\\` to check token savings statistics.\n`;\n  }\n\n  // Memory section\n  if (enableMemory) {\n    content += `\n## Memory\n\nKiroGraph has persistent memory. Use \\`kirograph_mem_search\\` to recall past decisions,\nerrors, and patterns before making changes. Use \\`kirograph_mem_store\\` to save important\nobservations (architecture decisions, bug root causes, patterns discovered).\n\nMemory is searchable via hybrid FTS + vector search. Observations are automatically\nlinked to code symbols in the graph and surface in \\`kirograph_context\\` and\n\\`kirograph_impact\\` results when relevant.\n\n**When to store:** After fixing a bug, making an architecture decision, discovering a pattern,\nencountering a non-obvious error, or learning something about the codebase that future sessions\nshould know. Keep observations concise \u2014 one fact per store call.\n`;\n  }\n\n  // Architecture section\n  if (enableArchitecture) {\n    content += `\n## Architecture\n\nKiroGraph analyzes the package structure and layer dependencies of the codebase.\n\n- \\`kirograph_architecture\\` \u2014 full package graph, detected layers (api/service/data/ui/shared), dependency edges\n- \\`kirograph_coupling\\` \u2014 Ca (afferent), Ce (efferent), instability per package; high Ca = load-bearing, high Ce = volatile\n- \\`kirograph_package\\` \u2014 drill into a single package: coupling metrics, deps, dependents, files\n\nUse \\`kirograph_architecture\\` for architectural questions instead of reading directory trees.\nHigh Ca + low instability = risky to change interface. High Ce + high instability = safe to refactor internals.\n`;\n  }\n\n  // Documentation section\n  if (enableDocs) {\n    content += `\n## Documentation\n\nKiroGraph indexes project documentation by heading structure. Use \\`kirograph_docs_search\\`\nto find relevant sections instead of reading entire files.\n\n- \\`kirograph_docs_toc\\` \u2014 table of contents for a file or the whole project\n- \\`kirograph_docs_search\\` \u2014 search sections by query\n- \\`kirograph_docs_section\\` \u2014 retrieve full section content by ID\n- \\`kirograph_docs_outline\\` \u2014 heading hierarchy for a single file\n- \\`kirograph_docs_refs\\` \u2014 code \u2194 doc cross-references\n\nBefore reading a doc file directly, try \\`kirograph_docs_search\\` or \\`kirograph_docs_outline\\` first.\n`;\n  }\n\n  // Data section\n  if (enableData) {\n    content += `\n## Data\n\nKiroGraph indexes tabular data files (CSV, TSV, JSONL, JSON, Excel, Parquet).\n\n- \\`kirograph_data_list\\` \u2014 list all indexed datasets\n- \\`kirograph_data_describe\\` \u2014 schema profile: column names, types, cardinality, samples\n- \\`kirograph_data_query\\` \u2014 filtered row retrieval (eq, gt, contains, in, between)\n- \\`kirograph_data_aggregate\\` \u2014 server-side GROUP BY: count, sum, avg, min, max\n\nUse \\`kirograph_data_describe\\` before reading a data file. Use \\`kirograph_data_query\\` with\nfilters instead of loading all rows. Use \\`kirograph_data_aggregate\\` for statistics.\nThis saves 95-99% of tokens compared to reading raw data files.\n`;\n  }\n\n  // Security section\n  if (enableSecurity) {\n    content += `\n## Security\n\nKiroGraph scans dependency manifests across 14 ecosystems for known vulnerabilities, performs\ncall-graph reachability analysis, tracks EPSS exploitation probability, checks license\ncompliance, and monitors dependency staleness.\n\n**Available tools:**\n- \\`kirograph_security\\` \u2014 overview: dep count, CVE count, verdict breakdown, stale warnings\n- \\`kirograph_vulns\\` \u2014 list CVEs with severity, EPSS score, reachability verdict, fix suggestion\n- \\`kirograph_reachability\\` \u2014 call paths, entry points, affected layers for one CVE or package\n- \\`kirograph_licenses\\` \u2014 list dependency licenses; flag policy violations\n- \\`kirograph_staleness\\` \u2014 identify outdated dependencies (staleness score 0.0\u20131.0)\n- \\`kirograph_sbom\\` / \\`kirograph_vex\\` \u2014 export CycloneDX 1.5 SBOM and VEX documents\n- \\`kirograph_vuln_add\\` \u2014 manually register a private/internal CVE\n\n**Proactive triggers:** Run \\`kirograph_security\\` when a dependency is added/updated, before a\nproduction deploy, or when the user asks about security/compliance.\n\n**Interpreting verdicts:**\n- \\`affected\\` \u2014 a call path exists from an entry point to the vulnerable code. Act on this.\n- \\`not_affected\\` \u2014 no reachable path found. Strong signal: likely safe.\n- \\`under_investigation\\` \u2014 unresolved symbols in traversal. Treat with caution.\n\n**EPSS scores:** >= 0.5 = patch immediately; 0.1\u20130.5 = elevated risk; < 0.1 = low probability.\n\n**Workflow:** \\`kirograph_security\\` \u2192 \\`kirograph_vulns --verdict affected\\` \u2192 \\`kirograph_reachability <cve>\\` \u2192 fix \u2192 \\`kirograph_vulns --refresh\\`\n`;\n  }\n\n  // Session hygiene for tools without hooks\n  if (!opts.hasHooks) {\n    content += `\n## Session Hygiene\n\nThis tool does not have automatic sync hooks. To keep the index fresh:\n- Run \\`kirograph sync\\` at the **start** of each session if files changed outside the agent.\n- Run \\`kirograph sync\\` at the **end** of each session after making changes.\n- If results from graph tools seem stale, run \\`kirograph sync\\` before retrying.\n${enableMemory ? '- Store important observations with `kirograph_mem_store` before ending your session.\\n' : ''}`;\n  }\n\n  // Caveman mode\n  const caveman = cavemanMode && cavemanMode !== 'off' ? CAVEMAN_RULES[cavemanMode] : null;\n  if (caveman) {\n    content = content.trimEnd() + '\\n\\n' + caveman + '\\n';\n  }\n\n  return content;\n}\n"],
+  "mappings": "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",
   "names": []
 }