Set up a machine: add viam-agent and viam-server explainer; rename section#4972
Merged
shannonbradshaw merged 6 commits intoviamrobotics:mainfrom Apr 17, 2026
Merged
Conversation
✅ Deploy Preview for viam-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
viambot
added
the
safe to build
…ction
Applies playbook-reviewer-feedback. Two items:
- Reviewer ask: new explainer page covering what viam-agent and
viam-server do, plus the four behaviors the reviewer called out
(module pull, module restart, offline operation, local inter-module
communication).
- User direction: rename docs/foundation/ to docs/set-up-a-machine/
so the URL matches the user-facing label. Inbound /foundation/
references across 12 other pages updated. Aliases list on _index.md
preserves /foundation/, /build/foundation/, and two initialize-
machine paths for backward compatibility.
Structural pattern decision: keep set-up-a-machine/_index.md as a
populated landing page (not the overview-pattern stub) because the
section name IS the landing page's topic. Section-with-content
pattern applies; overview-pattern does not. The child pages
(viam-agent-and-server, setup-micro/) appear as siblings in the
sidebar.
No graphic in this PR. Reviewer asked for one ("graphic of viam-
server pulling or restarting a module"). Text-only now; diagram is
a separate asset deliverable.
Verification log (full list in the PR description):
- viam-agent manages viam-server via OnUnexpectedExit:
viam-agent/subsystems/viamserver/viamserver.go:277
- viam-agent's three subsystems: manager.go:63-65
- viam-server exposes gRPC/REST/WebRTC: rdk/robot/web/web.go
- Modules run as subprocesses over UNIX sockets: rdk/module/doc.go:16-22
- Module pull from registry + local cache: rdk/robot/packages/
cloud_package_manager.go:120-182
- Module restart on crash: rdk/module/modmanager/module.go:277
- Manual restart API: rdk/robot/robot.go:140-141
- No direct module-to-module IPC: rdk/module/doc.go:25-27
Deliberate non-claims:
- Module restart backoff policy not confirmed in code; omitted.
- Specific offline-degradation list not fully documented; narrowed
claim to the items directly supported by the package-manager and
module-socket code.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… alignment Two issues from the foundation → set-up-a-machine rename: 1. No-more-404: the rename removed /foundation/setup-micro/, /foundation/setup-micro/micro-module/, and /foundation/setup-micro/micro-troubleshooting/ without aliases. Added each old path as an alias on the corresponding new-location file. Verified locally by checking public/foundation/setup-micro/* all resolve after make build-prod. 2. Prettier: the blanket sed to replace /foundation/ with /set-up-a-machine/ in docs/monitor/overview.md left a table cell over-padded because the new URL is longer. prettier normalizes column widths. I should have caught both by running make build-prod locally before pushing the rename. Playbook amendment coming separately. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The rename-sed run replaced /foundation/ with /set-up-a-machine/ across all docs files. On three files that had /foundation/* entries inside their aliases list (not just as body links), this broke the aliases: - docs/data/capture-sync/capture-and-sync-data.md - docs/data/capture-sync/stop-data-capture.md - docs/hardware/common-components/add-a-camera.md Each had two alias rows like "/foundation/add-a-camera/" that redirected users from legacy URLs to the current canonical page. After my sed, those aliases pointed at /set-up-a-machine/add-a- camera/, which is not a real URL and does not resolve anywhere. The no-more-404 Netlify plugin flagged the resulting missing /foundation/* URLs. Fixed by restoring the original /foundation/ and /build/foundation/ aliases. Verified locally with make build-prod: - public/foundation/capture-and-sync-data/index.html OK - public/foundation/stop-data-capture/index.html OK - public/foundation/add-a-camera/index.html OK This is the kind of thing a playbook amendment should catch. The sed was right for body-text link updates, wrong for alias-list updates. Future directory renames need a targeted approach that distinguishes the two, plus a mandatory local make build-prod before pushing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
shannonbradshaw
force-pushed
the
viam-agent-and-server
branch
from
9bd3d04 to
821a5a7
Compare
You flagged that the section sidebar needs an explicit link to the landing page, not just a clickable section header. Switched from the section-with-content pattern (populated _index.md) to the standard overview pattern. - _index.md: stub with manualLink to overview; just section metadata. - overview.md: linkTitle "Overview", title "Set up a machine", all the landing prose, all the aliases. Pattern matches fleet, multi-machine, data, and every other section on the site. Verified locally with make build-prod: /foundation/, /set-up-a-machine/, /set-up-a-machine/overview/, /set-up-a-machine/viam-agent-and-server/, and the setup-micro children all resolve. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sidebar now reads "Set up machine" for the landing page instead of
the default "Overview." Distinguishes from the section header
("Set up a machine") without duplicating it.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Include the article so the nav entry matches the section header. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Member
|
It looks like the following files may have been renamed. Please ensure you set all needed aliases: |
|
🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs' |
shannonbradshaw
added a commit
to shannonbradshaw/viam-docs
that referenced
this pull request
Apr 18, 2026
Section renamed to /set-up-a-machine/ in PR viamrobotics#4972. Updates body link and card link. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
shannonbradshaw
added a commit
to shannonbradshaw/viam-docs
that referenced
this pull request
Apr 18, 2026
Reference section previously had an empty _index.md with no landing content and no manualLink, so /reference/ rendered an empty page and the section header in the sidebar had nothing to click. Changes: - New overview.md with linkTitle "Overview", title "Reference", and a table of the section's nine subsections with one-line "use it for" blurbs (APIs, Components, Services, SDKs, viam-server, viam-agent, Triggers, Device setup, Glossary). - _index.md stubbed: kept all the legacy aliases, added manualLink to /reference/overview/. Scope expansion, flagged: - reference/viam-server.md (merged in PR viamrobotics#4971 before the foundation → set-up-a-machine rename in viamrobotics#4972) had a card linking to /foundation/, which is no longer a canonical URL. Hugo's card shortcode validates canonical URLs, not aliases, so the build errors with "Card has a bad link: /foundation". Updated the link to /set-up-a-machine/. This is a gap surfaced during verification while I was running make build-prod for the landing page, not anything I caused. Verified locally: make build-prod clean; /reference/, /reference/overview/, all nine subsection URLs, plus /set-up-a-machine/ all return 200. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Applies playbook-reviewer-feedback. One reviewer ask plus one user-directed structural change.
Reviewer feedback addressed
From the first reviewer feedback dump:
Changes
Item A — new page:
/set-up-a-machine/viam-agent-and-server/Explains both tools and the four behaviors the reviewer called out:
RestartModuleAPI.Item B (user-directed) — rename foundation → set-up-a-machine
The URL
/foundation/did not match the user-facing label "Set up a machine." Renameddocs/foundation/→docs/set-up-a-machine/.cli/,data/,fleet/,hardware/,monitor/,reference/updated from/foundation/to/set-up-a-machine/._index.mdaliases preserve/foundation/,/build/foundation/, and the two initialize-machine paths so existing bookmarks still resolve.setup-micro/subdirectory moved along with the rename; no content changes inside.Structural pattern decision
Chose the section-with-content pattern (populated
_index.md, sibling pages) rather than the overview pattern (stub_index.md+overview.md). Reason: the section name is the landing page's topic. "Set up a machine" means exactly the install quickstart on_index.md. An "Overview" linkTitle would either duplicate the section header or hide the real page name.Clicking the section header in the sidebar takes readers to the install quickstart; viam-agent-and-server and setup-micro appear as children beneath.
Verification
viam-agent/cmd/viam-agent/main.go:72,viam-agent/manager.go:44viam-agent/manager.go:63-65viam-agent/cmd/viam-agent/main.go:145-149,viam-agent/agent.go:93viam-agent/subsystems/viamserver/viamserver.go:277rdk/robot/web/web.go:1,513,550,557,593rdk/robot/impl/local_robot.go:1927,rdk/module/modmanager/module.gordk/module/doc.go:16-22,rdk/module/modmanager/module.go:72-78rdk/module/doc.go:25-27rdk/robot/packages/cloud_package_manager.go:120-182rdk/robot/packages/cloud_package_manager.go:133,rdk/robot/packages/local_package_manager.go:138-152rdk/module/modmanager/module.go:277RestartModuleAPI for manual restartrdk/robot/robot.go:140-141rdk/robot/packages/cloud_package_manager.go:98-108,rdk/module/doc.go:16-22Deliberate non-additions
Test plan
/set-up-a-machine/— current install quickstart renders at the new URL/foundation/— alias redirects to/set-up-a-machine//set-up-a-machine/viam-agent-and-server/— new page renders; sidebar places it as a sibling ofsetup-micro🤖 Generated with Claude Code