docs: add agent guidance + codegraph rules

.codegraph/.gitignore

@@ -0,0 +1,16 @@
+# CodeGraph data files
+# These are local to each machine and should not be committed
+
+# Database
+*.db
+*.db-wal
+*.db-shm
+
+# Cache
+cache/
+
+# Logs
+*.log
+
+# Hook markers
+.dirty

.cursor/rules/codegraph.mdc

@@ -0,0 +1,39 @@
+---
+description: CodeGraph MCP usage guide — when to use which tool
+alwaysApply: true
+---
+<!-- CODEGRAPH_START -->
+## 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` |
+
+### 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**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn.
+
+### 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?"*
+<!-- CODEGRAPH_END -->

products/beautify-FT.md

@@ -0,0 +1,16 @@
+Use the Figma frame below as the source of truth.
+
+Figma frame:
+https://www.figma.com/design/SoM5WFNLtI087WnxNutKHL/MyTodos?node-id=0-1&p=f&t=jfNpRjKeJGLPaEKZ-0
+
+Refactor the frontend to improve the UI.
+
+Requirements:
+- Match layout, spacing, typography, colors and border radius from Figma
+- Use shadcn/ui Card, Button, Table and Badge
+- Use lucide-react icons
+- Use Recharts for charts
+- Keep components reusable
+- Create components under src/components/dashboard
+- Avoid putting everything in App.tsx
+- Make the layout responsive

reference/agents.guide.md

@@ -0,0 +1,43 @@
+# agents.md generation guide
+
+## Steps to generate agents.md
+
+### Step 1 — Read the Repository
+
+- Read these files first:
+- README.md
+- package.json / pom.xml / pyproject.toml
+- docker-compose.yml
+- CI workflows
+- src/ structure
+- test/ structure
+- docs/
+- ADR documents
+- architecture diagrams
+
+### Step 2 — Extract Core Information
+
+Extract:
+
+- Tech stack
+- Startup commands
+- Build commands
+- Testing commands
+- Architecture layers
+- Core business modules
+- Restricted areas
+- Coding conventions
+- Deployment process
+
+### Step 3 — Generate the Instruction Layers
+
+Usually:
+
+- Root-level AGENTS.md
+- For large monorepos or platform systems:
+- frontend/AGENTS.md
+- backend/AGENTS.md
+- services/payment/AGENTS.md
+- packages/ui/AGENTS.md
+- This hierarchical instruction model works extremely well for AI-native engineering systems.
+

reference/agents.template.md

@@ -0,0 +1,29 @@
+## 1. Project Overview
+What the project does, core business goals, major tech stack.
+
+## 2. Repository Structure
+Directory layout and responsibilities of each module.
+
+## 3. Setup & Commands
+Install, start, test, build, lint, and typecheck commands.
+
+## 4. Architecture Rules
+Layering rules, dependency directions, module boundaries, forbidden patterns.
+
+## 5. Coding Standards
+Naming, formatting, error handling, logging, typing, comments.
+
+## 6. Testing Rules
+Unit tests, integration tests, E2E tests, mocking, coverage expectations.
+
+## 7. Agent Workflow
+What AI agents must do before and after changing code.
+
+## 8. Domain Rules
+Business workflows, permissions, state transitions, consistency guarantees.
+
+## 9. Security & Privacy
+Secrets, redaction, authorization, validation rules.
+
+## 10. PR Checklist
+Checklist before opening a pull request.