opencode-provider-switch/.trellis/tasks/archive/2026-04/04-17-04-17-agent-first-cli-help-prd/prd.md

OCSWITCH Agent-First CLI Help System

Summary

ocswitch already has a working CLI and a reasonably complete README, but its help surface is still optimized for a human reading source-adjacent docs, not for an AI agent trying to configure the tool end-to-end with high reliability.

This PRD defines a narrow product change:

• every user-facing ocswitch command must provide Long help
• every user-facing ocswitch command must provide Example help
• help content must be written for AI agent execution reliability first
• manual CLI ergonomics remain important, but are secondary to agent clarity

The intended result is that an AI agent can use ocswitch --help and nested --help output as a trustworthy local interface contract for discovery, planning, execution, and recovery during configuration.

Product Goal

Make ocswitch self-describing enough that a capable AI agent can complete normal configuration workflows without relying on hidden tribal knowledge, source code inspection, or README-only instructions.

Core User Need

User wants to say, in effect:

"Configure ocswitch for my providers and aliases, then sync OpenCode and tell me how to run it."

The agent should be able to do that safely by reading CLI help output and executing commands in order.

Why This Matters

Current repository state already supports the core workflow:

• add or import upstream providers
• create aliases and bind ordered targets
• validate config via ocswitch doctor
• sync aliases into OpenCode via ocswitch opencode sync
• run proxy via ocswitch serve

But the command tree does not yet expose the full operational contract through help text. In practice this means:

• some commands only have Short
• side effects are not always explained in help output
• default target paths and scope boundaries are not always repeated where used
• the "what to do next" step is often only in README, not in command help
• an agent may need to infer workflow rules from source code instead of help

This is acceptable for an engineering MVP, but not good enough if ocswitch wants to recommend agent-driven configuration as a first-class path.

Design Principle

Treat CLI help as a machine-consumable operational interface, not as a minimal hint for humans.

That means help text should answer these questions explicitly for each command:

1. What job does this command do?
2. When should an agent call it?
3. What must already exist before calling it?
4. What state does it read or write?
5. What does it intentionally not do?
6. What command usually comes next?
7. What concrete examples should be copied for common workflows?

Priority Order

When there is a tradeoff, the implementation should optimize for:

1. AI agent understanding and execution reliability
2. Deterministic and explicit side-effect descriptions
3. Copy-paste-safe examples
4. Human readability
5. Brevity

This means slightly longer help is acceptable if it reduces agent mistakes.

Non-Goals

1. No GUI or local web setup flow in this task.
2. No new interactive wizard in this task.
3. No major command model redesign unless required to support help clarity.
4. No attempt to encode every README detail into root help output.
5. No hidden behavior added only for agents; behavior must stay consistent with the real command implementation.

Scope

In Scope

All user-facing commands in the current Cobra tree:

• ocswitch
• ocswitch serve
• ocswitch doctor
• ocswitch provider
• ocswitch provider add
• ocswitch provider list
• ocswitch provider remove
• ocswitch provider import-opencode
• ocswitch alias
• ocswitch alias add
• ocswitch alias list
• ocswitch alias bind
• ocswitch alias unbind
• ocswitch alias remove
• ocswitch opencode
• ocswitch opencode sync

Also In Scope

• defining a consistent writing contract for Long and Example
• deciding which workflow facts must be repeated in help instead of delegated to README only
• optional README adjustments if needed to point agents toward --help as the authoritative interface contract

Out of Scope

• adding brand-new command groups just for documentation cosmetics
• changing proxy/runtime semantics unrelated to help clarity
• solving remote connectivity testing beyond what already exists

Agent-First Help Requirements

Every command help page must be written to support agent execution. The text does not need to be machine-parseable JSON, but it must be operationally unambiguous.

Requirement 1: Each command must define Long

Long must not repeat Short mechanically. It must explain behavior, preconditions, scope, and next-step guidance.

Minimum Long contents per command:

1. command purpose
2. state read/write behavior
3. prerequisites or expected prior commands
4. important defaults and path resolution rules
5. behavior boundaries or non-effects
6. recommended next step

Requirement 2: Each command must define Example

Example must contain realistic command lines that an agent can copy with minor substitutions.

Examples must prefer:

• real flag names
• complete command lines
• stable placeholder values
• workflow-oriented ordering
• one example per important usage pattern

Examples must avoid:

• vague ellipses when a concrete placeholder is better
• examples that omit required flags without explanation
• examples that imply unsupported behavior

Requirement 3: Root and group commands must explain workflow position

Commands like ocswitch, ocswitch provider, ocswitch alias, and ocswitch opencode are not action commands themselves, but they are decision points for an agent.

Their help must answer:

• what subcommands exist
• in what order agents usually use them
• which subcommand to inspect next for each workflow

Requirement 4: Help must surface side effects explicitly

Whenever a command writes local config or OpenCode config, help must say so.

Examples:

• provider commands write ocswitch config
• alias commands write ocswitch config
• opencode sync writes the target OpenCode config unless --dry-run
• doctor validates statically and does not call upstream providers
• serve starts a long-running local proxy and does not mutate config

Requirement 5: Help must surface defaults locally

Agents should not need to jump to README or source to know command-local defaults.

Examples of defaults that must appear where relevant:

• default ocswitch config path via --config
• default OpenCode sync target resolution order
• default proxy bind address and API key when describing serve or workflows

Requirement 6: Help must be safe for secrets

Help examples may use placeholder keys like sk-example, but must never suggest printing or leaking real secrets. Examples should not instruct agents to copy config files to chat or expose API keys in logs.

Content Contract By Command Type

Root Command: ocswitch

Long should define the full happy-path workflow:

1. add/import providers
2. create alias and bind targets
3. run doctor
4. run opencode sync
5. run serve

Example should include:

• inspect root help
• scratch setup flow
• import-first flow

Group Command: provider

Long should explain that providers are upstream OpenAI-compatible endpoints used by alias targets. It should state that provider definitions live in local ocswitch config and are separate from alias routing.

Example should include:

• add provider
• import from OpenCode
• list providers

Action Command: provider add

Long should explain:

• creates or updates a provider entry
• --base-url must include /v1
• omitted mutable fields may preserve existing values on update
• repeated --header appends explicit extra headers
• command does not validate upstream reachability

Example should include:

• minimal add
• add with API key
• add with repeated headers
• update only base URL of existing provider

Action Command: provider list

Long should explain that output is for inspection, redacts keys, and is often used by agents to confirm imported or saved provider IDs before binding aliases.

Example should include:

• plain listing
• listing with explicit --config

Action Command: provider remove

Long should explain:

• removes provider from ocswitch config
• does not automatically clean alias references
• follow-up doctor may fail if aliases still reference removed provider

Example should include:

• remove provider
• inspect aliases afterward

Action Command: provider import-opencode

Long should explain:

• source defaults to global OpenCode config resolution
• only supported import shape is config-defined @ai-sdk/openai custom providers with baseURL and apiKey
• unsupported providers are skipped by design
• --overwrite changes update semantics

Example should include:

• default import
• import from explicit file
• overwrite existing providers

Group Command: alias

Long should explain aliases as the primary user-facing abstraction exposed to OpenCode as ocswitch/<alias>, and that target order defines failover priority.

Example should include:

• create alias
• bind primary and fallback targets
• list aliases

Action Command: alias add

Long should explain:

• creates or updates alias metadata only
• does not add targets
• disabled aliases are not meant for OpenCode exposure until enabled and valid

Example should include:

• create enabled alias
• create disabled alias
• update display name

Action Command: alias list

Long should explain output semantics:

• alias enabled/disabled state
• target ordering
• target enabled markers
• common use before doctor and opencode sync

Example should include:

• plain listing
• listing under explicit config path

Action Command: alias bind

Long should explain:

• appends target in failover order
• provider must already exist
• alias auto-creates if missing
• binding does not test upstream health
• order matters operationally

Example should include:

• first target bind
• second fallback bind
• bind disabled target

Action Command: alias unbind

Long should explain:

• removes one concrete target tuple from alias
• does not delete the alias itself
• may leave alias invalid if no enabled targets remain

Example should include:

• remove one fallback target
• run doctor afterward

Action Command: alias remove

Long should explain:

• removes entire alias from local config
• future opencode sync will stop exposing it in provider.ocswitch.models
• does not directly remove model selection already set elsewhere in OpenCode

Example should include:

• remove alias
• sync afterward

Action Command: doctor

Long should explain:

• performs static validation only
• validates local config structure and OpenCode sync preview assumptions
• does not issue real upstream requests
• should be called before opencode sync or serve

Example should include:

• plain validation
• validation with alternate config path

Group Command: opencode

Long should explain that these commands manage the narrow integration boundary between ocswitch and OpenCode, and do not attempt full OpenCode config takeover.

Example should include:

• inspect sync help
• run sync dry-run

Action Command: opencode sync

Existing Long is a strong starting point but must be aligned to the new help contract.

Long should explain:

• exact write target rules
• what fields are mutated and not mutated
• that aliases become provider.ocswitch.models
• meaning of --dry-run
• recommended call order around doctor

Example should include:

• basic sync
• dry-run preview
• sync and set top-level model
• sync and set model plus small model
• sync to explicit target file

Action Command: serve

Long should explain:

• starts long-running proxy
• reads validated local config
• requires a valid alias/provider setup first
• handles OpenCode traffic at the configured local base URL
• should generally be called after doctor and opencode sync

Example should include:

• start with defaults
• start with explicit config path

Writing Rules For Long

All Long help should follow a shared style so agents can scan it quickly.

Recommended structure:

1. one-sentence job statement
2. short paragraph describing read/write effects
3. short paragraph describing prerequisites and defaults
4. short paragraph describing boundaries or important caveats
5. one-line next step recommendation when useful

Writing rules:

• use direct, operational language
• prefer exact nouns from the product: provider, alias, target, OpenCode config
• say "does" and "does not" explicitly
• repeat important defaults instead of assuming root help was read
• avoid marketing language
• avoid implementation trivia that does not affect execution

Writing Rules For Example

Examples should be optimized for agent reuse.

Rules:

• use fenced multi-line examples where grouping improves clarity
• order examples from safest/common to more advanced
• keep placeholders stable across commands when possible
• use provider IDs and alias names that match repository terminology
• reflect real workflow order

Preferred placeholder vocabulary:

• provider ids: su8, codex, relay
• alias names: gpt-5.4, gpt-5.4-mini
• api keys: sk-example
• local paths: /path/to/opencode.jsonc

Workflow Scenarios The Help Must Support

Help output across the command tree must enable an agent to execute these common scenarios without README-only dependency.

Scenario 1: Configure from scratch

1. inspect ocswitch --help
2. add one or more providers
3. add alias
4. bind targets in order
5. run doctor
6. run opencode sync
7. run serve

Scenario 2: Import existing OpenCode provider definitions first

1. inspect ocswitch provider import-opencode --help
2. import supported providers
3. list providers
4. create aliases and bindings
5. validate, sync, serve

Scenario 3: Change only one provider endpoint

1. inspect provider add --help
2. update existing provider base URL or key
3. run doctor
4. restart serve if already running

Scenario 4: Remove or replace a fallback target safely

1. inspect alias list
2. alias unbind
3. optionally provider remove
4. run doctor
5. run opencode sync if alias exposure changed

README Relationship

README remains useful, but after this task its role changes:

• README explains the product and quick-start narrative
• CLI help becomes the authoritative local execution contract
• README may include one short section telling users and agents to prefer command-local --help for exact behavior and flag usage

README should not be the only place where critical command semantics live.

Acceptance Criteria

Functional Acceptance

1. Every user-facing Cobra command in the current ocswitch tree defines non-empty Long and non-empty Example help.
2. ocswitch --help and all nested --help pages expose enough information for an agent to discover the intended configuration workflow without reading source.
3. Help text for mutating commands explicitly states what files/config are written.
4. Help text for non-mutating commands explicitly states that they do not write config or contact upstreams when that distinction matters.
5. opencode sync --help explicitly documents default target resolution and the non-default behavior of --set-model and --set-small-model.
6. provider add --help explicitly documents /v1 requirement and update semantics for omitted fields.
7. alias bind --help explicitly documents auto-create behavior and ordering semantics.

Quality Acceptance

1. Help examples are copy-paste-ready after simple placeholder substitution.
2. Help text does not contain contradictions with actual runtime behavior.
3. Terminology is consistent across all help pages.
4. No command relies only on README for a behavior that materially affects safe execution.

Agent Success Acceptance

This task is successful if a fresh agent can reasonably do the following with CLI help as its primary reference:

1. determine the canonical happy-path setup order
2. configure providers and aliases
3. understand what doctor validates and what it does not
4. sync aliases into OpenCode safely
5. understand when to start serve

Implementation Notes

This PRD does not require a new documentation subsystem. Current Cobra support is enough:

• Short
• Long
• Example

Implementation should prefer a small, consistent helper style only if needed to avoid repeated wording mistakes. Do not over-abstract help generation unless the duplication becomes genuinely harmful.

Risks

1. Help text may drift from behavior if future command semantics change without updating examples.
2. Longer help output may become noisy if not structured carefully.
3. Over-optimizing for agents could make help feel less natural for humans.

Risk Mitigation

1. Keep help operational and specific, not verbose by default.
2. Prefer one shared writing contract across all commands.
3. Add tests that assert key phrases exist for high-risk commands.
4. Treat help text as behavior-adjacent surface that must change with command semantics.

Future Extensions

These are explicitly out of this task, but compatible with it later:

• ocswitch setup guided workflow command
• shell completion tuned for provider/alias names
• structured --help-format json for agent-native consumption
• README agent prompt template that mirrors the help contract

Final Product Decision

ocswitch should recommend an agent-first, CLI-native configuration workflow.

The CLI itself must become the most reliable place to learn how to configure the tool. Long and Example are therefore not documentation polish; they are part of the product interface.