Documentation inventory
For the September 29, 2026 clarity review, see the documentation quality audit. It records 14 findings and their resolution in PR #615. The inventory below retains the earlier audit and its proposals.
This audit mapped the documentation to Getting Started, Topics, Integrations, Reference, and Contribute. It assigns a destination, action, and quality rating to 224 tracked Markdown files: 121 website pages and 103 repository-only files. This audit predates the website reorganization and records what the source looked like at the time.
The tables below preserve the earlier five-menu proposal, including suggestions that were not adopted. The site now has six sections: Getting Started, Topics, Integrations, Operate, Reference, and Contribute. Getting Started offers local Kubernetes setup and a first Agent; joining an existing installation and the Docker/Podman preview are deferred. Use the documentation home for the current layout and the organization and naming guidance when changing it. Pinned evidence below refers to the original source snapshot.
The snapshot is the documentation PR #258 at 6b345824, compared with main at 5f7728e. Of the 224, 209 were unchanged from main, 11 were updated in that PR, and four existed only in the PR: the product guide, first-Agent guide, contributor guide, and first-change guide. The new audit pages are not in that count. YAML, source code, workflows, and CLI implementation were checked as supporting evidence when needed, but are not Markdown inventory entries. No product behavior was run for this audit.
Audited menu and sidebars
This is the earlier proposal, not the current navigation. Bold items were its principal sidebar groups.
| Menu bar | Sidebar |
|---|---|
| Getting Started | Overview, Concepts, Quickstart, Deploy. Quickstart gives equal weight to Set up the platform and Join an existing installation. Put Deploy your first Agent under Deploy and link to it from both paths. Production installation, operations, and recovery also live under Deploy. |
| Topics | Agent: Compute, Harness, lifecycle, workspace files, troubleshooting. Security: IAM, Namespace, Sandbox, Secrets. Capabilities: Plugins, Repositories if product support is confirmed. Configuration: Agent configuration, installation settings, and observability. |
| Integrations | Drivers: catalog, comparisons, and named implementations such as Kubernetes, SSH, and OpenShell. Providers: overview and named implementations such as ChatGPT. Propose a separate Channels group for Slack and Microsoft Teams; these are not OCC Providers. |
| Reference | CLI. Also retain the existing generated HTTP API as a proposed second sidebar item, with an optional short usage guide ahead of it. |
| Contribute | Design, Local Development, Repository Layout, Documentation. Design includes current versus target architecture, base Driver contracts, runtime flows, and a link to repository-only specification history. Local Development includes code testing and developer tools. |
A named integration has one owning page and links from relevant Topics. OpenShell belongs in Integrations → Drivers, linked from Security → Sandbox. ChatGPT belongs in Integrations → Providers, linked from Service accounts and from Harness where dedicated Codex uses managed authentication; it is not a platform IAM system or a model-inference provider. Base Driver contracts belong in Contribute → Design and link back to concrete implementations. See the source rows for integrations and the missing-page recommendations.
Fix accuracy before moving pages
- Explain where a deployment can run. The architecture and controller reference imply the default Docker/Podman profile deploys Agents; the Docker implementation rejects required Harness authentication. The Docker reference also wrongly presents Kubernetes as the only option; SSH supports embedded runtime-managed authentication.
- Stop promising a working first model response on trusted-proxy installations. The first-Agent guide sends readers to an operator procedure whose TUI verification requires token authentication; private workspace routing requires trusted-proxy mode. Document a verified supported path or disclose that model-response verification is unavailable in this mode. File access is not model-response proof.
- Correct the promise about failed replacement. The reconciliation reference promises that a failed replacement preserves the predecessor. The Harness reference and Kubernetes implementation show that embedded replacement can stop the working gateway before validating the replacement credential.
- Correct security and integration guidance. The authorization reference omits permissions defined by native IAM. The OpenShell page buries stock-version identity and secret-delivery blockers. The console reference describes an Agent-owned plugin picker that the current form does not provide.
Browse the complete inventory
The complete CSV has one row per source file, exact repository paths, main/PR status, visibility, primary and secondary destinations, full reasoning, and pinned line evidence. The tables below provide the same coverage with shorter explanations.
| Website inventory | Pages | Repository-only inventory | Files |
|---|---|---|---|
| Getting Started | 12 | Repository guidance and tooling | 24 |
| Topics | 20 | Specifications 1 of 3 | 27 |
| Integrations and Reference | 20 | Specifications 2 of 3 | 27 |
| Contribute: Design | 18 | Specifications 3 of 3 | 25 |
| Contribute: runtime flows | 22 | ||
| Contribute: development and documentation | 29 |
Actions and quality
The recommendations are 76 keep, 55 rewrite, 16 split, nine merge, and 68 archive; none needs outright deletion. Archive means retain in repository history or remove from primary navigation, not erase the file. Archived drafts remain drafts; shipping or approval cannot be inferred from their location. For merges, carry over unique useful material and preserve old links; for splits, the inventory names the new owners.
Quality is separate from action: Good (60), Adequate (73), Weak (18), Historical (70), and Generated (3). Weak means substantive accuracy or usability issues, not just copyediting. Historical sources are evaluated as records, not as current promises. Generated pages can still need changes through their owner.
The missing pages and ownership gaps record other findings from this snapshot. Check the current documentation and source before treating an item as still open. Update the site navigation and repository instructions together when changing ownership; the site's access restrictions remain unchanged.