AspectAvy Platform — Start Here

Use When

• You are opening the rewrite repo in a fresh chat
• You need the current product status without re-deriving it from chat history
• You want to choose the next implementation or validation slice quickly

Quick Facts

- backend - contracts - ops

- mrbagels/aspectavy-ios - existing aspectavy-web repo

• Repo type: platform continuity repo after the split
• Main local surfaces:
• Sibling repos:
• Backend stack: Fastify, TypeScript, Postgres, Docker Compose
• Current phase: platform surfaces are implemented; the main work is QA, hardening, web parity, and repo-boundary cleanup
• The hosted docs at /docs are now the canonical interactive API and operator reference surface, with separate Overview, API, Operator, and Guides domains plus dedicated landing pages and contextual nav for each domain; the backend also exposes /api/openapi.json, /api/admin-cli.json, and /api/ai/defaults.json as machine-readable sources of truth

Recommended Read Order

1. documentation/reference/current-state.md
2. documentation/development/v1-remaining-milestones.md
3. documentation/development/handoff-next-chat.md
4. documentation/development/end-to-end-qa-runbook.md
5. documentation/development/manual-validation-remaining.md
6. documentation/development/manual-validation-checklist.md
7. documentation/development/follow-up-backlog.md
8. documentation/development/program-implementation-roadmap-spec.md
9. One targeted playbook or capability card from llm

Task Routing

- read llm/playbooks/local-setup-and-validation.md

- read llm/playbooks/implement-follow-up-slices.md

- read llm/capabilities/repo-map.md

- read llm/capabilities/current-state.md

- read llm/capabilities/branching-and-environments.md

- read llm/capabilities/admin-cli.md - for operator validation entrypoints, also read documentation/development/admin-portal-operator-qa.md

- read llm/playbooks/ai-tooling-and-mcp.md

• Local setup, running the stack, simulator validation:
• Picking the next product slice to build:
• Repo orientation and ownership boundaries:
• Current functionality and known gaps:
• Branch and environment strategy:
• Backend operator tooling and server-side support workflows:
• AI tooling, machine-readable defaults, or MCP-oriented work:

Source Of Truth

• documentation/reference/current-state.md for what works now
• llm/capabilities/branching-and-environments.md for the canonical branch-to-environment model
• documentation/development/v1-remaining-milestones.md for the canonical remaining V1 execution order
• documentation/development/handoff-next-chat.md for the best short handoff on near-term cleanup priorities
• documentation/development/follow-up-backlog.md for detailed implementation and discussion items
• documentation/development/program-implementation-roadmap-spec.md for the larger milestone detail across backend, parity surfaces, and on-device Foundation work
• documentation/development/end-to-end-qa-runbook.md for the current top-level QA plan
• documentation/development/manual-validation-remaining.md for older remaining-slice notes
• documentation/development/manual-validation-checklist.md for older milestone-era detailed steps
• mrbagels/aspectavy-ios for current iOS schemes, environment configs, and Xcode setup
• the current stabilization slice covers generated iOS test bundles, test plans, Xcode Cloud scaffolding, SQLiteData-friendly service tests, and the new navigation-driven developer tools dashboard with signed-in and logged-out entrypoints
• README.md and documentation/README.md for repo-level orientation
• iOS implementation work now belongs in aspectavy-ios; this repo should only carry shared product context when it affects platform contracts, docs, or parity behavior

Read Next

• documentation/development/v1-remaining-milestones.md
• documentation/development/handoff-next-chat.md
• llm/playbooks/local-setup-and-validation.md
• llm/playbooks/implement-follow-up-slices.md