DES-16: redirect the 129 dead URLs left by the IA revamp [render preview]

[jayeshbhole]

Fixes DES-16

Stacked on #94 (DES-15). Review that one first; this branch targets des-15-blog-redirects.

Problem

313 URLs were live on main in a past build and are dead today. redirects.config.js covered none of them.

81 returned 200, not 404, because of this line in server.mjs:

const SPA_FALLBACK = ["/sdk", "/meta-infra", "/recovery-flow", "/react", "/smart-wallet"];

Any path under one of those prefixes got the app shell. The shell has no content for a dead path, so Google reads it as a soft 404 and drops the URL. That list arrived in d358dc0 as a verbatim copy of the old Render static-site rewrites, the same copy that carried the /blog rule #94 removes. Vocs prerenders every page to its own index.html, so the fallback was never needed here: 4 of the 5 prefixes have zero built pages, and for /sdk the asset server answers first, so the fallback only ever masked a dead path.

Fix

1. 129 exact rules added to redirects.config.js, grouped by family. Each target was picked by comparing the deleted page against the live tree.
2. SPA_FALLBACK, isSpaFallback and the shell sirv instance deleted from server.mjs.
3. resolve-redirect.js added: one resolver, imported by server.mjs, the Vocs dev middleware and the new check. Before this the dev middleware had its own exact-match-only copy, so dev silently disagreed with production on trailing slashes and on /magic-account/*.
4. npm run check:redirects, an audit script to run by hand. No CI job, on purpose: this is a reviewer's aid, not a gate. It reports a target with no page, a redirect chain, a duplicate source, a rule (exact or prefix) that shadows a page that still exists, and a target no sidebar links to. It also fails if it cannot parse the sidebar block, so a rename in vocs.config.tsx cannot turn the reachability check into a silent pass.
5. Stale comment at redirects.config.js:133 corrected (it claimed render.yaml handled /magic-account/* subpaths; nothing did).
6. 9 pre-existing rules retargeted after a package-level audit (below).

Note for reviewers: 96 rules were removed before this was ready

The first pass of this branch shipped 225 rules. An audit found that 96 of them pointed at URLs that were never deployed.

The source list had been built with git log --all, which reads every ref in the repo. That swept in pages living only on unmerged branches: chain-abstracted-smart-account (39), smart-recipes-docs (13), zerodev-wallet (9), omar/react-kit-docs (6), wallet-docs-refresh (4), capabilities-rewrite (4) and others. Only main deploys, so none of those URLs were ever reachable or indexed.

Keeping them would have been worse than useless. smart-recipes-docs holds 13 finished pages and is a merge candidate; had it merged, every one of those pages would have been 301'd away on its first day.

Rebuilt with git log --first-parent --full-history origin/main. Two independent methods agreed on the count, and a control path known to have been live returns a hit, so the query is not silently matching nothing.

Coverage did not change. 311 of the 313 URLs that genuinely died on main have a rule. The 2 without are the offramp stubs below.

Deliberate omissions

• /modules/offramp and /smart-wallet/offramp get no rule and return 404. Both were one-line # Offramp stubs for their entire life, with no successor page (DES-12).
• /blog itself stays unmapped, per DES-15: redirect blog posts to their marketing-site URLs [render preview] #94.
• 19 /resources/* rules and /advanced/go-sdk also point at never-deployed URLs, but they predate this branch and a comment in the file says they were added deliberately in case an old link escaped. Left alone.
• The /magic-account prefix rule stays as a catch-all. All 19 known subpaths now have exact rules.

Verification

Against a local npm run build + npm start:

353/353 configured rules 301 to their exact target
96 never-live paths now 404, 20 kept on purpose, 0 stray
124/124 internal targets return 200
ok   404 /modules/offramp
ok   404 /smart-wallet/offramp
ok   404 /sdk/nope            (was 200 via SPA_FALLBACK)
ok   404 /meta-infra/nope     (was 200 via SPA_FALLBACK)
ok   404 /recovery-flow/nope  (was 200 via SPA_FALLBACK)
ok   404 /react/nope          (was 200 via SPA_FALLBACK)
ok   404 /smart-wallet/nope   (was 200 via SPA_FALLBACK)
trailing slash and query string preserved

Ground truth, recomputed from main alone after the strip:

routes ever live on main:  562
routes live today:         249
dead (was live, now gone): 313
  covered by a rule:       311
  NOT covered:               2   <- the two offramp stubs, by design

npm run check:redirects: 353 redirects ok, 249 routes.

Relevance audit, and why 15 targets changed

Every rule was scored by comparing the recovered old page against its target: 316 good, 23 acceptable, 14 poor, mean content similarity 81%, mean relevance 9.1/10.

Scoring on prose alone proved unreliable, so a second pass compared imported packages and API symbols instead. That caught redirects matching on topic word while sending the reader to a different SDK. 106 rules failed the package test, 69 of which the prose pass had called good.

The two worst were plainly wrong: /modules/signin and /smart-wallet/signin pointed at /onboarding/auth-providers, which documents third-party wallet services (Privy, Dynamic, Portal), when the old pages documented ZeroDev's own createPasskeyValidator, createSocialValidator and createEcdsaValidator. Both now go to /onboarding/create-a-smart-account.

@zerodev/waas is unmaintained, so pages that merely used it now point at the current wallet SDK rather than the legacy hooks tree. The 20 /react/* rules still point there, because those URLs were the waas docs and the content genuinely moved. That tree's future is DES-21.

Sidebar reachability

A redirect that lands on a page no sidebar links to leaves the reader with no navigation. Auditing this found one regression introduced earlier in this branch: /smart-wallet/one-click-trading had moved from transaction-automation (in the sidebar) to 1-click-trading (orphaned). Reverted.

check:redirects now reports any orphan target. Three areas are allowlisted so the existing backlog does not drown the output: the React hooks tree (DES-21), the /api-and-toolings/ gap (21 rules land on real pages that no sidebar lists), and 1-click-trading. No sidebar entries were added in this PR.

Note on the preview

Vercel serves docs/dist statically and never runs npm start, so none of these redirects apply on the preview URL. Production is the Render web service, where they do. Verify after merge against https://docs.zerodev.app.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 1, 2026 2:41pm UTC