Repository Layout
comstar/
├── docs/ # In-repo docs (source for much of this wiki)
│ ├── CONTRACTS.md
│ ├── IMPLEMENTATION_PLAN.md
│ ├── IMPLEMENTATION_TRACKER.md
│ ├── RUNBOOK.md
│ ├── DEV_LOOP.md
│ ├── BASELINES.md
│ ├── fixtures/ # CPAI JSON fixtures from M0 probes
│ └── adr/ # Architecture decision records
├── terminal/ # Everything that runs on the Pi
│ ├── bridge/ # Dart — attention, vision, speech, ao_reach
│ │ ├── bin/comstar_bridge.dart
│ │ └── lib/
│ │ ├── session.dart
│ │ ├── speech_routing.dart
│ │ ├── attention/
│ │ ├── vision/
│ │ └── local_ws.dart
│ ├── audio/ # Python — wake word, VAD, capture
│ ├── kiosk/ # Web — SVG avatar (TalkingHead/GLB planned)
│ └── admin/ # Ops console static UI (:8781/admin)
├── overlays/comstar/ # AO session overlay definitions
│ ├── agent_providers/
│ └── mcp_providers/
├── mcp/
│ ├── vision_mcp/ # wraps CodeProject.AI for the orchestrator
│ └── terminal_mcp/ # Pi-local: display, speaker, sleep, volume
├── config/
│ ├── comstar.example.yaml
│ ├── comstar.dev.example.yaml
│ └── comstar.mac.env.example
├── testdata/stt/ # STT golden + live-bridge fixtures
├── deploy/systemd/ # User unit files
├── scripts/ # enroll, STT/TTS servers, doctor, wake train
├── spike/ # Throwaway probes (e.g. reach_hello.dart)
└── vendor/ # agentic-orchestration (+ reach) submodules
| Need | Path |
|---|---|
| Cross-process interfaces |
docs/CONTRACTS.md → wiki Contracts
|
| Milestone tasks |
docs/IMPLEMENTATION_PLAN.md → Milestones
|
| Live status |
docs/IMPLEMENTATION_TRACKER.md → Progress Tracker
|
| Operator how-to |
docs/RUNBOOK.md → Runbook
|
| Mac↔Pi workflow |
docs/DEV_LOOP.md → Dev Loop
|
| Attention logic | terminal/bridge/lib/attention/ |
| Avatar | terminal/kiosk/avatar.js |
| Agent rules |
AGENTS.md → Contributing for Agents
|