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.

Validate documentation changes

Do not add unit tests that freeze documentation or README prose, headings, links, command snippets, sidebar labels, or exact file contents. Documentation must remain manually editable without test churn. Test executable behavior, schemas, generators, and public contracts at their implementation boundaries.

Run focused checks while iterating, then run:

yarn docs:check
git diff --check
yarn check

For visual changes, preview the site with yarn docs:dev and verify desktop and mobile layouts, light and dark themes, keyboard navigation, and search where relevant. Stop every development or preview server started for verification.

Publish safely

Pull requests and pushes validate the site without deploying it. Publish only from an up-to-date local checkout using browser-authenticated Wrangler; do not add Git integration, deployment Actions, API tokens, or repository secrets.

Before changing production, confirm Wrangler is using the Cloudflare account that owns microfeed.org, then deploy the isolated preview environment:

yarn docs:upload-preview

Verify the returned microfeed-docs-preview workers.dev URL, including internal links, search, the sitemap, the custom 404 page, and all three LLM text endpoints. Deploy that local source only after the preview passes:

yarn docs:deploy

docs/wrangler.jsonc is the source of truth for the asset-only microfeed-docs Worker and its docs.microfeed.org Custom Domain. It must not gain a runtime entry point, asset binding, run_worker_first, or secrets.

After deployment, repeat the preview checks against https://docs.microfeed.org. If production validation fails, inspect the last ten deployments with yarn wrangler deployments list --config docs/wrangler.jsonc and use the interactive yarn wrangler rollback <version-id> --config docs/wrangler.jsonc only after identifying the last known-good version.