Document Microfeed

Document microfeed

Keep the public documentation human-first, product-led, and directly useful to AI agents. Assume readers may have no prior Cloudflare, Git, or server administration experience.

Keep each source focused

• Use the root README.md for the product summary and shortest successful deployment path.
• Use task guides under docs/ for approachable procedures and explanations.
• Keep docs/manage-cli.md as the canonical command, option, side-effect, and safety contract. Update it together with manage-cli/help.ts when CLI behavior changes.
• Keep docs/microfeed-cli.md as the canonical command, option, output, and safety contract for @microfeed/cli. Update it together with the help inventory in packages/cli/src/help.ts when content CLI behavior changes.
• Keep docs/theme-kit-cli.md as the canonical command, option, output, and failure-behavior reference for @microfeed/theme-kit. Update it together with packages/theme-kit/src/help.ts and the command implementation when theme-kit CLI behavior changes.
• Keep agent execution safeguards in repository skills and AGENTS.md, not on the public documentation site.
• Derive API references from src/shared/OpenApiDocument.ts; do not maintain a duplicate OpenAPI specification under docs/.

Link to the canonical source instead of copying long reference material into a task guide.

Write for successful outcomes

1. Lead with what the reader will accomplish.
2. Present the recommended path before advanced alternatives.
3. Define Cloudflare-specific and development terms when they first appear.
4. Provide copyable commands and say where to run them.
5. Describe the expected result, a verification step, and the safest recovery when an important step fails.
6. Use consistent placeholders such as <instance-name>. Never include real account IDs, emails, tokens, private addresses, or setup links.

Use plain .md for guides. Reserve .mdx for product pages that need components. Give every page title and description frontmatter, keep heading levels sequential, use descriptive link text, and tag code fences.

Maintain the Starlight site

• Keep the independent Astro project rooted at docs/; do not couple it to the Worker build.
• Update docs/astro.config.ts whenever a public page is added, moved, or removed from navigation.
• Keep site set to https://docs.microfeed.org with no repository base path.
• Preserve Pagefind search, the sitemap, and generated /llms.txt, /llms-small.txt, and /llms-full.txt artifacts.
• Put theme-safe shared styles in docs/src/styles/custom.css and preserve keyboard focus, contrast, reduced motion, and mobile behavior.
• Keep maintainer-only publishing and writing procedures in this skill rather than exposing them as public docs pages.

Do not create, capture, add, or replace documentation screenshots unless the user explicitly requests screenshots. This keeps the repository small and avoids image churn for routine UI and documentation changes. When screenshots are explicitly requested, store them under docs/public/images/screenshots/, use public or demo content, remove private emails, account IDs, credentials, and setup links, and give every image a descriptive filename and useful alt text. Keep source captures replaceable, optimize generated composites and animation, and provide desktop and mobile variants only when requested. Never let an image be the only instruction.