scopecairn 0.10.0 → 0.12.1

package/README.md

@@ -1,4 +1,22 @@
-# ScopeCairn
+<p align="center">
+  <img src="assets/icon.png" alt="ScopeCairn Icon" width="140" height="140" style="border-radius: 32px;" />
+</p>
+
+<h1 align="center">ScopeCairn</h1>
+
+<p align="center">
+  <strong>Local-first codebase intelligence &amp; task scope guard for AI coding agents.</strong><br>
+  <em>Understand before exploring. Retrieve before reading.</em>
+</p>
+
+<p align="center">
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-22c55e.svg?style=flat-square" alt="Node.js version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-6366f1.svg?style=flat-square" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/local--first-100%25-00f0ff.svg?style=flat-square" alt="Local-First">
+  <img src="https://img.shields.io/badge/telemetry-zero-a855f7.svg?style=flat-square" alt="Zero Telemetry">
+</p>
+
+---
 
 Local-first codebase intelligence layer for AI coding agents.
 Understand the codebase, then give the agent only what it needs:
@@ -24,15 +42,15 @@ No MCP server, no embeddings, no network calls, no telemetry.
   Definition of Done, so the agent changes only what matters.
 - **Change impact** — direct, indirect (2-hop), tests, and UI components
   affected by a file or symbol.
-- **Call path tracing** — `scopecairn path <A> <B>` shows the shortest
+- **Call path tracing** — `scopecairn graph <A> --to <B>` shows the shortest
   multi-hop call/dependency chain between two symbols.
 - **Centrality ranking** — weighted PageRank + betweenness cached per
-  symbol; `context` surfaces critical hotspots, `doctor` flags
+  symbol; `context` surfaces critical hotspots, `status --doctor` flags
   single points of failure.
 - **Community detection** — Louvain clustering finds real modules by
   link density (not just folders); `graph` shows each symbol's community.
 - **Cycle detection** — Tarjan SCC finds circular dependencies;
-  reported by `doctor`, warned in `context`, listed in `GRAPH.md`.
+  reported by `status --doctor` and `verify`, warned in `context`, listed in `GRAPH.md`.
 - **Auto-refresh** — `context` and `impact` re-index changed files first;
   run `scan` after editing to close the loop.
 - **Framework adapters** — Next.js (App + Pages Router routes),
@@ -40,8 +58,8 @@ No MCP server, no embeddings, no network calls, no telemetry.
 - **Multi-language** — TypeScript, JavaScript, Python, Java, Go, Rust,
   PHP, C#, C/C++, Ruby, HTML, Vue SFC (plus config/schema files as
   graph nodes).
-- **Multi-agent setup** — skills for Claude Code (plugin + marketplace
-  ready), Antigravity, Cursor, Windsurf, Copilot, Kiro, and an OpenCode
+- **Multi-agent setup** — skills for Claude Code (project skill),
+  Antigravity, Cursor, Windsurf, Copilot, Kiro, and an OpenCode
   slash command. ScopeCairn never touches your `AGENTS.md`/`CLAUDE.md` —
   those hold your repo's details, not tool instructions.
 - **`GRAPH.md` knowledge file** — `.scopecairn/GRAPH.md` is a budgeted
@@ -58,7 +76,7 @@ No MCP server, no embeddings, no network calls, no telemetry.
   click-for-details side panel (callers, callees, centrality scores).
   Nodes sized by symbols/PageRank, colored by Louvain community.
   Pan, zoom, hover inspect. Double-click to open, no server.
-- **`export` for external tools** — `scopecairn export --format
+- **Graph export for external tools** — `scopecairn graph --export
   mermaid|graphml|dot|json` writes `.scopecairn/graph.<ext>` for PR
   diagrams (Mermaid), Gephi/Cytoscape (GraphML), Graphviz (DOT),
   or custom scripts (JSON).
@@ -74,8 +92,7 @@ Requires Node.js ≥ 20.
 Upgrade later with:
 
 ```bash
-scopecairn update          # or: npm install -g scopecairn@latest
-scopecairn update --check  # only check for a new version
+npm install -g scopecairn@latest
 ```
 
 ## Agent-driven setup
@@ -88,8 +105,8 @@ it runs project setup itself.
    npx skills add <github-user>/scopecairn -g
    ```
    (fallback without a skill: add one line to your global agent
-   instructions — `~/.claude/CLAUDE.md` or equivalent: *When the user
-   writes "scopecairn \<path\>", run `scopecairn init \<path\>`.*)
+   instructions — `~/.claude/CLAUDE.md` or equivalent: _When the user
+   writes "scopecairn \<path\>", run `scopecairn init \<path\>`._)
 2. In any project chat, type:
    ```
    scopecairn ./
@@ -111,82 +128,75 @@ Claude Code (project skill, committed with the repo):
 scopecairn claude install
 ```
 
-Or as a plugin from the bundled marketplace (this repo):
-
-```
-/plugin marketplace add <github-user>/scopecairn
-/plugin install scopecairn@scopecairn
-```
-
 After setup, your agent calls ScopeCairn automatically on every coding task.
-To query manually:
+To query manually (replace `src/indexer.ts` or `buildContext` with files/symbols from your codebase):
 
 ```bash
-scopecairn context "add approval workflow"
-scopecairn context ./                 # repository orientation map
-scopecairn impact src/request/RequestService.ts
-scopecairn read symbol approveRequest
-scopecairn graph RequestService
-scopecairn path handleLogin dbQuery
-scopecairn export --format mermaid
-scopecairn doctor
+scopecairn scan                             # index repository (--rebuild, --clean, --watch)
+scopecairn context "tambah fitur auth"      # AI agent task context + scope
+scopecairn impact src/indexer.ts            # blast radius & affected tests (--run-tests)
+scopecairn graph buildContext               # inspect relations, path (--to), export (--export)
+scopecairn verify                           # pre-commit safety guard (--diff, --arch)
+scopecairn status                           # index statistics & health checks (--doctor, --html)
+scopecairn read symbol indexFileSymbols     # symbol-level source excerpt
 ```
 
 Per-agent installers (instead of `init --agents …`):
 
 ```bash
 scopecairn antigravity install   # Skill + Workflow + allowlist guide
-scopecairn claude install        # project skill .claude/skills (also: cursor, windsurf, copilot, kiro)
+scopecairn claude install        # project skill .claude/skills (also: cursor, windsurf, copilot)
+scopecairn kiro install          # steering .kiro/steering + knowledge skill .kiro/skills/scopecairn-knowledge
 scopecairn opencode install      # /scopecairn slash command + permission snippet
 scopecairn claude uninstall      # clean removal, user content preserved
 scopecairn agents list
 ```
 
-## Commands
+## 6 Core Commands
+
+ScopeCairn organizes its capabilities into **6 core commands** aligned with codebase architecture:
+
+| Core Command | Description & Key Options |
+| ------------ | ------------------------- |
+| `scan` | **Index & Database Lifecycle:** Index repository. Options: `--rebuild` (rebuild from scratch), `--clean` (remove `.scopecairn/`), `--watch` (auto-refresh daemon on file save). |
+| `context "<task>"` | **AI Agent Context & Scope:** Main agent entry point with auto-refresh, task classification, relevant context, task scope, and Task Guard. Options: `--escalate`, `--mode NORMAL\|FAST\|SAFE\|AUDIT`, `--max-tokens N`, `--no-history`, `--with-diff`, `--json`. |
+| `impact <target>` | **Blast Radius & Test Selection:** Change impact analysis across direct, indirect, tests, UI components, and API clients. Options: `--run-tests` (run affected tests directly), `--tests` (list affected tests only), `--repos [list]` (cross-repo blast radius). |
+| `graph [symbol]` | **Knowledge Graph & Navigation:** Symbol relations, PageRank centrality, community clusters, and cycle status. Options: `--to <target>` (shortest multi-hop call path), `--export <fmt>` (`mermaid\|graphml\|dot\|json`). |
+| `verify` | **Pre-Commit Safety Guard:** Working tree check against protected files, task scope creep, and circular dependency regressions. Options: `--diff` (structural symbol-level diff vs HEAD), `--arch` (architectural layer rules), `--strict`, `--task <t>`. |
+| `status` | **Health & Diagnostics:** Index statistics and metadata. Options: `--doctor` (integration and adapter health check), `--verbose`, `--html` (generate local HTML dashboard). |
+
+### Helper & Setup Commands
 
 | Command | Description |
-|---|---|
-| `init [path]` | Initial indexing + Skill, Workflow, detected agent skills (`--agents …\|all`; never writes `AGENTS.md`) |
-| `scan` / `rebuild` / `clean` | Manual index management (`scan` incremental; `rebuild` from scratch; `clean` removes `.scopecairn/`) |
-| `status` / `doctor` | Index status (incl. adapters, invocations) and health checks |
-| `context "<task>"` | Main entry point: context + scope (`--escalate`, `--no-refresh`, `--mode NORMAL|FAST|SAFE|AUDIT`, `--max-tokens N`, `--no-history`, `--with-diff`); a path task returns an orientation map |
-| `history "<task>" [--limit N] [--json] [--with-diff]` | Analog commit lama paling mirip (BM25 + recency half-life 180 hari + co-change); co-change set ikut ke Optional di `context` |
-| `impact <path\|symbol>` | Change impact: direct, indirect, tests (via TESTS edges + static CALLS backward reachability), UI, queries, routes. Edge evidence tagged EXTRACTED/INFERRED/AMBIGUOUS |
-| `graph <symbol>` | Symbol relations (+ PageRank, community, cycle status) |
-| `path <from> <to>` | Shortest multi-hop call/dependency path between two symbols |
-| `export --format <fmt>` | Graph export: `mermaid`, `graphml`, `dot`, or `json` (default `.scopecairn/graph.<ext>`, override with `--out`) |
-| `read symbol <name>` | Symbol-level source excerpt (not whole files) |
-| `<agent> install` | Per-agent setup: `antigravity`, `claude`, `gemini`, `cursor`, `windsurf`, `copilot`, `kiro` (each also `uninstall`; `agents list` to see all) |
-| `dashboard` | Generate local HTML dashboard at `.scopecairn/dashboard.html` |
-| `test-select <target> [--run]` | List affected test files via graph dependency traversal & runner detection (`--run` executes runner) |
-| `verify [--task <t>] [--strict]` | Post-edit guard: check modified protected files, task scope creep, and circular dependency regressions |
-| `diff` | Structural symbol-level diff of working tree vs HEAD with breaking impact alerts |
-| `arch-check [--init]` | Check architectural layer rules & disallowed import boundaries (`--init` scaffolds `.scopecairn/arch.json`) |
-| `watch [--debounce <ms>]` | Daemon mode: auto-refresh index in background on file saves |
-| `doctor --verbose` | Also surface adapter/graph errors from `.scopecairn/last-run.log` to stderr |
-| `benchmark [--tune]` | Retrieval recall, irrelevant ratio, context reduction + weight calibration |
-| `update [--check]` | Update ScopeCairn to the latest npm release (`--check` only checks) |
-
-Agent commands (`context`, `impact`, `read`, `graph`, `status`, `doctor`, `verify`, `diff`, `test-select`, `arch-check`)
-are read-only toward source and only write to `.scopecairn/` — safe to
-allowlist. `init`, `scan`, `rebuild`, and `watch` are manual/user-side commands.
+| ------- | ----------- |
+| `init [path]` | Initial indexing + Skill, Workflow, detected agent skills (`--agents …\|all`). |
+| `read symbol <name>` | Symbol-level source excerpt (not whole files). |
+| `benchmark [--tune]` | Retrieval recall, irrelevant ratio, context reduction + weight tuning (dev-only, hidden from `--help`). |
+| `<agent> install` | Agent installers: `antigravity`, `claude`, `cursor`, `windsurf`, `copilot`, `kiro`, `opencode`. |
+
+> [!NOTE]
+> **Backward Compatibility:** All previous standalone commands (`rebuild`, `clean`, `watch`, `doctor`, `dashboard`, `test-select`, `path`, `export`, `diff`, `arch-check`, `history`) are preserved as hidden aliases mapped directly into these 6 core commands — they still work but no longer appear in `--help`. `update` is deprecated (use `npm install -g scopecairn@latest`).
+
+Agent commands (`context`, `impact`, `read`, `graph`, `status`, `verify`)
+are read-only toward source code and safe to allowlist. `init` and `scan`
+are user-side setup/lifecycle commands.
 
 ## Framework adapters
 
 Detected automatically during `scan` (shown in output and `status`).
 No configuration needed.
 
-| Adapter | Detects | Produces |
-|---|---|---|
-| `nextjs` | `app/`, `pages/`, `next.config.*` | Route symbols (`GET /api/x`, `PAGE /y` incl. route groups, dynamic segments), `ROUTES_TO` handler edges, `QUERIES` handler→model edges |
-| `prisma` | `schema.prisma` | `model` symbols for `QUERIES` resolution |
-| `drizzle` | `drizzle*` paths/config, `db/` schemas | `model` symbols from `pgTable`/`sqliteTable`/`mysqlTable`; `QUERIES` from `db.query.*` relational and `db.select/insert/update/delete` builder calls |
-| `express` | `package.json` deps | Route symbols from `app/router.METHOD(path)`, handler edges |
-| `fastapi` | `.py` routes, requirements/pyproject | Route symbols from `@app.METHOD("/path")` decorators |
-| `nestjs` | `*.controller.ts`, `*.service.ts`, `nest-cli.json` | Route symbols from `@Controller` and `@Get/@Post/...` decorators, `ROUTES_TO` handler edges, `@Injectable()` service providers |
-| `django` | `manage.py`, `urls.py`, `models.py` | Route symbols from `path()`/`re_path()` in `urls.py`, `ROUTES_TO` handler edges, `model` symbols from `models.Model` |
-| `sqlalchemy` | requirements/pyproject | `model` symbols from `class X(Base)`/`__tablename__`; `QUERIES` from `session.query/select` |
-| `vue` | `.vue` SFCs, `package.json` deps | `component` symbols per SFC; `IMPORTS` edges from used components in template |
+| Adapter      | Detects                                            | Produces                                                                                                                                             |
+| ------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nextjs`     | `app/`, `pages/`, `next.config.*`                  | Route symbols (`GET /api/x`, `PAGE /y` incl. route groups, dynamic segments), `ROUTES_TO` handler edges, `QUERIES` handler→model edges               |
+| `prisma`     | `schema.prisma`                                    | `model` symbols for `QUERIES` resolution                                                                                                             |
+| `drizzle`    | `drizzle*` paths/config, `db/` schemas             | `model` symbols from `pgTable`/`sqliteTable`/`mysqlTable`; `QUERIES` from `db.query.*` relational and `db.select/insert/update/delete` builder calls |
+| `express`    | `package.json` deps                                | Route symbols from `app/router.METHOD(path)`, handler edges                                                                                          |
+| `fastapi`    | `.py` routes, requirements/pyproject               | Route symbols from `@app.METHOD("/path")` decorators                                                                                                 |
+| `nestjs`     | `*.controller.ts`, `*.service.ts`, `nest-cli.json` | Route symbols from `@Controller` and `@Get/@Post/...` decorators, `ROUTES_TO` handler edges, `@Injectable()` service providers                       |
+| `django`     | `manage.py`, `urls.py`, `models.py`                | Route symbols from `path()`/`re_path()` in `urls.py`, `ROUTES_TO` handler edges, `model` symbols from `models.Model`                                 |
+| `sqlalchemy` | requirements/pyproject                             | `model` symbols from `class X(Base)`/`__tablename__`; `QUERIES` from `session.query/select`                                                          |
+| `vue`        | `.vue` SFCs, `package.json` deps                   | `component` symbols per SFC; `IMPORTS` edges from used components in template                                                                        |
 
 Limits (honest): non-Prisma/Drizzle/SQLAlchemy ORMs, inter-table
 references, raw SQL strings, and fully dynamic table names are not mapped
@@ -210,11 +220,11 @@ Measure retrieval quality anytime: `scopecairn benchmark [--tune]`.
 
 `scan` mengindeks pesan commit git lokal ke tabel `commits`/`commit_files` di
 `.scopecairn/scopecairn.db` (dilewati commit >40 file, lockfile, dan generated).
-Isi commit **tidak** masuk `GRAPH.md`/`GRAPH.html`/`export` (sering di-commit dan
-dibagikan) — riwayat hanya hidup di database lokal dan output `context`/`history`.
+Isi commit **tidak** masuk `GRAPH.md`/`GRAPH.html`/`graph --export` (sering di-commit dan
+dibagikan) — riwayat hanya hidup di database lokal dan output `context`.
 Pesan commit bisa memuat info sensitif; karena tidak keluar dari mesin, risikonya
 kecil. Repo tanpa git atau clone dangkal tetap didukung (riwayat parsial/absen,
-dilaporkan `doctor`).
+dilaporkan `status --doctor`).
 
 ## License
 

package/assets/banner.svg

@@ -0,0 +1,137 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 260" width="100%" height="100%">
+  <defs>
+    <!-- Background Gradient -->
+    <linearGradient id="bannerBg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#070A12" />
+      <stop offset="50%" stop-color="#0B101E" />
+      <stop offset="100%" stop-color="#05070D" />
+    </linearGradient>
+
+    <!-- Border Stroke -->
+    <linearGradient id="bannerBorder" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#00F0FF" stop-opacity="0.6" />
+      <stop offset="35%" stop-color="#6366F1" stop-opacity="0.3" />
+      <stop offset="70%" stop-color="#A855F7" stop-opacity="0.6" />
+      <stop offset="100%" stop-color="#00F0FF" stop-opacity="0.1" />
+    </linearGradient>
+
+    <!-- Text Title Gradient -->
+    <linearGradient id="titleGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="#38BDF8" />
+      <stop offset="45%" stop-color="#00F0FF" />
+      <stop offset="100%" stop-color="#C084FC" />
+    </linearGradient>
+
+    <!-- Glow Filter -->
+    <filter id="bannerGlow" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur stdDeviation="6" result="blur" />
+      <feMerge>
+        <feMergeNode in="blur" />
+        <feMergeNode in="SourceGraphic" />
+      </feMerge>
+    </filter>
+
+    <filter id="softGlow" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="16" result="blur" />
+    </filter>
+  </defs>
+
+  <!-- Banner Outer Card -->
+  <rect x="2" y="2" width="956" height="256" rx="20" fill="url(#bannerBg)" stroke="url(#bannerBorder)" stroke-width="1.5" />
+
+  <!-- Background Decorative Grid Lines -->
+  <g stroke="#1E293B" stroke-width="0.7" opacity="0.35">
+    <line x1="0" y1="65" x2="960" y2="65" />
+    <line x1="0" y1="130" x2="960" y2="130" />
+    <line x1="0" y1="195" x2="960" y2="195" />
+    <line x1="240" y1="0" x2="240" y2="260" />
+    <line x1="480" y1="0" x2="480" y2="260" />
+    <line x1="720" y1="0" x2="720" y2="260" />
+  </g>
+
+  <!-- Ambient Glow Pods -->
+  <circle cx="140" cy="130" r="110" fill="#00F0FF" opacity="0.12" filter="url(#softGlow)" />
+  <circle cx="210" cy="90" r="80" fill="#8B5CF6" opacity="0.15" filter="url(#softGlow)" />
+
+  <!-- ==================== LEFT: EMBEDDED ICON ==================== -->
+  <g transform="translate(40, 20)">
+    <!-- Outer Scope Ring -->
+    <circle cx="110" cy="110" r="85" fill="none" stroke="#6366F1" stroke-width="1.2" stroke-dasharray="3 7" opacity="0.5" />
+    <circle cx="110" cy="110" r="68" fill="none" stroke="#00F0FF" stroke-width="1.8" opacity="0.8" filter="url(#bannerGlow)" />
+    <circle cx="110" cy="82" r="38" fill="none" stroke="#A855F7" stroke-width="2" opacity="0.85" filter="url(#bannerGlow)" />
+
+    <!-- Scope Crosshairs -->
+    <line x1="110" y1="18" x2="110" y2="52" stroke="#00F0FF" stroke-width="2" stroke-linecap="round" filter="url(#bannerGlow)" />
+    <line x1="110" y1="168" x2="110" y2="202" stroke="#00F0FF" stroke-width="2" stroke-linecap="round" filter="url(#bannerGlow)" />
+    <line x1="18" y1="110" x2="52" y2="110" stroke="#00F0FF" stroke-width="2" stroke-linecap="round" filter="url(#bannerGlow)" />
+    <line x1="168" y1="110" x2="202" y2="110" stroke="#00F0FF" stroke-width="2" stroke-linecap="round" filter="url(#bannerGlow)" />
+
+    <!-- Cairn Stones Stack -->
+    <!-- Base Stone -->
+    <polygon points="50,158 110,168 170,158 160,176 110,183 60,176" fill="#141E33" stroke="#334155" stroke-width="1" />
+    <polygon points="50,158 75,145 145,145 170,158 110,168" fill="#1E293B" stroke="#475569" stroke-width="1" />
+    <path d="M 60,176 L 110,183 L 160,176" fill="none" stroke="#00F0FF" stroke-width="1.8" opacity="0.7" filter="url(#bannerGlow)" />
+    
+    <!-- Middle Stone -->
+    <polygon points="72,118 92,107 128,107 148,118 110,127" fill="#334155" stroke="#475569" stroke-width="1" />
+    <polygon points="72,118 110,127 110,143 78,134" fill="#1E293B" stroke="#334155" stroke-width="1" />
+    <polygon points="110,127 148,118 142,134 110,143" fill="#0F172A" stroke="#334155" stroke-width="1" />
+    <path d="M 78,134 L 110,143 L 142,134" fill="none" stroke="#A855F7" stroke-width="1.8" opacity="0.9" filter="url(#bannerGlow)" />
+
+    <!-- Apex Stone -->
+    <polygon points="110,60 88,94 110,100" fill="#334155" stroke="#475569" stroke-width="1" />
+    <polygon points="110,60 110,100 132,94" fill="#1E293B" stroke="#334155" stroke-width="1" />
+    <line x1="110" y1="60" x2="110" y2="100" stroke="#00F0FF" stroke-width="1.8" filter="url(#bannerGlow)" />
+    <circle cx="110" cy="82" r="3.5" fill="#FFFFFF" filter="url(#bannerGlow)" />
+    <circle cx="110" cy="82" r="1.8" fill="#00F0FF" />
+
+    <!-- Constellation Graph Node Accents -->
+    <circle cx="158" cy="85" r="3" fill="#00F0FF" filter="url(#bannerGlow)" />
+    <circle cx="62" cy="100" r="2.5" fill="#A855F7" />
+  </g>
+
+  <!-- ==================== RIGHT: BRAND IDENTITY ==================== -->
+  <g transform="translate(290, 48)">
+    <!-- Small Category Label -->
+    <text x="0" y="24" fill="#38BDF8" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif" font-size="12" font-weight="700" letter-spacing="3.5" opacity="0.9">LOCAL-FIRST AGENT INTELLIGENCE</text>
+
+    <!-- Main Title -->
+    <text x="0" y="74" fill="url(#titleGrad)" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif" font-size="44" font-weight="800" letter-spacing="-0.5">ScopeCairn</text>
+
+    <!-- Subtitle / Mission -->
+    <text x="0" y="108" fill="#94A3B8" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif" font-size="15" font-weight="400" letter-spacing="0.2">
+      Understand before exploring. Precise task scope &amp; codebase knowledge graph for AI coding agents.
+    </text>
+
+    <!-- Feature Badges / Pills -->
+    <g transform="translate(0, 134)">
+      <!-- Badge 1: Knowledge Graph -->
+      <g transform="translate(0, 0)">
+        <rect x="0" y="0" width="144" height="26" rx="13" fill="#0E1726" stroke="#00F0FF" stroke-opacity="0.4" stroke-width="1" />
+        <circle cx="13" cy="13" r="3.5" fill="#00F0FF" />
+        <text x="24" y="17" fill="#E2E8F0" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif" font-size="11" font-weight="600">Knowledge Graph</text>
+      </g>
+
+      <!-- Badge 2: Scope Guard -->
+      <g transform="translate(154, 0)">
+        <rect x="0" y="0" width="138" height="26" rx="13" fill="#141126" stroke="#A855F7" stroke-opacity="0.4" stroke-width="1" />
+        <circle cx="13" cy="13" r="3.5" fill="#A855F7" />
+        <text x="24" y="17" fill="#E2E8F0" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif" font-size="11" font-weight="600">Task Scope Guard</text>
+      </g>
+
+      <!-- Badge 3: Impact Analysis -->
+      <g transform="translate(302, 0)">
+        <rect x="0" y="0" width="134" height="26" rx="13" fill="#0C1B2A" stroke="#38BDF8" stroke-opacity="0.4" stroke-width="1" />
+        <circle cx="13" cy="13" r="3.5" fill="#38BDF8" />
+        <text x="24" y="17" fill="#E2E8F0" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif" font-size="11" font-weight="600">Impact Analysis</text>
+      </g>
+
+      <!-- Badge 4: Zero Telemetry -->
+      <g transform="translate(446, 0)">
+        <rect x="0" y="0" width="134" height="26" rx="13" fill="#0B171B" stroke="#10B981" stroke-opacity="0.4" stroke-width="1" />
+        <circle cx="13" cy="13" r="3.5" fill="#10B981" />
+        <text x="24" y="17" fill="#E2E8F0" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif" font-size="11" font-weight="600">Zero Telemetry</text>
+      </g>
+    </g>
+  </g>
+</svg>

package/assets/icon.svg

@@ -0,0 +1,210 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="100%" height="100%">
+  <defs>
+    <!-- Background Gradient -->
+    <radialGradient id="bgGlow" cx="50%" cy="45%" r="65%">
+      <stop offset="0%" stop-color="#141E33" />
+      <stop offset="60%" stop-color="#0B0F19" />
+      <stop offset="100%" stop-color="#05070D" />
+    </radialGradient>
+
+    <!-- Border Gradient -->
+    <linearGradient id="borderGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#00F0FF" stop-opacity="0.8" />
+      <stop offset="50%" stop-color="#6366F1" stop-opacity="0.4" />
+      <stop offset="100%" stop-color="#A855F7" stop-opacity="0.8" />
+    </linearGradient>
+
+    <!-- Scope Laser Gradient -->
+    <linearGradient id="cyanLaser" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#38BDF8" />
+      <stop offset="50%" stop-color="#00F0FF" />
+      <stop offset="100%" stop-color="#0284C7" />
+    </linearGradient>
+
+    <linearGradient id="purpleLaser" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#C084FC" />
+      <stop offset="100%" stop-color="#7C3AED" />
+    </linearGradient>
+
+    <!-- Stone Obsidian Shading -->
+    <!-- Top Apex Stone -->
+    <linearGradient id="apexLeft" x1="30%" y1="0%" x2="70%" y2="100%">
+      <stop offset="0%" stop-color="#334155" />
+      <stop offset="100%" stop-color="#0F172A" />
+    </linearGradient>
+    <linearGradient id="apexRight" x1="70%" y1="0%" x2="30%" y2="100%">
+      <stop offset="0%" stop-color="#1E293B" />
+      <stop offset="100%" stop-color="#090D16" />
+    </linearGradient>
+    <linearGradient id="apexBottom" x1="50%" y1="0%" x2="50%" y2="100%">
+      <stop offset="0%" stop-color="#475569" />
+      <stop offset="100%" stop-color="#1E293B" />
+    </linearGradient>
+
+    <!-- Middle Stone -->
+    <linearGradient id="midTop" x1="20%" y1="0%" x2="80%" y2="100%">
+      <stop offset="0%" stop-color="#334155" />
+      <stop offset="100%" stop-color="#1E293B" />
+    </linearGradient>
+    <linearGradient id="midFront" x1="50%" y1="0%" x2="50%" y2="100%">
+      <stop offset="0%" stop-color="#1E293B" />
+      <stop offset="100%" stop-color="#0A0E17" />
+    </linearGradient>
+    <linearGradient id="midLeft" x1="0%" y1="50%" x2="100%" y2="50%">
+      <stop offset="0%" stop-color="#2D3748" />
+      <stop offset="100%" stop-color="#141A24" />
+    </linearGradient>
+
+    <!-- Base Stone -->
+    <linearGradient id="baseTop" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#334155" />
+      <stop offset="100%" stop-color="#1E293B" />
+    </linearGradient>
+    <linearGradient id="baseFront" x1="50%" y1="0%" x2="50%" y2="100%">
+      <stop offset="0%" stop-color="#1A2234" />
+      <stop offset="100%" stop-color="#080C14" />
+    </linearGradient>
+
+    <!-- Filters for Glow Effect -->
+    <filter id="laserGlow" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="5" result="blur" />
+      <feMerge>
+        <feMergeNode in="blur" />
+        <feMergeNode in="blur" />
+        <feMergeNode in="SourceGraphic" />
+      </feMerge>
+    </filter>
+
+    <filter id="intenseGlow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="9" result="blur" />
+      <feMerge>
+        <feMergeNode in="blur" />
+        <feMergeNode in="SourceGraphic" />
+      </feMerge>
+    </filter>
+  </defs>
+
+  <!-- Container App Squircle (macOS / Modern Icon Standard) -->
+  <rect x="16" y="16" width="480" height="480" rx="108" fill="url(#bgGlow)" stroke="url(#borderGrad)" stroke-width="2.5" />
+
+  <!-- Ambient Internal Backdrop Glow -->
+  <circle cx="256" cy="240" r="140" fill="#00F0FF" opacity="0.07" filter="url(#intenseGlow)" />
+  <circle cx="256" cy="180" r="80" fill="#8B5CF6" opacity="0.12" filter="url(#intenseGlow)" />
+
+  <!-- Target Scope Reticle Elements -->
+  <!-- Outer Dotted Calibration Ring -->
+  <circle cx="256" cy="256" r="190" fill="none" stroke="#6366F1" stroke-width="1.5" stroke-dasharray="3 9" opacity="0.45" />
+
+  <!-- Scope HUD Corner Brackets -->
+  <g stroke="#00F0FF" stroke-width="2" fill="none" opacity="0.4">
+    <!-- Top-Left Bracket -->
+    <path d="M 80 120 L 80 80 L 120 80" />
+    <!-- Top-Right Bracket -->
+    <path d="M 392 80 L 432 80 L 432 120" />
+    <!-- Bottom-Left Bracket -->
+    <path d="M 80 392 L 80 432 L 120 432" />
+    <!-- Bottom-Right Bracket -->
+    <path d="M 432 392 L 432 432 L 392 432" />
+  </g>
+
+  <!-- Concentric Targeting Rings (Mid + Upper Focus) -->
+  <circle cx="256" cy="256" r="150" fill="none" stroke="#00F0FF" stroke-width="2" opacity="0.75" filter="url(#laserGlow)" />
+  <circle cx="256" cy="190" r="85" fill="none" stroke="#A855F7" stroke-width="2.5" opacity="0.8" filter="url(#laserGlow)" />
+  <circle cx="256" cy="190" r="48" fill="none" stroke="#00F0FF" stroke-width="1.8" opacity="0.9" />
+
+  <!-- Scope Reticle Crosshairs (Crosslines with precise gaps) -->
+  <!-- Main Vertical Scope Line -->
+  <line x1="256" y1="75" x2="256" y2="135" stroke="#00F0FF" stroke-width="2.5" stroke-linecap="round" filter="url(#laserGlow)" />
+  <line x1="256" y1="365" x2="256" y2="435" stroke="#00F0FF" stroke-width="2.5" stroke-linecap="round" filter="url(#laserGlow)" />
+  <line x1="256" y1="140" x2="256" y2="350" stroke="#00F0FF" stroke-width="1.2" stroke-dasharray="4 6" opacity="0.5" />
+
+  <!-- Main Horizontal Scope Line -->
+  <line x1="75" y1="256" x2="135" y2="256" stroke="#00F0FF" stroke-width="2.5" stroke-linecap="round" filter="url(#laserGlow)" />
+  <line x1="377" y1="256" x2="437" y2="256" stroke="#00F0FF" stroke-width="2.5" stroke-linecap="round" filter="url(#laserGlow)" />
+
+  <!-- Precision Sub-scope Crosshair at Apex Focal Center (256, 190) -->
+  <line x1="180" y1="190" x2="215" y2="190" stroke="#38BDF8" stroke-width="2" stroke-linecap="round" />
+  <line x1="297" y1="190" x2="332" y2="190" stroke="#38BDF8" stroke-width="2" stroke-linecap="round" />
+
+  <!-- ==================== THE CAIRN STONES ==================== -->
+
+  <!-- BASE STONE (Foundation / Repository Grounding) -->
+  <g id="base-stone">
+    <!-- Base Shadow / Glow Rim -->
+    <ellipse cx="256" cy="385" rx="145" ry="32" fill="#00F0FF" opacity="0.1" filter="url(#laserGlow)" />
+    
+    <!-- Facets of Base Stone -->
+    <!-- Front Face -->
+    <polygon points="120,365 256,388 392,365 372,405 256,418 140,405" fill="url(#baseFront)" stroke="#1E293B" stroke-width="1" />
+    <!-- Top Face -->
+    <polygon points="120,365 170,335 342,335 392,365 256,388" fill="url(#baseTop)" stroke="#334155" stroke-width="1" />
+    <!-- Bottom Bevel Rim Highlight -->
+    <path d="M 140,405 L 256,418 L 372,405" fill="none" stroke="#00F0FF" stroke-width="2" opacity="0.65" filter="url(#laserGlow)" />
+    
+    <!-- Codebase Knowledge Graph Circuit Trace on Base Stone -->
+    <path d="M 165,372 L 210,378 L 245,368 L 295,380 L 340,368" fill="none" stroke="#00F0FF" stroke-width="1.8" opacity="0.75" />
+    <circle cx="210" cy="378" r="3.5" fill="#00F0FF" filter="url(#laserGlow)" />
+    <circle cx="245" cy="368" r="3" fill="#A855F7" />
+    <circle cx="295" cy="380" r="3.5" fill="#00F0FF" filter="url(#laserGlow)" />
+  </g>
+
+  <!-- MIDDLE STONE (Task Context & Module Balance) -->
+  <g id="middle-stone">
+    <!-- Floating Shadow between base and middle -->
+    <ellipse cx="256" cy="318" rx="100" ry="16" fill="#000000" opacity="0.6" />
+
+    <!-- Facets of Middle Stone -->
+    <!-- Top Facet -->
+    <polygon points="170,270 215,245 297,245 342,270 256,290" fill="url(#midTop)" stroke="#475569" stroke-width="1" />
+    <!-- Left Facet -->
+    <polygon points="170,270 256,290 256,325 185,305" fill="url(#midLeft)" stroke="#1E293B" stroke-width="1" />
+    <!-- Right Facet -->
+    <polygon points="256,290 342,270 327,305 256,325" fill="url(#midFront)" stroke="#1E293B" stroke-width="1" />
+
+    <!-- Edge Neon Accent Highlight -->
+    <path d="M 170,270 L 256,290 L 342,270" fill="none" stroke="#818CF8" stroke-width="2" opacity="0.8" />
+    <path d="M 185,305 L 256,325 L 327,305" fill="none" stroke="#A855F7" stroke-width="2.2" opacity="0.85" filter="url(#laserGlow)" />
+
+    <!-- Graph Relation Line (Edge) -->
+    <path d="M 205,282 L 235,275 L 275,295 L 305,280" fill="none" stroke="#38BDF8" stroke-width="1.5" opacity="0.8" />
+    <circle cx="235" cy="275" r="3" fill="#38BDF8" filter="url(#laserGlow)" />
+    <circle cx="275" cy="295" r="3.5" fill="#C084FC" filter="url(#laserGlow)" />
+  </g>
+
+  <!-- APEX STONE (The Summit / Target Scope Focal Beacon) -->
+  <g id="apex-stone">
+    <!-- Hover Shadow -->
+    <ellipse cx="256" cy="235" rx="50" ry="10" fill="#000000" opacity="0.7" />
+
+    <!-- Facets of Apex Jewel / Pyramid Stone -->
+    <!-- Left Facet -->
+    <polygon points="256,140 205,215 256,228" fill="url(#apexLeft)" stroke="#475569" stroke-width="1" />
+    <!-- Right Facet -->
+    <polygon points="256,140 256,228 307,215" fill="url(#apexRight)" stroke="#334155" stroke-width="1" />
+    <!-- Top Ridge Line -->
+    <line x1="256" y1="140" x2="256" y2="228" stroke="#00F0FF" stroke-width="2" opacity="0.9" filter="url(#laserGlow)" />
+
+    <!-- Rim Accents -->
+    <path d="M 205,215 L 256,228 L 307,215" fill="none" stroke="#00F0FF" stroke-width="2.5" opacity="0.9" filter="url(#laserGlow)" />
+
+    <!-- Focal Center Reticle Core -->
+    <circle cx="256" cy="190" r="5" fill="#FFFFFF" filter="url(#intenseGlow)" />
+    <circle cx="256" cy="190" r="2.5" fill="#00F0FF" />
+  </g>
+
+  <!-- Constellation / Knowledge Graph Nodes floating around -->
+  <g id="graph-nodes">
+    <circle cx="370" cy="195" r="4" fill="#00F0FF" opacity="0.85" filter="url(#laserGlow)" />
+    <line x1="340" y1="210" x2="370" y2="195" stroke="#00F0FF" stroke-width="1" stroke-dasharray="2 3" opacity="0.5" />
+
+    <circle cx="140" cy="225" r="3.5" fill="#A855F7" opacity="0.85" filter="url(#laserGlow)" />
+    <line x1="170" y1="240" x2="140" y2="225" stroke="#A855F7" stroke-width="1" stroke-dasharray="2 3" opacity="0.5" />
+
+    <circle cx="345" cy="330" r="3.5" fill="#38BDF8" opacity="0.8" filter="url(#laserGlow)" />
+    <circle cx="165" cy="325" r="4" fill="#00F0FF" opacity="0.8" filter="url(#laserGlow)" />
+  </g>
+
+  <!-- Calibrated Boundary Angle Marks (Degree coordinates) -->
+  <text x="256" y="60" text-anchor="middle" fill="#00F0FF" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, monospace" font-size="11" font-weight="700" letter-spacing="3" opacity="0.75">SCOPE·CAIRN</text>
+  <text x="256" y="465" text-anchor="middle" fill="#818CF8" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, monospace" font-size="9" font-weight="600" letter-spacing="4" opacity="0.6">CODEBASE INTELLIGENCE</text>
+</svg>

package/dist/agentsmd-GS2DHP65.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import {
+  PROJECT_RULES_MAX_CHARS,
+  demoteHeadings,
+  findAgentsMd,
+  loadProjectRules
+} from "./chunk-ZV4BSIQM.js";
+export {
+  PROJECT_RULES_MAX_CHARS,
+  demoteHeadings,
+  findAgentsMd,
+  loadProjectRules
+};