Using AxiOwl for Documentation Maintenance

Documentation maintenance is not just a writing task. For a system like AxiOwl, it is an operating discipline: current behavior, supported provider status, installer expectations, logs, registry evidence, and release proof all have to stay aligned. If those pieces drift apart, operators start debugging yesterday's product instead of the one installed on the machine.

AxiOwl's own documentation structure is built around that problem. The current docs separate source-of-truth reference material from user-facing guides, provider pages, support notes, plans, reports, and historical evidence. That separation is useful because AxiOwl changes across several surfaces at once: the Windows executable, provider integrations, MCP tools, installer behavior, registry state, and provider-specific delivery paths.

Treat Reference Docs as the Contract

The strongest documentation-maintenance rule in the AxiOwl repo is simple: current product behavior belongs in docs/reference. The reference README names the canonical files for architecture, provider support, installer behavior, and release validation. Other documentation folders can explain those topics for a particular audience, but they should point back to the reference docs rather than redefining the same behavior.

That matters most for provider status. A provider page can describe how Codex, Cursor, VS Code, Antigravity, or a CLI surface is expected to work, but the current status lives in the Provider Support Matrix. The matrix defines terms such as supported, target, experimental, unsupported, and removed. It also records delivery method, installer action, required patch or config, current test status, and known risks.

The maintenance workflow follows from that: when provider status changes, update the matrix first. Then update the provider page that links to it. This prevents a common failure mode in fast-moving integration projects, where one document says a surface is supported while another still treats it as experimental.

Keep Evidence Boundaries Visible

AxiOwl documentation also has to preserve evidence boundaries. The product itself distinguishes between several different events:

• the MSI install completed selected actions;
• AxiOwl accepted a send request;
• a provider edge reported that delivery was accepted;
• a provider replied through AxiOwl MCP with usable sender identity.

Those are not interchangeable. The user docs and support docs both make the distinction explicit, and the implementation backs it up. SendReceipt includes accepted_by_axiowl and accepted_by_provider as separate fields. The message pipeline sets the receipt state to accepted_by_axiowl when AxiOwl has accepted and handed the message to the delivery layer. The MCP server's tool description says that axiowl_send_message success is a handoff receipt only, not proof of provider delivery or reply.

For documentation maintenance, this means release notes, troubleshooting guides, and provider pages should avoid vague language like "message delivered" unless the evidence really proves delivery. If the only proof is accepted_by_axiowl, say that. If the proof is a provider reply over MCP with the expected run id and provider-owned sender metadata, say that too. The distinction makes support faster because it tells the next operator where the chain stopped.

Use Runtime Artifacts as Maintenance Inputs

AxiOwl is useful for documentation maintenance because it leaves behind inspectable state. The docs identify the main local artifact areas:

• %LOCALAPPDATA%\AxiOwl\logs for runtime, installer helper, discovery, and delivery logs;
• %LOCALAPPDATA%\AxiOwl\registry for agent registry and bridge registry data;
• %LOCALAPPDATA%\AxiOwl\runtime for request, result, and worker handoff files;
• MSI verbose logs for installer action history;
• provider extension output channels for VS Code and Cursor bridge behavior.

Those artifacts are not just troubleshooting leftovers. They are maintenance inputs. If a provider page says a surface is sendable, the registry should show a current row with provider, provider session id, node id, source, sendable, last_seen_at, last_verified_at, and last_error fields that support that claim. If an installer page says unchecked providers are not touched, validation should confirm that unchecked providers were not installed, patched, closed, restarted, or removed.

The axiowl discover command is also part of this loop. The CLI exposes discovery for individual provider surfaces and for all, with JSON output available. The architecture docs describe discovery as a repair mechanism for stale or missing registry state, but not as a substitute for provider delivery proof. That sentence is a documentation-maintenance guardrail: discovery can update what AxiOwl knows, while an MCP reply proves the full message path.

Maintain Installer Docs as Selected-Feature Behavior

Installer documentation has a high risk of drift because the MSI touches multiple integration surfaces. The Installer Behavior Matrix gives maintainers a stable shape: AxiOwl installs one local runtime, but each provider feature should behave like a separate install unit.

The matrix records what each feature installs, patches, configures, removes, and intentionally does not touch. That last column is important. AxiOwl should not modify unrelated provider extensions, auth tokens, unrelated settings, unrelated workspace files, unchecked provider surfaces, or remote configuration unless explicitly selected. The security docs repeat the same expectation from a user-trust perspective.

When installer behavior changes, the maintenance job is not just to update a checkbox description. The reference matrix, user install docs, support diagnostics, and release validation checklist all need to stay consistent. For example, if a provider becomes patch-sensitive, support docs should tell operators what logs and bridge output to collect, while the installer docs should say when that patch is selected and what it intentionally avoids.

Turn Release Validation Into Documentation Review

The release checklist is also a documentation-maintenance checklist. Before publishing an installer, it calls for confirming provider support status, confirming installer behavior, removing stale release artifacts, running clean builds and tests, verifying MSI provenance, installing on a clean Windows 11 VM, running discovery, creating fresh chats, and testing send/receive paths.

That workflow naturally produces documentation updates. If a provider passes response-backed proof, the Provider Support Matrix may need to move it to supported. If auth or metadata blocks a CLI provider, the matrix should keep it at target instead of overstating support. If a stale path is discovered during VM validation, support docs should capture the failure pattern so the next incident starts with a known checklist rather than a guess.

The key is to document what the release actually proved. AxiOwl's current support bar is intentionally strict: discovery, install/config, send, provider receive, MCP reply, and correct sender identity. Documentation should match that bar.

Practical Maintenance Workflow

A practical AxiOwl documentation-maintenance pass can be short and repeatable:

1. Start with docs/reference and identify the contract affected by the change.
2. Check implementation or CLI behavior before changing wording.
3. Run or review discovery, registry, log, runtime, or release evidence that proves the claim.
4. Update the source-of-truth reference document first.
5. Update audience-specific docs only to explain or link back to that source.
6. Keep plans and reports historical unless the reference docs intentionally promote their content into current behavior.
7. Avoid treating install success, AxiOwl handoff, provider acceptance, and MCP reply as the same proof.

This is where AxiOwl's architecture helps. Because provider sessions are represented in a durable local registry and message flow records receipt boundaries, maintainers have concrete artifacts to compare against docs. The documentation can say what is supported, why it is supported, and what evidence would prove it again.

Closing

Good documentation maintenance for AxiOwl is evidence-driven. The current docs already encode the operating model: reference docs are the contract, provider pages link back to the matrix, support docs preserve forensic boundaries, and release validation checks the product before claims change.

That keeps AxiOwl documentation from becoming a pile of stale intentions. It turns the docs into an operational map of the real system: local Windows coordinator, MCP tool surface, provider registry, selected installer integrations, logs, runtime evidence, and end-to-end provider replies when the path truly works.