Contributing
How to work on Ensemble code and documentation. Start with the repository CONTRIBUTING.md and AGENTS.md; this hub collects the contributor-only documentation that used to sit in the main docs index.
Before you start
- Read CONTRIBUTING.md for setup, verification, and pull-request expectations.
- Read AGENTS.md and the domain glossary.
- Follow the issue tracker workflow and the triage labels.
- For TUI or host integration work, read the OpenCode/OpenTUI runtime guide.
Documentation work
- Documentation style guide: voice, canonical terms, page template, code samples, visuals, and review checklist.
- Redirect map: old docs-index entries and their new homes.
- Docs home: the user navigation this work must keep accurate.
- Evidence index: ADRs, verification records, implementation notes, assessments, and compatibility evidence.
Build the docs site locally with npm run docs:site and publish-preview it with npm run docs:site:preview. npm run docs:site:build runs the sidebar, reachability, redirect, SEO, sitemap, generated-artifact, and built-anchor checks before the VitePress build. npm run docs:check is the full local gate: Markdown lint, inventory, frontmatter, links and rendered anchors, Markdown fences, shell syntax, canonical version/host/Node claims, generated reference freshness, media, the VitePress build, and the built-site anchor crawl. CI runs npm run docs:check:fast in the separate Docs job; the Docs site job owns the single VitePress build. Fixture tests use the explicit --skip-site-build mode.
Update user documentation when externally visible behavior changes. If no doc update is needed, put a docs-not-needed: <reason> line in the pull request body; the docs-rationale workflow checks the changed-file list and PR body from the trusted base checkout. It is not yet a required status check on main: adding it needs an explicit maintainer decision and a GitHub ruleset change, which this repository does not configure. Until then the workflow is advisory and the program merge can proceed without claiming external enforcement. Keep ADRs and verification records public, but do not put them in the primary user navigation; link them from the evidence index or as a Go deeper link at the end of a concept page.
The Docs site workflow builds the Pages artifact on pull requests and deploys only from main after the repository's Pages environment is enabled. Enabling Pages and publishing the site are external maintainer actions; this branch does not deploy the site or claim that it is live.
Review and process
| Document | Purpose |
|---|---|
| Review workflow | The two-axis review process |
| Reviewer standards | Judgement calls that stay manual |
| Handoff contract | Server-owned completion, migration handoff, batch review, loop guards, and mentions |
| Domain document conventions | Glossary and ADR conventions |
Architecture and evidence
| Resource | What it contains |
|---|---|
| ADR index | Every accepted architecture decision |
| Evidence index | Current and historical verification records |
| Implementation notes | Service, TUI, storage, native tools, and acceptance notes |
| OpenTUI assessment | Historical host-evaluation evidence |
| OpenCode host support range | Supported CLI releases, peer range, and runtime warning |
| OpenCode 2.2.1 compatibility report | Historical extension behavior and gaps |
Boundaries
- Keep credentials, conversation content, and private paths out of the repository and public issues. The support policy lists the redaction rules.
- Do not rewrite an ADR or verification record to match a new claim; add a new record or supersede the decision.
- Do not hand-maintain generated reference lists. Run
npm run docs:referenceafter changing a catalog;npm run docs:checkfails when a generated page is stale, missing, or unreachable from the reference index.