docs(onboarding): add AGENT_SETUP.md playbook (Path B final piece) - #21
Merged
Conversation
Third and final slice of Path B (LLM-driven onboarding). With env-fingerprint (PR #19) describing state and verify (PR #20) asserting expectations, this document sequences them into an end-to-end install flow an agent can follow without scraping human-friendly output. Audience: AI coding agents (Claude Code / Codex / Gemini) running an llm-relay setup on a user's behalf. The document is explicit that it is NOT a human tutorial -- humans should use README.md and `llm-relay init` directly. Structure: Phase 0 — Probe (env-fingerprint) Phase 1 — Install or upgrade the package (with extras decision table) Phase 2 — Initialize local state (llm-relay init) Phase 3 — Per-CLI integration (claude-code / openai-codex / gemini-cli) Phase 4 — Optional: start the server (Linux/macOS vs Windows service) Phase 5 — Final acceptance (verify all) Each phase ends with a `verify` call, and the playbook spells out how to respond to pass / warn / fail outcomes. Permission protocol: The playbook never assumes consent for system-modifying actions. Five explicit markers gate any operation that touches outside of read-only probes: [PERMISSION: install-package] pip install [PERMISSION: write-config] llm-relay init (writes ~/.llm-relay/, edits ~/.claude/settings.json) [PERMISSION: edit-claude-settings] direct settings.json edit (last resort) [PERMISSION: fix-permissions] chmod / chown on home dir files [PERMISSION: install-service] Windows background service registration "When to stop and ask" section enumerates ambiguous states (no CLI installed, verify fail with no remediation, multiple Python interpreters, etc.) where the agent must defer to the user instead of improvising. "What not to do" section pins down the agent's scope: do not modify session transcripts, do not install LLM CLIs on the user's behalf, do not auto-edit shell rc files, do not retry a failing remediation more than once. README updated with an "Agent-driven setup" section linking to the playbook and showing the four entry-point commands. CHANGELOG documents the playbook under Unreleased ### Added. Schema contract: both env-fingerprint and verify use schema_version "1"; the playbook calls out that an agent should fall back to the in-tree playbook for whatever release it has installed if the schema version differs.
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
1 participant
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
Third and final piece of Path B (LLM-driven onboarding):
env-fingerprintverify *docs/AGENT_SETUP.mdAudience
AI coding agents (Claude Code / Codex / Gemini) automating an llm-relay
install on a user's behalf. The document explicitly states it is not a
human tutorial — humans should use
README.mdandllm-relay init.Structure
Five phases, each ending in a
verifycall with explicit pass / warn / failguidance:
env-fingerprint --format jsonpip install llm-relay[<extras>](decision table for extras)llm-relay init --port <port>verify integration --cli <id>per detected CLIllm-relay serveor Windows serviceverify all [--live]Permission protocol
The playbook never assumes consent. Five
[PERMISSION: …]markers gate anysystem-modifying action:
install-package—pip installwrite-config—llm-relay init(writes~/.llm-relay/, edits~/.claude/settings.json)edit-claude-settings— direct edit, last resort onlyfix-permissions—chmod/chownon home dirinstall-service— Windows background service registrationStop-and-ask rules
Explicit list of ambiguous states where the agent defers to the user:
verifyfails with noremediationstringenv-fingerprint/verifyWhat not to do
The agent's scope is bounded:
usage.dbor CC*.jsonltranscriptsverifymore than once with the same remediationOther changes
README.md— new "Agent-driven setup" section linking to the playbook andshowing the four entry-point commands.
CHANGELOG.md— entry under Unreleased### Added.Test plan
unchanged.
verify install/
verify config/verify integration --cli claude-codesmoke-testedon this host before writing).
What's next (after this lands)
Path B is structurally complete: an agent can probe, install, configure,
verify, and report. Realistic next tracks:
and capture the friction points.
(composition incremental cache, zone 1M restore, dup_reads fix, CSS fix(dashboard): status-text shrinks correctly when sibling text grows #15,
env-fingerprint, verify primitives, AGENT_SETUP).
--guidemode tollm-relay initthat surfacesthe same decision tree the playbook describes, for humans who prefer
doing it themselves.