manamind-weekly

Imported from willcook415/manamind-weekly (AGENTS.md). Install upstream with npx skills add willcook415/manamind-weekly. Copyright stays with the author.

Contributor Guide

Repository map

• src/: React application, routes, providers, and accessible UI components
• shared/: Zod domain contracts, date utilities, attention ranking, and export functions used by browser and server
• netlify/functions/api.ts: authenticated HTTP routing and domain orchestration
• server/: Blob/in-memory repositories and seed migration
• data/weekly-reviews.seed.json: versioned one-time source migration
• tests/unit/: deterministic domain and repository tests
• tests/e2e/: Playwright critical-flow coverage
• docs/: product, architecture, and integration contracts

Working rules

• Use Node.js 22 or newer and run the application through npm run dev; port 8888 is the application origin.
• Treat shared/schemas.ts as the domain boundary. Validate request input, persisted records, seed data, and externally returned structures.
• Store date-only values as YYYY-MM-DD, timestamps with an explicit offset, and ISO weeks as YYYY-Www. Use the shared UTC helpers instead of local-time arithmetic.
• Mutable entities start at revision 1. Every update must supply the expected revision and persist exactly the next revision. Surface stale writes as HTTP 409; never silently overwrite them.
• Persist a schemaVersion: "1.0" domain event for successful user-visible mutations. Use namespaced snake-case event types such as workstream.updated and keep event payloads additive.
• Keep Netlify Identity invite-only. Never enable the development bypass in production or treat X-Dev-Member-Id as production authentication.
• Do not edit live behavior to compensate for seed mistakes. Record migration assumptions, validate all owner references, and preserve stable seed IDs.
• Preserve accessibility names on controls. Playwright locates elements by roles, labels, and visible text rather than CSS implementation details.
• Do not add arbitrary sleeps or current-time-dependent fixtures. Inject fixed timestamps in unit tests and use web-first Playwright assertions.

Before handing off

npm run typecheck
npm run lint
npm test
npm run test:e2e
npm run build

If a command cannot run, report the exact environment or unavailable interface. Do not weaken assertions to make a broken contract pass.

Change checklist

• Update Zod schemas and inferred types together.
• Consider seed and persisted-data migration impact before changing a stored shape.
• Add or update revision and event behavior for mutations.
• Document integration response changes and schema-version implications.
• Cover domain logic with Vitest and user-critical behavior with Playwright.
• Keep production bypass variables unset and secrets out of source control.