Skip to content

docs: roll the flag-reference generator out to op-node, op-proposer, op-challenger, op-conductor - #21873

Merged
sbvegan merged 8 commits into
developfrom
docs-improver/b3-flag-gen-rollout
Jul 21, 2026
Merged

sbvegan merged 8 commits into
developfrom
docs-improver/b3-flag-gen-rollout

Conversation

@claude

@claude claude Bot commented Jul 17, 2026 •

Copy link
Copy Markdown
Contributor

Requested by Matthew Cruz · Slack thread

Tracks ethereum-optimism/solutions#971

What

Rolls the flag-reference generator introduced in #21847 (op-batcher) out to the remaining first-party Go services, so every published flag catalog is generated from the urfave/cli definitions the binaries actually register, pinned to a finalized release:

Component Pinned tag Visible flags Tag↔develop flag sources
op-node op-node/v1.19.3 109 (3 required) identical
op-proposer op-proposer/v1.16.3 54 (1 required) moved on develop — generated at the tag
op-challenger op-challenger/v1.9.3 88 (4 required) moved on develop — generated at the tag
op-conductor op-conductor/v0.9.4 61 (9 required) moved on develop — generated at the tag
op-batcher op-batcher/v1.16.11 87 unchanged from #21847
  • Pages reworked to import the snippets (hand policy/context prose kept, hand-typed tables deleted): node-operators/reference/op-node-config.mdx (1,278→143 lines, was pinned to v1.10.2), chain-operators/guides/configuration/proposer.mdx, chain-operators/tools/op-conductor/reference.mdx. New page: chain-operators/reference/challenger-configuration.mdx (op-challenger had no flag catalog at all).
  • -check redesigned around a manifest sha256 pin. The components release independently, so develop's flag sources routinely sit past one component's tag while matching another's — byte-comparing a committed snippet against a regeneration from an arbitrary tree is only meaningful at the tag. manifest.json now records {tag, sha256} per snippet; -check fails on any snippet/manifest hash mismatch (hand-edit detection, valid at every commit) and reports current-tree parity informationally. New -only {component} flag supports per-tag regeneration. See the rewritten scripts/gen-flags/README.md, including the honest residual-gap list.
  • canonicalizeUsage: the --network usage string enumerates the superchain-registry bundle's chain list, which changes with registry bumps independent of any release; the generator replaces the enumeration with a stable pointer so regeneration is byte-stable (documented deviation from raw --help).
  • op-reth-config.mdx retired to a pointer at the imported op-reth CLI reference (/rust/op-reth/cli/overview, /rust/op-reth/cli/op-reth/node) — the 2,685-line hand copy was pinned to an old release and duplicated the imported surface. Six inbound per-flag anchor links re-pointed (snap-sync, reth-historical-proofs, archive-node, upgrade-19). No pages under rust/op-reth/** touched; the existing op-geth-config redirect still lands on a live page.
  • generate-releases.ts: new rewriteSpecsBlobLinks transform canonicalizes specs-repo blob links in release bodies to the rendered specs site (outside code blocks only, idempotent); applied to the committed releases/op-batcher.mdx.
  • Corrected from the old hand pages: consensus.advertised was documented as required but is optional in source; op-node's --network/--rollup.config exactly-one-of rule is now called out in prose (it is enforced by CheckRequiredXor, outside the required flag slice).

Verification

An adversarial accuracy pass ran before this PR opened:

  • All four snippets regenerate byte-identical at their tags (fresh worktree per tag, committed generator, run twice for determinism).
  • Every flag row cross-checked against the actual op-node / op-proposer / op-challenger / op-conductor binaries built at the pinned tags: names, env vars, defaults match --help exactly; visible-flag sets match (hidden flags excluded on both sides); sampled usage strings match.
  • Required mirrors verified against each tag's flags.go — including op-challenger's l2-eth-rpc, which CheckRequired enforces unconditionally from outside its required slice, and op-conductor's nine.
  • -check is green for all five components; corrupting one committed snippet byte makes it fail on the sha256 pin.
  • The pass found and fixed two release-accuracy errors in the prose (second commit): the challenger page listed a game-proposal-outputs subcommand that exists on develop but not in v1.9.3, and the op-reth pointer page claimed op-node defaults --l2.enginekind to geth when the source (tag and develop) defaults to reth.
  • Lints: nav validator OK, redirect lint OK, link-policy lint clean against its baseline (pruned by exactly the two entries this diff resolves), gofmt/go vet clean.

Notes for reviewers

  1. docs.json serialization: this PR adds one nav line (the challenger reference page). Per the program rule, at most one docs.json-touching PR should be in flight at a time — rebase whichever of the open docs.json PRs merges second.
  2. Supersedes part of docs: badge or re-point version-pinned links (sweep batch 2: guides, tutorials, notices, op-stack references) #21867: the op-node-config rework deletes the Info block containing the pinned receipts_rpc.go link that docs: badge or re-point version-pinned links (sweep batch 2: guides, tutorials, notices, op-stack references) #21867 re-points (one hunk there). Whichever merges second needs a trivial lint-link-policy.baseline.json rebase (also against docs: fix link-policy violations (mechanical classes) #21866).
  3. Complementary to docs: fix link-policy violations (mechanical classes) #21866: that PR fixes the three release-page intro-string blob links at their source; this PR fixes the release-body link class in the generator. No overlap — an earlier duplicate fix here was reverted.

Reviewer checklist:

  • Spot-check a few rows of each generated table against the component's --help at its pinned tag
  • Provenance lines render correctly on each reworked page (Mintlify preview)
  • -check semantics in scripts/gen-flags/README.md read sensibly, including the residual-gap list
  • The op-reth pointer page and the six re-pointed inbound links land where expected

Mintlify automation (replaces the op-batcher-only prompt posted on #21847)

Placeholders below are written as {component} (angle brackets do not survive the PR API); substitute the component name.

Field Value
Name Flag reference refresh (op-batcher, op-node, op-proposer, op-challenger, op-conductor)
Trigger Custom schedule — 0 9 * * 1 (Mondays 09:00 UTC)
Context repositories ethereum-optimism/optimism
Integrations GitHub (default)
Apply mode Require review

Additional prompt:

For each covered component — op-batcher, op-node, op-proposer, op-challenger, op-conductor — check the newest finalized release tag (pattern {component}/vX.Y.Z, excluding any -rc or pre-release) in the context repository and compare it against that component's tag recorded in docs/public-docs/scripts/gen-flags/manifest.json. If they all match, do nothing. For each component with a newer finalized tag: regenerate its flag reference per docs/public-docs/scripts/gen-flags/README.md at that tag (go run ./docs/public-docs/scripts/gen-flags -only {component}; if the environment cannot check out the tag, first verify the flag-defining packages listed in the README are unchanged between the tag and the default branch, then generate). Update the generated snippet, the component's manifest.json entry (tag and sha256), and its provenance line together, and propose the change for review. Never hand-edit the generated tables. Never regenerate from unreleased code. If generation fails for one component, still process the others, and describe the failure instead of guessing.

Part of the docs-improver program — see projects/docs-improver/README.md in ethereum-optimism/solutions.

🤖 Drafted by the docs-improver agent — review before merge.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L

claude added 2 commits July 17, 2026 06:18
…op-challenger, op-conductor

Extend the B1 gen-flags pipeline to every first-party Go service, each
generated at its latest finalized release tag and pinned in manifest.json:

- op-node/v1.19.3 (109 flags) replaces the 1,278-line hand catalog pinned
  to v1.10.2; op-proposer/v1.16.3 (54) replaces the unversioned 507-line
  catalog; op-challenger/v1.9.3 (88) closes the no-catalog gap with a new
  reference page; op-conductor/v0.9.4 (61) replaces the 15-flag partial
  hand list on the conductor reference page.
- Snippets are generated from the source at each tag (op-proposer,
  op-challenger, op-conductor flag definitions have moved on develop since
  their tags, so their snippets are tag-generated; op-node and op-batcher
  are byte-identical between tag and develop). manifest.json now records a
  sha256 per snippet and -check verifies against it, with current-tree
  parity reported informationally — the multi-component tags make
  regenerate-and-diff meaningful only at each tag.
- canonicalizeUsage stabilizes the --network usage string (the enumerated
  superchain-registry chain list changes with registry bumps, independent
  of component releases).
- op-reth-config.mdx becomes a pointer at the imported op-reth CLI
  reference (facts in one place; placement stays with Option A). Inbound
  per-flag anchor links re-pointed.
- generate-releases.ts canonicalizes specs-repo blob links in release
  bodies to the rendered specs site (deferred finding from the b2 sweep);
  applied to the committed op-batcher releases page.
- Hand policy/context prose kept on every reworked page; one docs.json nav
  entry added (challenger reference). Baseline pruned for the two links
  this change removes.

Co-Authored-By: Claude <noreply@anthropic.com>
- challenger-configuration.mdx: drop game-proposal-outputs from the
  utility-subcommand list — it exists on develop but not in the
  documented op-challenger/v1.9.3 release (whose --help lists eight
  subcommands).
- op-reth-config.mdx: correct the l2.enginekind note — op-node defaults
  to reth (op-node/v1.19.3 and develop), so pairing needs no explicit
  engine-kind flag; the old 'defaults to geth' claim contradicted the
  generated flag table.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
claude Bot requested a review from a team as a code owner July 17, 2026 06:38
@claude claude Bot added docs-improver Opened by the docs-improver agent size:L docs-improver size band documentation labels Jul 17, 2026
@mintlify

mintlify Bot commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
Optimism-Docs 🟢 Ready View Preview Jul 17, 2026, 6:39 AM

@mintlify

mintlify Bot commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
Optimism-Docs 🟡 Building – Jul 17, 2026, 6:38 AM

Resolves the lint-link-policy.baseline.json conflict with #21866 (sweep
batch 1) by regenerating: 296 (post-batch-1 develop) minus this branch's
2 fixes (op-batcher.mdx spec-blob-link via the generator transform,
op-node-config.mdx pinned link removed by the rework) = 294 findings,
0 new, 0 stale.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude

claude Bot commented Jul 17, 2026

Copy link
Copy Markdown
Contributor Author

Synced with develop after #21866 merged: baseline conflict resolved by regenerating (296 post-batch-1 − this branch's 2 fixes = 294 findings, 0 new / 0 stale; pure shrink vs develop); nav + redirect lints green.

@sbvegan sbvegan left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just one comment to address and a meta note: the IA really needs a modern update. We'll probably do that after we fold in the "Rust" section.

Review follow-up from sbvegan on #21873: the non-kona cannon game types
execute op-program, which has reached end of support, so only the kona
variants are still maintained. Link the op-geth/op-program deprecation
notice from the cannon-*/cannon-kona-* section.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L
claude added 2 commits July 18, 2026 22:34
Regenerated with --update-baseline against the specs mirror after
merging origin/develop (#21866/#21849/#21842/#21860 baseline drift).
296 -> 293 entries, pure shrink: the two findings this branch fixed
(op-node-config.mdx unbadged pin, op-batcher.mdx spec blob link) plus
one entry already stale on develop (batcher.mdx anchor/UTM order,
fixed in #21866 but never pruned there). Linter: 0 new / 0 stale.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L
@claude

claude Bot commented Jul 18, 2026

Copy link
Copy Markdown
Contributor Author

Baseline rebased after the recent develop merges (#21866/#21849/#21842/#21860), as predicted in the PR description: merged origin/develop (clean, no conflicts) and regenerated lint-link-policy.baseline.json — linter now reports 0 new / 0 stale (296 → 293 entries, pure shrink: this branch's two fixes plus one entry already stale on develop). Nav and redirect lints green.

Sync after #21865 and #21867 merged. Conflicts resolved:
- node-operators/reference/op-node-config.mdx: kept this branch's
  generated-snippet rework, which supersedes the hand-typed flag
  section (including the receipts_rpc.go re-point from #21867),
  per the PR's supersedes note.
- scripts/lint-link-policy.baseline.json: regenerated with
  --update-baseline against the specs mirror (pure removal vs
  develop: 0 added, 2 removed - exactly the entries this PR
  resolves).
docs.json auto-merged; union verified (Contribute group tail and
Stack Components group preserved, challenger reference line added).
Link-policy, nav, and redirect lints green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L
@claude

claude Bot commented Jul 19, 2026

Copy link
Copy Markdown
Contributor Author

Synced with develop (0f5d053): merged post-#21865/#21867 develop; kept this branch's op-node-config rework over #21867's superseded re-point hunk, regenerated the baseline via --update-baseline with the specs mirror (pure removal vs develop: 0 added, 2 removed — exactly this PR's entries); docs.json union verified; link-policy, nav, and redirect lints green.

Resolves the lint-link-policy.baseline.json conflict by union of removals:
develop tip's baseline (55 entries after the merged sweep batches) minus
the releases/op-batcher.mdx spec-blob-link entry this branch's generator
fix resolves (54 entries, pure shrink, 0 added). The branch's other
baseline removal (batcher.mdx anchor-utm-order) was already resolved on
develop by the merged sweeps.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L
@claude

claude Bot commented Jul 20, 2026

Copy link
Copy Markdown
Contributor Author

Synced with develop after #21848 merged (511890d, merge commit, no force-push). The lint-link-policy.baseline.json conflict was resolved by union of removals: develop tip's baseline minus the releases/op-batcher.mdx spec-blob-link entry this branch's generator fix resolves (55 -> 54 entries, pure shrink, 0 added; the branch's other baseline removal, the batcher.mdx anchor-utm-order entry, was already resolved on develop by the merged sweeps). Everything else merged clean, including docs.json.

Lints on the merged tree: nav validator OK (415 pages, 1 allowlisted orphan), redirect lint OK (18 grandfathered), link-policy clean with baseline: 54 findings, all pre-existing baselined, 0 new.

@sbvegan
sbvegan added this pull request to the merge queue Jul 20, 2026
Merged via the queue into develop with commit d9bb562 Jul 21, 2026
18 checks passed
@sbvegan
sbvegan deleted the docs-improver/b3-flag-gen-rollout branch July 21, 2026 00:02
claude Bot pushed a commit that referenced this pull request Jul 21, 2026
)

The op-challenger hub's flags slot now links the new generated
challenger-configuration reference instead of the no-reference-yet
fallback wording, and the op-node hub's flag-reference description
matches the reworked generated op-node-config page.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
claude Bot pushed a commit that referenced this pull request Jul 21, 2026
Post-merge accuracy fixes after syncing with develop (#21873 rolled the
flag-reference generator out to op-node/op-proposer/op-challenger/
op-conductor):

- choose-your-node-stack: the op-node config reference is no longer
  hand-pinned to op-node/v1.10.2 (it is now generated per release), and
  the op-reth config page is now a router to the imported CLI reference;
  reword both Next-steps exits. Attribute the 1:1 pairing rule to the
  client configuration guides that actually state it.
- launch-a-chain-with-fault-proofs-and-ha-sequencing: link the new
  generated challenger configuration reference from the defense-stack
  step.
- run-a-fault-proof-challenger: the 'no rendered flag catalogue for
  op-challenger' exit is no longer true; replace it with a link to the
  generated challenger configuration reference.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L
ClaytonNorthey92 pushed a commit to hemilabs/optimism that referenced this pull request Sep 19, 2026
…op-challenger, op-conductor (ethereum-optimism#21873)

Co-authored-by: Claude <noreply@anthropic.com>

This branch was successfully deployed

1 active deployment
staging - docs/public-docs — 511890dd Deployed Jul 20, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs-improver Opened by the docs-improver agent documentation size:L docs-improver size band

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants