@tyroneross/navgator 0.1.0

package/dist/ui-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-server.js","sourceRoot":"","sources":["../src/ui-server.ts"],"names":[],"mappings":"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"}

package/hooks/hooks.json

@@ -0,0 +1,57 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "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"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "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."
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "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."
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "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."
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "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.'"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@tyroneross/navgator",
+  "version": "0.1.0",
+  "description": "Architecture connection tracker for Claude Code - know your stack before you change it",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "navgator": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./scanner": {
+      "types": "./dist/scanner.d.ts",
+      "import": "./dist/scanner.js"
+    },
+    "./setup": {
+      "types": "./dist/setup.d.ts",
+      "import": "./dist/setup.js"
+    }
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "commands",
+    "skills",
+    "hooks",
+    "agents",
+    ".claude-plugin",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && npm run build:fixshebang",
+    "build:fixshebang": "node -e \"const fs=require('fs');const f='dist/cli/index.js';let c=fs.readFileSync(f,'utf8');if(!c.startsWith('#!')){c='#!/usr/bin/env node\\n'+c;fs.writeFileSync(f,c);}\"",
+    "dev": "tsc --watch",
+    "start": "node dist/cli/index.js",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "lint": "eslint src/**/*.ts",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "postinstall": "node scripts/postinstall.cjs",
+    "link:local": "npm run build && npm link"
+  },
+  "keywords": [
+    "claude-code",
+    "architecture",
+    "dependencies",
+    "devtools",
+    "cli",
+    "connections",
+    "impact-analysis"
+  ],
+  "author": "Tyrone Ross",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tyroneross/navgator"
+  },
+  "homepage": "https://github.com/tyroneross/navgator#readme",
+  "bugs": {
+    "url": "https://github.com/tyroneross/navgator/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "glob": "^10.3.10"
+  },
+  "optionalDependencies": {
+    "ts-morph": "^22.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0"
+  }
+}

package/scripts/ibr-ui-test.mjs

@@ -0,0 +1,359 @@
+/**
+ * NavGator UI Functional Test Script
+ * Uses InterfaceBuiltRight (IBR) to verify all selectable buttons,
+ * navigation, and interactive elements across the Next.js dashboard.
+ *
+ * Prerequisites:
+ *   - NavGator web dashboard running: cd web && npm run dev
+ *   - IBR installed: npm install @tyroneross/interface-built-right
+ *
+ * Usage:
+ *   node scripts/ibr-ui-test.mjs [--base-url http://localhost:3000]
+ */
+
+import { InterfaceBuiltRight } from '@tyroneross/interface-built-right';
+
+const BASE_URL = process.argv.includes('--base-url')
+  ? process.argv[process.argv.indexOf('--base-url') + 1]
+  : 'http://localhost:3000';
+
+const ibr = new InterfaceBuiltRight({
+  baseUrl: BASE_URL,
+  outputDir: './.ibr',
+  fullPage: true,
+  timeout: 15000,
+});
+
+const results = [];
+let session;
+
+function log(status, msg) {
+  const icon = status === 'PASS' ? '\u2713' : status === 'FAIL' ? '\u2717' : '\u2022';
+  console.log(`  ${icon} ${msg}`);
+  results.push({ status, msg });
+}
+
+async function test(name, fn) {
+  try {
+    await fn();
+    log('PASS', name);
+  } catch (err) {
+    log('FAIL', `${name} — ${err.message}`);
+  }
+}
+
+// ==========================================================================
+// 1. INITIAL LOAD & SEMANTIC ANALYSIS
+// ==========================================================================
+
+console.log('\n--- NavGator IBR UI Test ---\n');
+console.log(`Target: ${BASE_URL}\n`);
+
+console.log('[1] Page Load & Semantic Understanding');
+
+session = await ibr.start('/', { viewport: 'desktop' });
+const semantic = await session.understand();
+
+test('Page loads with title', async () => {
+  const title = await session.page.title();
+  if (!title) throw new Error('No page title');
+});
+
+test('Header renders with NavGator branding', async () => {
+  await session.page.waitForSelector('header', { timeout: 5000 });
+});
+
+test('Sidebar renders with navigation items', async () => {
+  await session.page.waitForSelector('aside nav', { timeout: 5000 });
+});
+
+// ==========================================================================
+// 2. SIDEBAR NAVIGATION — All 7 views
+// ==========================================================================
+
+console.log('\n[2] Sidebar Navigation (7 views)');
+
+const sidebarViews = [
+  { label: 'Overview', expectText: 'Architecture Status' },
+  { label: 'Components', expectText: 'Components' },
+  { label: 'Connections', expectText: 'Connections' },
+  { label: 'Impact', expectText: 'Impact' },
+  { label: 'Diagram', expectText: 'Diagram' },
+  { label: 'LLM Tracking', expectText: 'LLM' },
+  { label: 'Settings', expectText: 'Settings' },
+];
+
+for (const view of sidebarViews) {
+  await test(`Navigate to "${view.label}" view`, async () => {
+    // Click sidebar button by text
+    const btn = await session.page.locator(`aside button:has-text("${view.label}")`).first();
+    await btn.click();
+    await session.page.waitForTimeout(500);
+
+    // Verify view rendered (check main content area has expected text)
+    const main = await session.page.locator('main').textContent();
+    if (!main.includes(view.expectText)) {
+      throw new Error(`Expected "${view.expectText}" in main content`);
+    }
+  });
+}
+
+// ==========================================================================
+// 3. HEADER ELEMENTS
+// ==========================================================================
+
+console.log('\n[3] Header Interactive Elements');
+
+await test('Search input is present and focusable', async () => {
+  const input = session.page.locator('header input[placeholder*="Search"]');
+  if (await input.count() === 0) throw new Error('Search input not found');
+  await input.focus();
+});
+
+await test('Scan button is present and clickable', async () => {
+  const scanBtn = session.page.locator('header button:has-text("Scan")');
+  if (await scanBtn.count() === 0) throw new Error('Scan button not found');
+  // Don't actually trigger scan, just verify it exists and is enabled
+  const disabled = await scanBtn.isDisabled();
+  if (disabled) throw new Error('Scan button is disabled');
+});
+
+// ==========================================================================
+// 4. OVERVIEW — Stat cards & quick actions
+// ==========================================================================
+
+console.log('\n[4] Overview — Stat Cards & Quick Actions');
+
+// Navigate back to overview
+await session.page.locator('aside button:has-text("Overview")').first().click();
+await session.page.waitForTimeout(500);
+
+await test('Stat cards are clickable (Components card)', async () => {
+  const card = session.page.locator('main button:has-text("Components")').first();
+  if (await card.count() === 0) throw new Error('Components stat card not found');
+  await card.click();
+  await session.page.waitForTimeout(300);
+  // Should navigate to components view
+  const main = await session.page.locator('main').textContent();
+  if (!main.includes('Components')) throw new Error('Did not navigate to Components');
+});
+
+// Go back to overview
+await session.page.locator('aside button:has-text("Overview")').first().click();
+await session.page.waitForTimeout(500);
+
+await test('Quick Action: "View Diagram" navigates to diagram', async () => {
+  const btn = session.page.locator('main button:has-text("View Diagram")');
+  if (await btn.count() === 0) throw new Error('View Diagram action not found');
+  await btn.click();
+  await session.page.waitForTimeout(300);
+  const main = await session.page.locator('main').textContent();
+  if (!main.includes('Diagram')) throw new Error('Did not navigate to Diagram');
+});
+
+// Go back to overview
+await session.page.locator('aside button:has-text("Overview")').first().click();
+await session.page.waitForTimeout(500);
+
+await test('Quick Action: "Impact Analysis" navigates to impact', async () => {
+  const btn = session.page.locator('main button:has-text("Impact Analysis")');
+  if (await btn.count() === 0) throw new Error('Impact Analysis action not found');
+  await btn.click();
+  await session.page.waitForTimeout(300);
+});
+
+await test('"View all" link in Components by Type card', async () => {
+  await session.page.locator('aside button:has-text("Overview")').first().click();
+  await session.page.waitForTimeout(500);
+  const viewAll = session.page.locator('main button:has-text("View all"), main a:has-text("View all")').first();
+  if (await viewAll.count() > 0) {
+    await viewAll.click();
+    await session.page.waitForTimeout(300);
+  }
+  // Acceptable if no data present — just check it doesn't crash
+});
+
+// ==========================================================================
+// 5. SETTINGS — Tabs, switches, selects, buttons
+// ==========================================================================
+
+console.log('\n[5] Settings Panel — Tabs, Switches, Selects, Buttons');
+
+await session.page.locator('aside button:has-text("Settings")').first().click();
+await session.page.waitForTimeout(500);
+
+const settingsTabs = ['Scanning', 'Detection', 'Notifications', 'Display'];
+
+for (const tab of settingsTabs) {
+  await test(`Settings tab: "${tab}" is clickable`, async () => {
+    const tabBtn = session.page.locator(`button[role="tab"]:has-text("${tab}"), [data-value="${tab.toLowerCase()}"]`).first();
+    // Fallback: find by text in tabs area
+    const fallback = session.page.locator(`button:has-text("${tab}")`).first();
+    const target = (await tabBtn.count() > 0) ? tabBtn : fallback;
+    await target.click();
+    await session.page.waitForTimeout(300);
+  });
+}
+
+await test('Save Changes button is clickable', async () => {
+  const saveBtn = session.page.locator('button:has-text("Save")').first();
+  if (await saveBtn.count() === 0) throw new Error('Save button not found');
+  await saveBtn.click();
+  await session.page.waitForTimeout(500);
+  // Check for "Saved" feedback
+  const text = await session.page.locator('button:has-text("Saved")').count();
+  if (text === 0) {
+    // Also accept if button still says "Save Changes" (no API connected)
+  }
+});
+
+await test('Reset button is clickable', async () => {
+  const resetBtn = session.page.locator('button:has-text("Reset")').first();
+  if (await resetBtn.count() === 0) throw new Error('Reset button not found');
+  await resetBtn.click();
+});
+
+await test('Switch toggles respond to click', async () => {
+  // Click the Scanning tab first
+  await session.page.locator('button:has-text("Scanning")').first().click();
+  await session.page.waitForTimeout(300);
+
+  const switches = session.page.locator('button[role="switch"]');
+  const count = await switches.count();
+  if (count === 0) throw new Error('No switch toggles found');
+
+  // Toggle the first switch
+  const first = switches.first();
+  const before = await first.getAttribute('data-state');
+  await first.click();
+  await session.page.waitForTimeout(200);
+  const after = await first.getAttribute('data-state');
+  if (before === after) throw new Error('Switch did not toggle');
+  // Toggle back
+  await first.click();
+});
+
+await test('Select dropdowns open and have options', async () => {
+  const triggers = session.page.locator('button[role="combobox"]');
+  const count = await triggers.count();
+  if (count === 0) throw new Error('No select dropdowns found');
+
+  // Open first select
+  await triggers.first().click();
+  await session.page.waitForTimeout(300);
+
+  const options = session.page.locator('[role="option"]');
+  const optCount = await options.count();
+  if (optCount === 0) throw new Error('Select opened but no options found');
+
+  // Close by pressing Escape
+  await session.page.keyboard.press('Escape');
+});
+
+// ==========================================================================
+// 6. HELP BUTTON (non-functional check)
+// ==========================================================================
+
+console.log('\n[6] Non-Functional Element Check');
+
+await test('Help button exists but has no navigation action', async () => {
+  const helpBtn = session.page.locator('aside button:has-text("Help")');
+  if (await helpBtn.count() === 0) throw new Error('Help button not found');
+  // This button has no onClick handler — it's non-functional
+  // IBR flags this as a potential Calm Precision violation (Affordance Theory)
+});
+
+// ==========================================================================
+// 7. INTERACTIVITY TEST (IBR built-in)
+// ==========================================================================
+
+console.log('\n[7] IBR Interactivity Audit');
+
+// Navigate to overview for broadest element coverage
+await session.page.locator('aside button:has-text("Overview")').first().click();
+await session.page.waitForTimeout(500);
+
+await test('IBR interactivity test passes', async () => {
+  const interactivity = await session.testInteractivity();
+  const issues = interactivity.issues || [];
+  const critical = issues.filter(i => i.severity === 'critical' || i.severity === 'error');
+  if (critical.length > 0) {
+    throw new Error(`${critical.length} critical interactivity issues: ${critical.map(i => i.message).join('; ')}`);
+  }
+  console.log(`    Found ${interactivity.buttons?.length || 0} buttons, ${interactivity.links?.length || 0} links, ${interactivity.forms?.length || 0} forms`);
+  if (issues.length > 0) {
+    console.log(`    Warnings: ${issues.length}`);
+    issues.slice(0, 3).forEach(i => console.log(`      - ${i.message}`));
+  }
+});
+
+// ==========================================================================
+// 8. PERFORMANCE CHECK (IBR built-in)
+// ==========================================================================
+
+console.log('\n[8] IBR Performance Metrics');
+
+await test('Web Vitals within acceptable range', async () => {
+  const perf = await session.measurePerformance();
+  const ratings = perf.ratings || {};
+  console.log(`    LCP: ${ratings.LCP?.value || 'N/A'}ms (${ratings.LCP?.rating || '?'})`);
+  console.log(`    CLS: ${ratings.CLS?.value || 'N/A'} (${ratings.CLS?.rating || '?'})`);
+  console.log(`    TBT: ${ratings.TBT?.value || 'N/A'}ms (${ratings.TBT?.rating || '?'})`);
+
+  if (ratings.LCP?.rating === 'poor') {
+    throw new Error(`LCP is poor: ${ratings.LCP.value}ms`);
+  }
+});
+
+// ==========================================================================
+// 9. VISUAL BASELINE CAPTURE
+// ==========================================================================
+
+console.log('\n[9] Visual Baseline Capture');
+
+const viewsToCapture = ['/', '/?view=components', '/?view=settings'];
+// Capture baselines by navigating sidebar
+const viewMap = [
+  { label: 'Overview', name: 'overview' },
+  { label: 'Components', name: 'components' },
+  { label: 'Settings', name: 'settings' },
+];
+
+for (const view of viewMap) {
+  await test(`Capture baseline: ${view.name}`, async () => {
+    await session.page.locator(`aside button:has-text("${view.label}")`).first().click();
+    await session.page.waitForTimeout(500);
+    await session.screenshot(`.ibr/navgator-${view.name}-baseline.png`);
+  });
+}
+
+// ==========================================================================
+// SUMMARY
+// ==========================================================================
+
+await session.close();
+
+console.log('\n========================================');
+console.log('TEST SUMMARY');
+console.log('========================================\n');
+
+const passed = results.filter(r => r.status === 'PASS').length;
+const failed = results.filter(r => r.status === 'FAIL').length;
+const total = results.length;
+
+console.log(`  Total: ${total}`);
+console.log(`  Passed: ${passed}`);
+console.log(`  Failed: ${failed}`);
+console.log();
+
+if (failed > 0) {
+  console.log('  FAILURES:');
+  results.filter(r => r.status === 'FAIL').forEach(r => {
+    console.log(`    \u2717 ${r.msg}`);
+  });
+  console.log();
+  process.exit(1);
+} else {
+  console.log('  All tests passed.\n');
+  process.exit(0);
+}

package/scripts/postinstall.cjs

@@ -0,0 +1,35 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const pluginDir = path.join(os.homedir(), '.claude', 'plugins');
+const linkPath = path.join(pluginDir, 'navgator');
+const packageRoot = path.resolve(__dirname, '..');
+
+// Only link if .claude directory exists (user has Claude Code)
+if (fs.existsSync(path.join(os.homedir(), '.claude'))) {
+  fs.mkdirSync(pluginDir, { recursive: true });
+
+  // Remove existing link if stale
+  try {
+    const existing = fs.readlinkSync(linkPath);
+    if (existing !== packageRoot) fs.unlinkSync(linkPath);
+  } catch {}
+
+  if (!fs.existsSync(linkPath)) {
+    try {
+      fs.symlinkSync(packageRoot, linkPath, 'dir');
+      console.log('\n\u{1F40A} NavGator plugin linked to Claude Code');
+      console.log(`   ${linkPath} -> ${packageRoot}\n`);
+    } catch (err) {
+      console.log('\n\u{1F40A} NavGator installed but could not auto-link plugin.');
+      console.log('   Link manually:');
+      console.log(`   ln -s ${packageRoot} ${linkPath}\n`);
+    }
+  } else {
+    console.log('\n\u{1F40A} NavGator plugin already linked. Run: navgator setup\n');
+  }
+} else {
+  console.log('\n\u{1F40A} NavGator installed! Run: navgator setup');
+  console.log('   (Claude Code not detected - plugin not auto-linked)\n');
+}

package/skills/architecture-awareness/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: Architecture Awareness
+description: Use this skill BEFORE making architectural changes. Triggers on "what packages", "what framework", "dependencies", "tech stack", "what version", "upgrade", "update packages", "add library", "install", "architecture", "what uses", "what calls", "impact of changing", database changes, API modifications, service integrations, or refactoring discussions.
+version: 1.0.0
+---
+
+# Architecture Awareness Workflow
+
+**Core principle:** Know your stack before you change it.
+
+## CRITICAL: When to Check NavGator
+
+### ALWAYS check NavGator impact BEFORE modifying:
+
+1. **Database schemas/models**
+   ```bash
+   navgator impact "users-table"  # See which APIs touch this table
+   ```
+
+2. **API endpoints**
+   ```bash
+   navgator connections "api-endpoint"  # See frontend components that call it
+   ```
+
+3. **External service integrations** (Stripe, OpenAI, Twilio, etc.)
+   ```bash
+   navgator impact "Stripe"  # See all files using this service
+   ```
+
+4. **Queue workers/job handlers**
+   ```bash
+   navgator connections "bullmq"  # See what triggers and is triggered by queues
+   ```
+
+5. **Shared utilities** (lib/, utils/, helpers/)
+   ```bash
+   navgator impact "utility-name"  # These often have wide impact
+   ```
+
+## Quick Reference
+
+| Situation | Command | Why |
+|-----------|---------|-----|
+| Before changing DB schema | `navgator impact <table>` | Find all APIs that need updating |
+| Before modifying API | `navgator connections <endpoint>` | Find frontend code to update |
+| Before touching service code | `navgator impact <service>` | Find all usage locations |
+| After npm install | `navgator scan --quick` | Update package tracking |
+| After migrations | `navgator scan` | Update schema connections |
+| Starting new session | `navgator status` | Check if data is fresh |
+
+## Workflow Examples
+
+### Example 1: Changing a Database Table
+
+**Before:**
+```bash
+navgator impact "users"
+```
+This shows:
+- Which API endpoints read/write this table
+- Which services depend on user data
+- File:line locations to update
+
+**Then:** Make your changes knowing what else needs updating.
+
+**After:**
+```bash
+navgator scan
+```
+
+### Example 2: Adding a New Service Integration
+
+```bash
+# Check current architecture
+navgator status
+
+# Add the package
+npm install stripe
+
+# Update architecture
+navgator scan --quick
+
+# Start implementing - NavGator now tracks your Stripe calls
+```
+
+### Example 3: Refactoring an API Endpoint
+
+```bash
+# Before refactoring
+navgator connections "api/users"
+
+# Shows:
+# - Frontend components calling this endpoint
+# - Services that depend on it
+# - Exact file:line references
+
+# Now you know what else needs updating when you change the API contract
+```
+
+## Session Start Checklist
+
+When starting work on a project:
+
+1. Check if architecture data exists: `navgator status`
+2. If missing or stale (>24h): `navgator setup` or `navgator scan`
+3. Before any architectural change: `navgator impact <component>`
+
+## What NavGator Tracks
+
+**Components:**
+- Packages (npm, pip, cargo, go, gem, composer)
+- Frameworks (Next.js, React, Django, FastAPI)
+- Databases (PostgreSQL, MongoDB, Redis, Supabase)
+- Queues (BullMQ, Celery, SQS)
+- Infrastructure (Railway, Vercel, Docker)
+- External Services (Stripe, OpenAI, Twilio)
+
+**Connections:**
+- API → Database (which endpoints touch which tables)
+- Frontend → API (which components call which endpoints)
+- Queue → Handler (which jobs trigger which code)
+- Service calls (where external APIs are used, with file:line)
+
+## Commands
+
+| Command | Use When |
+|---------|----------|
+| `navgator setup` | First time scanning a project |
+| `navgator scan` | Refresh after changes |
+| `navgator scan --quick` | After package install |
+| `navgator status` | Check scan freshness |
+| `navgator impact <X>` | Before modifying component X |
+| `navgator connections <X>` | Understanding how X is connected |
+| `navgator diagram` | Generate visual architecture |
+| `navgator ui` | Launch visual dashboard |
+
+## Key Principle
+
+**Don't modify architecture-critical code without checking impact first.**
+
+The few seconds to run `navgator impact` can save hours of debugging missed updates.