grocery-app/docs/README.md

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.