@tyroneross/navgator 0.2.2 → 0.9.0

package/README.md

@@ -1,10 +1,10 @@
 # NavGator
 
-**Architecture Connection Tracker for Claude Code**
+**Architecture Connection Tracker for Claude Code and Codex**
 
 > Know your stack before you change it
 
-NavGator tracks architecture connections across your entire stack—packages, services, databases, queues, and infrastructure—so Claude knows what else needs to change when you modify one part of the system.
+NavGator tracks architecture connections across your entire stack—packages, services, databases, queues, and infrastructure—so your coding agent knows what else needs to change when you modify one part of the system.
 
 ## Features
 
@@ -13,7 +13,8 @@ NavGator tracks architecture connections across your entire stack—packages, se
 - **Impact Analysis**: "What's affected if I change X?"
 - **Change Detection**: SHA-256 file hashing tracks what changed since last scan
 - **Mermaid Diagrams**: Visual architecture diagrams
-- **Claude Code Integration**: Hooks, skills, and slash commands
+- **Claude Code Integration**: Hooks, skills, agents, and slash commands
+- **Codex Integration**: Skills, MCP tools, and native marketplace metadata
 
 ## Installation
 
@@ -29,7 +30,7 @@ npx @tyroneross/navgator scan
 
 ### As a Claude Code Plugin
 
-After installing globally, use the `/gator:install` command inside Claude Code, or run the install script:
+Install the Claude surface directly from this repo:
 
 ```bash
 # Install for all projects (user scope)
@@ -42,10 +43,29 @@ bash scripts/install-plugin.sh --project
 Or link manually:
 
 ```bash
-ln -s $(npm root -g)/@tyroneross/navgator ~/.claude/plugins/gator
+ln -s $(npm root -g)/@tyroneross/navgator ~/.claude/plugins/navgator
 ```
 
-Restart Claude Code after installing. All `/gator:*` commands will be available.
+Restart Claude Code after installing. All `/navgator:*` commands will be available.
+
+### As a Codex Plugin
+
+Install the Codex surface directly from this repo:
+
+```bash
+# Install for your Codex user account
+bash scripts/install-codex-plugin.sh --user
+
+# Or refresh repo-local workspace metadata only
+bash scripts/install-codex-plugin.sh --workspace
+```
+
+This repo now includes native Codex metadata in:
+
+- `.codex-plugin/plugin.json`
+- `.agents/plugins/marketplace.json`
+
+Claude remains the authoritative host for slash commands and agent wiring. Hooks are disabled by default. Codex uses the additive plugin surface for skills and MCP tools.
 
 ## Quick Start
 
@@ -55,7 +75,7 @@ Restart Claude Code after installing. All `/gator:*` commands will be available.
 navgator setup
 ```
 
-This runs the initial scan and offers to link NavGator as a Claude Code plugin (if Claude Code is installed).
+This runs the initial scan and then you can install the Claude or Codex surface explicitly from the scripts above.
 
 ### 2. Scan Your Project
 
@@ -68,6 +88,9 @@ navgator scan --quick
 
 # With AI prompt detection
 navgator scan --prompts --verbose
+
+# With infrastructure analysis
+navgator scan --field-usage --typespec
 ```
 
 ### 3. Check Status
@@ -95,6 +118,12 @@ CONNECTIONS BY TYPE:
   service-call: 12
   api-calls-db: 8
   frontend-calls-api: 3
+
+INFRASTRUCTURE:
+  DB models: 12
+  Env vars: 34
+  Queues: 3
+  Cron jobs: 2
 ```
 
 ### 4. Analyze Impact
@@ -171,32 +200,28 @@ navgator diagram --output architecture.md --markdown
 
 ## Claude Code Slash Commands
 
-When installed as a Claude Code plugin, all commands are available as `/gator:*` slash commands:
+When installed as a Claude Code plugin, all commands are available as `/navgator:*` slash commands:
 
 | Command | Description |
 |---------|-------------|
-| `/gator:scan` | Scan project architecture |
-| `/gator:status` | Show architecture summary |
-| `/gator:impact <component>` | Analyze what's affected by a change |
-| `/gator:connections <component>` | Show all connections for a component |
-| `/gator:diagram` | Generate architecture diagram |
-| `/gator:export` | Export architecture to markdown or JSON |
-| `/gator:check` | Run health checks (outdated packages, vulnerabilities) |
-| `/gator:ui` | Launch the web dashboard |
-| `/gator:update` | Update NavGator to the latest version |
-| `/gator:install` | Install/reinstall the plugin (choose scope) |
+| `/navgator:map` | Map full architecture — components, connections, runtime topology, and LLM use cases |
+| `/navgator:plan "<intent>"` | Plan an architecture change or investigation. Delegates to the `architecture-planner` agent, which checks graph freshness, runs an incremental scan if stale, then dispatches the right read-only NavGator tools and aggregates findings |
+| `/navgator:scan` | Quick scan — refresh tracking data |
+| `/navgator:trace <component>` | Trace data flow through the system |
+| `/navgator:impact <component>` | Analyze what's affected by a change |
+| `/navgator:test [instructions]` | Run an end-to-end architecture test |
+| `/navgator:review` | Architectural integrity review (connections, flow, drift, lessons) |
+| `/navgator:review --all` | Review entire architecture, not just changes |
+| `/navgator:review --validate` | Validate lessons against current docs (internet research) |
+| `/navgator:review learn "..."` | Record a manual architectural lesson |
+| `/navgator:llm-map` | Map LLM use cases by purpose and provider |
+| `/navgator:schema [model]` | Show database readers and writers |
+| `/navgator:dead` | Find orphaned components and dead code |
+| `/navgator:lessons` | Manage project and global architecture lessons |
 
 ### Hooks
 
-NavGator includes hooks that integrate with Claude Code:
-
-**SessionStart**: Checks if architecture data is stale (>24h) and suggests running `/gator:scan`.
-
-**PreToolUse (Edit/Write)**: Before modifying architecture-critical files, reminds to check impact with `/gator:impact`.
-
-**PostToolUse (Bash)**: Detects package manager commands (`npm install`, `pip install`, etc.) and reminds to update architecture with `/gator:scan`.
-
-**Stop**: After significant changes, reminds to rescan.
+NavGator does not enable automatic Claude Code hooks by default. Run `/navgator:scan` or the MCP scan tool explicitly when architecture data needs to be refreshed.
 
 ## CLI Reference
 
@@ -210,8 +235,78 @@ Scan project and update architecture tracking.
 | `-c, --connections` | Focus on connection detection |
 | `-p, --prompts` | Enhanced AI prompt scanning with full content |
 | `-v, --verbose` | Detailed output |
-| `--clear` | Clear existing data before scan |
+| `--auto` | Auto-pick scan mode (default — see Scan modes below) |
+| `--full` | Force a full scan (clear all and rebuild) |
+| `--incremental` | Force an incremental scan (walk only changed files + reverse-deps) |
+| `--clear` | Alias for `--full` (legacy) |
 | `--ast` | Use AST-based scanning (requires `ts-morph`) |
+| `--field-usage` | Analyze Prisma model field usage across codebase |
+| `--typespec` | Validate Prisma types against TypeScript interfaces |
+| `--track-branch` | Capture git branch/commit in scan output |
+| `--json` | Output scan results as JSON |
+| `--agent` | Wrap output in agent envelope (implies `--json`) |
+
+#### Scan modes
+
+NavGator supports three scan modes. By default (`--auto`), the scanner picks one based on what changed since the last scan and how stale the cached graph is.
+
+| Mode | When it runs | Behavior |
+|------|--------------|----------|
+| `full` | first scan, or any of: `--full`/`--clear`, manifest or build-config changed (e.g. `package.json`, `prisma/schema.prisma`, `tsconfig.json`, `vercel.json`, `fly.toml`, `railway.json`, `.gitignore`), a new source file was added, `last_full_scan > 7 days ago`, or `incrementals_since_full ≥ 20` | Clears `.navgator/architecture/` and rebuilds the entire graph |
+| `incremental` | a code file changed and none of the full-scan triggers fire | Walks only changed files plus their reverse-dependencies, merges results into the existing graph by stable_id, runs an integrity check |
+| `noop` | nothing changed since the last scan | Updates `last_scan`, writes a `noop` timeline entry, leaves the graph untouched |
+
+If an incremental scan fails its integrity check, NavGator automatically promotes it to a full scan and records `scan_type: 'incremental→full'` in the timeline. Atomic file writes ensure that a crashed scan leaves the prior `.navgator/architecture/` intact.
+
+The mode used for any given scan appears in `.navgator/architecture/timeline.json` under `scan_type`.
+
+#### Audit (Run 2 — SQC self-measurement)
+
+After every scan, NavGator runs a statistical-quality-control audit on its own output. The audit samples a fraction of the just-stored components and connections, runs five deterministic verifiers, optionally requests an LLM-judge spot-check, and tracks defect-rate drift across runs via an EWMA control chart. **Audit failures never fail the scan** — they only update per-stratum EWMA state. The next scan auto-promotes to a tighter inspection if any stratum breaches its control limits.
+
+| Plan | When picked | What it does |
+|------|-------------|--------------|
+| `AQL` (default) | first three audits, or via `--audit-plan=aql` | MIL-STD-105E single-sampling table at AQL=2.5%. Sample size scales with population (e.g. n=80 c=5 for ~1k facts). |
+| `SPRT` | history ≥ 3 audits | Wald 1945 sequential probability ratio test with α=β=0.05, p₀=1%, p₁=5%. Continues sampling until logLR escapes the bounds A=19 / B=0.0526. |
+| `Cochran` | prior run breached EWMA, or `--audit-plan=cochran` | Cochran's formula with FPC at 95% CI, ±5% margin. Tightest inspection. |
+
+Six defect classes:
+
+| Class | Verifier | LLM? |
+|-------|----------|------|
+| HALLUCINATED_COMPONENT | filesystem + symbol existence on `source.config_files` | no |
+| HALLUCINATED_EDGE | both endpoint component_ids resolve in graph | no |
+| WRONG_ENDPOINT | grep target name/symbol in connection's source file | no |
+| STALE_REFERENCE | re-hash file vs `hashes.json` | no |
+| DEDUP_COLLISION | scan all components for duplicate `(type, name, primary-config)` triples (regression check on Run 1.7 fix) | no |
+| MISSED_EDGE | "list all outgoing edges, set-diff against graph" — emits a structured payload an MCP-side LLM judge can consume | yes (CLI-mode skips) |
+
+In CLI mode the LLM-judge verifier is skipped and `audit.llm_skipped: true` is set. In MCP mode the audit emits a structured payload (`audit.defect_evidence` carries up to 20 sample failures) for the running model.
+
+Per-stratum strata: `package`, `infra`, `connection-imports`, `connection-services`, `connection-llm`, `connection-prisma`, `__other`. Stratified sample selection uses Neyman optimal allocation (more samples → higher-variance strata).
+
+EWMA control chart (Hawkins-Wu defaults λ=0.2, L=2.7) tracks defect-rate drift per stratum across runs. On breach, `pending_drift_breach` is set on the index, and the next `--auto` scan promotes to `mode='full' + audit-plan='cochran'`.
+
+Flags:
+
+| Flag | Purpose |
+|------|---------|
+| `--no-audit` | Skip the audit pass entirely |
+| `--audit-plan <plan>` | Override plan auto-pick: `aql` \| `sprt` \| `cochran` |
+
+Audit output appears on the timeline entry under `audit`:
+
+```json
+{
+  "plan": "AQL",
+  "n": 80, "c": 5, "sampled": 156, "defects": 0,
+  "defect_rate": 0,
+  "by_class": { "HALLUCINATED_COMPONENT": { "sampled": 40, "defects": 0 }, ... },
+  "by_stratum": { "package": { "sampled": 18, "defects": 0, "defect_rate": 0 }, ... },
+  "verdict": "accept",
+  "llm_skipped": true
+}
+```
 
 ### `navgator status`
 
@@ -275,6 +370,53 @@ Scan and analyze AI prompts in the codebase.
 | `--json` | Output as JSON |
 | `--detail <name>` | Show detailed view of specific prompt |
 
+### `navgator coverage`
+
+Analyze database field usage and type alignment.
+
+```bash
+# Field usage analysis (requires Prisma schema)
+navgator coverage --fields
+
+# TypeSpec validation (Prisma vs TypeScript types)
+navgator coverage --typespec
+```
+
+| Option | Description |
+|--------|-------------|
+| `--fields` | Report unused, read-only, and write-only Prisma model fields |
+| `--typespec` | Compare Prisma model types against TypeScript interface definitions |
+| `--json` | Output as JSON |
+
+### `navgator trace <component>`
+
+Trace dataflow paths forward and backward through the system.
+
+| Option | Description |
+|--------|-------------|
+| `--direction <dir>` | forward, backward, or both (default: both) |
+| `--depth <n>` | Max trace depth (default: 5) |
+| `--json` | Output as JSON |
+
+### `navgator rules`
+
+Check architecture rules and report violations.
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON |
+
+Built-in rules: orphan components, database isolation, frontend-direct-db, circular dependencies, hotspot modules, high fan-out, layer violations.
+
+### `navgator subgraph <component>`
+
+Extract a focused subgraph around a specific component.
+
+| Option | Description |
+|--------|-------------|
+| `--depth <n>` | Include connections up to N hops away (default: 2) |
+| `--json` | Output as JSON |
+
 ## What Gets Detected
 
 ### Components
@@ -299,15 +441,35 @@ Scan and analyze AI prompts in the codebase.
 | `queue-triggers` | Queue job → Handler function |
 | `prompt-location` | AI prompt definition location |
 | `prompt-usage` | Code that uses an AI prompt |
+| `env-dependency` | Component → environment variable it depends on |
+| `schema-relation` | Database model → related model (FK/relation) |
+| `cron-triggers` | Cron job → API route handler |
+| `queue-produces` | Producer → queue |
+| `queue-consumes` | Queue → consumer worker |
+| `field-reference` | Database model field → file that references it |
+| `runtime-binding` | Component → its runtime service/resource |
+| `queue-uses-cache` | Queue system → Redis/cache instance |
+
+### Runtime Topology
+
+NavGator annotates architecture components with runtime identity information extracted from code and config:
+
+- **Database connections**: Parses `DATABASE_URL` and Prisma `datasource` to identify database engine (postgres, mysql, etc.), host, and port
+- **Redis/cache connections**: Extracts Redis URLs from BullMQ queue configurations and env vars
+- **Queue identity**: Maps queue names to their Redis backing store and producer/consumer relationships
+- **Deploy services**: Extracts service names from Railway, Vercel, Heroku (Procfile), and Nixpacks configs
+- **Cron handlers**: Links scheduled jobs to their handler functions and deployment platform
+
+Use `navgator status` to see the RUNTIME TOPOLOGY section showing all detected runtime bindings.
 
 ## Storage
 
-Data is stored in `.claude/architecture/` within your project:
+Data is stored in `.navgator/architecture/` within your project:
 
 ```
-.claude/architecture/
-├── SUMMARY.md           ← Hot context (read first)
-├── SUMMARY_FULL.md      ← Full version if compressed
+.navgator/architecture/
+├── NAVSUMMARY.md           ← Hot context (read first)
+├── NAVSUMMARY_FULL.md      ← Full version if compressed
 ├── components/           # Individual component JSON files
 │   ├── COMP_npm_react_a1b2.json
 │   └── COMP_service_stripe_c3d4.json
@@ -376,7 +538,7 @@ Without `ts-morph`, NavGator uses regex-based scanning which is faster but may m
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `NAVGATOR_MODE` | Storage mode: `local` or `shared` | `local` |
-| `NAVGATOR_PATH` | Custom storage path | `.claude/architecture` |
+| `NAVGATOR_PATH` | Custom storage path | `.navgator/architecture` |
 | `NAVGATOR_AUTO_SCAN` | Auto-scan on session start | `false` |
 | `NAVGATOR_HEALTH_CHECK` | Enable health checks | `false` |
 | `NAVGATOR_SCAN_DEPTH` | `shallow` or `deep` | `shallow` |
@@ -459,3 +621,28 @@ Contributions welcome! Please read the contributing guidelines first.
 - [GitHub Repository](https://github.com/tyroneross/navgator)
 - [Issue Tracker](https://github.com/tyroneross/navgator/issues)
 - [Claude Code](https://claude.ai/claude-code)
+
+## Codex
+
+This package now ships an additive Codex plugin surface alongside the existing Claude Code package. Claude remains the authoritative runtime for slash commands and agents. Hooks are disabled by default. Codex support is explicit and parallel rather than inferred from the Claude surface.
+
+Package root for Codex installs:
+- the repository root (`.`)
+
+Primary Codex surface:
+- manifest: `./.codex-plugin/plugin.json`
+- workspace marketplace metadata: `./.agents/plugins/marketplace.json`
+- skills from `./skills`
+- MCP config from `./.mcp.json`
+
+Recommended Codex flows:
+
+```bash
+# user-wide install
+bash scripts/install-codex-plugin.sh --user
+
+# repo-local workspace metadata
+bash scripts/install-codex-plugin.sh --workspace
+```
+
+The Codex package is additive only: Claude-specific slash commands and agent wiring remain unchanged for Claude Code.

package/agents/architecture-advisor.md

@@ -42,12 +42,12 @@ When advising on architecture:
 
 1. First, check if NavGator has scanned the project:
    ```bash
-   ls -la .claude/architecture/
+   ls -la .navgator/architecture/
    ```
 
 2. If scanned, read the index for quick overview:
    ```bash
-   cat .claude/architecture/index.json
+   cat .navgator/architecture/index.json
    ```
 
 3. For specific impact analysis:
@@ -60,6 +60,10 @@ When advising on architecture:
    npx @tyroneross/navgator connections "<component>"
    ```
 
+5. When Prisma is detected, suggest running `navgator coverage --fields` to identify unused database fields.
+
+6. When TypeScript interfaces mirror Prisma models, suggest `navgator coverage --typespec` to validate type alignment.
+
 ## Response Format
 
 When advising on changes:

package/agents/architecture-investigator.md

@@ -0,0 +1,163 @@
+---
+name: architecture-investigator
+description: Autonomous subagent for investigating architecture issues using NavGator MCP tools. Follows SRE-style read-only investigation before proposing changes. Deploy via the Task tool when a specific component, violation, or data-flow issue needs deep analysis.
+color: "#F59E0B"
+tools: ["Bash", "Read", "Glob", "Grep"]
+---
+
+# Architecture Investigator Agent
+
+You are an autonomous architecture investigator. Your role is to investigate architecture issues, violations, and anomalies using NavGator's analysis tools. You investigate first (read-only), then propose — you never modify files during investigation.
+
+## Investigation Methodology
+
+Follow these five phases in order. Do not skip phases.
+
+### Phase 1 — Architectural Overview
+
+Get the current state of the architecture before touching anything specific.
+
+```bash
+navgator status --agent
+```
+
+Read the output to understand:
+- Total components and connections
+- Layer distribution (frontend, backend, database, queue, infra, external)
+- Any flagged issues in the status summary
+- LLM use cases if relevant
+
+If the project hasn't been scanned recently, note this as a staleness risk.
+
+### Phase 2 — Identify the Affected Area
+
+Use `review` to get a high-level integrity assessment, then `explore` to drill into the specific component.
+
+```bash
+navgator review --agent
+```
+
+For a specific component under investigation:
+```bash
+navgator explore "<component-name>" --agent
+```
+
+`explore` returns the component's type, layer, connections, metadata, and associated files. Record:
+- Component ID and layer
+- File path(s) and line numbers
+- Inbound and outbound connection count
+- Any anomalies in metadata
+
+### Phase 3 — Trace Data Flow
+
+Follow connections forward and backward to understand the blast radius.
+
+```bash
+navgator trace "<component-name>" --agent
+```
+
+Document:
+- Full forward path (what this component feeds into)
+- Full backward path (what feeds into this component)
+- Depth of the longest path
+- Any circular or unexpected paths
+
+### Phase 4 — Check Rules
+
+Run the rules checker to identify structural violations.
+
+```bash
+navgator rules --agent
+```
+
+Flag any violations relevant to the investigated component:
+- Orphaned components (no connections)
+- Layer violations (e.g., frontend calling database directly)
+- Circular dependencies
+- Hotspot components (too many connections)
+
+### Phase 5 — Synthesize and Propose
+
+After completing phases 1–4, produce a structured findings report.
+
+## Output Format
+
+Always structure your response as:
+
+### Investigation Summary
+- **Target:** `<component or issue investigated>`
+- **Scan freshness:** `<timestamp from status or "unknown">`
+- **Components reviewed:** `<count>`
+
+### Findings
+
+For each finding:
+- **Severity:** Critical / Warning / Info
+- **Location:** `<file>:<line>` (from explore output)
+- **Finding:** What was observed
+- **Evidence:** The specific tool output that supports this
+
+### Data Flow Analysis
+Describe the trace results in plain language. Include the critical path if relevant.
+
+### Rule Violations
+List each violation with component name, rule type, and file location.
+
+### Proposed Actions
+Ordered list of concrete changes, each with:
+1. Action description
+2. Files affected (`file:line`)
+3. Justification (which finding drives this)
+4. Risk level (Low / Medium / High)
+
+### What Was NOT Changed
+Explicit list of what you investigated but left untouched, and why.
+
+## Operational Constraints
+
+- **Read-only during investigation.** Do not edit any project files in phases 1–4.
+- **Cite tool output.** Every finding must reference the specific command and output field that supports it.
+- **Scope discipline.** If investigation reveals adjacent issues outside the original scope, note them in a separate "Out of Scope Observations" section — do not expand the investigation.
+- **Staleness flag.** If `.navgator/architecture/` does not exist or `index.json` is missing, prepend all findings with: `WARNING: Architecture data not found. Run navgator scan first. Findings below are based on raw file inspection.`
+
+## Example Investigation
+
+**Task:** "Investigate why the email-queue component has no consumers"
+
+**Phase 1 — Overview:**
+```bash
+navgator status --agent
+# → 42 components, 3 queues detected, 1 warning flagged
+```
+
+**Phase 2 — Explore component:**
+```bash
+navgator explore "email-queue" --agent
+# → type: queue, layer: queue, 1 inbound (UserService), 0 outbound
+```
+
+**Phase 3 — Trace:**
+```bash
+navgator trace "email-queue" --agent
+# → Forward: no paths. Backward: UserService → email-queue
+```
+
+**Phase 4 — Rules:**
+```bash
+navgator rules --agent
+# → email-queue flagged as orphan (no consumers)
+```
+
+**Phase 5 — Findings:**
+
+### Findings
+- **Severity:** Warning
+- **Location:** `src/workers/email.ts` (no Worker instantiation found)
+- **Finding:** `email-queue` has a producer (UserService) but no registered consumer
+- **Evidence:** `explore` shows 0 outbound connections; `rules` flags as orphan
+
+### Proposed Actions
+1. Create `src/workers/email-worker.ts` with a BullMQ `Worker` consuming `email-queue`
+   - Files: `src/workers/email-worker.ts` (new file)
+   - Justification: Rules violation — orphaned queue with active producer
+   - Risk: Low