# Documentation Index

This directory contains practical project documentation. Root-level rules still take precedence:

1. `../PROJECT_INSTRUCTIONS.md`
2. `../DEBUGGING_INSTRUCTIONS.md` for bugfix work
3. `../AGENTS.md` for Codex and human workflow shortcuts

## 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.

## Architecture
- `architecture/component-structure.md`: frontend component organization and patterns.
- `architecture/multi-household-architecture-plan.md`: multi-household system planning notes.

## Features
- `features/classification-implementation.md`: item classification notes.
- `features/image-storage-implementation.md`: image storage and handling notes.

## 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.

## Migration
- `migration/MIGRATION_GUIDE.md`: historical multi-household migration instructions.
- `migration/POST_MIGRATION_UPDATES.md`: historical post-migration notes.

## Archive
Files in `archive/` are historical implementation records. They are useful for context, but they are not guaranteed to describe current behavior.

## 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.