Imported from fisherdan500/Cubby (AGENTS.md). Install upstream with npx skills add fisherdan500/Cubby. Copyright stays with the author.

AGENTS.md

This guide applies to the whole Cubby repository. It is written for Codex and other coding agents working in this project.

Start Here

Before making non-trivial changes, read:

1. README.md
2. docs/ARCHITECTURE.md
3. docs/DEVELOPMENT.md

If the work involves future features, product planning, or backlog grooming, read docs/ROADMAP.md after the current-state docs. Do not treat roadmap items as implemented unless the code or current-state docs confirm them.

Then inspect the files that own the requested behavior. Do not rely only on prior conversation context when the repo can answer the question.

Project Rules

• Keep changes focused on the user request.
• Optimize first for dependable daily use by one private household; do not add multi-household or generalized product infrastructure without approval.
• Prioritize fast mobile workflows and always-on reliability. Existing installability does not authorize offline writes, synchronization, or conflict handling; those remain low priority.
• Prefer existing service/module patterns over new architecture.
• Put business logic in src/server/services instead of page or route-handler bodies.
• Enforce household membership and permissions server-side for every household-scoped read or write.
• Preserve Better Auth and the invite-first household model.
• Preserve the protected owner and delegated-admin model: only owners may grant or revoke Admin access.
• Preserve the ActivityLog aggregate plus type-specific detail table pattern.
• Keep timestamps as stored instants and group/display them through APP_TIMEZONE.
• Treat Docker Compose as the primary deployment path.
• Respect Cubby's soft editorial nursery visual system in both light and dark themes: warm semantic surfaces, restrained family accents, original activity artwork, and familiar utility icons.
• Design and check Cubby UI mobile-first; most use is expected from phones, with desktop kept tidy but secondary.
• Use semantic theme tokens and ActivityArtwork; avoid page-specific saturated palettes, copied icon art, and decorative imagery that competes with daily tracking.
• Do not run destructive git commands unless the user explicitly asks for them.
• Use an approved isolated worktree for substantive changes. Commit, push, merge, deployment, secrets, and external-system changes require explicit approval.
• Preserve unrelated user changes in a dirty worktree.

Clean-Room Sprout Track Rule

Cubby may use Sprout Track only as a one-time clean-room migration source for household-owned data. Do not pursue ongoing workflow parity or compatibility, or copy Sprout Track code, Prisma schema, route names, assets, exact UI text, credentials, implementation structure, or icon art.

Sprout backup support must remain a Cubby importer that maps user-owned tracking data into Cubby's own schema. It must not import Sprout secrets, auth records, API keys, sessions, push subscriptions, email config, or runtime credentials.

Implementation Guidance

• Prefer the agent's native targeted search and patch tools. Shell-only agents may use rg/rg --files and apply_patch.
• Keep comments sparse and only where they clarify non-obvious logic.
• Add or update tests near the owning service for behavior changes.
• Avoid broad refactors while adding a feature or fixing a bug.
• Keep page links and redirects preserving selected babyId and relevant date/filter params when the current workflow depends on them.
• Use structured parsing or existing helpers for dates, imports, backups, and exports instead of ad hoc string manipulation.

Verification Expectations

Choose the smallest verification set that covers the risk:

• Docs-only: review links/headings and run git status --short.
• TypeScript/UI behavior: run npm run typecheck, npm run lint, and targeted tests.
• Service logic: run targeted Vitest tests plus npm run test when the change is shared.
• Prisma schema changes: run Prisma validation/generation, migrations, tests, and npm run build.
• Auth, registration, permissions, import, backup, or integration changes: include permission/cross-household tests.
• Database role/privilege grants or session-freshness changes: also run npm run verify:browser-operation-save-path (see docs/DEVELOPMENT.md "Verification Commands") - unit tests exercise the service layer directly and will not catch a restricted-role privilege regression.
• Docker-sensitive changes, especially Sprout SQLite import or startup behavior: run docker compose up --build -d and inspect app logs.

Full acceptance set (run only for a milestone/release gate, a broad shared change, or when the active goal explicitly requires it):

npm run lint
npm run typecheck
npm run test
npm run build
docker compose up --build -d

Do not start or rebuild Docker for routine docs, UI-only, or narrowly targeted service changes unless the risk matrix or active goal requires runtime acceptance.

If you cannot run a relevant verification command, say so in the final response and explain why.