AGENTS.md

1# Before starting work
2 
3- Run `lat search` to find sections relevant to your task. Read them to understand the design intent before writing code.
4- Run `lat expand` on user prompts to expand any `[[refs]]` — this resolves section names to file locations and provides context.
5 
6# Post-task checklist (REQUIRED — do not skip)
7 
8After EVERY task, before responding to the user:
9 
10- [ ] Update `lat.md/` if you added or changed any functionality, architecture, tests, or behavior
11- [ ] Run `lat check` — all wiki links and code refs must pass
12- [ ] Do not skip these steps. Do not consider your task done until both are complete.
13 
14---
15 
16# What is lat.md?
17 
18This project uses [lat.md](https://www.npmjs.com/package/lat.md) to maintain a structured knowledge graph of its architecture, design decisions, and test specs in the `lat.md/` directory. It is a set of cross-linked markdown files that describe **what** this project does and **why** — the domain concepts, key design decisions, business logic, and test specifications. Use it to ground your work in the actual architecture rather than guessing.
19 
20# Commands
21 
22```bash
23lat locate "Section Name"      # find a section by name (exact, fuzzy)
24lat refs "file#Section"        # find what references a section
25lat search "natural language"  # semantic search across all sections
26lat expand "user prompt text"  # expand [[refs]] to resolved locations
27lat check                      # validate all links and code refs
28```
29 
30Run `lat --help` when in doubt about available commands or options.
31 
32If `lat search` fails because no API key is configured, explain to the user that semantic search requires a key provided via `LAT_LLM_KEY` (direct value), `LAT_LLM_KEY_FILE` (path to key file), or `LAT_LLM_KEY_HELPER` (command that prints the key). Supported key prefixes: `sk-...` (OpenAI) or `vck_...` (Vercel). If the user doesn't want to set it up, use `lat locate` for direct lookups instead.
33 
34# Syntax primer
35 
36- **Section ids**: `lat.md/path/to/file#Heading#SubHeading` — full form uses project-root-relative path (e.g. `lat.md/tests/search#RAG Replay Tests`). Short form uses bare file name when unique (e.g. `search#RAG Replay Tests`, `cli#search#Indexing`).
37- **Wiki links**: `[[target]]` or `[[target|alias]]` — cross-references between sections. Can also reference source code: `[[src/foo.ts#myFunction]]`.
38- **Source code links**: Wiki links in `lat.md/` files can reference functions, classes, constants, and methods in TypeScript/JavaScript/Python/Rust/Go/C files. Use the full path: `[[src/config.ts#getConfigDir]]`, `[[src/server.ts#App#listen]]` (class method), `[[lib/utils.py#parse_args]]`, `[[src/lib.rs#Greeter#greet]]` (Rust impl method), `[[src/app.go#Greeter#Greet]]` (Go method), `[[src/app.h#Greeter]]` (C struct). `lat check` validates these exist.
39- **Code refs**: `// @lat: [[section-id]]` (JS/TS/Rust/Go/C) or `# @lat: [[section-id]]` (Python) — ties source code to concepts
40 
41# Test specs
42 
43Key tests can be described as sections in `lat.md/` files (e.g. `tests.md`). Add frontmatter to require that every leaf section is referenced by a `// @lat:` or `# @lat:` comment in test code:
44 
45```markdown
46---
47lat:
48  require-code-mention: true
49---
50# Tests
51 
52Authentication and authorization test specifications.
53 
54## User login
55 
56Verify credential validation and error handling for the login endpoint.
57 
58### Rejects expired tokens
59Tokens past their expiry timestamp are rejected with 401, even if otherwise valid.
60 
61### Handles missing password
62Login request without a password field returns 400 with a descriptive error.
63```
64 
65Every section MUST have a description — at least one sentence explaining what the test verifies and why. Empty sections with just a heading are not acceptable. (This is a specific case of the general leading paragraph rule below.)
66 
67Each test in code should reference its spec with exactly one comment placed next to the relevant test — not at the top of the file:
68 
69```python
70# @lat: [[tests#User login#Rejects expired tokens]]
71def test_rejects_expired_tokens():
72    ...
73 
74# @lat: [[tests#User login#Handles missing password]]
75def test_handles_missing_password():
76    ...
77```
78 
79Do not duplicate refs. One `@lat:` comment per spec section, placed at the test that covers it. `lat check` will flag any spec section not covered by a code reference, and any code reference pointing to a nonexistent section.
80 
81# Section structure
82 
83Every section in `lat.md/` **must** have a leading paragraph — at least one sentence immediately after the heading, before any child headings or other block content. The first paragraph must be ≤250 characters (excluding `[[wiki link]]` content). This paragraph serves as the section's overview and is used in search results, command output, and RAG context — keeping it concise guarantees the section's essence is always captured.
84 
85```markdown
86# Good Section
87 
88Brief overview of what this section documents and why it matters.
89 
90More detail can go in subsequent paragraphs, code blocks, or lists.
91 
92## Child heading
93 
94Details about this child topic.
95```
96 
97```markdown
98# Bad Section
99 
100## Child heading
101 
102Details about this child topic.
103```
104 
105The second example is invalid because `Bad Section` has no leading paragraph. `lat check` validates this rule and reports errors for missing or overly long leading paragraphs.
106 
107## CRM Agent APIs
108 
109The CRM exposes authenticated JSON endpoints for automation. Agents should prefer these endpoints over native browser file-picker automation.
110 
111### Discover Capabilities
112 
113`GET /api/crm/agent-capabilities`
114 
115Requires an authenticated CRM session cookie. Returns machine-readable capabilities, including the document upload endpoint and request body shape.
116 
117### Upload CRM Documents
118 
119`POST /api/crm/documents`
120 
121Requires an authenticated CRM session cookie. Use this endpoint to attach local files to CRM entries, especially transcript files referenced in interaction notes.
122 
123Body:
124 
125- `entryId`: CRM entry id, such as an interaction id.
126- `fileName`: original file name.
127- `fileBase64`: base64-encoded file contents.
128- `fileSize`: byte size.
129- `contentType`: MIME type, usually `text/markdown` for transcripts.
130- `title`: optional display label.
131 
132Example:
133 
134```json
135{
136  "entryId": "meet_nathan_cff_20260403_000",
137  "fileName": "2026-04-03-nathan-crossfit-fullerton.md",
138  "fileBase64": "...",
139  "fileSize": 50732,
140  "contentType": "text/markdown",
141  "title": "2026-04-03 Nathan CrossFit Fullerton transcript"
142}
143```
144 
145The CRM document panel also exposes DOM hints:
146 
147- `data-agent-capabilities="/api/crm/agent-capabilities"`
148- `data-agent-document-upload-api="/api/crm/documents"`
149- `data-agent-entry-id="<current entry id>"`
150- `data-agent-preferred-action="uploadCrmDocument"` on the upload form.
151- `data-agent-api="/api/crm/documents"` on the upload form.
152 
153<!-- gitnexus:start -->
154# GitNexus — Code Intelligence
155 
156This project is indexed by GitNexus as **thewodapp** (53782 symbols, 88590 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
157 
158> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
159 
160## Always Do
161 
162- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
163- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
164- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
165- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
166- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
167 
168## Never Do
169 
170- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
171- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
172- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
173- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
174 
175## Resources
176 
177| Resource | Use for |
178|----------|---------|
179| `gitnexus://repo/thewodapp/context` | Codebase overview, check index freshness |
180| `gitnexus://repo/thewodapp/clusters` | All functional areas |
181| `gitnexus://repo/thewodapp/processes` | All execution flows |
182| `gitnexus://repo/thewodapp/process/{name}` | Step-by-step execution trace |
183 
184## CLI
185 
186| Task | Read this skill file |
187|------|---------------------|
188| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
189| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
190| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
191| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
192| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
193| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
194 
195<!-- gitnexus:end -->
196