dvorakmortonxd/freezmo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
freezmo/AGENTS.md
Martin Dvorak aac6befb0d App versioning + the create page's missing top padding 
Versioning: package.json carries the app version (0.1.2 here; one bump per
task with `npm run version:bump`, patch 0-9 rolling into the minor at 10),
baked into the build via lib/version.ts, reported by /api/healthz and shown
in Settings next to the running commit. AGENTS.md documents the rule; the
native suite checks both the API and the Settings row.

Fix: on desktop the app header is hidden, so every page owns its top padding —
/create was the only one without `lg:pt-10`, which slammed the Study deck /
Make my homework switch against the top of the window while /homework had a
comfortable gap. Both now sit at 40px; the wizard suite asserts the clearance
and that the two pages stay in step (90 checks).

SW -> freezmo-v50.
2026-10-12 20:04:26 +00:00

3.6 KiB
Raw Blame History

AGENTS.md — working rules for this repo

Freezmo has two environments. Every session — human or agent — follows these rules. They are not optional: production is the app the user actually uses.

Environments

Dev (this working tree) Production
Path ~/freezmo (where you edit) ~/freezmo-prod/current (release symlink)
Service freezmo-dev.service freezmo.service
Port 3217 (http://<lan-ip>:3217, LAN only) 3207 + the public URL
Build folder .next-dev (hot reload) .next/standalone inside the release
Data ~/freezmo/.freezmo-dev/ ~/freezmo-prod/shared/freezmo/
Env ~/freezmo/.env.local ~/freezmo-prod/shared/env.local
Identity DEV badge, dev favicon/theme, "Freezmo Dev" PWA normal

Dev runs next dev with hot reload; all live, real-time changes go there. Production only ever runs a pushed, verified commit deployed by scripts/deploy.sh (releases under ~/freezmo-prod/releases/, last 5 kept, scripts/rollback.sh to go back).

Rules

  1. During a task, only the dev instance updates. Never restart or rebuild production mid-task; production changes only through scripts/deploy.sh at the very end.
  2. Never build into a running instance's folder. The dev service owns .next-dev; npm run build (used by the test suites' spawned instances) owns .next; a release build owns its own release directory. Any build or test that needs a production build uses a temporary directory and port.
  3. At the end of a task: run npm run lint, npm run test:e2e and npm run build, bump the service-worker cache (public/sw.js), update the README, commit, push to main, then run scripts/deploy.sh. Production only ever runs a pushed, verified commit.
  4. scripts/deploy.sh is the only deploy path. It refuses a dirty tree, refuses commits that aren't on origin/main, runs lint + build + the full e2e suite against the new release on a temporary port, switches the current symlink atomically, health-checks /api/healthz for the new commit and rolls back automatically on failure.
  5. The Ollama API key never leaves the browser. It must never appear in exports, sync payloads, share links, logs, URLs, .env files committed to the repo, or release directories. Server data (sync blobs, push subscriptions, question reports) lives only under shared/.
  6. Both languages, always. Every user-facing string goes into lib/i18n-dict.ts in en and cs (the i18n test enforces key parity).
  7. Phones are first-class: ≤639px layouts, 44px touch targets, 16px inputs, safe-area padding; verify at 360px and 390px as well as desktop.
  8. Versioned storage, never lose data. Deck/homework/chat schemas are validated with zod on read; backups and sync share the same payload schema.
  9. The test suites live in tests/ (npm run test:e2e, filterable: npm run test:e2e -- chat). Add or extend a suite for every feature; a green suite set is part of "done". Diagnostics that are not gates: tests/bubble-perf.mjs, tests/model-compare.mjs.
  10. Keep the service worker honest: bump CACHE_VERSION in public/sw.js for every user-visible deploy (the deploy itself does not do this).
  11. Version the app once per task. Bump package.json version with npm run version:bump: the patch digit goes 0-9 and after 9 it rolls into the minor (0.1.9 → 0.2.0). The version is baked into the build (lib/version.ts), reported by /api/healthz and shown in Settings next to the running commit — so every task's release is identifiable.