README.md

Wright Documentation

This directory contains Wright's durable product/integration contracts and supporting references. Keep architecture intent, decision history, current implementation reality, and mutable execution state separate.

Documentation model

architecture/README.md       current Wright architecture routing
  ├─ ownership.md            product/repository ownership + dependency direction
  ├─ integration.md          language/provider integration + failure routing
  └─ tooling.md              Wright-owned tooling/edit/agent/CI/LSP model
cli.md / embedding.md / ...  focused public/product contracts
compatibility.md             Wright integration verification contract
adr/                         point-in-time decisions and rationale
source/tests/CI/integrations current implementation reality
Issues / PRs / releases      mutable execution state

For substantive implementation work, start from architecture/README.md, resolve the smallest relevant current contract, then inspect the affected code/tests/owner and the Issue contract.

Current architecture

• Architecture routing
• Ownership and dependency contract
• Language/provider integration contract
• Wright tooling contract
• architecture.md is retained as a compatibility pointer for older links, not a second current architecture authority.

Focused product contracts

• CLI & driver: commands, exit behavior, and machine-readable result contracts.
• Embedding/tool API: programmatic session/query/edit services.
• Language services & LSP: editor-neutral language services and LSP framing.
• Integration verification: owner boundaries and Wright-owned tests.
• Licensing/provenance boundary: third-party reference and licensing constraints.
• Extensible lint rules: canonical facts, local declarative rules, metadata, and project configuration.
• Release/distribution: packaging and publication contract.
• Agent-team governance: role/authority coordination where still applicable.

Language implementation evidence

Wright is not the durable owner of OPY, DEL/OSTW, or raw Workshop semantics. Current language support claims must come from the owning repositories:

• wrightkit/opy-rs for OverPy syntax/semantics/compiler/reconstruction;
• wrightkit/deltin-rs for DEL/OSTW project/type/runtime/compiler/reconstruction;
• wrightkit/workshop-rs for canonical raw Workshop/WIR/catalog/settings/ localization/validation/emission.

Older Wright-side OPY/OSTW/Workshop paths may remain only as concise compatibility pointers when external links still need a landing page. They must route to the owning repository instead of retaining duplicate semantic, HIR, catalog, or compatibility authority. Do not keep historical implementation documents current inside Wright after ownership has moved.

Architecture decision history

docs/adr/ preserves point-in-time decisions and rationale. Accepted ADRs are historical decision records; they are not proof that current code still implements the decision. Materially changed architecture is represented in current contracts and, when needed, a new/superseding ADR rather than retroactively rewriting history.

Current reality and execution state

Source, Cargo metadata, tests, CI, provider integrations, releases, and real-project workflows establish current implementation reality. GitHub Issues and PRs carry scope, acceptance, sequencing, and transient progress.

Do not maintain feature counts, versions, migration progress, PR state, or roadmap snapshots in durable architecture documents.

Repository entry points

• README.md: public product overview and quick start.
• CONTRIBUTING.md: contributor onboarding and checks.
• AGENTS.md: implementation routing, ownership, verification, and delivery rules.
• LICENSE: repository license.