docs: draft overview audit tranche

[zeroxzerollc]

Summary

Draft review surface for the first Olympus docs audit tranche.

• refreshes Treasury, POL, YRF, and Cooler overview language for current protocol mechanics
• stages first-pass audit cleanup edits across overview, legacy, governance, old contract, and user-guide docs
• preserves dynamic/live-state caveats where values or operational status must be verified before citation

Commit structure

• 7a80283 refreshes Treasury, POL, and YRF overview language
• 43b97c2 tightens Cooler V2 overview language
• 189f0c2 stages the broader tranche-one audit cleanup edits

Review notes

• This is intentionally still a draft PR for JJ/internal recommendations, not upstream maintainer review.
• The branch keeps tranche commits separate so review can distinguish the focused overview truth patch from broader cleanup edits.

Evidence / verification

• Checked the original overview changes against Olympus protocol context from 2026-06-17.
• Avoided hardcoded moving values for backing, POL composition, ownership percentages, YRF budget, cadence, or live market operation.
• Removed unverified OIP-number citations from the YRF overview instead of carrying governance references without live Snapshot/forum verification.
• git diff --check passes.
• Local preview/build verification is being refreshed after the latest draft commit.

Known caveats

• Production search_olympus_docs was unavailable during the original audit because the docs knowledge base was not indexed yet. Local docs source plus live-state outputs were used instead.
• Docusaurus may report existing broken links elsewhere in the docs site; this tranche is being checked separately for new render/build issues.

[vercel]

Someone is attempting to deploy a commit to the Olympus Association Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2a0b832a-79ee-4d1b-83ec-2b0fd856263c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[zeroxzerollc]

Follow-on cleanup backlog from JJ review, after the YRF warning correction:

Tranche 2: warning / hedge cleanup

• Audit current-facing docs for over-cautious language like when active, when configured, historical design, or generic verify before using warnings.
• For live mechanisms, state the mechanism is live and reserve caveats for moving values, budgets, cadence, execution history, or supported lanes.
• Keep historical banners on genuinely legacy pages, but standardize wording.
• Initial targets: Range Bound / Emissions Manager wording, Cross-Chain bridge caution, governance proposal warning tone, staking guides, Etherscan legacy guides, BLV disabled notice, contracts-old historical banners.

Tranche 3: diagrams

• Add source-controlled Mermaid or equivalent diagrams for concept/contract pages.
• First candidates: Cooler V2 lifecycle, YRF weekly/daily loop, Cross-Chain bridge lanes, Convertible Deposits lifecycle, Kernel/Visualizer registry model.
• Evaluate Excalidraw/static diagrams and replace only where the page is current and Mermaid improves maintainability/readability.

Tranche 4: Protocol Visualizer page

• Add a page explaining what the Visualizer indexes, how Kernel/module/policy enabled state works, source freshness, and what still requires direct live contract/indexer reads.
• Include a data-flow diagram.

Tranche 5: Agents / MCP page

• Add a page explaining the read-only Olympus MCP server for agents, supported data surfaces, freshness expectations, and safe agent behavior.
• Include example workflows like checking YRF, POL, and current contract addresses.

Detailed local backlog: /home/ardor/workspace/reports/olympus-docs-audit-cleanup-backlog-2026-06-18.md.

[zeroxzerollc]

Upstream compatibility check after fetch/prune:

• origin/main has not advanced beyond PR docs: draft overview audit tranche #237’s base, so there is nothing to fast-forward against yet.
• Add SEO frontmatter and remove placeholder stubs #235 (seo-frontmatter-updates) broadly overlaps our touched pages but dry-run merges cleanly with docs: draft overview audit tranche #237. If it merges first, rebase docs: draft overview audit tranche #237 and rerun build/review.
• docs: add layer zero bridge upgrade documentation #236 (lz-bridge-upgrade) conflicts with docs: draft overview audit tranche #237 because it deletes docs/overview/07_cross-chain.md, adds docs/overview/07_cross-chain/, and renames 08_range-bound.md -> 09_range-bound.md, 09_convertible-deposits.md -> 10_convertible-deposits.md. Cross-chain follow-up work should target the new folder if docs: add layer zero bridge upgrade documentation #236 lands.
• Document PRICE v1.2 asset configuration #231 (price-1_2) conflicts in docs/overview/05_emissions-manager.md and adds PRICE/oracle docs plus Mermaid theme support. Diagram work should reuse that Mermaid support if it lands.
• docs: add agent source-of-truth guide #228 (docs/for-agents-olympus-state) dry-run merges cleanly and already adds a docs/for-agents/ section. The Agents/MCP follow-up should extend/integrate that PR rather than duplicate it.

Detailed compatibility map added to /home/ardor/workspace/reports/olympus-docs-audit-cleanup-backlog-2026-06-18.md.