OTerminus Documentation Handbook

OTerminus is a local AI terminal assistant that is capability-first, structured-first, and safety-first. This handbook is the source of truth for product usage, architecture, and contributor reference material.

Recommended reading paths

I want to use OTerminus

1. What is OTerminus?
2. User guide — REPL, one-shot, doctor, dry-run, explain, and ambiguity handling
3. Supported workflows
4. Policy modes

I want to understand the architecture

1. Architecture overview
2. Request lifecycle — direct-command detection, ambiguity handling, planning, validation, and execution
3. Routing and planning
4. Structured rendering and proposal modes
5. Validation and policy
6. Execution

I want to contribute changes

1. Contributor workflow
2. Capability system
3. Command registry
4. Capability map
5. Command families reference
6. Adding command families safely

I want to debug or test behavior

1. Observability
2. Evals
3. Configuration reference
4. Audit log schema

Sections

• Product docs: docs/product/
• Architecture docs: docs/architecture/
• Reference docs: docs/reference/
• ADRs: docs/adr/

Build and preview docs locally

poetry install --with dev,docs
poetry run mkdocs serve
poetry run mkdocs build --strict

See the contributor workflow for the complete local lint, format, test, and docs checklist.

Documentation contributor notes

When architecture, behavior, configuration, command support, or eval behavior changes, update docs in the same PR. Keep proposal-mode docs consistent across README and docs/: structured and experimental are the only supported first-class modes.

Before opening a PR, run poetry run mkdocs build --strict and fix any warnings or broken links.

Command capability reference pages are generated from the registry; run poetry run python scripts/generate_command_reference.py --write after command-spec changes and verify with --check before opening a PR.

Keep docs free of secrets, real tokens, personal local paths, or audit logs.

GitHub Pages setup note

After merging this setup, enable Pages deployment in the repository: Settings → Pages → Build and deployment → Source → GitHub Actions.