[Shannon Bradshaw (shannonbradshaw)]

Documents machine favorites, which are live in the Viam app, the Python SDK (v0.85.0), and the Viam MCP server.

Documents: DOCS-5024

Also matched: DOCS-5039 (Needs Triage, "Docs for User favorites should be stored in the cloud, not on device"), which links APP-15482 and covers the mobile app's switch to cloud favorites (viam-mobile#933, not yet in a viam-mobile release).

Source changes

• APP-15482, APP-18103 — app#13983: AddFavoriteMachine, RemoveFavoriteMachine and ListFavoriteMachines, plus the favorites UI (star toggle on the fleet Machines table, Add to favorites in the machine actions menu, Machine Favorites tab in user settings) behind ENABLE_MACHINE_FAVORITES_UI, which defaults to on
• api#913: the AppService favorites RPCs and the FavoriteMachine message
• viam-python-sdk#1291: add_favorite_machine, remove_favorite_machine, list_favorite_machines (in the published v0.85.0 release, and on python.viam.dev)
• APP-18301 — app#14018: the list_favorite_machines, add_favorite_machine and remove_favorite_machine MCP tools; ListFavoriteMachines now leaves out machines that were deleted or that the caller can no longer read
• app#14034: removed ENABLE_USER_SETTINGS, so every user's profile menu has the Settings link to the page with the Machine Favorites tab

Docs changes

• docs/monitor/monitor.md: new "Favorite machines" subsection under "Check fleet status": the star in the machines table (including the header star that lists favorites first), the machine page's ... menu items, the Machine Favorites tab in user settings, that favorites are per user and span organizations, and that deleted or inaccessible machines drop out. Links to the API methods and MCP tools.
• .github/workflows/sdk_protos_map.csv: rows for the three RPCs, with only the Python column filled. The Go SDK (RDK app client), TypeScript SDK and Flutter docs columns have no favorites methods to point at (Flutter v0.23.0 has them, but no app row in the CSV fills the Flutter column).
• static/include/app/apis/overrides/protos/app.{Add,Remove,List}FavoriteMachine(s).md: proto descriptions, taken from domains/service/server.go (Add reads the machine through the permissioned layer; Remove deliberately skips the machine lookup) and data.ReadableFavoriteMachines.
• static/include/app/apis/generated/app.md and app-table.md: regenerated with update_sdk_methods.py "" app. The diff is only the three new methods.
• static/include/app/mcpserver/generated/mcp-tools-table.md: the three tools, categorized from mcpserver/tools_favorites.go (readOnlyTool, writeTool(..., false), writeTool(..., true)). This file is hand-maintained; Update MCP reference for the use_skill tool #5441 adds use_skill to a different part of the same table.
• docs/reference/mcp/_index.md: one paragraph saying the favorite tools touch only your own favorites, and why remove_favorite_machine is listed as destructive.

How I found these

• Xref lookup: app-api-xref.md (AppService) for the fleet API page; the MCP table rule in the docs repo's CLAUDE.md
• Grep matches: favorit, Machine Favorites, machines table, user settings across the docs repo found no existing mention of favorites; monitor.md is the page that describes the machines table
• Carried from the docs-agent backlog (item app-13983-machine-favorites, added 2026-10-20). DOCS-5024 is In Progress with a human owner and had no docs PR; if this overlaps work in progress, close whichever is redundant.

Checks: repo-local prettier 3.2.5, markdownlint, vale 3.12.0, scripts/frontmatter_rules.py, and make build-prod pass. The built pages have the #favorite-machines and #addfavoritemachine/#removefavoritemachine/#listfavoritemachines anchors.

---

Generated by daily docs change agent

https://claude.ai/code/session_01KtWAzVC4pY7CUow7BH7XES

---

Generated by Claude Code

[netlify]

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	31a7c14
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6ad9d64e5c23a32ce6dd58a2
😎 Deploy Preview	https://deploy-preview-5453--viam-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 47 (🟢 up 9 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.

[Jeremy Rose (jeremyrose-viam)]

Hi! DOCS-5024 is owned by Jeremy Rose, and a draft for it has been waiting on a fork branch while the favorites UI and MCP tools shipped: https://github.com/jeremyrose-viam/docs/tree/worktree-machine-favorites-docs (a Monitor page subsection plus the MCP table rows, a few dozen lines in total). Both are live now (the list_favorite_machines and remove_favorite_machine tools were checked against production today), so this PR and that branch overlap. We'd like to settle on one. Where they differ, and why we made our choices:

1. Python SDK methods in the API reference: we left them out. Favorites belong to a signed-in user, but the Python app client only accepts API-key credentials (Credentials.type is "robot-secret" or "api-key", and ViamClient rejects robot-secret), so add_favorite_machine and the other two can't act as a user for typical callers. Rather than document methods that mostly fail, we put them on the Python ignore list in update_sdk_methods.py, the same way the push-token methods are handled, so the coverage job stays quiet. Does this PR have evidence that these calls succeed with an API key? If so, we would reconsider.
2. UI detail: we kept it short. The docs avoid click-by-click steps because the app UI changes often. Ours says what favorites are, that favorited machines appear at the top of the table, where the Machine Favorites tab is, and that favorites are per user. The menu paths, the header star and the initials-menu route in this PR are the parts we would trim.
3. Where we agree: placement on the Monitor machine status page, favorites being per user and spanning organizations, the three MCP table rows and their categories (remove_favorite_machine as Write (destructive)), and no Go, TypeScript or Flutter rows in the CSV.
4. Worth keeping from this PR: the paragraph on the MCP reference page explaining why remove_favorite_machine is marked destructive, and the note that deleted or inaccessible machines drop out of the list. The fork branch has neither.

Proposal: Because Jeremy owns the ticket and made the scope decisions in 1 and 2, we suggest closing this PR, as its description allows when it overlaps in-progress work, and we will carry item 4 into the fork branch's PR. If you would rather keep this PR, the alternative is to trim it to the shape described in 1 and 2. Either works for us. Please say which, or share evidence on item 1.

Posted by Claude Code on Jeremy Rose's behalf.

[Shannon Bradshaw (shannonbradshaw)]

Thanks. Item 1 holds up against the code: AddFavoriteMachine and RemoveFavoriteMachine in auth/permissioned_data.go reject a caller unless state.AppUser matches the user, and the Python ViamClient only dials app with API-key credentials. So this PR's Python rows would document calls that fail for typical callers. I have no evidence that they succeed with an API key.

Closing this in favor of the fork branch, as you suggest. Please carry over item 4: the MCP reference paragraph on why remove_favorite_machine is marked destructive, and the note that deleted or inaccessible machines drop out of the list.

---

Generated by Claude Code