docs: clean up nav-validator and redirect-lint baselined violations

[claude]

Requested by Matthew Cruz · Slack thread

What / why

The cleanup half of Option A slice 2 (CI guardrails) of the canonical-homes plan: fixes the nav/redirect violations that were grandfathered when the validators landed, and prunes the corresponding allowlist/baseline entries in the same PR (stale entries are lint errors by design).

The validator tooling merged as #21843. This PR now sits directly on develop, and the diff is cleanup-only: grandfather-file prunes, nav re-homes, and 5 page deletions with redirect coverage.

docs.json lane: this PR holds the docs.json nav/redirects serialization slot; both predecessors in the lane (#21841, #21843) have merged, so there is no remaining merge-order constraint.

Tracks ethereum-optimism/solutions#955

Before / After

Guardrail state	Before	After
Grandfathered nav orphans	11	0 (2 allowlisted with terminal reasons, see below)
Grandfathered duplicate nav entries	1 (rust/op-reth/cli/op-reth)	0
Grandfathered shadowed redirect sources	1 (/chain-operators/tools/op-deployer/usage/upgrade)	0
Baselined dead internal links	24 occurrences (22 file→target pairs)	unchanged — deliberately left (see below)
lint:nav / lint:redirects	green (via grandfather files)	green (near-empty grandfather files)

Orphans re-homed into the nav (4)

• op-stack/features/preinstalls → OP Stack > Features (two live redirects already point at this page)
• op-stack/features/experimental/alt-da-mode → OP Stack > Features (a live redirect points at it)
• node-operators/tutorials/node-from-docker-simple-optimism-node → Node Operators > Archive, alongside the other op-geth-era pages — the page's own warning says simple-optimism-node defaults to end-of-support op-geth and steers new deployments to the docker-compose tutorial
• rust/kona/glossary → Rust > Kona - Introduction (6 live kona pages deep-link its anchors)

Orphans deleted, with redirect coverage in this tree (5 pages / 4 redirects)

• chain-operators/tools/op-deployer/usage/upgrade.mdx — a 12-line stub whose entire content is a warning pointing at /notices/op-deployer-upgrade-deprecation; the redirect to that notice already existed (it was the shadowed-source violation — one deletion resolves both findings, keep-redirect-drop-page)
• rust/kona/run.mdx — older, shorter duplicate of the rust/kona/node/run/* chapter, zero inbound links → new redirect to /rust/kona/node/run/overview
• rust/kona/sdk/fpp-dev/io.mdx — empty title-only stub, zero inbound links → new redirect to /rust/kona/sdk/fpp-dev/intro
• rust/op-reth/cli/op-reth/db/settings/set/receipts_in_static_files.mdx and ..._transaction_senders_in_static_files.mdx — stale generated pages for the since-renamed receipts / transaction_senders subcommands (the renamed pages are on disk and in the nav); new redirects to the renamed pages

Duplicate nav entry (1)

• Removed the bare rust/op-reth/cli/op-reth entry directly under "op-reth - CLI Reference"; the page keeps its home as the first entry of the nested op-reth group.

Remaining allowlist entries (2, both with terminal reasons — not grandfathered violations)

• chain-operators/tutorials/create-l2-rollup/code-setup — handed off to Option C slice C1 (homepage router / flagship-tutorial repair), which owns re-homing it; the C1 PR removes the entry when its nav fix lands.
• chain-operators/guides/features/sequencer-defined-metering — kept out of the nav deliberately: the page carries hidden: true frontmatter and documents a feature that is not yet live (expected with the Lagoon hardfork). Nav-listing it would announce an unshipped feature; the allowlist reason says to add it to Chain Operators > Guides > Features when the feature ships. This is the one deviation from "empty allowlist" — flagged for reviewer judgment.

Dead internal links: left baselined on purpose

The 24 baselined dead internal links (19 files) are not touched here: they are content-level link repairs that belong to the Option B slice B2 cross-repo link policy + mechanical sweep, which is held until the B2 linter PR merges. Fixing them piecemeal here would collide with that sweep and bloat this docs.json-lane PR.

Verification

• pnpm lint:nav — OK: 398 pages on disk, 396 distinct nav entries, 2 allowlisted orphans
• pnpm lint:redirects — OK: 465 redirects, 402 files scanned, 22 grandfathered violations remaining (all dead-link baseline)
• docs.json parses; every nav entry maps to a file on disk (validator check N2)

Reviewer checklist

• The four re-homed pages sit in sensible nav groups (especially simple-optimism-node under Archive)
• The five deletions are acceptable (all superseded/stub pages; every deleted URL is redirect-covered in this tree)
• Keeping sequencer-defined-metering hidden-by-design is the right call
• The code-setup handoff to the C1 tutorial-repair PR is acceptable

More context: projects/docs-improver/README.md

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

🤖 Generated with Claude Code

https://claude.ai/code/session_01EBBBR8m2V8LjzMvuG7Go2L

---

Generated by Claude Code

[claude]

The op-reth-integration-tests failure here is the known flake #20973 (peers_negotiate_eth_69 SIGSEGV on teardown after the test passed) — unrelated to this docs-only diff, and the same job passed on the parent commit. Synced this branch with its base docs/nav-validator-redirect-lint to pick up the lint script hardening; both lints pass locally and the push re-runs CI, which should clear the flake.

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Optimism-Docs	🟢 Ready	View Preview	Jul 16, 2026, 6:16 PM

[mintlify]

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

Project	Status	Preview	Updated (UTC)
Optimism-Docs	🟡 Building	–	Jul 16, 2026, 6:15 PM

One change needed

[sbvegan]

While we're doing this, let's clear out all these archived pages in this section