DX-065/066/077/080 — docs contribution guide, home page, oracles concept, and product guides

[bade22brazy]

Implements the four DX1 documentation issues. 10 commits: DX-065 first (the contract the other 74 content issues depend on), then DX-066/077/080.

DX-065 — contribution guide and templates (#577)

• apps/docs/CONTRIBUTING.md — where content lives, the line-based frontmatter contract (title ≤ 60, description 50–160, ISO updated, status), adding a page to content/meta.json, the three checks (check:content, check:links, lint:prose) and where CI runs them, the prose rules the linter enforces, previewing with bun run --cwd apps/docs dev, and the sourcing requirement.
• apps/docs/templates/{concept,guide,reference}.mdx — the three shapes from content map §5. Placed outside content/ so check:content does not treat them as orphan pages; each carries valid frontmatter and the section skeleton for its shape.
• .github/PULL_REQUEST_TEMPLATE/documentation.md — mirrors the content map §4 definition of done, with a per-claim source-file table and the "every documented action performed on testnet" confirmation for guides.
• apps/docs/REVIEWER_CHECKLIST.md — scoped to accuracy and reader fit; explicitly defers style to lint:prose / DX-053.
• Root CONTRIBUTING.md and AGENTS.md both link to apps/docs/CONTRIBUTING.md.

DX-066 — docs home page (#578)

apps/docs/content/index.mdx replaces the placeholder with a three-door router: trade → quickstart + liquidation, provide liquidity → the pools guide, integrate → architecture + local setup + oracles. Each door names its reader. Plus a popular-pages row and links to search (Cmd/Ctrl + K), the changelog, and the repository. No marketing copy. /index is exempt from the sidebar orphan check.

DX-077 — /concepts/oracles (#589)

Sourced from apps/web/src/features/trade/lib/oracle.ts, .../lib/pyth.ts, and .../components/OracleStalenessIndicator.tsx:

• Source priority as shipped, not as the README describes it: fetchTokenPrices() tries the SO4 oracle service first, then Pyth Hermes, then Binance REST, then the GMX oracle, then a static DUMMY_PRICES array. The page flags that this diverges from the "Binance primary, GMX fallback" summary.
• Fallback triggers (per-source try/catch; throw or empty result → next source; no retry, no health scoring).
• Staleness thresholds: fresh < 5s, warning 5–30s, stale > 30s.
• Failure modes table — including that an all-sources-down state serves static prices with no banner, and that the price feed does not cross-check sources for deviation. Both stated as current behaviour.
• A price-path diagram (fenced text) from source to the liquidation check, with a caption.
• Mark-vs-execution price: the page states the min/max spread exists and points to /concepts/liquidation and oracle.ts consumers rather than guessing the selection rule.

DX-080 — pools, earn, referrals, faucet guides (#592)

• /guides/faucet — claim_many, the single cooldown_ledgers value tracked per account and per token, error code 6 (ClaimTooSoon) surfaced as the cooldown message, and that the UI shows a last-claim ledger number, not a countdown. Sources: apps/web/src/features/faucet/{hooks/useClaim.tsx,hooks/useFaucetData.ts,data/tokens.ts}.
• /guides/pools — the three GM markets (features/pools/data/markets.ts), unified-liquidity exposure, the two-step keeper-executed deposit/withdrawal (pool-actions.tsx: "~60s"), and a worked share-value example. Flags that the page's APY/TVL are hard-coded to 0 today (features/earn/data/pools.ts).
• /guides/earn — portfolio + rewards views, stakeSO4/unstakeSO4, on-chain reward accrual, claim vs compound vs vesting (features/earn/lib/earn.ts). Does not quote a reward rate — there is no constant for one in the client.
• /guides/referrals — the exact tier table from features/referrals/data/tiers.ts: Bronze (0 USD/mo, 5% discount, 5% commission), Silver (2,500, 5%, 10%), Gold (25,000, 5%, 15%); trader discount is flat 5%. Actions from lib/referrals.ts.

Verification status

Not built or run in this environment. I emulated check:content (frontmatter bounds, orphan/route resolution) and lint:prose (banned words, capitalisation, exclamation marks) locally against the five content pages and all pass; the real toolchain and a maintainer accuracy pass have not run. Specifically still needing a maintainer:

• DX-077: confirm the mark-vs-execution price selection, and whether the diagram should use the <Mermaid> component instead of a fenced block (no content page uses <Mermaid> today).
• DX-080: the acceptance criteria require each documented action to have been performed on testnet. I wrote these from code, not from testnet runs — the pages hedge where a number is a placeholder or unverified. status: beta on all four.

Closes #577, closes #578, closes #589, closes #592

[vercel]

@bade22brazy is attempting to deploy a commit to the Ijai's projects Team on Vercel.

A member of the Team first needs to authorize it.