@tyroneross/navgator 0.2.0 → 0.2.2

package/.claude-plugin/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "name": "navgator",
+  "owner": { "name": "Tyrone Ross", "url": "https://github.com/tyroneross" },
+  "metadata": {
+    "description": "Architecture connection tracker — know your stack before you change it",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "gator",
+      "source": "./",
+      "description": "Architecture connection tracker for Claude Code — know your stack before you change it",
+      "version": "0.2.2",
+      "author": { "name": "Tyrone Ross" },
+      "homepage": "https://github.com/tyroneross/navgator#readme",
+      "repository": "https://github.com/tyroneross/navgator",
+      "license": "MIT",
+      "keywords": ["architecture", "connections", "dependencies", "impact-analysis"],
+      "category": "development",
+      "tags": ["architecture", "dependency-tracking", "impact-analysis"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -1,10 +1,13 @@
 {
-  "name": "navgator",
-  "version": "0.1.0",
-  "description": "Architecture connection tracker - know your stack before you change it",
-  "author": {
-    "name": "Tyrone Ross"
-  },
+  "name": "gator",
+  "version": "0.2.2",
+  "description": "Architecture connection tracker — know your stack before you change it",
+  "author": { "name": "Tyrone Ross" },
   "homepage": "https://github.com/tyroneross/navgator",
-  "license": "MIT"
+  "repository": "https://github.com/tyroneross/navgator",
+  "license": "MIT",
+  "keywords": ["architecture", "connections", "context", "dependencies", "impact-analysis"],
+  "hooks": "../hooks/hooks.json",
+  "skills": "../skills/",
+  "agents": "../agents/"
 }

package/CLAUDE.md

@@ -0,0 +1,72 @@
+# NavGator — Architecture Context for Claude
+
+## What NavGator Does
+
+NavGator externalizes architecture knowledge so you never lose track of file paths, dependencies, model routing, or component connections between sessions.
+
+## Context Model (Three Tiers)
+
+**Tier 1 — Hot Context** (`SUMMARY.md`)
+Read this first. It's a concise overview (~40-150 lines) with:
+- Components by layer (frontend, backend, database, queue, infra, external)
+- AI/LLM routing table (provider, file, line, purpose)
+- Top connections with `file:line` references
+- Delta from last scan (what changed)
+- Pointers to detail files for drill-down
+
+If `SUMMARY.md` was compressed (large projects), the full version is at `SUMMARY_FULL.md`.
+
+**Tier 2 — Structured Index** (`index.json`, `graph.json`, `file_map.json`, `prompts.json`)
+Use for programmatic lookups:
+- `index.json` — component counts, types, layers, stats
+- `graph.json` — full connection graph for impact analysis
+- `file_map.json` — maps file paths to component IDs (O(1) lookup)
+- `prompts.json` — full prompt content with LLM provider associations (scan with `--prompts`)
+
+**Tier 3 — Detail Files** (`components/COMP_*.json`, `connections/CONN_*.json`)
+Load on demand when you need full detail about a specific component or connection. Each entry in SUMMARY.md points to its detail file.
+
+## When to Read Architecture Context
+
+**Always read `SUMMARY.md` at the start of a session.** It's located at:
+```
+<project-root>/.claude/architecture/SUMMARY.md
+```
+
+**Before editing tracked files:** If you're about to edit a file that belongs to a tracked component, read the component's detail file first. The architecture-check hook will remind you.
+
+**After dependency changes:** If you ran `npm install`, `pip install`, etc., architecture data may be stale. Run `/gator:scan` to update.
+
+## Available Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/gator:scan` | Scan project architecture |
+| `/gator:status` | Show architecture summary |
+| `/gator:impact` | Analyze what's affected by a change |
+| `/gator:connections` | Show all connections for a component |
+| `/gator:diagram` | Generate visual 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 |
+
+## Architecture Data Location
+
+All data lives in `<project-root>/.claude/architecture/`:
+```
+.claude/architecture/
+├── SUMMARY.md          ← Read this first (hot context)
+├── SUMMARY_FULL.md     ← Full version if compressed
+├── index.json          ← Master index
+├── graph.json          ← Connection graph
+├── file_map.json       ← File path → component ID lookup
+├── prompts.json        ← Full prompt content + LLM associations
+├── hashes.json         ← File change detection
+├── components/         ← One JSON per component
+└── connections/        ← One JSON per connection
+```
+
+## Key Principle
+
+Instead of trying to "remember" architecture details, reload the externalized source of truth. SUMMARY.md is cheap to read and gives you the full picture. Drill into detail files only when needed.

package/README.md

@@ -29,12 +29,24 @@ npx @tyroneross/navgator scan
 
 ### As a Claude Code Plugin
 
-After installing, run `navgator setup` — it will detect Claude Code and offer to link the plugin automatically. You can also link manually:
+After installing globally, use the `/gator:install` command inside Claude Code, or run the install script:
 
 ```bash
-ln -s /path/to/navgator ~/.claude/plugins/navgator
+# Install for all projects (user scope)
+bash scripts/install-plugin.sh --global
+
+# Install for current project only
+bash scripts/install-plugin.sh --project
+```
+
+Or link manually:
+
+```bash
+ln -s $(npm root -g)/@tyroneross/navgator ~/.claude/plugins/gator
 ```
 
+Restart Claude Code after installing. All `/gator:*` commands will be available.
+
 ## Quick Start
 
 ### 1. Set Up NavGator
@@ -54,8 +66,8 @@ navgator scan
 # Quick scan (packages only, faster)
 navgator scan --quick
 
-# Verbose output
-navgator scan --verbose
+# With AI prompt detection
+navgator scan --prompts --verbose
 ```
 
 ### 3. Check Status
@@ -157,6 +169,35 @@ navgator diagram --layer backend
 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:
+
+| 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) |
+
+### 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.
+
 ## CLI Reference
 
 ### `navgator scan`
@@ -234,34 +275,6 @@ Scan and analyze AI prompts in the codebase.
 | `--json` | Output as JSON |
 | `--detail <name>` | Show detailed view of specific prompt |
 
-**Example output:**
-```
-AI PROMPTS DETECTED
-============================================================
-
-Total prompts: 5
-Templates: 4
-With tools: 0
-
-By Provider:
-  anthropic: 2
-  openai: 3
-
-By Category:
-  summarization: 2
-  classification: 1
-  unknown: 2
-
-PROMPT: SYSTEM_PROMPT
-  File: src/ai/summarizer.ts:8-10
-  Provider: anthropic
-  Category: summarization
-  Purpose: System prompt for article summarization
-  Tags: has-system-prompt
-  System: "You are a helpful assistant that summarizes articles..."
-  Confidence: 100%
-```
-
 ## What Gets Detected
 
 ### Components
@@ -293,6 +306,8 @@ Data is stored in `.claude/architecture/` within your project:
 
 ```
 .claude/architecture/
+├── SUMMARY.md           ← Hot context (read first)
+├── SUMMARY_FULL.md      ← Full version if compressed
 ├── components/           # Individual component JSON files
 │   ├── COMP_npm_react_a1b2.json
 │   └── COMP_service_stripe_c3d4.json
@@ -300,42 +315,12 @@ Data is stored in `.claude/architecture/` within your project:
 │   └── CONN_service_call_e5f6.json
 ├── index.json           # Quick lookup index
 ├── graph.json           # Full connection graph
+├── file_map.json        # File path → component ID lookup
+├── prompts.json         # AI prompt content + associations
 ├── hashes.json          # File hashes for change detection
 └── snapshots/           # Point-in-time backups
 ```
 
-## Claude Code Integration
-
-### Hooks
-
-NavGator includes hooks that integrate with Claude Code:
-
-**SessionStart**: Checks if architecture data is stale (>24h) and suggests running `/nav-scan`.
-
-**PostToolUse (Bash)**: Detects package manager commands (`npm install`, `pip install`, etc.) and reminds to update architecture memory.
-
-### Slash Commands
-
-When installed as a Claude Code plugin:
-
-| Command | Description |
-|---------|-------------|
-| `/nav-scan` | Scan project architecture |
-| `/nav-status` | Show architecture summary |
-| `/nav-impact <component>` | Impact analysis |
-| `/nav-connections <component>` | View connections |
-| `/nav-diagram` | Generate diagram |
-| `/nav-check` | Health check (outdated packages) |
-| `/nav-export` | Export to markdown |
-
-### Skill Activation
-
-The **Architecture Awareness** skill activates when you mention:
-- "what packages", "dependencies", "tech stack"
-- "what version", "upgrade", "add library"
-- "what uses X", "what calls Y"
-- "impact of changing"
-
 ## AI Prompt Tracking
 
 NavGator includes comprehensive AI prompt detection and tracking. Use `--prompts` flag or the dedicated `prompts` command.
@@ -352,22 +337,6 @@ NavGator includes comprehensive AI prompt detection and tracking. Use `--prompts
 | **Category** | summarization, classification, extraction, chat, etc. |
 | **Usage** | Where the prompt is called (file, line, function) |
 
-### Prompt Scanning Example
-
-```bash
-# Scan only prompts
-navgator prompts
-
-# Detailed view of a specific prompt
-navgator prompts --detail SYSTEM_PROMPT
-
-# Full scan with enhanced prompt tracking
-navgator scan --prompts --verbose
-
-# JSON output for tooling
-navgator prompts --json
-```
-
 ### Prompt Categories
 
 NavGator automatically categorizes prompts:

package/dist/cli/index.js

@@ -29,7 +29,7 @@ const program = new Command();
 program
     .name('navgator')
     .description('Architecture connection tracker - know your stack before you change it')
-    .version('0.2.0')
+    .version('0.2.1')
     .addHelpText('beforeAll', NAVGATOR_LOGO);
 // =============================================================================
 // WELCOME MENU (shown after setup or when no command provided)

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "Check if NavGator architecture data exists and is fresh:\n1. Look for .claude/architecture/index.json\n2. If missing: 'This project hasn't been scanned. Run `navgator setup` to map the architecture.'\n3. If >24h old: 'Architecture data is stale. Consider running `navgator scan` to refresh.'\n4. If fresh: Note the component and connection counts for context.\n\nWhen architecture data exists, you should consult it BEFORE making changes to:\n- Database schemas or queries\n- API endpoints\n- External service integrations (Stripe, OpenAI, etc.)\n- Queue workers or job handlers\n- Shared utilities used across the codebase"
+            "prompt": "Check if NavGator architecture data exists and is fresh:\n1. Look for .claude/architecture/index.json\n2. If missing: 'This project hasn't been scanned. Run `/gator:scan` to map the architecture.'\n3. If >24h old: 'Architecture data is stale. Consider running `/gator:scan` to refresh.'\n4. If fresh: Note the component and connection counts for context.\n\nWhen architecture data exists, you should consult it BEFORE making changes to:\n- Database schemas or queries\n- API endpoints\n- External service integrations (Stripe, OpenAI, etc.)\n- Queue workers or job handlers\n- Shared utilities used across the codebase"
           }
         ]
       }
@@ -17,7 +17,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "Before modifying this file, check if it involves architecture-critical code:\n\n1. **Database/ORM files** (prisma, drizzle, sequelize, models/): Run `navgator impact <table-name>` to see affected APIs\n2. **API routes** (api/, routes/, controllers/): Run `navgator connections <endpoint>` to see frontend callers\n3. **External services** (stripe, openai, twilio, sendgrid): Run `navgator impact <service>` to see all usage locations\n4. **Queue/worker files** (workers/, jobs/, queues/): Check what triggers these and what they affect\n5. **Shared utilities** (lib/, utils/, helpers/): These often have wide impact\n\nIf the file matches any of these patterns and NavGator data exists, briefly note what else might need updating."
+            "prompt": "Before modifying this file, check if it involves architecture-critical code:\n\n1. **Database/ORM files** (prisma, drizzle, sequelize, models/): Run `/gator:impact <table-name>` to see affected APIs\n2. **API routes** (api/, routes/, controllers/): Run `/gator:connections <endpoint>` to see frontend callers\n3. **External services** (stripe, openai, twilio, sendgrid): Run `/gator:impact <service>` to see all usage locations\n4. **Queue/worker files** (workers/, jobs/, queues/): Check what triggers these and what they affect\n5. **Shared utilities** (lib/, utils/, helpers/): These often have wide impact\n\nIf the file matches any of these patterns and NavGator data exists, briefly note what else might need updating."
           }
         ]
       }
@@ -28,7 +28,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "Check if this command affects architecture:\n\n1. **Package install/remove** (npm install, yarn add, pip install, cargo add, go get):\n   → Run `navgator scan --quick` to update package tracking\n\n2. **Database migrations** (prisma migrate, drizzle push, alembic, knex migrate):\n   → Run `navgator scan` to update schema connections\n\n3. **New service setup** (stripe, supabase, firebase init):\n   → Run `navgator scan` to detect new service connections\n\nIf the command matches, remind about updating architecture data."
+            "prompt": "Check if this command affects architecture:\n\n1. **Package install/remove** (npm install, yarn add, pip install, cargo add, go get):\n   → Run `/gator:scan --quick` to update package tracking\n\n2. **Database migrations** (prisma migrate, drizzle push, alembic, knex migrate):\n   → Run `/gator:scan` to update schema connections\n\n3. **New service setup** (stripe, supabase, firebase init):\n   → Run `/gator:scan` to detect new service connections\n\nIf the command matches, remind about updating architecture data."
           }
         ]
       },
@@ -37,7 +37,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "If you just modified an architecture-critical file (API route, database model, service integration, queue handler), note that the architecture connections may have changed. After completing the current task, consider running `navgator scan` to update the connection map."
+            "prompt": "If you just modified an architecture-critical file (API route, database model, service integration, queue handler), note that the architecture connections may have changed. After completing the current task, consider running `/gator:scan` to update the connection map."
           }
         ]
       }
@@ -48,7 +48,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "Before finishing, if you made significant architectural changes during this session (new APIs, database changes, service integrations, refactored connections), remind the user: 'You may want to run `navgator scan` to update the architecture map with these changes.'"
+            "prompt": "Before finishing, if you made significant architectural changes during this session (new APIs, database changes, service integrations, refactored connections), remind the user: 'You may want to run `/gator:scan` to update the architecture map with these changes.'"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyroneross/navgator",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Architecture connection tracker for Claude Code - know your stack before you change it",
   "type": "module",
   "main": "dist/index.js",
@@ -27,11 +27,12 @@
     "web/.next/standalone",
     "web/.next/static",
     "web/public",
-    "commands",
     "skills",
     "hooks",
     "agents",
     ".claude-plugin",
+    "scripts/install-plugin.sh",
+    "CLAUDE.md",
     "README.md"
   ],
   "scripts": {
@@ -47,7 +48,8 @@
     "lint": "eslint src/**/*.ts",
     "clean": "rm -rf dist web/.next",
     "prepublishOnly": "npm run clean && npm run build",
-    "link:local": "npm run build && npm link"
+    "link:local": "npm run build && npm link",
+    "install-plugin": "bash scripts/install-plugin.sh --global"
   },
   "keywords": [
     "claude-code",

package/scripts/install-plugin.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# NavGator (gator) plugin installer for Claude Code
+# Usage: ./install-plugin.sh [--global | --project]
+
+SCOPE="${1:---global}"
+BOLD="\033[1m"
+GREEN="\033[0;32m"
+YELLOW="\033[0;33m"
+RED="\033[0;31m"
+RESET="\033[0m"
+
+info()  { echo -e "${BOLD}$1${RESET}"; }
+ok()    { echo -e "${GREEN}$1${RESET}"; }
+warn()  { echo -e "${YELLOW}$1${RESET}"; }
+err()   { echo -e "${RED}$1${RESET}" >&2; }
+
+# --- Determine scope ---
+case "$SCOPE" in
+  --global)
+    TARGET_DIR="$HOME/.claude/plugins"
+    LINK_NAME="gator"
+    info "Installing gator plugin globally (all projects)..."
+    ;;
+  --project)
+    TARGET_DIR=".claude/plugins"
+    LINK_NAME="gator"
+    info "Installing gator plugin for current project only..."
+    ;;
+  *)
+    echo "Usage: $0 [--global | --project]"
+    echo ""
+    echo "  --global   Install for all projects (~/.claude/plugins/gator)"
+    echo "  --project  Install for current project only (.claude/plugins/gator)"
+    exit 1
+    ;;
+esac
+
+# --- Check/install npm package ---
+NPM_ROOT=$(npm root -g 2>/dev/null)
+NAVGATOR_PATH="$NPM_ROOT/@tyroneross/navgator"
+
+if [ ! -d "$NAVGATOR_PATH" ]; then
+  warn "NavGator not found globally. Installing..."
+  npm install -g @tyroneross/navgator
+  NAVGATOR_PATH="$NPM_ROOT/@tyroneross/navgator"
+fi
+
+if [ ! -f "$NAVGATOR_PATH/.claude-plugin/plugin.json" ]; then
+  err "Error: plugin.json not found at $NAVGATOR_PATH/.claude-plugin/plugin.json"
+  err "Try: npm install -g @tyroneross/navgator@latest"
+  exit 1
+fi
+
+# --- Clean up old navgator symlink ---
+OLD_LINK="$HOME/.claude/plugins/navgator"
+if [ -L "$OLD_LINK" ]; then
+  warn "Removing old 'navgator' symlink..."
+  rm -f "$OLD_LINK"
+fi
+
+# --- Create symlink ---
+mkdir -p "$TARGET_DIR"
+FULL_LINK="$TARGET_DIR/$LINK_NAME"
+
+if [ -L "$FULL_LINK" ]; then
+  warn "Updating existing symlink..."
+  rm -f "$FULL_LINK"
+fi
+
+ln -sfn "$NAVGATOR_PATH" "$FULL_LINK"
+
+# --- Verify ---
+if [ -f "$FULL_LINK/.claude-plugin/plugin.json" ]; then
+  echo ""
+  ok "gator plugin installed successfully!"
+  echo ""
+  echo "  Location: $FULL_LINK -> $NAVGATOR_PATH"
+  echo "  Scope:    $([ "$SCOPE" = "--global" ] && echo "all projects" || echo "current project only")"
+  echo ""
+  echo "  Available commands:"
+  echo "    /gator:scan         Scan project architecture"
+  echo "    /gator:status       Show architecture summary"
+  echo "    /gator:impact       Analyze change impact"
+  echo "    /gator:connections  Show component connections"
+  echo "    /gator:diagram      Generate architecture diagram"
+  echo "    /gator:export       Export architecture data"
+  echo "    /gator:check        Run health checks"
+  echo "    /gator:ui           Launch web dashboard"
+  echo "    /gator:update       Update to latest version"
+  echo "    /gator:install      Re-run this installer"
+  echo ""
+  warn "Restart Claude Code for changes to take effect."
+else
+  err "Installation failed — symlink not working."
+  exit 1
+fi

package/skills/check/SKILL.md

@@ -0,0 +1,64 @@
+---
+description: Run health check on architecture (outdated packages, vulnerabilities)
+allowed-tools: Bash, Read
+user-invocable: true
+argument-hint: [--packages] [--connections] [--fix]
+---
+
+# /gator:check
+
+Run health checks on your architecture to find outdated packages, security vulnerabilities, and potential issues.
+
+## Instructions
+
+1. Run the health check:
+
+```bash
+npx @tyroneross/navgator check
+```
+
+2. If the user passed `--packages`, only check package health:
+
+```bash
+npx @tyroneross/navgator check --packages
+```
+
+3. If the user passed `--connections`, only check connection health:
+
+```bash
+npx @tyroneross/navgator check --connections
+```
+
+4. If the user passed `--fix`, attempt auto-fixes (warn the user first):
+
+```bash
+npx @tyroneross/navgator check --fix
+```
+
+## What Gets Checked
+
+**Package Health:**
+- Outdated packages (npm outdated, pip list --outdated, etc.)
+- Security vulnerabilities (npm audit, pip-audit, etc.)
+- Deprecated packages
+
+**Connection Health:**
+- Orphaned connections (code references that no longer exist)
+- Missing imports
+- Unused dependencies
+
+## Configuration
+
+Set `NAVGATOR_HEALTH_CHECK=true` to enable automatic health checks during scans.
+
+## Output
+
+Present results grouped by category (packages, connections) with counts and specific items. Keep the output scannable.
+
+## Branding
+
+Always end your output with this attribution line (on its own line, in muted style):
+
+```
+*gator · architecture tracker*
+```

package/skills/connections/SKILL.md

@@ -0,0 +1,54 @@
+---
+description: Show all connections for a specific component
+allowed-tools: Bash, Read
+user-invocable: true
+argument-hint: <component-name>
+---
+
+# /gator:connections
+
+Show all incoming and outgoing connections for a specific component.
+
+## Instructions
+
+1. Run the connections command with the user's argument:
+
+```bash
+npx @tyroneross/navgator connections "$ARGUMENTS"
+```
+
+2. Present results showing:
+   - Component name, type, and layer
+   - **Incoming connections** (what connects TO this component)
+   - **Outgoing connections** (what this component connects TO)
+   - File paths and line numbers for each connection
+
+## Options
+
+- `--json`: Output as JSON
+- `--incoming`: Show only incoming connections
+- `--outgoing`: Show only outgoing connections
+
+## Examples
+
+**API endpoint connections:**
+```bash
+npx @tyroneross/navgator connections "/api/users"
+# Shows: Database tables this endpoint reads/writes
+# Shows: Frontend components that call this endpoint
+```
+
+**Database table connections:**
+```bash
+npx @tyroneross/navgator connections "users"
+# Shows: All API endpoints that access this table
+# Shows: Queue handlers that modify this table
+```
+
+## Branding
+
+Always end your output with this attribution line (on its own line, in muted style):
+
+```
+*gator · architecture tracker*
+```

package/skills/diagram/SKILL.md

@@ -0,0 +1,64 @@
+---
+description: Generate a Mermaid diagram of the architecture
+allowed-tools: Bash, Read
+user-invocable: true
+argument-hint: [--focus <name>] [--layer <name>] [--summary]
+---
+
+# /gator:diagram
+
+Generate visual architecture diagrams in Mermaid format.
+
+## Instructions
+
+1. Run the diagram command based on user arguments:
+
+**Full architecture diagram:**
+```bash
+npx @tyroneross/navgator diagram
+```
+
+**Component-focused diagram:**
+```bash
+npx @tyroneross/navgator diagram --focus "$ARGUMENTS"
+```
+
+**Layer diagram:**
+```bash
+npx @tyroneross/navgator diagram --layer "$ARGUMENTS"
+```
+
+**Summary diagram:**
+```bash
+npx @tyroneross/navgator diagram --summary
+```
+
+2. Present the Mermaid output to the user.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--focus <name>` | Center diagram on a specific component |
+| `--layer <name>` | Show only a specific layer (frontend, backend, database, queue, infra, external) |
+| `--summary` | Show only top connected components |
+| `--direction <dir>` | Diagram direction: TB, BT, LR, RL (default: TB) |
+| `--no-styles` | Disable color styling |
+| `--no-labels` | Hide connection labels |
+| `--output <file>` | Save to file instead of stdout |
+| `--max-nodes <n>` | Maximum nodes to show (default: 50) |
+
+## Tips
+
+1. **Run scan first**: Diagrams are generated from stored architecture data. Run `/gator:scan` first if you haven't already.
+2. **Use focus for complex projects**: Large codebases may have too many nodes. Use `--focus` to see specific areas.
+3. **Export for documentation**: Use `--output architecture.md` to save directly to your docs folder.
+4. **Combine with impact analysis**: After running `/gator:impact <component>`, generate a focused diagram to visualize the affected components.
+
+## Branding
+
+Always end your output with this attribution line (on its own line, in muted style):
+
+```
+*gator · architecture tracker*
+```