docs: improve project onboarding

.agents/skills/fiddy-verify/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: fiddy-verify
+description: Run and report the Fiddy repository verification loop. Use when Codex is finishing changes, checking repo health, validating docs/scripts/config updates, or deciding which lint/typecheck/test/build commands are appropriate for this Express/Vite/npm project.
+---
+
+# Fiddy Verification
+
+Use this workflow from the repo root.
+
+## Before Running Commands
+- Read `AGENTS.md`, `PROJECT_INSTRUCTIONS.md`, and any doc related to the touched area.
+- Check `git status --short --branch` so user work is not mistaken for Codex changes.
+- Do not print real `.env` values. Inspect keys only if environment context is needed.
+- Do not run DB migrations unless the user explicitly asked for migration execution.
+
+## Choose Checks
+- Docs-only changes: validate affected Markdown links/content where practical, then run JSON/script sanity checks if package files changed.
+- Root or frontend script changes: run `npm run lint`, `npm run typecheck`, and the relevant build command.
+- Backend behavior changes: run `npm test`; add focused Jest/Supertest coverage for changed API behavior.
+- Frontend behavior changes: run `npm run lint`, `npm run typecheck`, and focused Playwright tests when a browser flow changed.
+- Dependency or lockfile changes: run `npm run audit` after install/update commands.
+- Migration changes: run `npm run db:migrate:stale:check` and `npm run db:migrate:verify` only against the intended external DB environment.
+
+## Default Safe Loop
+Run these when dependencies are already installed and the touched files justify them:
+
+```bash
+npm run lint
+npm run typecheck
+npm run audit
+npm test
+npm run build:backend
+npm run build:frontend
+```
+
+## Report
+- List exact commands run and pass/fail.
+- For failures, include the short relevant error and whether it appears caused by the current changes.
+- If a check is skipped, state the concrete reason.
+- End with unresolved risks and the smallest useful next step.

AGENTS.md

@@ -1,57 +1,111 @@
-# AGENTS.md - Fiddy (External DB)
+# AGENTS.md - Fiddy
 
 ## Authority
-- Source of truth: `PROJECT_INSTRUCTIONS.md` (repo root). If conflict, follow it.
-- Bugfix protocol: `DEBUGGING_INSTRUCTIONS.md` (repo root).
-- Do not implement features unless required to fix the bug.
+- Source of truth: `PROJECT_INSTRUCTIONS.md` in the repo root.
+- Bugfix protocol: `DEBUGGING_INSTRUCTIONS.md`.
+- Current-stack mapping: `docs/AGENTIC_CONTRACT_MAP.md`.
+- If files conflict, follow `PROJECT_INSTRUCTIONS.md`.
 
-## Non-negotiables
-- External DB: `DATABASE_URL` points to on-prem Postgres (NOT a container).
-- Dev/Prod share schema via migrations in `packages/db/migrations`.
-- No cron/worker jobs. Fixes must work without background tasks.
-- Server-side RBAC only. Client checks are UX only.
+## Project Overview
+- Full-stack grocery list app with household/group behavior, RBAC, image support, and Postgres persistence.
+- Backend: Express 5 CommonJS API in `backend/`.
+- Frontend: React 19 + Vite SPA in `frontend/`, with partial TypeScript.
+- Database: external on-prem Postgres. Do not add or assume a DB container.
+- Canonical migrations live in `packages/db/migrations`.
 
-## Security / logging (hard rules)
-- Never log secrets (passwords/tokens/cookies).
-- Never log receipt bytes.
-- Never log full invite codes; logs/audit store last4 only.
+## Important Directories
+- `backend/routes`, `backend/controllers`: route registration and request/response handling.
+- `backend/models`, `backend/services`, `backend/middleware`, `backend/db`: DB access, domain logic, auth, RBAC, request IDs, image handling.
+- `frontend/src/api`: client API wrappers using the shared Axios instance.
+- `frontend/src/context`, `frontend/src/hooks`, `frontend/src/components`, `frontend/src/pages`: UI state and screens.
+- `frontend/tests`: Playwright e2e tests.
+- `backend/tests`: Jest/Supertest backend tests.
+- `scripts`: DB migration helpers.
+- `docs`: practical maps, runbooks, architecture notes, and archived implementation history.
 
-## Non-regression contracts
-- Sessions are DB-backed (`sessions` table) and cookies are HttpOnly.
-- Receipt images stored in `receipts` (`bytea`).
-- Entries list endpoints must NEVER return receipt bytes.
-- API responses must include `request_id`; audit logs must include `request_id`.
-- Frontend actions that manipulate database state must show a toast/bubble notification with basic outcome info (action + target + success/failure).
-- Progress-type notifications must reuse the existing upload toaster pattern (`UploadQueueContext` + `UploadToaster`).
+## Setup
+- Install root tools: `npm ci`
+- Install backend tools: `npm --prefix backend ci`
+- Install frontend tools: `npm --prefix frontend ci`
+- Use Node.js 20.19+ or 22.12+ for frontend/Vite commands.
+- Configure backend env from `backend/.env.example`; never commit real `.env` values.
+- For migration scripts, set `DATABASE_URL` in the shell before running root DB commands.
 
-## Architecture boundaries (follow existing patterns; do not invent)
-1) API routes: `app/api/**/route.ts`
-   - Thin: parse/validate + call service, return JSON.
-2) Server services: `lib/server/*`
-   - Own DB + authz. Must include `import "server-only";`.
-3) Client wrappers: `lib/client/*`
-   - Typed fetch + error normalization; always send credentials.
-4) Hooks: `hooks/use-*.ts`
-   - Primary UI-facing API layer; components avoid raw `fetch()`.
+## Run Commands
+- Dev with Docker: `docker compose -f docker-compose.dev.yml up`
+- Backend only: `npm run dev:backend`
+- Frontend only: `npm run dev:frontend`
+- Backend default port: `5000`
+- Frontend Docker-mapped port: `3010`; Vite direct default is `5173` unless overridden.
 
-## Next.js dynamic route params (required)
-- In `app/api/**/[param]/route.ts`, treat `context.params` as async:
-  - `const { id } = await context.params;`
+## Verification Commands
+- Backend unit/API tests: `npm test`
+- Frontend lint: `npm run lint`
+- Frontend typecheck: `npm run typecheck`
+- Vulnerability audit: `npm run audit`
+- Backend build: `npm run build:backend`
+- Frontend build: `npm run build:frontend`
+- Full build: `npm run build`
+- E2E tests: `npm run test:e2e`
+- Migration status: `npm run db:migrate:status`
+- Migration verification: `npm run db:migrate:verify`
 
-## Working style
-- Scan repo first; do not guess file names or patterns.
-- Make the smallest change that resolves the issue.
-- Religiously commit work in small, verified slices; prefer frequent checkpoint commits over large end-state batches.
-- Follow the commit discipline in `PROJECT_INSTRUCTIONS.md` for every slice, including Conventional Commit messages and related-file-only scope.
-- Keep touched files free of TS warnings and lint errors.
-- Add/update tests when API behavior changes (include negative cases).
-- Keep text encoding clean (no mojibake).
+## Environment Notes
+- `backend/.env` is used by the backend and Docker dev service.
+- `frontend/.env` may define `VITE_API_URL` and `VITE_ALLOWED_HOSTS`.
+- Do not print, log, or commit secrets, tokens, cookies, DB URLs, receipt bytes, or full invite codes.
+- Logs/audit entries for invite codes may include last4 only.
 
-## Response icon legend
-Use the same status icons defined in `PROJECT_INSTRUCTIONS.md` section "Agent Response Legend (required)":
+## Coding Conventions
+- Preserve the current stack; do not migrate to Next.js or another framework.
+- Keep Express routes/controllers thin; put DB-heavy work in models/services and authz in backend layers.
+- Keep frontend network calls in `frontend/src/api` wrappers and UI state in context/hooks.
+- Always send credentials through the shared Axios client when touching authenticated frontend API calls.
+- Enforce RBAC server-side; client guards are UX only.
+- Frontend DB-mutating actions must show toast/bubble outcome notifications.
+- Progress notifications must reuse `UploadQueueContext` and `UploadToaster`.
+- Keep encoding clean; do not introduce mojibake.
+
+## Dependency Rules
+- npm is the package manager; do not introduce pnpm, yarn, bun, or another build tool.
+- Do not add production dependencies unless the task clearly requires it and the repo has no practical existing option.
+- Do not add cron, workers, polling daemons, or background job frameworks.
+
+## Testing Expectations
+- Add or update tests when API behavior changes.
+- Include negative cases for authz, membership, and invalid input where applicable.
+- For UI behavior changes, prefer focused Playwright tests.
+- Run the narrowest relevant checks first, then broader checks when risk warrants it.
+
+## Done Means
+- Behavior is preserved unless the task explicitly requires a change.
+- Relevant tests/lint/typecheck/build commands were run or the reason they could not run is documented.
+- Touched files have no known TS/lint errors.
+- Migrations are in `packages/db/migrations` when schema changes are required.
+- Documentation is updated for changed commands, contracts, or workflows.
+
+## Codex Must Not
+- Do not read or expose real `.env` values; inspect variable names only when needed.
+- Do not touch production data or run DB migrations without explicit operator intent.
+- Do not log secrets, receipt bytes, or full invite codes.
+- Do not delete user work or generated artifacts unless explicitly asked.
+- Do not make broad refactors, file moves, or framework changes for cleanup alone.
+
+## Deeper Docs
+- `docs/PROJECT_MAP.md`: quick repo orientation.
+- `docs/DEVELOPMENT.md`: setup, run, verify, and troubleshooting.
+- `docs/DB_MIGRATION_WORKFLOW.md`: migration runbook.
+- `docs/PLANS.md`: template for multi-step work.
+- `.agents/skills/fiddy-verify/SKILL.md`: repo-specific verification workflow for Codex.
+
+## Response Icon Legend
 - `🔄` in progress
 - `✅` completed
 - `🧪` verification/test result
-- `⚠️` risk/blocker/manual action
-- `❌` failure
-- `🧭` recommendation/next step
+- `📄` documentation update
+- `🗄️` database or migration change
+- `🚀` deploy/release step
+- `⚠️` risk, blocker, or manual operator action needed
+- `❌` failed command or unsuccessful attempt
+- `ℹ️` informational context
+- `🧭` recommendation or next-step option

README.md

@@ -2,6 +2,8 @@
 
 A full-stack web application for managing grocery shopping lists with role-based access control, image support, and intelligent item classification.
 
+> Current maintainer notes: `PROJECT_INSTRUCTIONS.md` is the source of truth for project constraints. For current setup, run, and verification commands, start with `docs/DEVELOPMENT.md` and `docs/PROJECT_MAP.md`; some older sections below are historical and should be checked against current code before changing behavior.
+
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
 ![Node](https://img.shields.io/badge/node-20.x-green.svg)
 ![React](https://img.shields.io/badge/react-19.2.0-blue.svg)

docs/DEVELOPMENT.md

@@ -0,0 +1,95 @@
+# Development
+
+Use this as the practical setup and verification guide. `PROJECT_INSTRUCTIONS.md` remains the source of truth for constraints.
+
+## Prerequisites
+- Node.js 20.19+ or 22.12+ for the current Vite toolchain.
+- npm.
+- PostgreSQL client tools if running migration scripts (`psql` must be on `PATH`).
+- Access to the external Postgres database through `DATABASE_URL` or backend DB variables.
+- Docker is optional for local app containers.
+
+## Install
+Run installs separately because this repo does not define npm workspaces.
+
+```bash
+npm ci
+npm --prefix backend ci
+npm --prefix frontend ci
+```
+
+## Environment
+- Copy `backend/.env.example` to `backend/.env` for backend runtime configuration.
+- Copy `frontend/.env.example` to `frontend/.env` if the frontend needs non-default API or host settings.
+- Do not commit real `.env` files.
+- Root DB migration scripts read `DATABASE_URL` from the shell environment; they do not load `backend/.env` automatically.
+
+Important variables:
+
+| Variable | Used by | Notes |
+| --- | --- | --- |
+| `DATABASE_URL` | backend, root migration scripts | Preferred external Postgres connection string. |
+| `DB_USER`, `DB_PASS`, `DB_HOST`, `DB_PORT`, `DB_NAME` | backend fallback | Used only when `DATABASE_URL` is absent. |
+| `JWT_SECRET` | backend auth | Required for token/session-compatible auth paths. |
+| `ALLOWED_ORIGINS` | backend CORS | Comma-separated allowed frontend origins. |
+| `SESSION_COOKIE_NAME`, `SESSION_TTL_DAYS` | backend cookies | Optional; defaults are defined in code. |
+| `VITE_API_URL` | frontend | Defaults to `http://localhost:5000`. |
+| `VITE_ALLOWED_HOSTS` | Vite dev server | Comma-separated host allowlist. |
+| `PLAYWRIGHT_BASE_URL` | Playwright | Defaults to `http://localhost:3010`. |
+
+## Run Locally
+Docker dev stack:
+
+```bash
+docker compose -f docker-compose.dev.yml up
+```
+
+Separate terminals:
+
+```bash
+npm run dev:backend
+npm run dev:frontend
+```
+
+Default local endpoints:
+- Backend: `http://localhost:5000`
+- Frontend through Docker compose port mapping: `http://localhost:3010`
+- Frontend direct Vite default: `http://localhost:5173`
+
+## Verification Commands
+Root entry points:
+
+```bash
+npm test
+npm run lint
+npm run typecheck
+npm run audit
+npm run build:backend
+npm run build:frontend
+npm run build
+npm run test:e2e
+```
+
+Migration checks:
+
+```bash
+npm run db:migrate:status
+npm run db:migrate:verify
+npm run db:migrate:stale:check
+```
+
+Do not run `npm run db:migrate` against a shared or production database unless that is the explicit operator task.
+
+## Common Troubleshooting
+- `DATABASE_URL is required`: export/set `DATABASE_URL` in the shell before root migration commands.
+- `psql executable was not found in PATH`: install PostgreSQL client tools.
+- Frontend cannot reach backend: confirm `VITE_API_URL`, backend port `5000`, and backend `ALLOWED_ORIGINS`.
+- Playwright starts the frontend but API calls fail: start the backend separately or use the Docker dev stack.
+- CORS blocked origin: add the exact frontend origin to `ALLOWED_ORIGINS`.
+
+## Before Finishing Work
+- Re-read `AGENTS.md` and any relevant deeper doc.
+- Run the smallest useful checks first.
+- For API behavior changes, add/update Jest tests with negative cases.
+- For user-facing UI behavior changes, add/update focused Playwright coverage.
+- Summarize any command that failed, whether it appears pre-existing, and the unresolved risk.

docs/PLANS.md

@@ -0,0 +1,36 @@
+# Planning Template
+
+Use this template for multi-step features, refactors, risky bugfixes, or DB work. Keep plans short and update them as evidence changes.
+
+## Goal
+- What user-visible or operator-visible outcome should be true?
+
+## Context
+- Relevant files, routes, data tables, docs, tests, and prior decisions.
+- Current behavior and desired behavior.
+
+## Constraints
+- External DB only; migrations go in `packages/db/migrations`.
+- No cron, workers, or background jobs.
+- RBAC must be enforced server-side.
+- No secrets, receipt bytes, or full invite codes in logs.
+- Preserve current behavior outside the target area.
+
+## Milestones
+1. Recon and evidence.
+2. Minimal design.
+3. Implementation slice.
+4. Tests and verification.
+5. Documentation update.
+
+## Validation
+- Commands to run.
+- Manual checks needed.
+- Negative cases to cover.
+
+## Rollback
+- Files or migrations that would need reverting.
+- Data or operator action needed, if any.
+
+## Open Questions
+- Only questions that materially affect architecture, runtime behavior, public APIs, data storage, security, deployment, package manager, or dependency footprint.

docs/PROJECT_MAP.md

@@ -0,0 +1,61 @@
+# Project Map
+
+This is the fast orientation map for Fiddy.
+
+## Stack
+- Backend: Express 5 on Node 20, CommonJS modules, PostgreSQL via `pg`.
+- Frontend: React 19 + Vite, mostly JSX with partial TypeScript.
+- Package manager: npm.
+- Database: external on-prem Postgres. Migrations are canonical in `packages/db/migrations`.
+
+## Root
+- `PROJECT_INSTRUCTIONS.md`: source-of-truth constraints and delivery contract.
+- `AGENTS.md`: concise Codex/human working guide.
+- `DEBUGGING_INSTRUCTIONS.md`: required bugfix workflow.
+- `package.json`: root DB, test, lint, typecheck, build, and e2e command entry points.
+- `docker-compose.dev.yml`: local app containers with backend env loaded from `backend/.env`.
+- `.gitea/workflows`: deploy workflows for `main` and `main-new`.
+- `.github/copilot-instructions.md`: compatibility shim that points back to root instructions.
+
+## Backend
+- `backend/server.js`: starts the Express app.
+- `backend/app.js`: middleware, CORS, route mounting, and error handling.
+- `backend/build.js`: copies runtime backend files into `backend/dist` for the existing backend build script.
+- `backend/routes`: Express routers.
+- `backend/controllers`: request handlers.
+- `backend/models`: database query modules.
+- `backend/services`: domain service logic where present.
+- `backend/middleware`: auth, optional auth, RBAC, request IDs, rate limiting, and image upload processing.
+- `backend/utils`: logging, HTTP response helpers, cookies, redaction.
+- `backend/tests`: Jest/Supertest tests run from the root Jest config.
+- `backend/migrations`: legacy/reference SQL only; do not add new canonical migrations here.
+
+## Frontend
+- `frontend/src/main.tsx`: browser entry point.
+- `frontend/src/App.jsx`: top-level routing and providers.
+- `frontend/src/config.ts`: API base URL.
+- `frontend/src/api`: API wrappers and shared Axios client.
+- `frontend/src/context`: app state providers.
+- `frontend/src/hooks`: reusable UI-facing hooks.
+- `frontend/src/pages`: route-level pages.
+- `frontend/src/components`: shared and domain UI components.
+- `frontend/src/styles`: global, page, component, and theme CSS.
+- `frontend/tests`: Playwright e2e tests.
+
+## Database and Scripts
+- `packages/db/migrations`: canonical SQL migration set.
+- `packages/db/migrations/stale-files.json`: known skipped/stale migration filenames.
+- `scripts/db-migrate*.js`: migration apply/status/verify/new/stale helpers.
+- `docs/DB_MIGRATION_WORKFLOW.md`: operator runbook for DB changes.
+
+## Documentation
+- `docs/DEVELOPMENT.md`: setup, run, verification, and troubleshooting.
+- `docs/AGENTIC_CONTRACT_MAP.md`: maps Next.js-oriented architecture language to the current Express/Vite stack.
+- `docs/PLANS.md`: lightweight template for multi-step work.
+- `docs/architecture`, `docs/features`, `docs/guides`, `docs/migration`: deeper reference docs.
+- `docs/archive`: historical implementation notes; useful context, not necessarily current.
+
+## Known Maintainability Hotspots
+- `frontend/src/pages/GroceryList.jsx` is large and should be split only during focused UI work.
+- `frontend/src/components/manage/ManageHousehold.jsx`, `backend/services/group-invites.service.js`, and `backend/models/group-invites.model.js` are also large enough to review carefully before editing.
+- Some older README/guides may describe pre-session or pre-household behavior; verify against current code and root instructions before relying on them.

docs/README.md

@@ -1,77 +1,41 @@
 # Documentation Index
 
-This directory contains all project documentation organized by category.
+This directory contains practical project documentation. Root-level rules still take precedence:
 
-## 📁 Directory Structure
+1. `../PROJECT_INSTRUCTIONS.md`
+2. `../DEBUGGING_INSTRUCTIONS.md` for bugfix work
+3. `../AGENTS.md` for Codex and human workflow shortcuts
 
-### `/architecture` - System Design & Structure
-- **[component-structure.md](architecture/component-structure.md)** - Frontend component organization and patterns
-- **[multi-household-architecture-plan.md](architecture/multi-household-architecture-plan.md)** - Multi-household system architecture design
+## Start Here
+- `PROJECT_MAP.md`: quick repo structure and ownership map.
+- `DEVELOPMENT.md`: install, run, test, lint, build, and troubleshooting.
+- `DB_MIGRATION_WORKFLOW.md`: external Postgres migration runbook.
+- `AGENTIC_CONTRACT_MAP.md`: maps source-of-truth architecture language to the current Express/Vite stack.
+- `PLANS.md`: lightweight template for multi-step work.
 
-### `/features` - Feature Implementation Details
-- **[classification-implementation.md](features/classification-implementation.md)** - Item classification system (zones, types, groups)
-- **[image-storage-implementation.md](features/image-storage-implementation.md)** - Image storage and handling (bytea, MIME types)
+## Architecture
+- `architecture/component-structure.md`: frontend component organization and patterns.
+- `architecture/multi-household-architecture-plan.md`: multi-household system planning notes.
 
-### `/guides` - How-To & Reference Guides
-- **[api-documentation.md](guides/api-documentation.md)** - REST API endpoints and usage
-- **[frontend-readme.md](guides/frontend-readme.md)** - Frontend development guide
-- **[MOBILE_RESPONSIVE_AUDIT.md](guides/MOBILE_RESPONSIVE_AUDIT.md)** - Mobile-first design guidelines and audit checklist
-- **[setup-checklist.md](guides/setup-checklist.md)** - Development environment setup steps
+## Features
+- `features/classification-implementation.md`: item classification notes.
+- `features/image-storage-implementation.md`: image storage and handling notes.
 
-### `/migration` - Database Migrations & Updates
-- **[MIGRATION_GUIDE.md](migration/MIGRATION_GUIDE.md)** - Multi-household migration instructions (also in `backend/migrations/`)
-- **[POST_MIGRATION_UPDATES.md](migration/POST_MIGRATION_UPDATES.md)** - Required updates after migration
+## Guides
+- `guides/api-documentation.md`: REST API reference. Verify against current code before changing APIs.
+- `guides/frontend-readme.md`: frontend development notes.
+- `guides/MOBILE_RESPONSIVE_AUDIT.md`: mobile design and audit checklist.
+- `guides/setup-checklist.md`: older setup checklist; prefer `DEVELOPMENT.md` for current commands.
 
-### `/archive` - Completed Implementation Records
-Historical documentation of completed features. Useful for reference but not actively maintained.
+## Migration
+- `migration/MIGRATION_GUIDE.md`: historical multi-household migration instructions.
+- `migration/POST_MIGRATION_UPDATES.md`: historical post-migration notes.
 
-- **[ACCOUNT_MANAGEMENT_IMPLEMENTATION.md](archive/ACCOUNT_MANAGEMENT_IMPLEMENTATION.md)** - Phase 4: Display name and password change
-- **[code-cleanup-guide.md](archive/code-cleanup-guide.md)** - Code cleanup checklist (completed)
-- **[HOUSEHOLD_MANAGEMENT_IMPLEMENTATION.md](archive/HOUSEHOLD_MANAGEMENT_IMPLEMENTATION.md)** - Household management UI implementation
-- **[IMPLEMENTATION_STATUS.md](archive/IMPLEMENTATION_STATUS.md)** - Multi-household migration sprint status
-- **[settings-dark-mode.md](archive/settings-dark-mode.md)** - Dark mode implementation notes
-- **[TEST_SUITE_README.md](archive/TEST_SUITE_README.md)** - Testing infrastructure documentation
+## Archive
+Files in `archive/` are historical implementation records. They are useful for context, but they are not guaranteed to describe current behavior.
 
----
-
-## 📄 Root-Level Documentation
-
-These files remain at the project root for easy access:
-
-- **[../README.md](../README.md)** - Project overview and quick start
-- **[../PROJECT_INSTRUCTIONS.md](../PROJECT_INSTRUCTIONS.md)** - Canonical project constraints and delivery contract
-- **[../AGENTS.md](../AGENTS.md)** - Agent behavior and guardrails
-- **[../DEBUGGING_INSTRUCTIONS.md](../DEBUGGING_INSTRUCTIONS.md)** - Required bugfix workflow
-- **[../.github/copilot-instructions.md](../.github/copilot-instructions.md)** - Copilot compatibility shim to root instructions
-
----
-
-## 🔍 Quick Reference
-
-**Setting up the project?** → Start with [setup-checklist.md](guides/setup-checklist.md)
-
-**Understanding the API?** → See [api-documentation.md](guides/api-documentation.md)
-
-**Working on mobile UI?** → Check [MOBILE_RESPONSIVE_AUDIT.md](guides/MOBILE_RESPONSIVE_AUDIT.md)
-
-**Need architecture context?** → Read [AGENTIC_CONTRACT_MAP.md](AGENTIC_CONTRACT_MAP.md) and [../PROJECT_INSTRUCTIONS.md](../PROJECT_INSTRUCTIONS.md)
-
-**Running migrations?** → Follow [DB_MIGRATION_WORKFLOW.md](DB_MIGRATION_WORKFLOW.md)
-
----
-
-## 📝 Contributing to Documentation
-
-When adding new documentation:
-
-1. **Guides** (`/guides`) - General how-to, setup, reference
-2. **Features** (`/features`) - Specific feature implementation details
-3. **Architecture** (`/architecture`) - System design, patterns, structure
-4. **Migration** (`/migration`) - Database migrations and upgrade guides
-5. **Archive** (`/archive`) - Completed implementation records (for reference only)
-
-Keep documentation:
-- ✅ Up-to-date with code changes
-- ✅ Concise and scannable
-- ✅ Linked to relevant files (use relative paths)
-- ✅ Organized by category
+## Documentation Rules
+- Keep docs concise and linked to real files or commands.
+- Prefer updating `PROJECT_MAP.md` and `DEVELOPMENT.md` before adding new top-level docs.
+- Move completed implementation narratives to `archive/` when they are no longer active runbooks.
+- Keep text encoding clean.

frontend/.env.example

@@ -0,0 +1,2 @@
+VITE_API_URL=http://localhost:5000
+VITE_ALLOWED_HOSTS=localhost,127.0.0.1