[Repo Misalignment] Directory Structure Suggests Stability Not Matched By Code

[bjl13]

Repo File Structure vs Docs/Roadmap: Directory Content Ambiguity

• The repo contains folders like agents/, internal/, and dashboard/ with mixed levels of code and documentation. Documentation claims they support certain objects, reference models, and minimal dashboard UI, but the actual implementation varies in stability and completeness.
• Folder hierarchy and file names may give the impression of finished, production-grade modules. Some directories may contain placeholders, partial implementations, or prototypes only. The distinction is not always clear in structure or documentation.

What needs fixing:

• Make folders and files self-documenting: Add README stubs to major directories explaining stability, readiness, or intended use (reference, example, alpha/beta).
• Cross-link sections in the main README and roadmap to directory-level guidance on what to expect inside.
• Periodically audit and clean up/relabel folders as code matures.

---

Relates to parent: [META] Misalignment: README, Roadmap, and Repo Structure