docs: refresh docs and add shared Claude Code instructions

[klin2686]

Summary

Brings the repo's Markdown docs back in line with the current code, and adds shared Claude Code instructions so both maintainers' Claude sessions follow the same repo conventions. No application code or code comments change.

What changed

Docs

• README.md: auth is described as database-backed session cookies (it said JWT), the tech stack lists current versions, the project tree includes backend/docs/ and docs/, and a broken bullet is fixed.
• CONTRIBUTING.md: shorter setup and workflow sections, notes that the API-key check is skipped only in development/test, documents the post-checkout hook that gives each worktree its own database, and says docs/ syncs on every push to main as well as at release.
• backend/docs/form-edit-lifecycle.md: availability write-through is described as scoped by track (it said by day, with availability_{YYYYMMDD} keys), the track-status transition table now matches can_set_track_status (declined → interested is allowed), and the lunch backfill exception to forward-only write-through is documented.
• backend/docs/form-question-types-reference.md: Form.status rules match update_form (a form with responses can go back to draft but stays history-preserving; an archived form must return to draft before publishing), lunch keys accept short_text/long_text, and the question type configs are a single table.
• backend/docs/track-status-rules.md: now the single home for the transition table that two other notes used to repeat.
• backend/docs/audit-log-conventions.md: adds track_delete_pending, track_delete_cancelled and track_purged, and notes that a new action also needs a DESCRIBERS entry in frontend/lib/auditLog.tsx.
• backend/docs/anonymize-users.md: drops the step that set JWT_SECRET, which no longer exists.
• backend/docs/member-seeding.md: adds the --age-consent flag, uses uv run, and fixes a recipe whose --email-prefix member matched no seeded accounts.
• Deletes CHANGELOG.md, a leftover from release-please that stopped at v1.2.1; CONTRIBUTING already said no changelog is kept.
• Paragraphs in these files are no longer hard-wrapped, so future edits produce small diffs.

Claude Code instructions

• CLAUDE.md (loaded in every session): project overview, how to run the apps, when and how to run tests, branch/commit/PR conventions, and code conventions, including keeping comments rare and trimming unnecessary comments in any file a PR touches.
• backend/CLAUDE.md and frontend/CLAUDE.md (loaded when working in that folder): layout, route conventions, auth and permissions, UI kit, and styling.
• .claude/rules/ (each loaded only when matching files are read): forms.md, audit-log.md, models-and-migrations.md, backend-tests.md, releases-and-docs.md.
• .gitignore no longer ignores CLAUDE.md, and now ignores CLAUDE.local.md for personal instructions.
• Personal preferences (response style, commit habits, when to ask before acting) are deliberately left out; those belong in each person's own ~/.claude files.

Out of scope

• frontend/lib/auditLog.tsx has no labels or describers for the three track_* audit actions, so they render without a label in the audit log.
• The docstring on _write_through_reserved_fields in forms.py still describes availability as scoped by day, and the comment above bulk_update_fields says a question_type change archives the field; the code does neither.
• _unique_track_statuses in app/schemas/form.py is never called.
• Whether PR descriptions should include Alembic revision hashes: the template says yes (in trailing parens), but this should be settled between maintainers.

Test plan

• No code changes, so no tests affected
• Each doc claim checked against the current code
• git check-ignore confirms CLAUDE.md and .claude/rules/ are tracked

Manual

• Start a Claude Code session in the repo and confirm the root CLAUDE.md loads, and that reading a file under backend/app/core/form/ loads the forms rule.

[railway-app]

This PR was not deployed automatically as @klin2686 does not have access to the Railway project.

In order to get automatic PR deploys, please add @klin2686 to your workspace on Railway.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
nexus	Ready	Preview	Oct 13, 2026 11:53am UTC