[DOCS-4811] Document the AI configuration assistant by btshrewsbury-viam · Pull Request #5217 · viamrobotics/docs

btshrewsbury-viam · 2026-07-15T17:23:00Z

Closes #5204.

Adds a new how-to page documenting the AI assistant for machine configuration, verified against a live app.viam.com session on 2026-07-15.

New page

docs/hardware/ai-assistant.md — "Configure a machine with the AI assistant" (how-to, with a short explanation of what the assistant does and the review-before-save model). Sections map to the issue's learning objectives:

Configure a resource by describing it (Apply)
Review each staged edit, then save or discard (Evaluate)
Use the assistant on a fragment (Apply)
When to use the assistant instead of editing config directly (Analyze)

Placement and discoverability

Placed in the machine-configuration how-to area (docs/hardware/, weight 11, between machine-configuration and fragments). Linked from the section front door configure-hardware.md and from machine-configuration.md so it is discoverable. Additive only; no pages moved, renamed, or deleted.

Fidelity notes

Uses the exact verified UI labels: AI assistant, Builder / JSON, Describe a task or ask a question…, Send, New conversation, Conversation history, Collapse, AI assistant feedback, Let's start configuring, What do you want to do?, Unsaved changes, Save, Discard.
Documents one current unified assistant across Builder and JSON views (supersedes the earlier separate JSON-mode resource assistant); no version history.
Fragment coverage is limited to availability plus standard config-sync propagation; no fragment-specific save UI is narrated (not separately verified live).
Follows house style for service personification: mechanical verbs (the assistant "stages", "reads", "proposes", "generates") and user-centered framing (you describe the change; you save or discard).

Checks (run in the worktree)

prettier: clean (no changes)
markdownlint: pass (0)
vale: 0 errors; readability grade 8.22 (below the section's neighbors)

make build-prod was intentionally not run to avoid contending with the coordinator and Netlify builds; the coordinator should confirm the production build and the Netlify deploy preview.

Add a how-to page for configuring a machine with the AI assistant, covering describing changes, reviewing staged edits, using the assistant on a fragment, and when to use it versus editing config directly. Link it from the configure hardware overview and the machine configuration page.

netlify · 2026-07-15T17:23:05Z

✅ Deploy Preview for viam-docs ready!

Name	Link
🔨 Latest commit	`365b0f3`
🔍 Latest deploy log	https://app.netlify.com/projects/viam-docs/deploys/6a84aa70d49a2f000832acb7
😎 Deploy Preview	https://deploy-preview-5217--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 1 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.

Petr Novikov (petrnovikov) · 2026-07-20T18:11:47Z

+date: "2026-07-15"
+---
+
+On your machine's **CONFIGURE** tab, you can describe a configuration change in


Just in case, AI assistant is now accessible on all machine config tabs, including "Control", "3D scene" and others.

Fixed in e4200f4. Updated the intro and "Where it lives" to say the assistant is available on any tab of the machine's page, not just CONFIGURE.

Generated by Claude Code

Petr Novikov (petrnovikov) · 2026-07-20T18:16:53Z

+The **AI assistant** turns a plain-language request into a proposed
+configuration change that you review before it takes effect.
+
+- **Where it lives.** The assistant is available on the **CONFIGURE** tab for


Same here: the assistant is now available on all machine config tabs.

Fixed in e4200f4. Same change — "Where it lives" now says "available on any tab of your machine's page."

Generated by Claude Code

Petr Novikov (petrnovikov) · 2026-07-20T18:20:43Z

+  configuration, in the **Builder** and **JSON** config views (the config view
+  toggle is labeled **Builder** / **JSON**). Open it from the **AI assistant**
+  button (sparkle icon) at the bottom right of the Builder view. The assistant
+  opens in a panel on the right side of the page.


Maybe a screenshot would be helpful here?

Agreed a screenshot would help here. I can't capture screenshots in this environment — leaving this for a human contributor to add after merge.

Generated by Claude Code

Petr Novikov (petrnovikov) · 2026-07-20T18:21:48Z

+  opens in a panel on the right side of the page.
+- **What it can change.** From your request, the assistant adds, updates, or
+  deletes components, services, modules, remotes, and triggers.
+- **What it reads.** The assistant reads your current configuration (including


Also it can read Viam docs, search registry items (if it's relevant).

Fixed in e4200f4. Added "Viam documentation, and the module registry" to the "What it reads" list.

Generated by Claude Code

Petr Novikov (petrnovikov) · 2026-07-20T18:41:27Z

+- **Conversation history** reopens a past conversation. Conversations are saved,
+  so you can return to earlier requests.
+- **Collapse** hides the panel.
+- **AI assistant feedback** opens a form where you can report how a response


This is technically for Viam employees only at the moment, but I'll make it available to everyone this week.

The feature is now GA (ENABLE_CONFIG_AI_ASSISTANT flag removed in app#13035). Keeping the Conversation history item in the docs since it should now be available to all users. Let me know if it's still restricted.

Generated by Claude Code

Petr Novikov (petrnovikov) · 2026-07-20T18:43:25Z

+   sensor component named test-sensor."
+
+When the panel is empty, it shows the heading **Let's start configuring** and
+the prompt **What do you want to do?**, along with suggested starter requests


Is showing these suggestions here useful to the readers? They will also likely change pretty frequently. Also fragment config AI assistant has different suggestions.

Fixed in e4200f4. Removed the hardcoded prompt list. The page now just says "it shows suggested starter requests you can select instead of typing your own" without listing specific prompts.

Generated by Claude Code

Petr Novikov (petrnovikov) · 2026-07-20T18:51:47Z

+After you send a request, the assistant replies in the panel and stages the
+change: the new or updated resource appears in the Builder marked as modified.
+For the request above, the assistant replies with a confirmation such as
+"Added the fake sensor `test-sensor`. Save the config to apply it.", and the


The answer is non-deterministic and may vary depending on the initial state of user's config, so we might want to avoid using the exact response here.

Fixed in e4200f4. Removed the specific response text. The page now says "the assistant replies in the panel and stages the change: the new or updated resource appears in the Builder marked as modified, ready for you to review" without quoting a specific AI response.

Generated by Claude Code

Petr Novikov (petrnovikov)

Added some non-blocking comments and suggestions, otherwise LGTM

viam-overwatch · 2026-07-21T14:47:17Z

Hey btshrewsbury-viam — this PR has been approved and CI has been green for 4+ business days. Ready to merge?

Auto-comment from overwatch. Will not re-nudge for 7 days.

viam-overwatch · 2026-07-28T14:55:15Z

Hey btshrewsbury-viam — this PR has been approved and CI has been green for 9+ business days. Ready to merge?

Auto-comment from overwatch. Will not re-nudge for 7 days.

viam-overwatch · 2026-08-04T14:55:30Z

Hey btshrewsbury-viam — this PR has been approved and CI has been green for 14+ business days. Ready to merge?

Auto-comment from overwatch. Will not re-nudge for 7 days.

- Assistant is available on all machine tabs, not just CONFIGURE - Add Viam docs and registry search to "What it reads" - Remove hardcoded suggested prompts (they change frequently) - Remove specific AI response text (non-deterministic) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DedtfUcgbZGPEMrGSqVhUY

viam-overwatch · 2026-08-13T14:32:19Z

Hey btshrewsbury-viam — this PR has been approved and CI has been green for 3+ business days. Ready to merge?

Auto-comment from overwatch. Will not re-nudge for 7 days.

…ontent change)

github-actions · 2026-08-19T14:42:56Z

🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs'

viambot added the safe to build This pull request is marked safe to build from a trusted zone label Jul 15, 2026

btshrewsbury-viam requested review from Michael Lee (michaellee1019) and Petr Novikov (petrnovikov) July 15, 2026 17:27

Fix example name consistency and present-tense in AI assistant page

a23d6e9

btshrewsbury-viam marked this pull request as ready for review July 15, 2026 17:51

Petr Novikov (petrnovikov) reviewed Jul 20, 2026

View reviewed changes

Petr Novikov (petrnovikov) approved these changes Jul 20, 2026

View reviewed changes

DOCS-4811: link PR to its docs ticket (empty commit, no content change)

8586329

10zingpd changed the title ~~Document the AI configuration assistant~~ [DOCS-4811] Document the AI configuration assistant Aug 18, 2026

DOCS-4811: re-trigger index with key now in title (empty commit, no c…

365b0f3

…ontent change)

btshrewsbury-viam merged commit 7b626f1 into main Aug 19, 2026
13 checks passed

btshrewsbury-viam deleted the claude/ai-config-assistant branch August 19, 2026 14:42

10zingpd mentioned this pull request Aug 19, 2026

Record the ticket key in the branch name and Source changes #5273

Draft

Uh oh!

Conversation

btshrewsbury-viam commented Jul 15, 2026

New page

Placement and discoverability

Fidelity notes

Checks (run in the worktree)

Uh oh!

netlify Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for viam-docs ready!

Uh oh!

Petr Novikov (petrnovikov) Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Petr Novikov (petrnovikov) left a comment

Choose a reason for hiding this comment

Uh oh!

viam-overwatch Bot commented Jul 21, 2026

Uh oh!

viam-overwatch Bot commented Jul 28, 2026

Uh oh!

viam-overwatch Bot commented Aug 4, 2026

Uh oh!

viam-overwatch Bot commented Aug 13, 2026

Uh oh!

Uh oh!

github-actions Bot commented Aug 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

netlify Bot commented Jul 15, 2026 •

edited

Loading

Petr Novikov (petrnovikov) Jul 20, 2026 •

edited

Loading