This page is the documentation entry point. It separates current behavior, current evidence, operating guides, engineering policy, and future proposals so readers can tell what CodeMesh does from what it may do later.
| Reader | Read first | Then use |
|---|---|---|
| Evaluating CodeMesh | README.md |
MCP Setup, Project Status |
| Using CodeMesh through MCP | MCP Setup | Agent Prompts, Agent Access Contracts |
| Contributing | CONTRIBUTING.md |
COMMANDS.md, Testing, Engineering Standards |
| Understanding, debugging, or extending the implementation | Developer Handbook | Source Walkthroughs, Development and Debugging, Making Changes |
| Coding agent working in this repository | Agent Quickstart | AGENTS.md, Architecture |
| Reviewing product direction | Project Status | Next Steps, then the relevant proposal |
The Backup and Recovery guide records the verified disposable Linux procedure and the remaining upgrade/acceptance gates.
The source review packet consolidates local artifact evidence, draft release notes, and remaining acceptance gates.
When documents overlap, use this order:
- Source code and tests define implemented behavior.
- Agent Access Contracts and Architecture describe the current supported surfaces and component boundaries.
COMMANDS.mdindexes supported repository invocations; Testing, MCP Setup, and Security and Redaction are current operating guides.- Engineering Standards and the Software Engineering Methodology define contributor policy, evidence states, and authority boundaries.
- Project Status records the latest reviewed implementation and evidence position.
- Next Steps is the execution-order authority for future product work.
- Proposal and roadmap documents describe unimplemented possibilities unless current source and contracts say otherwise.
- Dated evidence and publication reviews describe only the commit and time they identify.
Document labels have these meanings:
- Current reference: intended to match current implemented behavior.
- Operating guide: commands and procedures for the current product.
- Status snapshot: reviewed implementation and evidence at a stated date.
- Policy: contributor, security, or engineering rules.
- Proposal: requirements or design that is not implemented.
- Historical evidence: immutable or retained evidence for an earlier commit; never a claim about current HEAD by itself.
| Folder | Purpose |
|---|---|
current/ |
Implemented architecture, interfaces, security behavior, and current status. |
guides/ |
Task-oriented setup, operation, self-analysis, and agent workflows. |
evaluation/ |
Verification procedures, effectiveness evaluation, prompt assets, and retained evidence. |
planning/ |
Execution order, proposals, qualification procedures, and deferred roadmaps. |
engineering/ |
Contribution standards and repository-quality controls. |
decisions/ |
Architecture decision records for consequential implemented choices. |
history/ |
Dated reviews retained for provenance, not current status. |
README.md— public product overview and local demonstration.- Project Status — current capability and evidence summary.
- Architecture — implemented components, flow, and stores.
- Identity and Persistence — graph/content identities, physical keys, publication, retention, and partial failures.
- Ingestion Internals — selection, each parser, composition, incremental writes, refresh, and watch.
- Retrieval Internals — binding, freshness, ranking, expansion, package assembly, and output budgets.
- Enrichment and Evaluation Internals — embeddings, summaries, qualification, onboarding, feedback, and harnesses.
- Agent Access Contracts — REST, MCP, CLI-facing, UI, and .NET client contracts.
- Security and Redaction — implemented redaction, known gaps, and safety constraints.
- Developer Handbook — human entry point, mental model, glossary, chapter index, and recommended reading paths.
- Developer Walkthroughs — three source traces from ingestion through retrieval and changed-source refresh.
- Development and Debugging — setup, configuration, debugging entry points, symptoms, and inspection findings.
- Making Changes — parser, ranking, interface, and lifecycle change walkthroughs with validation selection.
- MCP Setup — services, ingestion, stdio MCP configuration, and troubleshooting.
- Self-Analysis — index and query CodeMesh itself.
- Agent Prompts — source-grounded example tasks.
- Agent Quickstart — repository navigation for coding agents.
- Testing — canonical risk-scaled validation commands.
- MCP Effectiveness Evaluation — fixture, live, agent, and model evaluation procedures.
- Evidence manifests — sanitized, commit-bound evidence retained in Git.
- Evaluation prompt assets — pinned chat templates used by explicitly authorized model-backed evaluation.
- Publication Readiness Review — historical 2026-08-11 publication-preparation evidence, not current readiness status.
- Next Steps — canonical execution order and capability map.
- Agent Integration Contract — selected explicit-onboarding contract, implemented checkout binding, freshness enforcement, tool profiles, runtime probes, reviewable installation, and evaluation classification.
- one|nine Adoption and Feedback Priority — owner-activated plan and passed local pilot gate for safe checkout-bound adoption, atomic Python/Rust ingestion, a Rust parser, agent feedback artifacts, and controlled evaluation.
- Development-Session MCP Feedback Loop — completed owner-activated plan for explicit session-scoped client feedback tools, read-only CodeMesh maintainer intake, human-approved changes, and append-only verified rechecks.
- Graph Intelligence and Agent Memory — relationship evidence, graph analysis, parser tiers, memory, and portability proposal.
- Method Load and Retrieval Granularity — proposed human-maintainability, model-representation, token-accounting, and method-decomposition evaluation.
- Repository Identity and Snapshot Retention — implemented local multi-checkout retention and future shared-store requirements.
- Summary Model Qualification — implemented runner and operating procedure; no deployment profile is currently qualified.
- SDLC Roadmap — deferred broader artifact coverage.
CONTRIBUTING.md— contribution entry point.COMMANDS.md— canonical supported command index.SECURITY.md— vulnerability reporting and safe operation.THIRD_PARTY_NOTICES.md— third-party and distribution boundaries.- Engineering Standards — change discipline, verification, documentation, and definition of done.
- Software Engineering Methodology — evidence, authority, guidance placement, and reusable-control admission boundaries.
- Conventional Commit Validation — local commit-message checker.
- GitHub Actions Baseline — exact workflow scope and evidence boundary.
- Markdown Link Checking — deterministic local link validation.
- Release Preparation — source version, candidate contract, compatibility, and reviewable release gates; no release authorization.
- Release Notes Template — prepared, tagged, published, deployed, and stable-state separation for a future release.
- Decision Record Template — ADR format for implemented architecture decisions.
- Keep supported contributor and agent invocations in the root
COMMANDS.md; keep ordered operational and evaluation procedures in their controlling guides and link between them. - Keep current implementation and evidence in
current/project-status.md; keep future execution order inplanning/next-steps.md. - Mark proposals and historical reviews explicitly near the title.
- Update contracts and architecture when implemented behavior changes.
- Bind measurements to a date and commit, and retain negative evidence.
- Do not convert a passing fixture, local test, or configured workflow into a hosted, production, release, or product-benefit claim.
- Preserve stable documentation paths when practical. When an approved reorganization moves them, update tests, suites, prompts, and repository links in the same change.