Develop Microfeed

Develop microfeed

Follow the repository's agent rules and human-facing contribution guide. Keep the change focused and leave the repository in a reviewable state.

Design principles

• Keep Cloudflare Free sufficient. Keep every feature required for initial deployment or normal core use available on Cloudflare Free. Before implementation, verify the current official Cloudflare documentation for service availability and every limit the design exercises. Evaluate worst-case Worker CPU time and relevant request, storage, operation, payload, and other quotas; do not copy changing numeric limits into this skill. Redesign an essential path that does not fit. Permit paid-only capabilities only as optional enhancements with complete free-account behavior.
• Design for people, with or without an agent. Assume no technical fluency across the product interface, yarn manage, documentation, and agent guidance. Use familiar, task-oriented vocabulary first; introduce technical terms only when necessary and explain them where they appear. Keep deployment on one yarn manage workflow that works directly or through an agent, and make its choices, effects, progress, and recovery steps clear. Do not depend on an agent-only deployment path.

Prepare the work

1. Confirm the repository root contains package.json, yarn.lock, src/, and manage-cli/.
2. Inspect git status --short, the current branch, recent commits, worktrees, and remotes before editing. Identify exactly which existing changes belong to the task.
3. Never work directly on main. Continue an existing task branch when it is relevant, or create <type>/<short-kebab-case> using the primary outcome:
   • feature: new user-facing behavior
   • fix: defect correction
   • docs: documentation only
   • refactor: behavior-preserving restructuring
   • test: test-only work
   • ci: continuous-integration changes
   • chore: repository maintenance spanning other categories
4. Base ordinary work on the current upstream main. Use another base only when the user explicitly requests dependent or stacked work.
5. If unrelated changes are present, preserve them exactly. Create an isolated worktree and transfer only known task hunks. Never stash, reset, discard, or silently include unrelated files.

Implement the change

1. Inspect the affected implementation, tests, and documentation before editing. Prefer the smallest coherent change that satisfies the request.
2. Respect the source boundaries, frontend component rules, and interactive styling requirements in AGENTS.md.
3. Add or update focused tests for behavior changes and regression fixes. Update contributor or user documentation when commands, behavior, or public expectations change.
4. Treat Cloudflare deployment as a separate workflow. Invoke deploy-microfeed for any install, deploy, publish, configure, or destroy request; do not improvise deployment steps.
5. Do not commit secrets, local instance state, build output, generated Worker types, or unrelated formatting changes.

Change the external API

When adding or changing a public endpoint, keep runtime behavior and every reference format synchronized through the shared contract:

1. Inspect the route, transport-neutral service, existing schemas, generated OpenAPI document, and relevant runtime and contract tests.
2. Add or update reusable Zod request and response schemas in src/shared/ApiSchemas.ts. Preserve deprecated inputs or outputs explicitly when existing integrations require backward compatibility.
3. Register the operation in src/shared/OpenApiDocument.ts, including its method, path, operation ID, parameters, request body, every response status and schema, authentication, descriptions, and compatibility notes. Document Bearer as the only API-key authentication method; compatibility-only authentication remains a tested runtime detail and is not shown in API reference formats or product UI.
4. Implement the Astro route using the same schemas where practical and shared domain services. Do not make an internal HTTP request to microfeed's own API or duplicate business logic solely for a transport. Put canonical external endpoints under the current versioned API base from src/shared/ApiVersion.ts. When an existing unversioned endpoint must remain compatible, route both paths to the same server-side handler and keep the compatibility path out of generated reference formats and new product examples.
5. Do not maintain OpenAPI JSON, OpenAPI YAML, Scalar, llms.txt, or llms-full.txt separately. src/server/openapi/document.ts derives them from OPENAPI_DOCUMENT, and llms-full.txt embeds the complete generated contract so it remains self-contained.
6. Add focused tests for handler behavior and contract generation. Ensure every new route is represented in OPENAPI_DOCUMENT, the embedded LLM contract parses back to that same document, and compatibility behavior is covered.
7. Run yarn lint:openapi while iterating, followed by the normal git diff --check and yarn check validation before publishing.