From 767def37cffc4e42f3e49e38e6eae39127b9e75c Mon Sep 17 00:00:00 2001 From: Nico Date: Mon, 25 May 2026 11:47:21 -0700 Subject: [PATCH] docs: improve project onboarding --- .agents/skills/fiddy-verify/SKILL.md | 40 ++++++++ AGENTS.md | 144 ++++++++++++++++++--------- README.md | 2 + docs/DEVELOPMENT.md | 95 ++++++++++++++++++ docs/PLANS.md | 36 +++++++ docs/PROJECT_MAP.md | 61 ++++++++++++ docs/README.md | 98 ++++++------------ frontend/.env.example | 2 + 8 files changed, 366 insertions(+), 112 deletions(-) create mode 100644 .agents/skills/fiddy-verify/SKILL.md create mode 100644 docs/DEVELOPMENT.md create mode 100644 docs/PLANS.md create mode 100644 docs/PROJECT_MAP.md create mode 100644 frontend/.env.example diff --git a/.agents/skills/fiddy-verify/SKILL.md b/.agents/skills/fiddy-verify/SKILL.md new file mode 100644 index 0000000..8d45d6e --- /dev/null +++ b/.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. diff --git a/AGENTS.md b/AGENTS.md index baca243..baa0921 100644 --- a/AGENTS.md +++ b/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 diff --git a/README.md b/README.md index 35f86b3..5e92180 100644 --- a/README.md +++ b/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) diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md new file mode 100644 index 0000000..5853ee6 --- /dev/null +++ b/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. diff --git a/docs/PLANS.md b/docs/PLANS.md new file mode 100644 index 0000000..d975022 --- /dev/null +++ b/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. diff --git a/docs/PROJECT_MAP.md b/docs/PROJECT_MAP.md new file mode 100644 index 0000000..dd2c412 --- /dev/null +++ b/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. diff --git a/docs/README.md b/docs/README.md index b2487a5..24b6be8 100644 --- a/docs/README.md +++ b/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. diff --git a/frontend/.env.example b/frontend/.env.example new file mode 100644 index 0000000..610beb1 --- /dev/null +++ b/frontend/.env.example @@ -0,0 +1,2 @@ +VITE_API_URL=http://localhost:5000 +VITE_ALLOWED_HOSTS=localhost,127.0.0.1