[META] Misalignment: README, Roadmap, and Repo Structure #6

Misalignment: README vs Roadmap vs Actual Repo

This issue tracks identified misalignments between the README.md, the live repository, and the current roadmap (roadmap.md). These may cause confusion for new users, contributors, or integration partners.

1. Product vs. Reference Implementation/Architecture

• The README.md states: "This repository is a reference architecture, not a product." This is clear, but:
  • Roadmap phases repeatedly mention features and tasks using "production" language ("production-quality async Python agent," "operational hardening," etc.).
  • Repo Structure & Files include subfolders (e.g., agents/obs_server) that may appear productized or stable, but are marked as reference or experimental in docs.
• Impact: This blurring of reference code vs. production readiness can confuse potential users and contributors.
• Recommendation: Clarify throughout docs and file layout which parts are experimental, reference-only, or production-ready. Keep README, roadmap, and architecture docs consistent.

2. Scope and Feature Completeness

• The README.md lists architecture (object store, ledger, agents, dashboard, etc.) but this doesn't precisely map to the phased, sequential milestones in the roadmap.md (e.g., timeline, partial implementations).
• The actual repo features may lag or lead vis-à-vis what's described in either file.
• Impact: Ambiguity around current versus future/roadmap features.
• Recommendation: Clearly differentiate released features from those planned (with issue links & badges) in README and roadmap. Consider a features/status matrix.

3. Technical Stack & Usage Guidance

• The README.md "Quick Start" assumes everything spins up via make up/docker-compose. However, the roadmap and actual code point to features that may not be fully wired, and various language components (Go, Python, TypeScript) are at different completeness.
• Impact: Getting started may fail, or users get an incomplete view.
• Recommendation: Indicate in the README or roadmap precisely what is ready-to-test, what is prototype/inactive, and what's coming next.

Please review this issue for further breakdown of specific mismatches, and comment below with additional discrepancies you've found.