docs: update all documentation for current CLI state#62
Merged
Conversation
Audit and update all core documentation to reflect PRs #58-#61: README.md: - Add 'What harness up replaces' section showing the single command vs 8+ raw openshell commands for a 4-provider agent - Remove deleted commands (preflight, providers) - Update config files table (gateway.yaml, remove providers.toml/openshell.toml) - Add OpenCode support, --provider-refresh flag, --env injection - Add v0.0.59 prerequisite SPEC.md: - Remove deleted commands and config files - Update payload section (no more env.sh/sandbox.env) - Document three registration flows (standard, ADC, custom) - Add --provider-refresh, task -p application, empty env host lookup AGENTS.md: - Update sandbox image workaround (adds opencode-ai) - Fix test target description (bats removed) sandbox/CLAUDE.md: - Add opencode as available agent - Remove stale kubectl/deploy-kubeconfig reference - Generalize inference description demo/DEMO-SCRIPT.md: - Fix entrypoint (claude not claude --bare -p) - Replace providers.toml with profiles directory - Replace gateway.toml with gateway.yaml - Remove harness providers step
The demo/ directory and agents/demo.yaml were not actively used. Updated README task agent example to use a generic name.
registerProviders() now takes the agent's provider name list instead of a gateway config. Only providers listed in the agent YAML are registered — no more hardcoded list of all four providers. The agent YAML is the single source of truth for which providers a sandbox needs. If a provider isn't in the YAML, it's not registered.
The 'What harness up replaces' section now flows: the harness command, the agent YAML it reads, then the openshell commands it replaces. Removed the duplicate Agent Configs section.
The agent YAML can now specify its deployment target via gateway: field. harness up reads it to determine local vs remote — no --local/--remote flag needed when the agent config declares it. - gateway: local (default) — Podman on your machine - gateway: ocp — OpenShift cluster - gateway: kind — local kind cluster - --local/--remote flags override the agent config Added agents/ocp.yaml as a concrete example.
Show the additional Helm deploy + sandbox create commands that harness up runs when gateway: ocp is set.
The correct OCP sequence is: namespace + CRD + SCCs + Helm + rollout + gateway register → then provider registration → then sandbox create. Previously showed providers before deploy.
…-env Provider config values (JIRA_URL, JIRA_USERNAME, etc.) now flow through the provider system via --config on 'openshell provider create' instead of being merged into --env on sandbox create. - BuildEnvMap() returns only the agent's env: section (sandbox-level vars) - ProviderRef.ConfigList() returns config as KEY=VALUE pairs for --config - registerProviders() takes []agent.ProviderRef instead of []string, passing each provider's config to the registration call - Provider configs are managed by the gateway, not manually injected
Provider non-secret vars (JIRA_URL, JIRA_USERNAME) are sandbox env vars, not gateway-managed config. Rename the field from 'config' to 'env' to make this clear. Both top-level env: and providers[].env: merge into BuildEnvMap() and are injected via --env on sandbox create. Provider env overrides top-level env on collision. The gateway only manages secrets (credentials) — non-secret vars go directly to the container.
…pdate README commands - Add status.Cmd() call for 'gws auth export --unmasked' so it shows with --show-commands - Add gws provider to builtin.yaml (was missing vs default.yaml) - Update README 'What harness up replaces' with actual captured output from --show-commands (includes gws export, inference set order, env var alphabetical order) - Add --debug flag to test-flow.sh (passes --show-commands, shows output)
Provider registration now returns errors instead of silently skipping. If you declare a provider in your agent YAML, you need it — missing credentials are a configuration error, not a graceful degradation. builtin.yaml slimmed to vertex-local only (inference). Users who need github/atlassian/gws create agents/default.yaml with the full list.
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
Comprehensive documentation audit (22-agent workflow) and update across all core MD files to reflect PRs #58-#61.
Key addition: "What harness up replaces"
New README section showing the single
harness upcommand vs the 8+ rawopenshellcommands it replaces for a 4-provider agent (github, vertex-local, atlassian, gws).Updates across files
Test plan
make test— unit tests passmake test-local— 22/22 pass🤖 Generated with Claude Code