@caddis/cli 0.1.0 → 0.2.0

package/bundles/antigravity-plugin-extras/skills/ui-ux-intelligence/scripts/search.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UI/UX Pro Max Search - BM25 search engine for UI/UX style guides
+Usage: python search.py "<query>" [--domain <domain>] [--stack <stack>] [--max-results 3]
+       python search.py "<query>" --design-system [-p "Project Name"]
+       python search.py "<query>" --design-system --persist [-p "Project Name"] [--page "dashboard"]
+
+Domains: style, prompt, color, chart, landing, product, ux, typography, google-fonts
+Stacks: html-tailwind, react, nextjs
+
+Persistence (Master + Overrides pattern):
+  --persist    Save design system to design-system/MASTER.md
+  --page       Also create a page-specific override file in design-system/pages/
+"""
+
+import argparse
+import sys
+import io
+from core import CSV_CONFIG, AVAILABLE_STACKS, MAX_RESULTS, search, search_stack
+from design_system import generate_design_system, persist_design_system
+
+# Force UTF-8 for stdout/stderr to handle emojis on Windows (cp1252 default)
+if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
+    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
+
+
+def format_output(result):
+    """Format results for Claude consumption (token-optimized)"""
+    if "error" in result:
+        return f"Error: {result['error']}"
+
+    output = []
+    if result.get("stack"):
+        output.append(f"## UI Pro Max Stack Guidelines")
+        output.append(f"**Stack:** {result['stack']} | **Query:** {result['query']}")
+    else:
+        output.append(f"## UI Pro Max Search Results")
+        output.append(f"**Domain:** {result['domain']} | **Query:** {result['query']}")
+    output.append(f"**Source:** {result['file']} | **Found:** {result['count']} results\n")
+
+    for i, row in enumerate(result['results'], 1):
+        output.append(f"### Result {i}")
+        for key, value in row.items():
+            value_str = str(value)
+            if len(value_str) > 300:
+                value_str = value_str[:300] + "..."
+            output.append(f"- **{key}:** {value_str}")
+        output.append("")
+
+    return "\n".join(output)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="UI Pro Max Search")
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("--domain", "-d", choices=list(CSV_CONFIG.keys()), help="Search domain")
+    parser.add_argument("--stack", "-s", choices=AVAILABLE_STACKS, help="Stack-specific search (html-tailwind, react, nextjs)")
+    parser.add_argument("--max-results", "-n", type=int, default=MAX_RESULTS, help="Max results (default: 3)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    # Design system generation
+    parser.add_argument("--design-system", "-ds", action="store_true", help="Generate complete design system recommendation")
+    parser.add_argument("--project-name", "-p", type=str, default=None, help="Project name for design system output")
+    parser.add_argument("--format", "-f", choices=["ascii", "markdown"], default="ascii", help="Output format for design system")
+    # Persistence (Master + Overrides pattern)
+    parser.add_argument("--persist", action="store_true", help="Save design system to design-system/MASTER.md (creates hierarchical structure)")
+    parser.add_argument("--page", type=str, default=None, help="Create page-specific override file in design-system/pages/")
+    parser.add_argument("--output-dir", "-o", type=str, default=None, help="Output directory for persisted files (default: current directory)")
+
+    args = parser.parse_args()
+
+    # Design system takes priority
+    if args.design_system:
+        result = generate_design_system(
+            args.query, 
+            args.project_name, 
+            args.format,
+            persist=args.persist,
+            page=args.page,
+            output_dir=args.output_dir
+        )
+        print(result)
+        
+        # Print persistence confirmation
+        if args.persist:
+            project_slug = args.project_name.lower().replace(' ', '-') if args.project_name else "default"
+            print("\n" + "=" * 60)
+            print(f"✅ Design system persisted to design-system/{project_slug}/")
+            print(f"   📄 design-system/{project_slug}/MASTER.md (Global Source of Truth)")
+            if args.page:
+                page_filename = args.page.lower().replace(' ', '-')
+                print(f"   📄 design-system/{project_slug}/pages/{page_filename}.md (Page Overrides)")
+            print("")
+            print(f"📖 Usage: When building a page, check design-system/{project_slug}/pages/[page].md first.")
+            print(f"   If exists, its rules override MASTER.md. Otherwise, use MASTER.md.")
+            print("=" * 60)
+    # Stack search
+    elif args.stack:
+        result = search_stack(args.query, args.stack, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))
+    # Domain search
+    else:
+        result = search(args.query, args.domain, args.max_results)
+        if args.json:
+            import json
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(format_output(result))

package/bundles/antigravity-plugin-extras/skills/understand-anything/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: understand-anything
+description: >
+  Analyze any codebase or knowledge base and produce a searchable interactive knowledge graph.
+  Use this skill whenever the user asks to understand a codebase, analyze project architecture,
+  map a repo, generate an architecture diagram, create onboarding docs, explain a specific file
+  or function, analyze the impact of a PR or diff, chat about code, or run any /understand command.
+  Also triggers on phrases like "how does this project work", "map out the codebase", "what changed
+  in this PR", "explain this file", "onboard me to this project", "what does X depend on",
+  "analyze this repo", "generate a knowledge graph", or "what is the architecture of this project".
+  Always use this skill for /understand, /understand-chat, /understand-dashboard, /understand-diff,
+  /understand-domain, /understand-explain, /understand-knowledge, and /understand-onboard commands.
+---
+
+# Understand Anything
+
+Multi-agent pipeline that scans a project, extracts files/functions/classes/dependencies, and
+builds an interactive knowledge graph saved to `.understand-anything/knowledge-graph.json`.
+
+## Commands
+
+| Command | When to use | Reference |
+|---|---|---|
+| `/understand [path] [opts]` | Build (or rebuild) the knowledge graph | `references/pipeline.md` |
+| `/understand-chat <query>` | Q&A about codebase using existing graph | `references/commands.md#chat` |
+| `/understand-dashboard [path]` | Launch interactive web dashboard | `references/commands.md#dashboard` |
+| `/understand-diff` | Analyze git diff / PR impact against graph | `references/commands.md#diff` |
+| `/understand-domain [--full]` | Extract business domain flows | `references/commands.md#domain` |
+| `/understand-explain <file>` | Deep-dive explanation of a file/function | `references/commands.md#explain` |
+| `/understand-knowledge [dir]` | Analyze Karpathy-pattern LLM wiki | `references/commands.md#knowledge` |
+| `/understand-onboard` | Generate onboarding guide for new team members | `references/commands.md#onboard` |
+
+## Decision Tree
+
+**No graph exists yet** (no `.understand-anything/knowledge-graph.json`) → `/understand`
+→ read `references/pipeline.md` in full before proceeding.
+
+**Graph already exists:**
+- Question about how the codebase works → `/understand-chat`
+- Explain a specific file or function → `/understand-explain`
+- What a PR or set of changes touches → `/understand-diff`
+- Business flows and domain model → `/understand-domain`
+- Onboarding guide for new devs → `/understand-onboard`
+- Launch visual dashboard → `/understand-dashboard`
+- Input is a Karpathy LLM wiki (has `index.md` + `[[wikilinks]]`) → `/understand-knowledge`
+
+For all commands except `/understand`: read `references/commands.md` for full instructions.
+
+## Plugin Detection (Required Before Running /understand)
+
+The pipeline uses bundled Node.js + Python scripts. Resolve the plugin root first:
+
+```bash
+PLUGIN_ROOT=""
+for candidate in \
+  "${CLAUDE_PLUGIN_ROOT:-}" \
+  "$HOME/.understand-anything-plugin" \
+  "$HOME/.understand-anything/repo/understand-anything-plugin" \
+  "$HOME/.copilot/skills/../../../understand-anything/understand-anything-plugin" \
+  "$HOME/understand-anything/understand-anything-plugin"; do
+  if [ -n "$candidate" ] && [ -f "$candidate/package.json" ] && \
+     [ -f "$candidate/pnpm-workspace.yaml" ]; then
+    PLUGIN_ROOT="$candidate"; break
+  fi
+done
+```
+
+**Plugin found + `packages/core/dist/index.js` exists** → **Scripted mode** (fast, reliable). Skip LLM fallbacks.
+
+**Plugin found but not built** → Build once:
+```bash
+cd "$PLUGIN_ROOT" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install) && \
+  pnpm --filter @understand-anything/core build
+```
+Requires Node.js ≥ 22 and pnpm ≥ 10. If missing, tell the user and stop.
+
+**Plugin not found** → **LLM-native mode**. All phases run as pure LLM analysis without bundled scripts.
+Phases 1.5 (batch computation) and 7 (fingerprints) are skipped in LLM-native mode.
+
+## /understand Options
+
+| Flag | Effect |
+|---|---|
+| `--full` | Force full rebuild, ignoring existing graph |
+| `--review` | Run LLM graph reviewer (Phase 6) instead of inline deterministic validation |
+| `--auto-update` | Write `autoUpdate: true` to config (enables post-commit incremental updates) |
+| `--no-auto-update` | Write `autoUpdate: false` to config |
+| `--language <code>` | Output language for all text content: `en`, `zh`, `zh-TW`, `ja`, `ko`, `es`, `fr`, `de`, `ru`, `pt`, `ar` |
+| `<dir-path>` | Analyze given directory instead of current working directory |
+
+## Pipeline Phases Summary
+
+Read `references/pipeline.md` for full phase specifications.
+
+| # | Phase | Key Output |
+|---|---|---|
+| 0 | Pre-flight | Resolve `PROJECT_ROOT`, check for existing graph, incremental vs full decision |
+| 0.5 | Ignore config | Generate `.understandignore`, **wait for user confirmation** before proceeding |
+| 1 | Scan | File inventory, language/framework detection, import map |
+| 1.5 | Batch | Semantic batches for concurrent file analysis *(scripted mode only)* |
+| 2 | Analyze | Dispatch file-analyzer subagents (≤5 concurrent), merge results |
+| 3 | Assemble Review | Validate graph, fix dangling edges |
+| 4 | Architecture | Assign nodes to architectural layers (API, Service, Data, UI, Utility) |
+| 5 | Tour | Build dependency-ordered guided learning tour |
+| 6 | Review | Inline deterministic validation (default) or full LLM review (`--review`) |
+| 7 | Save | Write `knowledge-graph.json`, fingerprints, `meta.json`, clean intermediate |
+
+## Output Structure
+
+```
+.understand-anything/
+├── knowledge-graph.json      ← commit this
+├── meta.json                 ← commit this
+├── config.json               ← commit this
+├── .understandignore         ← commit this
+├── intermediate/             ← DO NOT commit (scratch)
+└── diff-overlay.json         ← DO NOT commit (local only)
+```
+
+## Graph Structure (Quick Reference)
+
+```
+knowledge-graph.json
+├── project: { name, description, languages[], frameworks[], analyzedAt, gitCommitHash }
+├── nodes[]: { id, type, name, filePath?, summary, tags[], complexity, languageNotes? }
+├── edges[]: { source, target, type, direction, weight }
+├── layers[]: { id, name, description, nodeIds[] }
+└── tour[]: { order, title, description, nodeIds[] }
+```
+
+Node ID convention: `<type>:<relative-path>[:<name>]` — e.g., `file:src/App.tsx`, `function:src/auth.ts:login`
+
+For full node types (13), edge types (26), and weight conventions → `references/graph-schema.md`
+
+## Error Handling (All Commands)
+
+- Retry failed subagent dispatches **once** with additional context about the failure
+- Always save partial results — a partial graph is better than no graph
+- Report all skipped phases and errors in the final summary; never drop failures silently
+- Track warnings in `$PHASE_WARNINGS` throughout and surface them in Phase 7 report

package/bundles/antigravity-plugin-extras/skills/understand-anything/references/commands.md

@@ -0,0 +1,252 @@
+# Sub-Command Instructions
+
+All commands below require `.understand-anything/knowledge-graph.json` to exist.
+If it doesn't, tell the user to run `/understand` first.
+
+## Efficient Graph Reading (All Commands)
+
+- **Never dump the full graph into context** — always search first
+- Use `grep -i "<term>"` in the graph file to find relevant entries
+- Read only sections you need: project metadata, matched nodes, connected edges, relevant layers
+- Node `summary` and `name` are the most useful fields for understanding
+- Edges reveal how components connect — follow `imports` and `calls` for dependency chains
+
+---
+
+<a name="chat"></a>
+## /understand-chat — Q&A About Codebase
+
+Answer questions about the codebase using the knowledge graph.
+
+**Steps:**
+1. Read project metadata only — grep or read the top few lines for `"project"` section
+2. Search for relevant nodes matching the user's query keywords:
+   - Search `"name"` fields: `grep -i "<keyword>" knowledge-graph.json`
+   - Search `"summary"` fields for semantic matches
+   - Search `"tags"` arrays for topic matches
+   - Note the `id` values of all matching nodes
+3. Find connected edges for each matched node ID:
+   - Grep for the ID to find outgoing (`"source"`) and incoming (`"target"`) edges
+   - This gives the 1-hop subgraph around the query
+4. Read layer context — grep for the matched node IDs in `"layers"` to find architectural context
+5. Answer using only the relevant subgraph:
+   - Reference specific files, functions, and relationships from the graph
+   - Explain which layers are relevant and why
+   - If query matches nothing, say so and suggest related terms from the graph
+
+---
+
+<a name="dashboard"></a>
+## /understand-dashboard — Launch Interactive Dashboard
+
+Start the interactive web dashboard for the knowledge graph.
+
+**Steps:**
+1. Resolve project directory from `$ARGUMENTS` (if provided) or use CWD
+2. Verify `$PROJECT_ROOT/.understand-anything/knowledge-graph.json` exists
+3. Resolve plugin root (same logic as main SKILL.md plugin detection)
+4. Start the dashboard:
+
+   **Scripted mode:**
+   ```bash
+   # Find dashboard server in plugin packages
+   DASHBOARD_DIST="$PLUGIN_ROOT/packages/dashboard/dist"
+   if [ ! -d "$DASHBOARD_DIST" ]; then
+     cd "$PLUGIN_ROOT" && pnpm --filter @understand-anything/dashboard build
+   fi
+   node "$PLUGIN_ROOT/packages/dashboard-server/bin/serve.js" \
+     --graph "$PROJECT_ROOT/.understand-anything/knowledge-graph.json" \
+     --port 8080
+   ```
+   Report: `Dashboard running at http://localhost:8080`
+
+   **LLM-native mode:** Report that the dashboard requires the plugin to be installed:
+   > The interactive dashboard requires the Understand Anything plugin.
+   > Install with: `curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s vscode`
+   > Then re-run `/understand-dashboard`.
+   > Alternatively, I can provide a text-based summary of the graph using `/understand-chat`.
+
+---
+
+<a name="diff"></a>
+## /understand-diff — Analyze Git Diff / PR Impact
+
+Analyze code changes against the knowledge graph to surface affected components and risk.
+
+**Steps:**
+1. Read project metadata (grep `"project"` section)
+2. Get changed files:
+   - Uncommitted changes: `git diff --name-only`
+   - Feature branch vs base: `git diff main...HEAD --name-only`
+   - User specifies branch or PR: use that
+3. Find nodes for each changed file — grep for `"filePath"` matching each changed path
+   - Captures file-level nodes AND function/class nodes defined in those files
+   - Note all matched node IDs as `$CHANGED_NODE_IDS`
+4. Find 1-hop connected nodes (affected components):
+   - For each changed node ID, grep for that ID in `"edges"` section
+   - Upstream: nodes where changed ID appears as `"target"` (they depend on it)
+   - Downstream: nodes where changed ID appears as `"source"` (it depends on them)
+   - Record as `$AFFECTED_NODE_IDS` (exclude `$CHANGED_NODE_IDS`)
+5. Identify affected layers — grep for matched IDs in `"layers"`
+6. Produce structured analysis:
+   - **Changed Components**: directly modified (with summaries from matched nodes)
+   - **Affected Components**: potentially impacted (from 1-hop edges), with relationship explanation
+   - **Affected Layers**: which architectural layers are touched, cross-layer concerns
+   - **Risk Assessment**: based on node `complexity`, number of cross-layer edges, blast radius
+   - Suggest what to review carefully; flag high-complexity affected nodes
+7. Write diff overlay (enables dashboard visualization):
+   ```json
+   // .understand-anything/diff-overlay.json
+   {
+     "version": "1.0.0",
+     "baseBranch": "<base>",
+     "generatedAt": "<ISO timestamp>",
+     "changedFiles": ["<paths>"],
+     "changedNodeIds": ["<ids>"],
+     "affectedNodeIds": ["<ids>"]
+   }
+   ```
+   Tell user they can run `/understand-dashboard` to see the overlay visually.
+
+---
+
+<a name="domain"></a>
+## /understand-domain — Extract Business Domain Flows
+
+Extract business domains, flows, and process steps from the codebase and add them to the graph.
+
+**When to derive from existing graph** (default): read `knowledge-graph.json`, extract domain concepts from node summaries and tags
+**When to do lightweight scan** (`--full` flag or no graph exists): file tree + entry point detection + sampled files
+
+**Steps:**
+1. Resolve `PROJECT_ROOT` (same logic as main skill)
+2. Check for `--full` flag or absence of `knowledge-graph.json`
+
+   **From existing graph** (fast path):
+   - Read nodes and their summaries, tags, and layer assignments
+   - Identify business domains by clustering nodes with related tags and summaries
+   - Extract flows: sequences of operations that accomplish a business goal
+   - Map each flow to its constituent nodes
+
+   **Lightweight scan** (`--full` or no graph):
+   - Run file discovery (reduced Phase 1): detect entry points, key files
+   - Sample representative files from each directory
+   - Analyze sampled files for business logic patterns
+
+3. For each domain/flow identified, dispatch `domain-analyzer` subagent (scripted) or analyze inline (LLM-native)
+
+4. Produce domain nodes:
+   - `domain` nodes: high-level business areas (e.g., `domain:authentication`, `domain:billing`)
+   - `flow` nodes: business processes (e.g., `flow:user-registration`)
+   - `step` nodes: individual steps within a flow (e.g., `step:validate-email`)
+
+5. Produce domain edges:
+   - `contains_flow`: domain → flow
+   - `flow_step`: flow → step (ordered)
+   - `related`: step → existing graph nodes that implement the step
+
+6. Merge domain nodes/edges into `knowledge-graph.json` (append, preserving existing nodes/edges)
+7. Report: domains found, flows extracted, steps mapped
+
+---
+
+<a name="explain"></a>
+## /understand-explain — Deep-Dive Explanation of a Component
+
+Provide a thorough explanation of a specific file, function, class, or module.
+
+**Steps:**
+1. Find the target node — grep `knowledge-graph.json` for `$ARGUMENTS` (path or name):
+   - File path match: search `"filePath"` fields
+   - Function notation (`file.ts:functionName`): search `"name"` filtered by file path
+   - Partial name: search `"name"` fields broadly
+   - Note the exact `id`, `type`, `summary`, `tags`, `complexity`
+2. Find all connected edges for the target node ID:
+   - Outgoing (`"source"` matches): what this node calls/imports/depends on
+   - Incoming (`"target"` matches): what calls/imports/depends on this node
+   - Note connected node IDs and edge types
+3. Read connected nodes (names, summaries, types) to build the component's neighborhood
+4. Identify the layer — grep target ID in `"layers"`
+5. Read the actual source file at the node's `filePath`
+6. Produce explanation:
+   - **Role in architecture**: which layer, why it exists, what problem it solves
+   - **Internal structure**: contained functions/classes (from `contains` edges)
+   - **External connections**: what it imports, what calls it, what it depends on
+   - **Data flow**: inputs → processing → outputs (from source code)
+   - **Patterns and complexity**: idioms, design patterns, areas worth careful attention
+   - Assume the reader may not know the programming language deeply
+
+---
+
+<a name="knowledge"></a>
+## /understand-knowledge — Analyze LLM Wiki Knowledge Base
+
+Analyze a Karpathy-pattern LLM wiki and produce a knowledge graph of entities, relationships, and topics.
+
+**Detection signals** (all should be present):
+- `index.md` exists with category structure
+- Multiple `.md` files with `[[wikilink]]` syntax
+- Optional: `raw/` directory with source documents
+- Optional: `log.md` chronological operation log
+- Optional: `CLAUDE.md`, `AGENTS.md`, or similar schema file
+
+**Steps:**
+1. Resolve wiki directory from `$ARGUMENTS` or CWD
+2. Detect the wiki structure:
+   - Parse `index.md` for categories and wikilink references
+   - Enumerate all `.md` files in the wiki
+   - Check for `raw/` directory (source documents)
+   - Read schema/config file if present
+
+3. **Phase: Deterministic extraction**
+   - Extract all explicit wikilinks from each wiki file: `[[target]]` → `related` edge
+   - Extract categories from `index.md`
+   - Build initial node list: one node per wiki file
+
+4. **Phase: LLM enrichment** (dispatch `article-analyzer` subagent or analyze inline)
+   For each wiki article:
+   - Extract named entities (people, places, concepts, technologies)
+   - Identify implicit relationships not captured by wikilinks
+   - Extract claims and their source references
+   - Identify topic clusters
+
+5. Produce knowledge graph nodes:
+   - `article` nodes: one per wiki file
+   - `entity` nodes: extracted named entities
+   - `topic` nodes: thematic clusters
+   - `claim` nodes: key assertions in the wiki
+   - `source` nodes: raw source documents (if `raw/` exists)
+
+6. Produce knowledge graph edges:
+   - `related`: wikilinks and implicit relationships
+   - `cites`: claim → source document
+   - `contains`: topic → article/entity
+
+7. Write `knowledge-graph.json` with full KnowledgeGraph structure
+8. Launch dashboard (if scripted mode available)
+
+---
+
+<a name="onboard"></a>
+## /understand-onboard — Generate Onboarding Guide
+
+Generate a comprehensive onboarding guide from the project's knowledge graph.
+
+**Steps:**
+1. Read project metadata (grep `"project"` section: name, description, languages, frameworks)
+2. Read layers — grep for `"layers"` to get full layer array with names and descriptions
+3. Read tour — grep for `"tour"` to get the ordered guided walkthrough steps
+4. Read file-level structural nodes only (skip function/class nodes for high-level guide):
+   - Types: `file`, `config`, `document`, `service`, `pipeline`, `table`, `schema`, `resource`, `endpoint`
+   - Extract `name`, `filePath`, `summary`, `complexity` for each
+5. Identify complexity hotspots — nodes with `complexity: "complex"` or `"high"`
+6. Generate onboarding guide as markdown with these sections:
+   - **Project Overview**: name, languages, frameworks, description
+   - **Architecture**: each layer's name, description, and key files
+   - **Key Concepts**: important patterns and design decisions (from node summaries and tags)
+   - **Guided Tour**: step-by-step walkthrough (from the `tour` section, ordered by `order`)
+   - **File Map**: what each key file does, organized by layer
+   - **Complexity Hotspots**: areas to approach carefully (from complexity values)
+   - **Getting Started**: how to run, configure, and contribute (from config/pipeline nodes)
+7. Offer to save as `docs/ONBOARDING.md` in the project
+8. Suggest committing it so the team benefits from it

package/bundles/antigravity-plugin-extras/skills/understand-anything/references/graph-schema.md

@@ -0,0 +1,116 @@
+# Knowledge Graph Schema Reference
+
+## Node Types (13 total)
+
+| Type | Description | ID Convention |
+|---|---|---|
+| `file` | Source code file | `file:<relative-path>` |
+| `function` | Function or method | `function:<relative-path>:<name>` |
+| `class` | Class, interface, or type | `class:<relative-path>:<name>` |
+| `module` | Logical module or package | `module:<name>` |
+| `concept` | Abstract concept or pattern | `concept:<name>` |
+| `config` | Config file (YAML, JSON, TOML, env) | `config:<relative-path>` |
+| `document` | Docs file (Markdown, RST, TXT) | `document:<relative-path>` |
+| `service` | Deployable service (Dockerfile, K8s) | `service:<relative-path>` |
+| `table` | Database table or migration | `table:<relative-path>:<table-name>` |
+| `endpoint` | API endpoint or route | `endpoint:<relative-path>:<endpoint-name>` |
+| `pipeline` | CI/CD pipeline config | `pipeline:<relative-path>` |
+| `schema` | Schema definition (GraphQL, Protobuf, Prisma) | `schema:<relative-path>` |
+| `resource` | Infrastructure resource (Terraform, CloudFormation) | `resource:<relative-path>` |
+
+**File-level types** (assigned to layers, used in tour):
+`file`, `config`, `document`, `service`, `table`, `endpoint`, `pipeline`, `schema`, `resource`
+
+**Sub-file types** (not assigned to layers):
+`function`, `class`, `module`, `concept`
+
+**Domain/knowledge types** (used by `/understand-knowledge` and `/understand-domain`):
+`domain`, `flow`, `step`, `article`, `entity`, `topic`, `claim`, `source`
+
+## Node Fields
+
+| Field | Required | Description |
+|---|---|---|
+| `id` | ✓ | Unique identifier (type-prefixed) |
+| `type` | ✓ | One of the 13 types above |
+| `name` | ✓ | Display name |
+| `summary` | ✓ | Plain-English description |
+| `tags` | ✓ | Array of topic strings |
+| `filePath` | ✓ (file-level) | Relative path from project root |
+| `complexity` | — | `simple`, `moderate`, or `complex` |
+| `languageNotes` | — | Language-specific idioms worth noting |
+| `languageLesson` | — | Teaching note for the guided tour |
+
+## Edge Types (26 total)
+
+| Category | Types |
+|---|---|
+| Structural | `imports`, `exports`, `contains`, `inherits`, `implements` |
+| Behavioral | `calls`, `subscribes`, `publishes`, `middleware` |
+| Data flow | `reads_from`, `writes_to`, `transforms`, `validates` |
+| Dependencies | `depends_on`, `tested_by`, `configures` |
+| Semantic | `related`, `similar_to` |
+| Infrastructure | `deploys`, `serves`, `provisions`, `triggers` |
+| Schema/Data | `migrates`, `documents`, `routes`, `defines_schema` |
+| Knowledge graph | `contains_flow`, `flow_step`, `cites` |
+
+## Edge Fields
+
+| Field | Description |
+|---|---|
+| `source` | Source node ID |
+| `target` | Target node ID |
+| `type` | One of the 26 edge types |
+| `direction` | `outgoing` (source→target) or `incoming` |
+| `weight` | 0.0–1.0 relevance weight |
+
+## Edge Weight Conventions
+
+| Type | Weight |
+|---|---|
+| `contains` | 1.0 |
+| `inherits`, `implements` | 0.9 |
+| `calls`, `exports`, `defines_schema` | 0.8 |
+| `imports`, `deploys`, `migrates` | 0.7 |
+| `depends_on`, `configures`, `triggers` | 0.6 |
+| `tested_by`, `documents`, `provisions`, `serves`, `routes` | 0.5 |
+| All others | 0.5 (default) |
+
+## Architecture Layers (Standard)
+
+Typical layer assignments (may vary by project):
+
+| Layer | Description | Typical types |
+|---|---|---|
+| `layer:api` | API endpoints, controllers, routes | `endpoint`, `file` |
+| `layer:service` | Business logic, services | `file`, `function`, `class` |
+| `layer:data` | Database access, models, migrations | `table`, `file`, `schema` |
+| `layer:ui` | UI components, views, styles | `file` |
+| `layer:utility` | Shared utilities, helpers, types | `file`, `module`, `concept` |
+| `layer:config` | Configuration, environment | `config` |
+| `layer:infra` | Infrastructure, CI/CD, containers | `service`, `pipeline`, `resource` |
+| `layer:docs` | Documentation | `document` |
+
+## Graph-Level Structure
+
+```json
+{
+  "version": "1.0.0",
+  "project": {
+    "name": "string",
+    "description": "string",
+    "languages": ["string"],
+    "frameworks": ["string"],
+    "analyzedAt": "ISO 8601",
+    "gitCommitHash": "string"
+  },
+  "nodes": [/* GraphNode objects */],
+  "edges": [/* GraphEdge objects */],
+  "layers": [
+    { "id": "layer:<name>", "name": "string", "description": "string", "nodeIds": ["string"] }
+  ],
+  "tour": [
+    { "order": 1, "title": "string", "description": "string", "nodeIds": ["string"], "languageLesson?": "string" }
+  ]
+}
+```