surface

Bedside: Surface

Layer 2 of 3. Product patterns that encode operator manners in tools so agents and humans are guided even when contract prose is skimmed.

Layer	Path	Job
Contract	contract/	Human-readable rules
Surface	surface/	Tools encode manners (this artifact)
Eval	eval/	Manners cannot rot

Without surface work, Bedside is doctrine agents may ignore. Without the contract, surface copy has no normative bar. Without eval, surface quality can rot unnoticed.

This repo ships a minimal Python CLI (bedside init|doctor|eval|ask|step) as a first surface. Command cores are UI-agnostic for a future tui-cs/cli front-end; see the root README.

Purpose

The contract says what good operator care is. The surface is where it ships:

• CLI and TUI verbs and flags.
• Error messages and exit codes.
• Guided multi-step flows (especially body and browser acts).
• Discovery UIs (ports, accounts, devices, clusters).
• Docs generators that leave a routine path.

Design for smart, high-judgment non-experts and for the agents driving the tools on their behalf.

Core patterns

1. Guided verbs

Thin, scriptable commands with operator-facing messages (not only machine logs).

Verb (examples)	Intent
doctor	Check host, tool, or device readiness; report in plain language; exit non-zero with recovery hints
ask	One structured yes/no or multi-choice operator gate; recommended option first; stable id for logs/eval
step	One human body/browser act: show instruction → confirm in their words → next
first-run / flash-first	Own first-time setup from zero once; detect blank vs ready
deploy --verify	Deploy then prove identity or version; fail closed on mismatch
gate	Named host proof of done (tests or sim); green means claimable

Agents should prefer these verbs over assembling ad-hoc shell walls or free-text multi-choice menus. Humans should be able to re-run one documented verb tomorrow.

Operator gates (bedside ask / bedside step)

Products that pin Bedside should not restate long "how to ask the human" essays in every AGENTS.md. Point agents at these verbs (or the host structured UI that implements the same contract):

bedside ask --id confirm-deploy --prompt "Deploy to production now?" --choices yes,no --default no
bedside step --id plug-usb --prompt "Plug the data USB cable into the board." --expect "Power LED is on."

Verb	Intent
ask	One structured choice or yes/no with recommended default; plain-language prompt required; stable --id
step	One human body/browser act: show instruction → wait/confirm in their words → next

Rules:

1. UI-agnostic cores under commands/ so argparse, tui-cs/cli, or an agent host adapter can render pickers without rewriting behavior.
2. Prefer the agent host structured choice UI when present; CLI --answer / --confirm is the scriptable path; interactive stdin is the human fallback.
3. Exit codes (silico#84 overlay): 0 any valid ask choice or step confirmed; 10 still needed or step declined; 30 setup error (missing id/prompt, bad flags). For ask, branch on choice= / matched_recommended — exit 0 + non-recommended is an explicit alternate fork, not a decline.
4. Each run prints a fixture-friendly Record: line (bedside.ask / bedside.step) so sessions can be scored later.
5. Scope is the operator path (setup, scary surfaces, irreversible writes, physical steps). Domain design taste stays in the product.

Prefer ask / step (or host pickers) over multi-choice free-text walls. See also anti-walls below.

Maps to contract tenets 2, 5, 8, and 9.

2. Step machines (human body or account)

When the path requires the operator's body or browser:

action → wait → confirm in their words → next

Rules:

1. One physical or click instruction at a time.
2. Name the control, window, or label exactly.
3. Block progress until confirmation (or a clear timeout and re-prompt).
4. Never batch "do A, B, C, then tell me."

Maps to contract tenets 5, 8, and 9.

3. Candidate listing (plain language)

For multi-candidate scary surfaces (serial ports, kube contexts, cloud projects, USB devices):

1. List candidates with plain-language likelihood ("likely the board", "likely a different adapter").
2. Prefer explicit IDs over blind auto when more than one candidate exists.
3. On failure, say what you will try next. Do not shame the operator.

Maps to contract tenet 7.

4. Fail closed and recovery

Bad surface	Bedside surface
Stack trace as the product UX	Short failure reason plus what to do next
Warning then continue on identity mismatch	Fail closed; explicit override only if safe and documented
"Error: failed" with no recovery	Numbered recovery steps the agent can drive or the human can do

Exit codes should be stable enough for agents. Messages should be stable enough for operators.

5. Anti-walls

Tools and agent wrappers should not make a bulk "run these N commands" dump the primary UX.

Prefer:

1. One verb that orchestrates.
2. Or one command at a time with explanation, run by the agent when possible.

If a tool must print a command for the human to paste (for example a browser device code), print that one string with context. Not five unlabeled blocks.

Maps to contract tenets 2 and 3.

6. Structured choice UI (no free-text multi-choice)

When the agent host provides a structured picker (AskUserQuestion-style tools, radio lists, plan-fork choosers), use it for:

1. Yes/no gates before irreversible or scary work.
2. Plan forks the operator must choose among.
3. Multi-candidate picks that are not open-ended prose (accounts, regions, devices already listed by a discovery verb).

Rules:

1. Prefer the structured UI over a chat free-text menu of options.
2. Put the recommended option first (and label it when the API allows).
3. Keep free text for open-ended domain judgment the picker cannot express.
4. If no structured UI exists, one short numbered list is better than a shell wall, but it is still a weaker fallback. Prefer a surface verb that encodes the gate (see guided verbs and step machines).

Anti-pattern (choice wall): a good plan table followed by "reply with start #15, fold issues, reprioritize P1, …" when a picker was available.

Maps to contract tenets 2 and 5.

7. Progress and status

Long work reports itself. A surface that blocks for more than about five seconds shows a progress indicator, a count, or an estimate of time remaining, not a frozen cursor.

Rules:

1. Anything past roughly five seconds gets progress, a step count, or an estimate.
2. Work delegated to subagents, workers, or background jobs reports what each one is doing and how far along it is.
3. Use one status shape across the whole tool, so the operator learns to read it once.
4. On a long failure, say how far it got before it failed. "Failed" alone hides whether the last four minutes were wasted.

Anti-pattern: spawning parallel workers whose only operator-visible output is the final result.

Maps to contract tenet 4.

8. Leave-behind

After success, the surface (or the docs it generates) leaves one routine path:

1. One update, deploy, or verify command (or short script).
2. What "good" looks like (LED pattern, health URL, version string).

No textbook of equivalent alternatives.

Maps to contract tenet 10.

Agent-first CLI notes

Surfaces that agents drive should:

1. Be non-interactive by default when flags can replace prompts.
2. Use clear exit codes (0 success; non-zero classes for retry vs human-needed vs hard fail).
3. Print operator prose on stderr or a dedicated summary stream; keep machine-readable output optional (--json) without making JSON the only recovery path.
4. Refuse or loudly warn on dangerous blind defaults (for example auto-pick among many devices).

Interactive TUIs are fine for humans. Agents need a scriptable path to the same manners.

Domain packs (surface side)

Domain packs supply verbs, copy, and step graphs. Not new tenets.

Domain	Example surface concerns
Embedded / metal	Port discovery, first flash, BOOT/RESET steps, version verify on device
Cloud first-deploy	Auth device code, project or account pick, region, fail-closed IAM
Data / ML bootstrap	Runtime or env install, GPU checks, one re-run training or serve command
Appliance / on-prem	Network join, admin password once, health URL leave-behind

Reference illustration: silico host path (doctor / deploy / verify style intent; implementation may lag doctrine).

Surface checklist

• At least one guided verb or error path encodes plain-language recovery.
• First-run is a first-class path (verb or documented step machine), not folklore.
• Multi-candidate discovery lists plain-language candidates; avoids blind auto when unsafe.
• Fail closed on identity or verify mismatches (or documented exception).
• Work slower than about five seconds shows progress, a count, or an estimate.
• Delegated or background work reports what each worker is doing.
• Success leaves one routine command and what "good" looks like.

Contract pin: contract/. Prove manners: eval/.