[rafacm]

M7 of #612 (plan, implementation doc section). A new deployment's first agent is vinga, the built-in one: the presets stop creating assistant and a default agent, and Getting Started claims the first board for vinga. The local default model becomes Gemma 4 e4b (gemma4:e4b), as Rafael confirmed on #612 on 2026-10-09.

What changes

• Presets: examples/presets/local-stack.yaml and cloud-stack.yaml carry only providers and agent_defaults; their headers say vinga is the first agent and that a claim naming no agent binds the board to it. The quoted bind line ends in vinga and the default-agent set assistant line is gone, so the generated recipes in docs/reference/cli.md follow.
• Local model: gemma4:e4b replaces qwen3:8b and llama3.1:8b as the current default in the local preset, examples/llm-openai-compatible.yaml, Getting Started (pull, pin, stop, step 3), docs/run/security.md's recipe and docs/run/llm.md, with reasoning_effort: none (Gemma 4 e4b otherwise streams its thinking first; passed through to Ollama as the old qwen3:8b recipe did). The 8B measurements stay in llm.md as dated history.
• Getting Started (README.md): step 3 configures the engines only; step 5's claim binds the board to vinga, with what to ask it and how a person's own agent joins; a vinga bullet in the feature list. Step 0 says the path was walked with llama3.1:8b and has not yet been walked with Gemma 4 e4b on macOS.
• Follow-on pages: config.example.yaml, examples/README.md, and beyond the plan's footprint docs/run/configuration.md (bound a board to assistant straight after the import) and docs/run/with-a-coding-agent.md (its interview and example assumed assistant).
• The preset boot case: test_a_preset_s_first_agent_is_vinga (integration, once per preset) imports the preset verbatim, builds the boot configuration and asserts the served agents are exactly ['vinga'] with no stored default, then checks a board in, claims its code naming no agent (wrote device ... bound to vinga), and asserts the device reaches ['vinga'].
• Fragment: changelog.d/612-presets-first-contact.md with an Upgrade: line: nothing to run; an existing assistant, default agent and bindings stay (importing is additive); how to move an existing deployment to gemma4:e4b.

The first turn on small hardware (stated, not solved)

M6's local rerun measured that on a Raspberry Pi 5 (CPU only) Gemma 4 e4b takes 107.6 s to the first byte of a conversation's first request (about 1,990 tokens) while the prompt is not yet cached, and 2.4 to 3.4 s once it is. With the defaults, the first-token watchdog (llm_first_token_timeout_s, 10 s) resends once and then ends the turn with the fallback phrase about 20 s in; the 30 s transport read timeout in providers/kit.py is a separate bound that caps any larger watchdog. Seven consecutive cold conversations, each with its retry, all ended in FirstTokenTimeout. Getting Started (a warning in step 0) and docs/run/llm.md (a paragraph of its own) now say so with the numbers, and name the options that exist today (a smaller model, a GPU, a vendor's model). Nothing an operator can run today warms the prompt; whether the server should warm the model or give the first round more time is a follow-up decision, and is not invented here.

Deviations (recorded in the implementation doc)

• "Boots" means building the boot configuration (load_boot_config()), not starting the app, which with the local preset would download speech models and dial Ollama; the existing preset test and the deployment-profile test use the word the same way.
• The presets quote a bind line naming vinga rather than a claim, because the recipe lane runs every quoted line and a claim needs a live code.
• examples/llm-openai-compatible.yaml sets reasoning_effort: none uncommented, so the open-doors fragment test names it.
• Two Run pages beyond the footprint moved: configuration.md and security.md.

Verification

• uv run ruff check .: all checks passed (also after the rebase onto M6).
• The preset boot case run red first against the old presets (2 failed, both ['assistant', 'vinga'] == ['vinga']), green after (5 passed).
• Mutations of the local preset, all killed: a stored default_agent: vinga, agent_defaults without vad, a preset storing its own default agent.
• The suites touching presets and examples (docgen, examples, round trip, config): 229 passed, then 73 passed after the fragment change; the recipe lane 1 passed.
• Drift checks current (after the rebase: domain and server references and the OpenAPI document regenerate byte-identical); doc links 0 failures; Run/Use pages 0 findings; fragments 0 failures.
• tests/census after the rebase onto M6: 69 passed; the command-spellings manifest regenerated by its own command.
• Inventory, untruncated: the old model names went from 85 to 77 lines over tracked files outside history; every remaining line is dated measurement, a test fixture, a field-description example, or the local lane's preferred model (left for M5, which runs that lane). The preset's assistant went from 124 to 103 lines; every remaining one is the conversation role, an operator's own agent in a generic command, or a measured utterance.
• External review round (gpt-6.1-sol, high): 3 P2 and 1 P3, all adopted and fixed; resolutions in the PR comments.
• Full unit and integration lanes locally: deliberately not run, because M5's model gate was running on the same machine; CI runs both on this head.
• Getting Started walked with Gemma 4 e4b on any machine: not done.
• Image, smoke lane, a board or browser onboarded against this build: CI's for the image; no board attached.

Attribution: plan and PR text by anthropic/claude-opus-5-5, thinking high; commits by anthropic/claude-opus-5-5, thinking medium; review round 1 by openai/gpt-6.1-sol, thinking high.

🤖 Generated with Claude Code

[rafacm]

External review round

Automated external review of this PR's diff (origin/main...4c892e9). Reviewed 2026-10-09 by openai/gpt-6.1-sol, thinking high via codex CLI 0.162.0, read-only sandbox, runtime 4m59s, at commit 4c892e9. Posted verbatim by the review run itself; resolutions follow as replies.

---

1. P2: The security recipe re-enables Gemma’s thinking.
   Evidence: docs/run/security.md:283–289 replaces the local entry with gemma4:e4b but omits reasoning_effort: none. config/store.py:736–745 replaces the entity rather than merging fields, so following this recipe removes the preset’s setting. The new model guide records 39–137-second tool turns with thinking enabled.
   Fix: add reasoning_effort: none to this recipe.

2. P2: The cold-turn warning misstates the timeout operators encounter.
   Evidence: README.md:90 and docs/run/llm.md:101–104 say the server gives up after 30 seconds. Getting Started uses the default 10-second first-event watchdog (config/models.py:1502–1505), which retries once (runtime/provider_watch.py:241–275), producing FirstTokenTimeout after roughly 20 seconds without stream activity. The 30-second transport timeout is a separate per-operation bound (providers/kit.py:44–48).
   Fix: distinguish the default watchdog and retry from the fixed transport read timeout; correct the corresponding implementation-doc explanation.

3. P2: Getting Started advertises command help absent from the shipped knowledge.
   Evidence: README.md:317 promises an answer about making an agent, grounded in shipped documentation. knowledge/persona.py:35–44 injects only the persona and concept summary; that summary contains no agent-creation command. tools/source.py:252–280 offers no documentation lookup, and M5 remains unchecked in the governing plan. The model must decline or invent the command.
   Fix: defer this example until lookup ships, or supply the authoritative command through the built-in’s knowledge and verify that path.

4. P3: “Fastest” contradicts the recorded model measurements.
   Evidence: README.md:66 calls e4b the fastest local model measured. The governing plan’s Gate table records e4b search at a 9-second median and e2b search at 6 seconds.
   Fix: say e4b was most accurate and substantially faster than the two previous 8B models.

Verdict: mergeable after the listed fixes.

[rafacm]

Resolutions for the external review round

All four findings adopted; fixes by the milestone's implementer (anthropic/claude-opus-5-5, thinking medium), recorded in the implementation doc's M7 "PR review round" subsection (92ce6c9).

1. P2, the security recipe re-enables Gemma's thinking: fixed in 7baf32b. Confirmed: ConfigStore.set_provider replaces the stored entry rather than merging fields. docs/run/security.md's recipe now carries reasoning_effort: none. An untruncated grep for every recipe writing a local Gemma entry (29 lines) found no other omission: the preset, the openai_compatible example, Getting Started step 3 and llm.md's recipe already carried it.
2. P2, the cold-turn warning named the wrong timeout: fixed in 7c670d8. Getting Started and docs/run/llm.md now say what an operator meets with the defaults: the first-token watchdog (llm_first_token_timeout_s, 10 s) resends the request once, and a second stall ends the turn with FirstTokenTimeout and the fallback phrase about 20 s after the reply began; the 30 s per-operation transport read timeout in providers/kit.py is separate and only matters once the watchdog is raised. Numbers re-checked against M6's logs: the "about 13 tokens per second" rate did not match its own example and was removed in favour of the two measured times (107.6 s for a 1,990-token request, 179.8 s for a 2,363-token probe); "trying again did not get through" is now stated only as far as the logs show it (seven consecutive cold conversations, five at a 10 s and two at a 30 s watchdog, each with its retry, all ended in FirstTokenTimeout), with no cause claimed. The implementation doc and the fragment are corrected to match.
3. P2, Getting Started promised an answer vinga cannot ground: fixed in 3e0d5a9. vinga's prompt today holds its persona, the concept summary and the board guide's opening and Controls section, none of which names a command for creating an agent. Step 5 now suggests questions those answer (the LCD-1.54's volume buttons and turning the screen off; the difference between an agent and a device) and says that beyond them vinga is told to say so rather than guess. "Which command does the rest" is removed from the README feature bullet and both preset headers (their quoted lines are unchanged, so the generated recipes did not move). Three older descriptions of the persona's design in docs/concepts.md, docs/glossary.md and docs/run/configuration.md are left for M5, which decides whether the lookup ships on each stack and therefore what is true.
4. P3, "fastest": fixed in f7366de. Step 0 now says Gemma 4 e4b was the most accurate model measured and substantially faster than the two 8B models it replaces (medians 9 s against 117 s and 27 s); e2b's 6 s median was lower.

Checks after the fixes: ruff clean; docgen, examples and round-trip tests 73 passed; the preset import, first-contact and recipe cases 5 passed; drift checks all current; doc links 0 failures; Run/Use pages 0 findings; fragments 0 failures; tests/census last, 69 passed. The full lanes rerun in CI on the new head.