|
| 1 | +# Agent Playbook |
| 2 | + |
| 3 | +## Repository Snapshot |
| 4 | + |
| 5 | +- Documentation site built with Next.js 13 and Nextra (`pages/` holds `.mdx` content, `_meta.json` defines navigation order). |
| 6 | +- Key scripts: `npm run dev`, `npm run build`, `npm run start`, `npm run lint`. |
| 7 | +- Node.js 22 is available; Python execution may be blocked in this environment. |
| 8 | + |
| 9 | +## Workflow Guidelines |
| 10 | + |
| 11 | +- Default to `apply_patch` for hand edits; avoid bulk formatters unless requested. |
| 12 | +- Keep additions ASCII unless the surrounding file already uses Unicode. |
| 13 | +- Preserve any pre-existing local changes; never revert files you did not modify for the current task. |
| 14 | +- When touching documentation directories, update the sibling `_meta.json` so every `.mdx`/`.md` page appears in the navigation. |
| 15 | +- Comment only when clarification is essential—most prose and code should remain self-explanatory. |
| 16 | + |
| 17 | +## Documentation Style |
| 18 | + |
| 19 | +- Organize content according to the [Diátaxis](https://diataxis.fr/) framework: Tutorials (learning-oriented), How-to guides (goal-oriented), Explanations (understanding-oriented), and Reference (information-oriented). |
| 20 | +- Tutorials: guide the reader through a concrete end-to-end task; assume no prior knowledge, provide step-by-step instructions, and postpone theory until after success. |
| 21 | +- How-to guides: focus on achieving a specific outcome; start with prerequisites, list concise actionable steps, and limit background details to what is essential for completing the task. |
| 22 | +- Explanations: clarify concepts, trade-offs, and rationale; connect ideas, reference related materials, and avoid procedural instructions. |
| 23 | +- Reference: present facts, APIs, configuration tables, and schemas; structure information for quick lookup with consistent formatting and terminology. |
| 24 | +- Match the existing section type when editing; move or split content if it drifts outside the intended Diátaxis category. |
| 25 | +- Lead with user needs, keep paragraphs short, and surface actionable steps early for tutorials and how-to guides. |
| 26 | +- Use consistent terminology across related pages; prefer active voice and second person. |
| 27 | +- Include code snippets or command blocks only when they advance the user goal for that section type. |
| 28 | + |
| 29 | +## Command & Sandbox Notes |
| 30 | + |
| 31 | +- Run shell commands through `bash -lc` and always set the `workdir` argument (usually the repo root). |
| 32 | +- Network access is restricted; prefer local data. Use `rg` for searching. |
| 33 | +- Destructive git commands (`reset --hard`, `checkout --`) are off limits unless the user explicitly requests them. |
| 34 | + |
| 35 | +## Validation |
| 36 | + |
| 37 | +- Run `npm run lint` after significant content or component changes when feasible. |
| 38 | +- For structural documentation edits, double-check rendered navigation by restarting the docs dev server if already running. |
| 39 | + |
| 40 | +## Deliverables |
| 41 | + |
| 42 | +- Summaries should state what changed and reference file paths with line numbers when practical. |
| 43 | +- Suggest logical follow-up actions (tests, builds, deploy checks) when they help the user. |
0 commit comments