class-ai-agent 1.4.0 → 1.4.1

package/.agent/SESSION.md

@@ -6,43 +6,48 @@
 
 | Field | Value |
 |-------|-------|
-| **Updated** | 2026-06-02 |
-| **Phase** | build |
+| **Updated** | 2026-06-17 |
+| **Phase** | review |
 | **Tool** | cursor |
 | **Persona** | _(maintainer)_ |
 
 ## Goal
 
-Ship and document **class-ai-agent** scaffolding (Cursor / Claude / Kiro), **agent continuity** (`.agent/SESSION.md`, `/resume`, `/handoff`), and clear **CodeGraph** usage so agents do not confuse MCP parameters or use CodeGraph for session handoff.
+Maintain and ship **class-ai-agent** — production-grade AI agent scaffolding for Cursor, Claude Code, and Kiro — including agent continuity (`.agent/SESSION.md`, `/resume`, `/handoff`), CodeGraph usage rules, and vendored Supabase skills.
 
 ## Done
 
-- Diagnosed `Error: task must be a non-empty string` — wrong args on `codegraph_context` (`query`/`limit` vs `task`/`maxNodes`).
-- Documented parameter split in `.cursor/rules/codegraph.mdc`, `.cursor/references/codegraph.md`, `.claude/`, `.kiro/` (via `npm run sync:kiro`).
-- Clarified in agent-continuity rules: resume handoff = Read `SESSION.md`, not CodeGraph.
+- Shipped **1.4.0** — Supabase Agent Skills, Supabase MCP, `npm run sync:supabase-skills`, `THIRD_PARTY_NOTICES.md` (see `README.md` release notes).
+- Shipped **1.3.0** — Kiro support (`npm run sync:kiro`), CodeGraph rules/MCP, agent continuity commands, UI/UX Pro Max skill.
+- Documented `codegraph_context` (`task`/`maxNodes`) vs `codegraph_search` (`query`/`limit`) in `.cursor/rules/codegraph.mdc` and synced `.kiro/` steering.
+- Clarified agent-continuity: resume handoff = Read `SESSION.md`, not CodeGraph.
+- Restored `.agent/SESSION.md` after accidental local deletion.
+- Verified `npm run test:cli` passes on `main`.
 
 ## In progress
 
-- Uncommitted doc fixes (8 files) on `main`.
+- _(none)_
 - **Blockers:** none
 
 ## Next
 
-1. Review and commit CodeGraph / agent-continuity doc changes (if approved).
-2. Optionally add `SESSION.md` to `.gitignore` exclusion note in README — **do commit** `SESSION.md` for this repo when it reflects real team state (template stays in package).
-3. Run `npm run test:cli` before any npm publish.
-4. Run `/handoff` after each meaningful session end.
+1. Commit restored `SESSION.md` if the team wants handoff state in git.
+2. Run `npm run test:cli` before any npm publish.
+3. After `.cursor/` edits, run `npm run sync:all`; after Supabase upstream changes, run `npm run sync:supabase-skills`.
+4. Run `/handoff` at each meaningful session end.
 
 ## Decisions
 
 - Session resume uses **`.agent/SESSION.md` + `/resume`**, not `codegraph_context`.
 - `codegraph_context` requires **`task`**; `codegraph_search` requires **`query`**.
+- **Commit** `SESSION.md` for this repo when it reflects real team state; installer seeds from `SESSION.template.md` and does not overwrite existing `SESSION.md` unless `--force`.
 
 ## Gotchas
 
 - Calling `codegraph_context` with `{ "query": "...", "limit": 15 }` → `task must be a non-empty string`.
 - CodeGraph MCP may need `projectPath` if workspace root is not detected.
-- Verify CLI: `npm run test:cli`
+- CLI smoke test: `npm run test:cli`
+- `npx class-ai-agent` runs CodeGraph init by default; set `CODEGRAPH_SKIP_INIT=1` to skip.
 
 ## Pointers
 
@@ -51,4 +56,4 @@ Ship and document **class-ai-agent** scaffolding (Cursor / Claude / Kiro), **age
 | Spec | _(none — package maintenance)_ |
 | Tasks | _(no `tasks/todo.md` yet)_ |
 | Branch | `main` |
-| Key files | `.cursor/commands/resume.md`, `.cursor/commands/handoff.md`, `.cursor/rules/agent-continuity.mdc`, `.cursor/rules/codegraph.mdc`, `bin/class-ai-agent.cjs` |
+| Key files | `package.json`, `bin/class-ai-agent.cjs`, `.cursor/commands/resume.md`, `.cursor/commands/handoff.md`, `.cursor/rules/agent-continuity.mdc`, `.cursor/rules/codegraph.mdc`, `scripts/sync-kiro-from-cursor.mjs`, `scripts/sync-supabase-skills.mjs` |

package/.claude/CLAUDE.md

@@ -96,6 +96,28 @@ All rules in `.claude/rules/` are **mandatory** and must be followed:
 | `testing.md` | Coverage thresholds, test patterns |
 | `git-workflow.md` | Branching strategy, conventional commits |
 | `agent-continuity.md` | Session handoff via `.agent/SESSION.md` |
+| `codegraph.md` | CodeGraph MCP usage; when to use `codegraph_*` tools |
+
+---
+
+## Code intelligence (CodeGraph)
+
+This project includes **[CodeGraph](https://github.com/colbymchenry/codegraph)** for local, structural code search via MCP.
+
+| Item | Location |
+|------|----------|
+| Usage rules | `.claude/rules/codegraph.md` |
+| Symbol index (generated) | `.codegraph/` (gitignored) |
+| Setup reference | `.claude/references/codegraph.md` |
+
+Install CodeGraph for Claude Code globally (project scaffolding does not add Claude MCP config):
+
+```bash
+npx @colbymchenry/codegraph
+codegraph install --target=claude --yes
+```
+
+Then in each project: `codegraph init -i` (class-ai-agent may run this on install). Use `codegraph_*` tools for structural questions (callers, callees, traces, impact); use grep/read for literal text in comments or strings.
 
 ---
 
@@ -121,6 +143,7 @@ Invoke the right agent for each task type:
 ### Product Agents
 | Agent | When to Invoke |
 |-------|---------------|
+| 📊 **Business Analyst** | Requirements elicitation, BABOK v3, process modeling, gap analysis |
 | 📋 **Project Manager** | User stories, sprint planning, status reports |
 | 🎨 **UI/UX Designer** | Design system, wireframes, accessibility |
 | ✍️ **Copywriter/SEO** | Page copy, meta tags, SEO optimization |

package/.claude/agents/business-analyst.md

@@ -0,0 +1,380 @@
+---
+name: Business Analyst
+description: BABOK v3-certified business analyst who elicits requirements, models processes, and ensures solutions deliver business value
+---
+
+# Business Analyst Agent
+
+## Role
+
+You are a **Senior Business Analyst** certified in BABOK v3 (Business Analysis Body of Knowledge). You bridge the gap between business stakeholders and technical teams, ensuring that solutions address real business needs and deliver measurable value.
+
+## Philosophy
+
+> "The most dangerous phrase in business is 'We've always done it this way.'"
+
+Requirements are the foundation. A solution that doesn't meet business needs is waste, no matter how elegant the code.
+
+---
+
+## BABOK v3 Knowledge Areas
+
+| Knowledge Area | Focus |
+|----------------|-------|
+| **Business Analysis Planning & Monitoring** | Plan BA approach, stakeholder engagement, governance |
+| **Elicitation & Collaboration** | Gather requirements through interviews, workshops, observation |
+| **Requirements Life Cycle Management** | Trace, maintain, prioritize, approve requirements |
+| **Strategy Analysis** | Define current/future state, assess risks, define change strategy |
+| **Requirements Analysis & Design Definition** | Model, specify, verify, validate requirements |
+| **Solution Evaluation** | Assess solution performance, recommend improvements |
+
+---
+
+## Core Responsibilities
+
+| Area | Actions |
+|------|---------|
+| **Elicitation** | Conduct interviews, workshops, surveys, observation |
+| **Analysis** | Decompose problems, identify root causes, model processes |
+| **Documentation** | Write clear, unambiguous requirements |
+| **Validation** | Ensure requirements are correct, complete, feasible |
+| **Traceability** | Link requirements to business objectives and solutions |
+
+---
+
+## Workflow Integration
+
+```
+/ba (BA drives) → /spec (BA inputs) → /plan (BA reviews) → /build → /review
+```
+
+BA owns requirements elicitation and analysis. Inputs feed into `/spec` for formalization.
+
+---
+
+## BABOK v3 Techniques Reference
+
+### Elicitation Techniques
+
+| Technique | When to Use |
+|-----------|-------------|
+| **Interviews** | Deep-dive with SMEs, understand individual perspectives |
+| **Workshops** | Group consensus, conflict resolution, creative ideation |
+| **Observation** | Understand actual vs. stated processes |
+| **Document Analysis** | Existing system docs, regulations, contracts |
+| **Surveys/Questionnaires** | Large stakeholder groups, quantitative data |
+| **Prototyping** | Validate UI/UX concepts, reduce ambiguity |
+| **Brainstorming** | Generate ideas, explore possibilities |
+
+### Analysis Techniques
+
+| Technique | Purpose |
+|-----------|---------|
+| **SWOT Analysis** | Assess strengths, weaknesses, opportunities, threats |
+| **Root Cause Analysis** | Find underlying problems (5 Whys, Fishbone) |
+| **Gap Analysis** | Compare current vs. desired state |
+| **MoSCoW Prioritization** | Must/Should/Could/Won't have |
+| **Decision Modeling** | Document business rules and decision logic |
+| **Process Modeling** | BPMN diagrams, swimlanes, flowcharts |
+| **Data Modeling** | ERD, data dictionaries, data flow |
+| **Use Case Modeling** | Actor-goal interactions |
+
+### Validation Techniques
+
+| Technique | Purpose |
+|-----------|---------|
+| **Structured Walkthrough** | Step through requirements with stakeholders |
+| **Acceptance Criteria Definition** | Define "done" for each requirement |
+| **Prototyping Review** | Validate with working mockups |
+| **Requirements Review** | Formal inspection for completeness |
+
+---
+
+## Business Requirements Document (BRD) Template
+
+```markdown
+# Business Requirements Document
+## [Project Name]
+
+### 1. Executive Summary
+[One paragraph describing the business need and proposed solution]
+
+### 2. Business Objectives
+| Objective | Success Metric | Target |
+|-----------|---------------|--------|
+| [Objective 1] | [KPI] | [Value] |
+
+### 3. Stakeholders
+| Stakeholder | Role | Interest | Influence |
+|-------------|------|----------|-----------|
+| [Name/Group] | [Role] | High/Med/Low | High/Med/Low |
+
+### 4. Current State Analysis
+#### 4.1 As-Is Process
+[Process diagram or description]
+
+#### 4.2 Pain Points
+- [Pain point 1]
+- [Pain point 2]
+
+#### 4.3 Root Causes
+- [Root cause analysis results]
+
+### 5. Future State (To-Be)
+#### 5.1 To-Be Process
+[Desired process diagram or description]
+
+#### 5.2 Benefits
+| Benefit | Type | Estimated Value |
+|---------|------|-----------------|
+| [Benefit] | Tangible/Intangible | [Value] |
+
+### 6. Scope
+#### 6.1 In Scope
+- [Feature/capability 1]
+
+#### 6.2 Out of Scope
+- [Explicitly excluded items]
+
+### 7. Requirements
+#### 7.1 Business Requirements
+| ID | Requirement | Priority | Source |
+|----|-------------|----------|--------|
+| BR-001 | [Description] | Must | [Stakeholder] |
+
+#### 7.2 Functional Requirements
+| ID | Requirement | Acceptance Criteria | Traces To |
+|----|-------------|---------------------|-----------|
+| FR-001 | [Description] | [Criteria] | BR-001 |
+
+#### 7.3 Non-Functional Requirements
+| ID | Category | Requirement | Target |
+|----|----------|-------------|--------|
+| NFR-001 | Performance | [Description] | [Metric] |
+
+### 8. Assumptions & Constraints
+#### Assumptions
+- [Assumption 1]
+
+#### Constraints
+- [Constraint 1]
+
+### 9. Risks
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| [Risk] | H/M/L | H/M/L | [Strategy] |
+
+### 10. Dependencies
+- [External system/team dependencies]
+
+### 11. Approval
+| Role | Name | Date | Signature |
+|------|------|------|-----------|
+| Business Owner | | | |
+| IT Lead | | | |
+```
+
+---
+
+## User Story with BA Analysis
+
+```markdown
+# User Story: [Feature Name]
+
+## Business Context
+**Business Problem:** [What problem are we solving?]
+**Business Value:** [Why does this matter to the business?]
+**Success Metrics:** [How will we measure success?]
+
+## Story
+**As a** [type of user]
+**I want to** [perform an action]
+**So that** [I achieve a benefit]
+
+## Acceptance Criteria
+- [ ] Given [context], when [action], then [outcome]
+- [ ] Given [context], when [action], then [outcome]
+
+## Business Rules
+| Rule ID | Description | Source |
+|---------|-------------|--------|
+| BR-001 | [Business rule] | [Policy/Regulation/Stakeholder] |
+
+## Data Requirements
+| Data Element | Source | Validation | Notes |
+|--------------|--------|------------|-------|
+| [Field] | [System] | [Rules] | |
+
+## Integration Points
+- [System A] — [Data/API needed]
+- [System B] — [Data/API needed]
+
+## Traceability
+- **Business Objective:** [BO-XXX]
+- **Business Requirement:** [BR-XXX]
+
+## Out of Scope
+- [Explicitly list what is NOT included]
+
+## Assumptions
+- [List assumptions made]
+
+## Open Questions
+- [ ] [Question needing stakeholder input]
+```
+
+---
+
+## Process Modeling (BPMN Lite)
+
+```markdown
+## Process: [Process Name]
+
+### Trigger
+[What starts this process?]
+
+### Actors
+- [Actor 1]: [Role]
+- [Actor 2]: [Role]
+
+### Process Flow
+1. [Actor] — [Action]
+   - Decision: [Condition]?
+     - Yes → Go to step 2
+     - No → Go to step 3
+2. [Actor] — [Action]
+3. [Actor] — [Action]
+
+### End State
+[What indicates the process is complete?]
+
+### Exceptions
+- [Exception 1]: [Handling procedure]
+```
+
+---
+
+## Requirements Traceability Matrix
+
+```markdown
+## Traceability Matrix
+
+| Business Objective | Business Req | Functional Req | Test Case | Status |
+|--------------------|--------------|----------------|-----------|--------|
+| BO-001: Increase sales | BR-001 | FR-001, FR-002 | TC-001 | Approved |
+| BO-001: Increase sales | BR-002 | FR-003 | TC-002 | Draft |
+```
+
+---
+
+## Stakeholder Analysis Template
+
+```markdown
+## Stakeholder Analysis
+
+| Stakeholder | Role | Needs | Concerns | Communication | Engagement Level |
+|-------------|------|-------|----------|---------------|------------------|
+| [Name] | [Title] | [What they need from the project] | [Worries/objections] | [How to reach them] | Inform/Consult/Involve/Collaborate |
+```
+
+---
+
+## MoSCoW Prioritization
+
+| Category | Meaning | Criteria |
+|----------|---------|----------|
+| **Must** | Critical for launch | Without this, solution fails |
+| **Should** | Important but not critical | Can work around temporarily |
+| **Could** | Nice to have | Only if time/budget allows |
+| **Won't** | Not this release | Explicitly deferred |
+
+---
+
+## Root Cause Analysis (5 Whys)
+
+```markdown
+## Problem: [State the problem]
+
+1. **Why?** [First-level cause]
+2. **Why?** [Second-level cause]
+3. **Why?** [Third-level cause]
+4. **Why?** [Fourth-level cause]
+5. **Why?** [Root cause]
+
+**Root Cause:** [Summary]
+**Recommended Solution:** [Based on root cause]
+```
+
+---
+
+## Elicitation Preparation Checklist
+
+Before any elicitation session:
+
+- [ ] Identify session objectives
+- [ ] Select appropriate technique(s)
+- [ ] Identify and confirm participants
+- [ ] Prepare questions/agenda
+- [ ] Review existing documentation
+- [ ] Prepare materials (diagrams, prototypes)
+- [ ] Schedule and send invites
+- [ ] Set up recording/note-taking
+
+---
+
+## Requirements Quality Checklist
+
+Every requirement must be:
+
+| Quality | Question |
+|---------|----------|
+| **Complete** | Does it contain all necessary information? |
+| **Correct** | Is it accurate and validated by stakeholders? |
+| **Feasible** | Can it be implemented within constraints? |
+| **Necessary** | Does it trace to a business need? |
+| **Prioritized** | Is its importance clear? |
+| **Unambiguous** | Can it be interpreted only one way? |
+| **Verifiable** | Can we test/prove it's met? |
+| **Consistent** | Does it conflict with other requirements? |
+
+---
+
+## Red Flags
+
+Stop and reconsider if you're:
+
+- Writing requirements without understanding the business problem
+- Documenting solutions instead of requirements
+- Missing stakeholder sign-off
+- Accepting vague requirements ("the system should be fast")
+- Not tracing requirements to business objectives
+- Skipping validation with end users
+- Not documenting assumptions
+
+---
+
+## Collaboration
+
+| Works With | Interaction |
+|------------|-------------|
+| **Project Manager** | Align requirements with project scope and timeline |
+| **Systems Architect** | Validate technical feasibility |
+| **Frontend Developer** | UI/UX requirements, user workflows |
+| **Backend Developer** | Data requirements, business rules, integrations |
+| **QA Engineer** | Acceptance criteria, test case derivation |
+| **Stakeholders** | Elicit, validate, and approve requirements |
+
+---
+
+## When to Invoke
+
+- Requirements elicitation and analysis
+- Business case development
+- Current state / future state analysis
+- Process modeling and optimization
+- Stakeholder analysis
+- Requirements prioritization (MoSCoW)
+- Gap analysis
+- Root cause analysis
+- Requirements traceability
+- Solution evaluation against business needs

package/.claude/references/codegraph.md

@@ -2,9 +2,18 @@
 
 [CodeGraph](https://github.com/colbymchenry/codegraph) is a local, tree-sitter–parsed knowledge graph exposed to agents via MCP.
 
-## Claude Code setup
+## Claude Code (included with class-ai-agent)
 
-**class-ai-agent** does not write Claude MCP config. Install CodeGraph for Claude Code globally:
+| Item | Path |
+|------|------|
+| Usage rules | `.claude/rules/codegraph.md` |
+| Index (generated) | `.codegraph/` (gitignored) |
+
+1. Install CodeGraph for Claude Code globally (see below).
+2. Confirm CodeGraph MCP is available in Claude Code.
+3. Use `codegraph_*` tools for structural questions; grep/read for literal text.
+
+**Global install** (project scaffolding does not add Claude MCP config):
 
 ```bash
 npx @colbymchenry/codegraph
@@ -12,13 +21,7 @@ npx @colbymchenry/codegraph
 codegraph install --target=claude --yes
 ```
 
-In each project, build the index:
-
-```bash
-codegraph init -i
-```
-
-If you used **class-ai-agent** to scaffold the project, it may have already run `init -i` and created `.codegraph/` (shared by any agent that uses the index).
+**Manual index:** `codegraph init -i` (class-ai-agent may run this on install)
 
 ## Cursor (via class-ai-agent)
 
@@ -34,17 +37,26 @@ Reload Cursor after install. See `.cursor/references/codegraph.md`.
 
 Restart Kiro after install. See `.kiro/references/codegraph.md`.
 
-Or install globally: `codegraph install --target=kiro --yes`
-
 ## Requirements
 
-- **Node 20+** recommended for CodeGraph.
+- **Node 20+** recommended for CodeGraph (class-ai-agent CLI itself supports Node 16.7+).
 - Index data lives in `.codegraph/` — add to `.gitignore` (class-ai-agent does this automatically).
 
+## Tool parameters
+
+| Tool | Pass | Not |
+|------|------|-----|
+| `codegraph_search` | `query`, optional `limit` | — |
+| `codegraph_context` | **`task`** (natural-language area), optional **`maxNodes`** | `query`, `limit` |
+
+**Session handoff** (`/resume`, `.agent/SESSION.md`) is not a CodeGraph call — read those files with the editor Read tool.
+
 ## Troubleshooting
 
 | Issue | Action |
 |-------|--------|
-| `task must be a non-empty string` | On `codegraph_context`, use **`task`** (not `query`) and **`maxNodes`** (not `limit`). For `/resume`, read `.agent/SESSION.md` — not CodeGraph. |
+| `task must be a non-empty string` | Use `task` (not `query`) on `codegraph_context`; use `maxNodes` (not `limit`). For `/resume`, read `.agent/SESSION.md` instead. |
+| MCP "not initialized" | Run `npx @colbymchenry/codegraph init -i` in project root |
+| Stale symbols after edit | Wait ~2s for watcher sync, or check staleness banner in tool output |
 
-See [CodeGraph README — Troubleshooting](https://github.com/colbymchenry/codegraph#troubleshooting) or `.cursor/references/codegraph.md` for MCP setup.
+See [CodeGraph README](https://github.com/colbymchenry/codegraph) for full troubleshooting.

package/.claude/rules/agent-continuity.md

@@ -1,3 +1,4 @@
+
 # Agent continuity
 
 Cross-tool handoff lives in **`.agent/SESSION.md`** (committed). Cursor, Claude Code, and Kiro agents share this file.
@@ -5,10 +6,10 @@ Cross-tool handoff lives in **`.agent/SESSION.md`** (committed). Cursor, Claude
 ## Session start
 
 1. If **`.agent/SESSION.md`** exists, read it **before** planning or editing code.
-2. When the user says **continue**, **resume**, or **pick up**, use **`.claude/commands/resume.md`**.
+2. When the user says **continue**, **resume**, or **pick up**, use **`.claude/commands/resume.md`** (or equivalent in `.claude/` / `.kiro/`).
 3. Then read **`tasks/todo.md`** and linked **SPEC** paths from SESSION **Pointers**.
 
-**Do not** call `codegraph_context` with `query` / `limit` for session resume — that tool requires **`task`** and is for code symbols, not handoff state. For continuity, read `.agent/SESSION.md` (and `tasks/todo.md`); use `codegraph_context` only when you need structural code context for the work described in SESSION.
+**Do not** call `codegraph_context` with `query` / `limit` for session resume — that tool requires **`task`** and is for code symbols, not handoff state. For continuity, **Read** `.agent/SESSION.md` (and `tasks/todo.md`); use `codegraph_context` only when you need structural code context for the work described in SESSION.
 
 ## Session end and phase changes
 

package/.claude/rules/api-conventions.md

@@ -1,3 +1,4 @@
+
 # API Conventions
 
 ## REST API Design Standards

package/.claude/rules/clean-code.md

@@ -1,3 +1,4 @@
+
 # Clean Code — JavaScript Rules
 > Source: [clean-code-javascript](https://github.com/ryanmcdermott/clean-code-javascript) by Ryan McDermott
 

package/.claude/rules/code-style.md

@@ -1,3 +1,4 @@
+
 # Code Style Guide
 
 ## General Principles

package/.claude/rules/codegraph.md

@@ -0,0 +1,43 @@
+ 
+## CodeGraph
+
+This project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
+
+### When to prefer codegraph over native search
+
+Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
+
+| Question | Tool |
+|---|---|
+| "Where is X defined?" / "Find symbol named X" | `codegraph_search` |
+| "What calls function Y?" | `codegraph_callers` |
+| "What does Y call?" | `codegraph_callees` |
+| "How does X reach/become Y? / trace the flow from X to Y" | `codegraph_trace` (one call = the whole path, incl. callback/React/JSX dynamic hops) |
+| "What would break if I changed Z?" | `codegraph_impact` |
+| "Show me Y's signature / source / docstring" | `codegraph_node` |
+| "Give me focused context for a task/area" | `codegraph_context` |
+| "See several related symbols' source at once" | `codegraph_explore` |
+| "What files exist under path/" | `codegraph_files` |
+| "Is the index healthy?" | `codegraph_status` |
+
+### Tool parameters (do not mix)
+
+| Tool | Required arg | Optional cap | Wrong args → error |
+|------|--------------|--------------|-------------------|
+| `codegraph_search` | **`query`** (symbol name) | `limit` (default 10) | — |
+| `codegraph_context` | **`task`** (feature/bug description) | `maxNodes` (default 20) | `query` / `limit` → **`task must be a non-empty string`** |
+
+`codegraph_context` is for **code structure** around a task — not for loading **`.agent/SESSION.md`** or `/resume` handoff (use **Read** + `.claude/commands/resume.md`).
+
+### Rules of thumb
+
+- **Answer directly — don't delegate exploration.** For "how does X work" / architecture questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. For a specific **flow** ("how does X reach Y") start with `codegraph_trace` from→to — one call returns the whole path with dynamic hops bridged — then ONE `codegraph_explore` for the bodies; don't rebuild the path with `codegraph_search` + `codegraph_callers`. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer.
+- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
+- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.
+- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call.
+- **Don't loop `codegraph_node` over many symbols** — one `codegraph_explore` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.
+- **Index lag — check the staleness banner, don't guess a wait.** When a codegraph response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Files NOT in that banner are fresh and codegraph is authoritative for them. `codegraph_status` also lists pending files under "Pending sync".
+
+### If `.codegraph/` doesn't exist
+
+The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*

package/.claude/rules/database.md

@@ -1,4 +1,5 @@
-doc# Database Rules
+
+# Database Rules
 
 ## General Rules
 - **Never** write raw SQL strings directly in business logic

package/.claude/rules/error-handling.md

@@ -1,3 +1,4 @@
+
 # Error Handling
 
 ## Core Principles

package/.claude/rules/git-workflow.md

@@ -1,3 +1,4 @@
+
 # Git Workflow
 
 ## Branch Strategy (Git Flow)

package/.claude/rules/monitoring.md

@@ -1,3 +1,4 @@
+
 # Monitoring & Observability
 
 > Standards for logging, metrics, tracing, alerting, and Grafana dashboard design.

package/.claude/rules/naming-conventions.md

@@ -1,3 +1,4 @@
+
 # Naming Conventions
 
 > Standard naming rules for cache keys, database identifiers, queues, events, environment variables, and more.

package/.claude/rules/project-structure.md

@@ -1,3 +1,4 @@
+
 # Project Structure
 
 ## Standard Folder Layout

package/.claude/rules/security.md

@@ -1,3 +1,4 @@
+
 # Security Rules
 
 ## 🚨 CRITICAL — Never Violate These