Skip to content

[codex] Fix About and Developers docs IA#887

Draft
its-DeFine wants to merge 4 commits intolivepeer:docs-v2-devfrom
its-DeFine:codex/about-developers-qa-20260504
Draft

[codex] Fix About and Developers docs IA#887
its-DeFine wants to merge 4 commits intolivepeer:docs-v2-devfrom
its-DeFine:codex/about-developers-qa-20260504

Conversation

@its-DeFine
Copy link
Copy Markdown

Summary

This PR cleans up the public About and Developers docs surface on docs-v2-dev after a dedicated QA pass in a fresh PC2 VM.

Main changes:

  • removes duplicated/draft public navigation such as Developers2, deprecated protocol2/network2 groups, empty groups, zero-byte pages, and malformed entries
  • fixes rooted internal links in the public About/Developers surface
  • normalizes remaining public About/Developers pages to status: current
  • quarantines command-heavy or externally keyed pages from public nav until they can be validated with real credentials/service state
  • fixes invalid pasted IA text in jsconfig.json
  • excludes v2/developers2/** from Mintlify scanning via .mintignore
  • rewrites the local testnet guide around the validated Anvil + localhost path instead of the broken gethDev/Hardhat-node path

Validation

Run in dedicated PC2 VM livepeer-docs-qa-20260503.

  • prompt-injection scan before trusting repo content: 9,021 files inventoried; 8,641 text files scanned; 184,978,220 text bytes scanned
  • mint validate: passed
  • public About/Developers audit: 45 public pages, 0 missing refs, 0 duplicate refs, 0 public rooted broken links, 0 public frontmatter issues
  • local Mintlify preview smoke: 45/45 current public About/Developers routes returned HTTP 200
  • local protocol/go-livepeer smoke: Anvil chain, protocol deploy, round-length update, unpause, faucet request, LPT approval, bond, local go-livepeer orchestrator startup, and local go-livepeer gateway startup all passed
  • no real keys, funded wallets, or mainnet actions used

Deferred follow-up

Real keyed/public-network validation is intentionally deferred. In particular, this PR does not claim validation of:

  • production/public-network orchestrator registration with a funded wallet
  • production gateway traffic
  • paid market job flow through public gateway/orchestrator infra
  • hosted API-key flows, current pricing/model-support claims, or beta-service state

Those keyed flows can be validated in a follow-up pass with the owner-provided orchestrator key.

@DeveloperAlly DeveloperAlly self-assigned this May 4, 2026
@its-DeFine
Copy link
Copy Markdown
Author

Second validation pass pushed in f9b02b7.

What changed:

  • Replaced scaffold content in governance-and-economics.mdx and developers/concepts/role.mdx with real public-page content.
  • Removed public TODO/planning comments from the touched About/Developers pages.
  • Corrected governance parameters against LIP/live-contract evidence: 100 staked LPT proposal threshold, 1-round delay, 10-round voting period, ~33.33% quorum.
  • Fixed broken LIP links from blob/main/LIPs/LIP-00xx.md to the actual master branch non-zero-padded filenames.
  • Corrected payment-flow wording: TicketBroker deposits/reserves and winning-ticket redemptions are ETH-denominated; LPT is staking/governance/inflation rewards.
  • Removed or softened unvalidated hard metrics and status claims: 10x/5-10x cost claims, 40% staking return, 10x-100x AI usage growth, fabricated future LIP-78/81/85 auction items, BYOC production-grade claims, and Growth-tier sufficiency wording.
  • Added safer treasury wording: current treasury reward cut is 10%, on-chain treasury balance ceiling is 750,000 LPT, but current balances/inflows should be checked live before quoting.
  • Tightened testnet private-key wording to explicitly warn against using mainnet wallet keys.

Primary evidence used:

  • livepeer/LIPs: LIP-73, LIP-89, LIP-92, LIP-100, plus governance/process LIPs.
  • livepeer/protocol confluence: Governor, PollCreator, TicketBroker payment code.
  • Read-only Arbitrum contract calls for BondingManager/Minter/Governor/Treasury parameters.
  • Livepeer Studio pricing page and current docs for pricing/API sanity checks.

Checks run:

  • git diff --check
  • targeted public-page scans for stale numeric claims, broken LIP links, TODO/prompt-injection-style comments, fabricated future LIPs, and ETH/LPT payment confusion
  • npx --yes mintlify@latest validate -> success build validation passed

Remaining boundary:

  • PC2 VM/Tailscale access hit a re-auth wall during this follow-up pass, so this commit used the local PR worktree plus public primary sources and read-only live Arbitrum calls. Orchestrator-key/gateway live-flow validation remains for tomorrow with the owner-provided key.

@its-DeFine
Copy link
Copy Markdown
Author

Follow-up after PC2 re-auth:

I reconnected to PC2 and confirmed the dedicated VM is running:

  • livepeer-docs-qa-20260503 running
  • pfw-oss-eval-20260503 remains shut off

I created/refreshed a scratch checkout inside the VM at /home/define/livepeer-docs-qa/repo/pr887-current and validated PR head 3ea0135 there.

Additional cleanup pushed after the broader scan:

  • 5e9bf38 removes unresolved REVIEW/SCOPE notes and softens unvalidated production/BYOC/ComfyStream/model-support claims in AI developer pages.
  • 3ea0135 explicitly quarantines deprecated duplicate About trees in .mintignore: network2, protocol2, concepts/unclassified, and x-*.mdx pages.

PC2 VM checks at 3ea0135:

  • git diff --check passed
  • targeted scan over non-quarantined About/Developers MDX returned no hits for stale numeric claims, unresolved REVIEW/TODO/SCOPE notes, fabricated future LIPs, broken zero-padded blob/main LIP links, or ETH/LPT payment confusion
  • npx --yes mintlify@latest validate inside the VM -> success build validation passed

Known VM checkout caveat:

  • Git marks 7 media/LFS files as modified in the scratch VM checkout because they are non-pointer media files where LFS expected pointers. I did not touch or commit media.

Remaining boundary:

  • This still does not validate real public-network orchestrator registration, production gateway traffic, paid job flow, or owner-key flows. Those require the orchestrator key / service credential boundary and should stay deferred until the owner provides that specific key workflow.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants