forked from mirrors/kingfisher
46 lines
1.9 KiB
Markdown
46 lines
1.9 KiB
Markdown
# AGENTS.md
|
|
|
|
Guidance for editing documentation under `docs/`.
|
|
|
|
## Scope
|
|
|
|
- Applies to `docs/` and all files under it.
|
|
- This file overrides broader repository guidance for documentation work in this subtree.
|
|
|
|
## Purpose
|
|
|
|
- Keep documentation accurate, link-safe, and aligned with the current CLI, library APIs, and repository structure.
|
|
|
|
## Documentation Conventions
|
|
|
|
- Prefer concise, task-oriented docs over long narrative prose.
|
|
- Use relative links for repo-local documentation (`INSTALLATION.md`, `../README.md`, etc.).
|
|
- When adding a new top-level doc that users should discover, update the README documentation table.
|
|
- Keep command examples consistent with current CLI syntax and option names.
|
|
- When documenting output formats, prefer `toon` for agent/LLM-oriented examples unless human-interactive formatting is the point.
|
|
|
|
## Link Hygiene
|
|
|
|
- Check local markdown links after substantial doc edits.
|
|
- Prefer fixing broken links by creating or restoring the intended target when the topic is still relevant.
|
|
- If a document is intentionally removed, update all inbound links in README and related docs in the same change.
|
|
|
|
## Diagrams
|
|
|
|
- Keep Mermaid diagrams simple enough to render reliably in GitHub/Cursor markdown viewers.
|
|
- Prefer short labels and fewer crossing arrows over exhaustive detail.
|
|
- If one diagram becomes hard to read, split it into a small number of focused diagrams.
|
|
|
|
## Content Alignment
|
|
|
|
- Installation flows belong in `INSTALLATION.md`.
|
|
- Platform-specific usage belongs in `INTEGRATIONS.md`.
|
|
- Advanced runtime flags and tuning belong in `ADVANCED.md`.
|
|
- Library embedding guidance belongs in `LIBRARY.md`.
|
|
- Rule-authoring and validation schema guidance belongs in `RULES.md`.
|
|
- Architecture overviews belong in `ARCHITECTURE.md`.
|
|
|
|
## Validation
|
|
|
|
- For doc-only changes, verify link targets and obvious command/example consistency.
|
|
- If examples depend on current crate/module names, confirm they still exist before updating prose.
|