AxiOwl Documentation Source Of Truth
This folder is the current product contract for AxiOwl. Other docs can explain the product for a specific audience, but they should not invent a second version of provider support, installer behavior, release gates, or architecture.
Why This Folder Exists
AxiOwl has several moving parts: a Windows installer, local runtime, provider discovery, MCP tools, provider-specific bridges, patches, and CLI integrations. When those parts are documented in separate dated reports, it becomes easy for one page to say a provider is separate, another to say it is folded into the MSI, and a third to describe an old experiment as current behavior.
The source-of-truth pattern prevents that loop. Current behavior belongs here. Historical discoveries belong in reports. Future ideas belong in plans. Troubleshooting stories belong in support docs.
Canonical Docs
| Document | Purpose |
|---|---|
| Architecture Overview | Explains the system shape, message flow, registry, discovery, delivery, and receipt boundaries. |
| Provider Support Matrix | Defines which provider surfaces are supported, target, experimental, unsupported, or removed. |
| Installer Behavior Matrix | Defines what the MSI installs, patches, configures, removes, avoids, and logs. |
| Release Validation Checklist | Defines the minimum release proof before publishing a Windows installer or docs update. |
Definitions Used Everywhere
| Term | Meaning |
|---|---|
| Provider | A brand and surface pair, such as cursor:agents, codex:cli, or copilot:vsix extension. |
| Surface | The specific place AxiOwl talks to: editor, agent window, CLI, VSIX-backed session, or remote node. |
| Supported | End-to-end response proof exists under the current rules. |
| Target | Code or design exists, but the current support bar has not been met. |
| Receipt | A record that AxiOwl accepted a request. It is not the same as provider delivery proof. |
| MCP reply | A provider response through AxiOwl MCP with provider-owned sender metadata. This is the strongest routine proof. |
| Discovery | The process of finding provider sessions and adding or refreshing registry rows. |
| Patch | A selected provider modification needed when the provider does not expose a stable public API for the required behavior. |
Documentation Rules
- Describe what exists now, not what would be ideal.
- Do not mark a provider supported because config files exist.
- Do not mark a provider supported because AxiOwl accepted a send request.
- Do not use historical proof as current proof when the support bar has changed.
- Do not hide fragile paths. Explain why they are fragile and what proof is required.
- Keep provider pages consistent with the matrix.
- Keep installer docs consistent with the installer behavior matrix.
- When a provider changes status, update the matrix first.
Architecture Opinion
AxiOwl should stay explicit and evidence-driven. The system should prefer a louder failure with useful logs over a quiet fallback that makes a broken path look successful. This matters because provider automation often fails in ambiguous ways: stale sessions, old workspace paths, missing MCP tools, partial patch installs, and provider auth failures can all look similar from the outside.
The docs should help a user or developer answer three questions quickly:
- What was supposed to happen?
- What actually happened?
- Which boundary failed: install, discovery, send handoff, provider delivery, or MCP reply?