[Claude CI Failure] Fix broken /dev/reference/apis/* redirects for removed/renamed API pages

[btshrewsbury-viam]

What

The Org docs-link check job (check-org-docs-links.yml, issue #5170) scans rdk, app, api, viam-python-sdk, viam-typescript-sdk, and viam-flutter-sdk for docs.viam.com links and classifies each as broken / stale-redirect / broken-anchor. The latest run (30193440177, 2026-07-26) found 368 problems: 30 broken, 321 stale-redirect, 17 broken-anchor.

I pulled the complete findings (job log + live per-URL classification output, not just the truncated issue-body summary) and root-caused all 30 "broken" entries to two bugs entirely on the docs.viam.com side:

1. /dev/reference/apis/* → /reference/apis/ redirect was missing :splat. Every sub-path collapsed to the bare /reference/apis/ index instead of the specific page. components/generic, components/input-controller, and services/vision all still exist as real pages (docs/reference/apis/components/generic.md, input-controller.md, docs/reference/apis/services/vision.md) — they just never got a working redirect. This alone accounts for 18 of the 30 broken findings.
2. Removed SLAM API pages' aliases pointed at the same dead-end index, instead of the motion-planning replacement content, unlike the existing SLAM redirect convention already present in netlify.toml for other removed SLAM URLs (/operate/reference/services/slam/*, /services/slam/*, /mobility/slam/* → /motion-planning/). Accounts for 11 of the 30.
3. The encode component was renamed to encoder with no redirect for the old slug (viam-flutter-sdk/lib/src/components/encoder/encoder.dart:82 still links to /dev/.../components/encode/). Accounts for the last 1 of the 30.

Fix (fixes 30 of 30 broken-link findings)

• netlify.toml: restore :splat on the /dev/reference/apis/* redirect.
• netlify.toml: add a redirect for the encode → encoder rename.
• netlify.toml: add 3 new SLAM redirects (/reference/apis/services/slam/*, /reference/services/slam/*, /appendix/apis/services/slam/* → /motion-planning/), matching the existing convention for other removed SLAM URLs in the same file.
• docs/reference/apis/_index.md: remove the now-redundant SLAM aliases that were producing the dead-end redirect (superseded by the netlify redirects above, which point at the correct destination instead of the generic index).

Out of scope (left unchanged, with counts)

• 321 stale-redirect findings: these already resolve correctly (e.g. /dev/reference/apis/components/arm/ → /reference/apis/components/arm/) via existing Hugo alias stubs or (after this fix) the corrected splat redirect — the "fix" the checker wants is updating the source links in viam-python-sdk/viam-typescript-sdk/viam-flutter-sdk/rdk/app/api to use the canonical URL directly. This repo doesn't own those repos, so out of scope here.
• 17 broken-anchor findings, both already-tracked, non-fixable-by-edit:
  • 8 are on /reference/apis/fleet/ (disablebillingservice, getbillingserviceconfig, listoauthapps, organizationgetlogo, organizationgetsupportemail, organizationsetlogo, organizationsetsupportemail, transferregistryitem) — I confirmed these methods have no corresponding heading at all in the generated static/include/app/apis/generated/app.md, i.e. genuine SDK-coverage documentation gaps, the same sdk_protos_map.csv-backlog category already tracked and being chipped away at under CI failure: SDK method coverage #5142.
  • 9 are on /reference/apis/services/navigation/ (addwaypoint, getlocation, getmode, getobstacles, getpaths, getproperties, getwaypoints, removewaypoint, setmode) — the Navigation service API page is now an intentional stub ("The navigation service API has been removed... see Motion service API") with no method-level content left to anchor to.

Verification

• npx prettier@3.2.5 --check docs/reference/apis/_index.md — passes
• npx markdownlint-cli --config .markdownlint.yaml docs/reference/apis/_index.md — clean
• vale docs/reference/apis/_index.md — 0 errors/warnings/suggestions
• make build-prod — completes with only the expected old-page-date warnings, no errors
• Manually traced the redirect chains against docs/reference/apis/* and docs/motion-planning/ page structure to confirm every new/changed redirect target is a real, existing page before pointing anything at it

Refs #5170 (the stale-redirect and broken-anchor categories above remain open items requiring other-repo edits or a coverage-gap decision, so this does not fully resolve what the job checks).

---

Generated by Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	327d7c9
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6a6751f2c40453000868f3b0
😎 Deploy Preview	https://deploy-preview-5227--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 39 (🔴 down 4 from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 92 (no change from production) PWA: 60 (no change from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[btshrewsbury-viam]

Status update: all content-side checks are green — prettier, Check Markdown files (markdownlint), vale (both instances), htmltest, Check Python snippets in Markdown files, codespell, and Check for moved files all passed on the latest commit.

The only failing checks are Netlify's own deploy-preview annotations (Redirect rules, Header rules, Pages changed, and the underlying netlify/viam-docs/deploy-preview status). I've verified this is not caused by this PR's diff:

• Pushed an empty commit (fb065365c, zero file changes vs. the prior failing commit 22f60bdb9) and the Netlify deploy failed identically — a byte-for-byte unchanged tree cannot have a content bug, so the failure is external to this change.
• Independently validated netlify.toml's redirects with Netlify's own official @netlify/redirect-parser library: 0 errors, all 128 rules (including the 4 this PR adds) parse and normalize cleanly.
• Ran a full local production build (make build-prod, Hugo v0.152.2 matching the pinned HUGO_VERSION) — completes with only the expected old-page-date warnings, no errors.

I don't have access to the actual Netlify deploy log (it 403s without dashboard auth from this environment), so I can't pin down the exact platform-side cause, but the evidence rules out this PR's content. Flagging for a human to check the Netlify dashboard/build minutes/site status directly if this persists — I won't keep retriggering deploys since two consecutive failures (one with real changes, one with none) already isolate the cause to something outside this diff.

---

Generated by Claude Code

[btshrewsbury-viam]

Follow-up on the Netlify deploy-preview failure, since it's still failing after b7902130e (the unreachable-/reference/services/slam/*-rule fix):

That fix was a real bug — I confirmed against git history that the original commit did place /reference/services/slam/* after the broader /reference/services/* catch-all, so it was genuinely unreachable. Good catch. But it wasn't the cause of this deploy failure: the deploy still fails identically on b7902130e.

New evidence pointing at a platform-side issue rather than anything in this diff:

• Re-ran my full shadowing/reachability audit against the current HEAD (b7902130e) — a script that checks every [[redirects]] from pattern against every earlier one for prefix-shadowing, the same class of bug just fixed. Zero remaining issues found.
• netlify.toml has zero [[headers]] blocks — yet the "Header rules - viam-docs" check fails too, on every attempt. There is nothing for that check to validate, which means these three checks (Redirect rules, Header rules, Pages changed) aren't independently validating their named concern — they're all just reporting the same underlying "deploy failed," whatever that root cause is.
• Re-ran the full local production build (make build-prod, Hugo v0.152.2 matching the pinned HUGO_VERSION) against the exact current HEAD — completes cleanly, same 955 pages, only the expected old-page-date warnings.
• Netlify's own official @netlify/redirect-parser library still parses all 128 redirects with 0 errors.

I still can't reach the actual Netlify deploy log (403s without dashboard auth from this environment) to identify the real cause. Given a real, valid docs-side bug fix didn't change the outcome, and there's nothing left to find via static analysis or a local build, I believe this needs a human with Netlify dashboard access — worth checking build minutes/quota, the Netlify plugin/site configuration, or an active Netlify incident, rather than further redirect-content changes here.

---

Generated by Claude Code

[btshrewsbury-viam]

All checks are green now (327d7c94c). For the record, the actual root cause of the Netlify deploy failures was found: Netlify's no-more-404 build plugin does a case-sensitive, single-hop reachability check on every link/redirect, and flagged the uppercase SLAM alias variant and the multi-hop /dev/reference/apis/services/slam/* path that my original fix didn't cover directly. 327d7c94c added direct redirects for all the case/prefix variants, which resolved it — my two earlier "unrelated platform issue" comments were wrong; apologies for the noise while chasing that down.

Status: Redirect rules/Header rules/Pages changed all pass or are neutral, all content checks (prettier, markdownlint, vale, htmltest, python-lint, codespell) are green, CLA is signed, no unresolved review threads. Ready to merge pending human review.

---

Generated by Claude Code