Documentation Standards
Audience: Developer, Contributor, Support Related: Terminology · Index · Testing
Blackcap documentation is organized by feature, subsystem, user task, deployment target, or stable operational responsibility. Do not create canonical files named after a chat, prompt, request number, date, implementation batch, or unrelated group of changes.
Update the canonical feature document when behavior changes. Update docs/index.md when adding or moving a canonical page. Update ../../README.md only when the application-level summary changes. Use cross-links instead of duplicated authoritative guidance, remove obsolete documents after extracting durable content, use current terminology, and never include secrets or personal deployment values.
Emoji and visual navigation
Use emoji as restrained visual wayfinding in the root README, documentation index, feature catalog, and other high-level navigation pages. Documentation must use the canonical feature and navigation mappings in UI, Icons, and Documentation Assets; do not invent a different emoji for the same concept in each file.
Emoji reinforce descriptive text and never replace it. Do not create emoji-only links, warnings, or instructions, and do not scatter decorative emoji through commands, database rules, security guidance, or step-by-step troubleshooting. Documentation must match the application UI for functional topics: 🧑🍳 Let’s Cook, 🤖 AI, 🎮 Games, 🧩 Chrome Extension, and 🧺 Kitchen Inventory.
Documentation navigation symbols are UI wayfinding. They do not automatically become valid recipe/content emoji. Any emoji stored by Blackcap users or rendered into PDFs, generated images, or e-ink output must still follow the Blackcap-Safe Emoji registry, validation, and asset rules.
In-application documentation
Authenticated Blackcap users can open 📄 Documentation from the Admin user menu. The in-application documentation browser renders the same canonical docs/index.md publication set directly from the installed repository, with branded navigation, search, breadcrumbs, page contents, and previous/next links. It does not maintain a second documentation copy. Repository-only package references and cleanup audit artifacts remain excluded from the normal user-facing documentation browser.
The Microwave Pie website and the in-application browser are two presentation layers over the same Markdown source. Changes belong in docs/; do not edit generated public HTML or create separate application-only copies of feature guidance.
LLM project primer
The root LLM_PRIMER.md is an intentionally retained orientation document for LLMs and developers. Keep it limited to stable project-wide constraints and working practices. When a feature-specific rule changes, update the canonical feature document first, then update the primer only when the change affects cross-project guidance. The primer must link to canonical detail rather than becoming another complete user or implementation guide.
Overview-page navigation
When a documentation folder contains overview.md and one or more companion Markdown pages, the overview must end with a More information section that links to every companion page in that folder. Keep the list task-oriented and give each link a short description. The top metadata links may highlight the most important relationships, but they do not replace the complete list at the bottom.
Runtime publication requirement
The canonical docs/ directory is runtime content for the in-application 📄 Documentation browser. Deployment packages that add or update the browser must include the complete indexed documentation tree, especially docs/index.md; do not deploy only the rendering code.