@mgamil/mapx 0.2.4

package/LICENSE

@@ -0,0 +1,194 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and incorporated
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any Contribution
+      embodied within the Work constitutes direct or contributory patent
+      infringement, then any patent licenses granted to You under this License
+      for that Work shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an addendum to
+          the NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the
+          License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, reproduce, modify,
+      and distribute Your modifications as part of a Derivative Work,
+      under the terms and conditions of this License; provided, however,
+      that such additional grant of rights does not reduce or restrict
+      the rights granted to You herein by this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Liability. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee
+      for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may offer such obligations only on
+      Your own behalf and on Your sole responsibility, not on behalf of
+      any other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by, or
+      claims asserted against, such Contributor by reason of your accepting
+      any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format in question. It should also be
+      included in any file distribution as the source form of the work.
+
+   Copyright 2026 Mohamed Gamil
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,488 @@
+# MapX
+
+**Local code graph memory for LLMs.** Scan your codebase once — instantly query symbols, trace dependencies, analyze impact, and generate structured summaries without re-reading files.
+
+MapX uses [tree-sitter](https://tree-sitter.github.io/) to parse source files across **22 languages**, builds a PageRank-weighted dependency graph, and persists everything to a local SQLite database. Works as a standalone CLI or as an [MCP server](https://modelcontextprotocol.io/) with **25 tools** for Claude Desktop, Cursor, VS Code, and any other MCP-compatible client.
+
+---
+
+## Features
+
+- **22 languages** — 8 built-in (PHP, JS, TS, Python, Go, Rust, Java, C#), 7 bundled (Ruby, C, C++, Swift, Kotlin, Scala, Vue), 7 installable (Svelte, Lua, Elixir, Zig, Bash, Pascal, Dart)
+- **Deep symbol extraction** — classes, methods, functions, interfaces, traits, enums, structs, modules, constants, properties, namespaces — with full import/inheritance/instantiation reference tracking
+- **Incremental scans** — git-aware change detection; only re-parses files that changed
+- **Fast** — parallelised file reads, bounded WASM concurrency, batched SQLite writes
+- **Resumable** — scan progress is checkpointed; `Ctrl+C` and re-run picks up where it left off
+- **25 MCP tools** — scan, query, search, trace, callers, callees, impact, export, context, workspaces, and more
+- **Data flow tracing** — trace call chains, find sources/sinks, analyze change impact with blast radius scoring
+- **Multi-repo workspaces** — register multiple repos, discover submodules, track cross-repo dependencies
+- **Multiple export formats** — LLM summary (token-budgeted), JSON, GraphViz DOT, SVG, TOON
+- **Framework detection** — 21 frameworks recognized (Laravel, Express, Next.js, Django, Flask, FastAPI, Spring, Rails, and more)
+- **Web dashboard** — built-in `mapx ui` for interactive graph visualization
+- **Zero cloud** — everything stays on disk in `.mapx/` inside your project
+- **87% LLM cost reduction** — drops context token consumption by 87% vs baseline workspace reads by feeding exact signatures and transitive impact summaries
+
+---
+
+## Installation
+
+### Pre-built binary (recommended)
+
+Download the latest release for your platform from the [Releases](../../releases) page and place it on your `PATH`:
+
+```bash
+# Linux x86_64
+curl -fsSL https://github.com/MohamedGamil/mapx/releases/latest/download/mapx-linux-x64-installer.sh | sh
+
+# macOS Apple Silicon
+curl -fsSL https://github.com/MohamedGamil/mapx/releases/latest/download/mapx-darwin-arm64-installer.sh | sh
+```
+
+Or extract the archive manually:
+
+```bash
+tar xzf mapx-<version>-linux-x64.tar.gz
+cd mapx-<version>
+./install.sh --local          # installs to ~/.local/bin (no sudo)
+./install.sh --system         # installs to /usr/local/bin (needs sudo)
+```
+
+### From npm
+
+```bash
+npm install -g mapx
+```
+
+### From source
+
+Requires [Node.js](https://nodejs.org/) ≥ 20 or [Bun](https://bun.sh/).
+
+```bash
+git clone https://github.com/MohamedGamil/mapx.git
+cd mapx
+npm install
+npx tsx src/main.ts --help
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Initialize mapx in your project (auto-adds .mapx/ to .gitignore)
+cd /path/to/your/project
+mapx init
+
+# 2. Scan all source files
+mapx scan
+
+# 3. View a token-efficient summary (great for pasting into an LLM)
+mapx export
+
+# 4. Search for a symbol
+mapx query UserService
+
+# 5. Show a file's dependencies
+mapx deps src/app.ts
+
+# 6. Trace who calls a function
+mapx callers handleRequest
+
+# 7. Assess change impact before refactoring
+mapx impact UserService
+
+# 8. Check what changed since the last scan
+mapx status
+```
+
+All commands accept a target directory via a positional argument, `--dir`, or `-d`:
+
+```bash
+mapx scan /path/to/project
+mapx query "MyClass" --dir /path/to/project
+mapx -d /path/to/project export
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `mapx init [path]` | Initialise mapx; create `.mapx/`, `AGENTS.md`, auto-detect agent tools, generate MCP configs |
+| `mapx uninit [path]` | Remove mapx; delete `.mapx/`, reverse LLM integration changes, clean MCP configs |
+| `mapx scan [path]` | Full scan — builds the graph from scratch (supports `--force` to bypass cache) |
+| `mapx update [path]` | Incremental scan — only re-parses changed files |
+| `mapx status [path]` | Show graph metrics, language breakdown, PageRank rankings, git changes |
+| `mapx query <term>` | Search symbols by name (partial match) |
+| `mapx search <term>` | Advanced symbol search with `--kind`, `--file`, `--exact`, `--limit` filters |
+| `mapx deps <file>` | Show dependencies and reverse-dependencies |
+| `mapx trace <symbol>` | Trace data flow paths from a symbol |
+| `mapx callers <symbol>` | Show direct and nested callers |
+| `mapx callees <symbol>` | Show direct and nested callees |
+| `mapx impact <symbol>` | Change impact analysis — blast radius and risk scoring |
+| `mapx node <symbol>` | Inspect a symbol with metadata and optional `--source` |
+| `mapx files` | List and filter files with `--path`, `--lang`, `--sort`, `--limit` |
+| `mapx clusters` | List detected code clusters/modules |
+| `mapx export` | Export graph (default: LLM summary, 8K tokens) |
+| `mapx export --format=json` | Full graph as JSON |
+| `mapx export --format=dot` | GraphViz DOT (with `--cluster` and `--depth`) |
+| `mapx export --format=svg` | SVG visualisation |
+| `mapx export --format=toon` | TOON compact format (with `--delimiter`, `--key-folding`) |
+| `mapx export -o out.txt` | Write export to a file |
+| `mapx summary [path]` | One-line project summary |
+| `mapx lang list` | List supported languages and status |
+| `mapx lang install <name>` | Install an installable-tier language |
+| `mapx lang uninstall <name>` | Uninstall a language |
+| `mapx ui` | Open the web dashboard for interactive visualization |
+| `mapx workspaces list` | List registered repositories |
+| `mapx workspaces add <path>` | Register a new repository |
+| `mapx workspaces discover` | Discover unregistered submodules, peers, VS Code folders |
+| `mapx workspaces sync` | Auto-register discovered repositories |
+| `mapx agents mcp` | Auto-detect agent tools and generate MCP config files |
+| `mapx serve --dir <path>` | Start MCP server (stdio) |
+| `mapx serve --sse --port 3456` | Start MCP server (SSE/HTTP) |
+
+See [docs/cli-reference.md](docs/cli-reference.md) for full details on all flags.
+
+---
+
+## Token Consumption Benchmarks
+
+MapX significantly reduces LLM context window usage when performing agentic coding tasks. The built-in benchmark suite simulates typical AI workflows (understanding structure, tracing dependencies, multi-file edits) to compare baseline file reads versus MapX MCP tool calls.
+
+**Average Savings: 87% reduction in token usage.**
+
+| Scenario | Baseline (No MapX) | With MapX | Savings | Cost (Sonnet 3.5) |
+|----------|-------------------|-----------|---------|-------------------|
+| Understand structure | 28.4K tokens (15 tool calls) | 600 tokens (1 tool call) | **98%** | $0.0852 → $0.0018 |
+| Multi-file edit | 40.4K tokens (25 tool calls) | 7.2K tokens (9 tool calls) | **82%** | $0.1213 → $0.0215 |
+| Full session (15 tasks) | 194.4K tokens (123 calls) | 29.8K tokens (43 calls) | **85%** | $0.5832 → $0.0894 |
+
+Run the benchmark on your own codebase:
+```bash
+make bench DIR=/path/to/project
+```
+See [docs/benchmarking.md](docs/benchmarking.md) for full scenario breakdowns and methodology.
+
+---
+
+## MCP Integration
+
+Start the MCP server and paste the printed configuration into your tool:
+
+```bash
+mapx serve --dir /path/to/your/project
+```
+
+You can optionally append the `--debug` flag to log all incoming MCP tool calls, parameters, execution durations, and success/error status to `stderr` (allowing stdout to remain clean for transport protocols):
+
+```bash
+mapx serve --dir /path/to/your/project --debug
+```
+
+On startup mapx prints ready-to-copy configuration for Claude Desktop, Cursor, and VS Code.
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "mapx": {
+      "command": "mapx",
+      "args": ["serve", "--dir", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+### Cursor / VS Code (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "mapx": {
+      "command": "mapx",
+      "args": ["serve", "--dir", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+### Available MCP tools (25 total)
+
+| Category | Tools |
+|----------|-------|
+| **Graph Building** | `mapx_scan`, `mapx_sync` |
+| **Symbol Discovery** | `mapx_query`, `mapx_search`, `mapx_node`, `mapx_files` |
+| **Dependencies & Flow** | `mapx_dependencies`, `mapx_callers`, `mapx_callees`, `mapx_trace`, `mapx_sources`, `mapx_sinks` |
+| **Analysis** | `mapx_impact`, `mapx_clusters`, `mapx_status` |
+| **Export** | `mapx_export`, `mapx_context` |
+| **Workspaces** | `mapx_workspaces` |
+| **Language Management** | `mapx_lang_list`, `mapx_lang_install`, `mapx_lang_uninstall` |
+
+See [docs/mcp-integration.md](docs/mcp-integration.md) for full tool parameters and client setup.
+
+---
+
+## Programmatic Usage
+
+MapX can be imported programmatically as an ESM library in Node.js or TypeScript projects to execute scans, load code graphs, or build token-optimized LLM context:
+
+```typescript
+import { Config, Store, Scanner, MapxGraph, ContextBuilder } from '@mgamil/mapx';
+
+const dir = '/path/to/project';
+const config = await Config.load(dir);
+const store = new Store(`${dir}/.mapx/mapx.db`);
+
+// 1. Run incremental scan
+const scanner = new Scanner(dir, store);
+await scanner.scanIncremental();
+
+// 2. Query code metrics
+console.log(`Scanned ${store.getFileCount()} files and ${store.getSymbolCount()} symbols.`);
+
+// 3. Close database connection
+store.close();
+```
+
+See [docs/getting-started.md](docs/getting-started.md#programmatic-usage) for a detailed programmatic API example.
+
+---
+
+## Supported Languages
+
+### Built-in (Tier 1) — Always available
+
+| Language | Extensions | Key Symbols |
+|----------|-----------|-------------|
+| PHP | `.php`, `.phtml` | classes, methods, functions, interfaces, traits, enums, constants, properties, namespaces |
+| JavaScript | `.js`, `.mjs`, `.cjs` | classes, methods, functions, interfaces, enums, properties |
+| TypeScript | `.ts`, `.cts`, `.mts` | classes, methods, functions, interfaces, enums, properties, namespaces |
+| Python | `.py` | classes, functions, constants |
+| Go | `.go` | structs, interfaces, functions, methods, constants, packages |
+| Rust | `.rs` | structs, traits, enums, functions, impl blocks, constants, modules, macros |
+| Java | `.java` | classes, interfaces, enums, methods, fields, constants, packages |
+| C# | `.cs` | classes, interfaces, enums, structs, methods, properties, namespaces, records |
+
+### Bundled (Tier 2) — Ships with the tool
+
+| Language | Extensions | Key Symbols |
+|----------|-----------|-------------|
+| Ruby | `.rb` | classes, modules, methods, constants, properties |
+| C | `.c`, `.h` | structs, functions, enums, typedefs, macros |
+| C++ | `.cpp`, `.hpp`, `.cc` | classes, structs, functions, namespaces, enums, templates |
+| Swift | `.swift` | classes, structs, protocols, enums, functions, properties |
+| Kotlin | `.kt`, `.kts` | classes, objects, functions, interfaces, properties |
+| Scala | `.scala`, `.sc` | classes, objects, traits, functions, vals |
+| Vue | `.vue` | functions, classes, methods, properties (supports `@/` alias resolution) |
+
+### Installable (Tier 3) — `mapx lang install <name>`
+
+| Language | Extensions | Key Symbols |
+|----------|-----------|-------------|
+| Svelte | `.svelte` | functions, classes, methods, props, constants |
+| Lua | `.lua` | functions, methods, variables |
+| Elixir | `.ex`, `.exs` | modules, functions, macros, structs, protocols |
+| Zig | `.zig` | functions, structs, constants, tests |
+| Bash | `.sh`, `.bash` | functions, variables, aliases |
+| Pascal | `.pas`, `.pp` | classes, records, interfaces, methods, functions, constants, units |
+| Dart | `.dart` | classes, functions, enums, mixins, extensions |
+
+All languages track **imports**, **inheritance/implementation**, **instantiation**, and **calls** where applicable. See [docs/adding-languages.md](docs/adding-languages.md) to add your own.
+
+---
+
+## Agentic Integration
+
+`mapx init` creates (or updates) an `AGENTS.md` file in your project root. This file documents the mapx CLI and MCP tools so LLM coding agents can discover and use them automatically.
+
+During initialization, mapx also **auto-detects installed agent tools** and generates MCP server config files:
+
+| Agent Tool | Config File | Auto-Detection |
+|------------|-------------|----------------|
+| opencode | `opencode.json` | `opencode.json` or `opencode.jsonc` exists |
+| Gemini CLI | `.gemini/settings.json` | `.gemini/` directory exists |
+| Cursor | `.cursor/mcp.json` | `.cursor/` directory exists |
+| VS Code | `.vscode/mcp.json` | `.vscode/` directory exists |
+| Antigravity | `.agents/mcp.json` | `.agents/` directory exists |
+
+This means running `mapx init` in a project that uses Cursor and Gemini CLI will auto-register mapx as an MCP server in both tools — no manual config editing needed.
+
+You can also run `mapx agents mcp --detect` to see which tools are available, or `mapx agents mcp --all` to generate configs for all supported tools.
+
+The AGENTS.md content is wrapped in markers and can safely coexist with existing AGENTS.md content:
+
+```markdown
+<!-- mapx -->
+...mapx documentation for LLMs...
+<!-- /mapx -->
+```
+
+---
+
+## Storage
+
+mapx stores everything locally inside your project:
+
+```
+.mapx/
+├── config.json    # Repo configuration and language settings
+├── mapx.db        # SQLite database — symbols, edges, scan cache
+└── scan.lock      # Present only while a scan is running
+```
+
+`.mapx/` is automatically added to `.gitignore` during `mapx init`.
+
+---
+
+## Architecture
+
+<!-- ![Architecture Diagram](./docs/images/01-arch.png) -->
+
+```mermaid
+graph TD
+    classDef interface fill:#e1f5fe,stroke:#01579b,stroke-width:2px;
+    classDef core fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
+    classDef storage fill:#fff3e0,stroke:#e65100,stroke-width:2px;
+    classDef engine fill:#f3e5f5,stroke:#4a148c,stroke-width:2px;
+
+    CLI["CLI Interface<br>(cli.ts)"]:::interface
+    MCP["MCP Server<br>(mcp.ts)"]:::interface
+    UI["Web Dashboard<br>(ui-server.ts)"]:::interface
+
+    Scanner["Scanner<br>(scanner.ts)"]:::core
+    GitTracker["Git Tracker<br>(git-tracker.ts)"]:::core
+    Workspace["Workspace Manager<br>(workspace-manager.ts)"]:::core
+
+    Registry["Language Registry<br>(registry.ts)"]:::core
+    Parsers["Parsers<br>(parsers/)"]:::core
+
+    Store["Store Interface<br>(store.ts)"]:::storage
+    SQLite[("SQLite DB<br>(mapx.db)")]:::storage
+    Graphology["In-Memory Graph<br>(graphology)"]:::storage
+
+    Exporters["Exporters<br>(exporters/)"]:::engine
+    FlowTracer["Flow Tracer<br>(flow-tracer.ts)"]:::engine
+    Context["Context Builder<br>(context-builder.ts)"]:::engine
+
+    CLI --> Scanner
+    MCP --> Scanner
+    UI --> Store
+
+    Scanner --> GitTracker
+    Scanner --> Registry
+    Registry --> Parsers
+
+    Scanner --> Store
+    Workspace --> Store
+
+    Store --> SQLite
+    Store --> Graphology
+
+    Store --> Exporters
+    Store --> FlowTracer
+    Store --> Context
+
+    FlowTracer --> CLI
+    FlowTracer --> MCP
+    Context --> MCP
+    Exporters --> CLI
+    Exporters --> MCP
+```
+
+See [docs/architecture.md](docs/architecture.md) for a detailed breakdown of each component.
+
+---
+
+## Documentation
+
+| Doc | Description |
+|-----|-------------|
+| [Getting Started](docs/getting-started.md) | Installation, quick start, supported languages |
+| [CLI Reference](docs/cli-reference.md) | All 31 commands and their flags |
+| [MCP Integration](docs/mcp-integration.md) | MCP server setup and all 25 tools |
+| [Configuration](docs/configuration.md) | Config file, workspace setup, settings |
+| [Benchmarking](docs/benchmarking.md) | Token cost analysis vs baseline LLM usage |
+| [Adding Languages](docs/adding-languages.md) | Extend mapx with new tree-sitter grammars |
+| [Framework Integration](docs/framework-integration.md) | Heuristics and routing/hook extraction for 21 frameworks |
+| [Agent Best Practices](docs/agent-best-practices.md) | Prompting guidelines and tool selection cheat sheet for LLM agents |
+| [Architecture](docs/architecture.md) | Internals and component overview |
+
+---
+
+## Development
+
+### npm script shortcuts
+
+All CLI commands are available as npm scripts for development:
+
+```bash
+npm run scan                    # Full scan
+npm run update                  # Incremental scan
+npm run status                  # Show status
+npm run export                  # LLM summary
+npm run export:svg              # SVG export
+npm run query -- UserService    # Symbol search
+npm run search -- User --kind class  # Advanced search
+npm run callers -- handleRequest     # Trace callers
+npm run impact -- UserService        # Change impact
+npm run ui                      # Web dashboard
+npm run serve                   # MCP server (stdio)
+npm run serve:sse               # MCP server (SSE)
+```
+
+### Makefile shortcuts
+
+```bash
+make help                       # Show all targets
+make scan DIR=/path             # Full scan
+make search q=User k=class     # Advanced search
+make callers s=handleRequest   # Trace callers
+make impact s=UserService d=3  # Impact with depth
+make node s=UserService src=1  # Inspect with source
+make export-toon DIR=/path     # TOON export
+make serve-sse PORT=3456       # SSE server
+make ui PORT=8080              # Web dashboard
+```
+
+### Building binaries
+
+Requires [Bun](https://bun.sh/) for binary compilation.
+
+```bash
+# Build for all platforms
+make build-all
+
+# Build for a single platform
+make build-linux
+make build-mac-arm
+make build-win
+
+# Package into distributable archives + self-extracting installers
+make package-all
+
+# Install locally (no sudo)
+make install-local
+```
+
+---
+
+## Publishing to npm
+
+To publish new releases of the npm package:
+
+1. Create a tag matching the version in `package.json` and push it:
+   ```bash
+   git tag v0.1.7
+   git push origin v0.1.7
+   ```
+2. The GitHub Actions publish workflow will automatically run, verify version synchronization, build WASM grammars, compile the TypeScript code using `tsup`, and publish to the npm registry with provenance.
+3. **Important**: The workflow requires a repository secret named `NPM_TOKEN`. This token must be generated on `npmjs.com` as an **Automation** access token.
+
+---
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

package/VERSION

@@ -0,0 +1 @@
+0.2.4