From 0908f3ab13e689a6a7e0d5878011829a317aa69a Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 30 Jun 2026 22:30:26 +0000 Subject: [PATCH] docs(cli): resolve missing_docs CLI drift (oz agent, oz run messaging, oz provider) Demonstrates the missing_docs drift-watch loop end to end on real drift. The audit flagged 15 undocumented `oz` subcommands; this resolves all of them according to each command's GA rollout status: - GA (NamedAgents): document the `oz agent` named-agent management group (list/get/create/update/delete + `oz agent skills`) and fix the existing `oz agent list` entry, which incorrectly described skill listing. - GA (ConversationApi): document `oz run conversation get` and the `oz run message` inbox commands (list/read/watch/send/mark-delivered). - Non-GA (ProviderCommand = dogfood): defer the whole `oz provider` group via `gated:ProviderCommand` so it auto-surfaces for docs when it goes GA. All command flags drafted from crates/warp_cli source (agent.rs, task.rs, provider.rs). CLI audit now reports 0 gaps; cli_commands gated_non_ga = 14. Co-Authored-By: Oz --- .../references/feature_surface_map.md | 9 +- src/content/docs/reference/cli/index.mdx | 100 +++++++++++++++++- 2 files changed, 105 insertions(+), 4 deletions(-) diff --git a/.agents/skills/missing_docs/references/feature_surface_map.md b/.agents/skills/missing_docs/references/feature_surface_map.md index 4fd203106..b3baa644f 100644 --- a/.agents/skills/missing_docs/references/feature_surface_map.md +++ b/.agents/skills/missing_docs/references/feature_surface_map.md @@ -203,7 +203,6 @@ oz whoami -> src/content/docs/reference/cli/index.mdx oz integration -> src/content/docs/reference/cli/integration-setup.mdx oz schedule -> src/content/docs/reference/cli/index.mdx oz secret -> src/content/docs/reference/cli/index.mdx -oz provider -> src/content/docs/reference/cli/index.mdx oz federate -> src/content/docs/reference/cli/federate.mdx oz artifact -> src/content/docs/reference/cli/artifacts.mdx oz api-key -> src/content/docs/reference/cli/api-keys.mdx @@ -238,6 +237,14 @@ oz memory-store list -> gated:AIMemories oz memory-store list-store-agents -> gated:AIMemories oz memory-store update -> gated:AIMemories +# `oz provider` (link third-party services like Slack and Linear) is gated by +# ProviderCommand, which is non-GA (dogfood), so the whole command group is +# deferred via `gated:` — it auto-surfaces for docs when ProviderCommand goes +# GA. See "Public vs. private surfaces" in SKILL.md. +oz provider -> gated:ProviderCommand +oz provider setup -> gated:ProviderCommand +oz provider list -> gated:ProviderCommand + # Internal/hidden command — not a user-facing surface, so no public docs. oz harness-support -> internal diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/reference/cli/index.mdx index 9aad722de..5792ffe0e 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/reference/cli/index.mdx @@ -365,13 +365,68 @@ The `--share` flag can be repeated, and uses the following syntax: The following commands are available for managing and inspecting Oz resources. -### `oz agent list` +### Managing named agents -List all available skills discovered from your environments. Optionally filter by repository: +[Named agents](/platform/agents/) are reusable agent configurations — a name, description, skills, secrets, base model, and default environment — that you can run with `oz agent run-cloud --agent ` and scope API keys to. + +List the named agents on your team, optionally sorting by name or creation time: ```sh oz agent list -oz agent list --repo owner/repo +oz agent list --sort-by created-at --sort-order desc +``` + +Show the full configuration for a single agent by its UID: + +```sh +oz agent get +``` + +Create a named agent. Only `--name` is required; attach skills and secrets by repeating the flags: + +```sh +oz agent create \ + --name "release-notes" \ + --description "Drafts release notes from merged PRs" \ + --skill "myorg/repo:release-notes" \ + --secret GITHUB_TOKEN \ + --base-model \ + --environment +``` + +Update an existing agent. Each attribute has an explicit add/remove flag so changes are unambiguous: + +```sh +# Rename the agent and swap one of its skills +oz agent update --name "weekly-release-notes" \ + --remove-skill "myorg/repo:old" --add-skill "myorg/repo:release-notes" + +# Clear attributes entirely +oz agent update --remove-description --remove-all-secrets +``` + +Common `oz agent update` flags: + +* `--name ` (`-n`) — rename the agent. +* `--description ` / `--remove-description` — set or clear the description. +* `--add-secret ` / `--remove-secret ` / `--remove-all-secrets` — manage attached secrets. +* `--add-skill ` / `--remove-skill ` / `--remove-all-skills` — manage attached skills. +* `--base-model ` / `--remove-base-model` — set or clear the base model. +* `--environment ` (`-e`) / `--remove-environment` — set or clear the default cloud environment. + +Delete a named agent by its UID: + +```sh +oz agent delete +``` + +### `oz agent skills` + +List the agent skills discovered across your environments. Pass `--repo` (`-r`) to list skills from a specific GitHub repository instead: + +```sh +oz agent skills +oz agent skills --repo owner/repo ``` ### `oz run list` / `oz run get` @@ -387,6 +442,45 @@ oz run list --limit 20 oz run get ``` +### Run conversations and messages + +Read an agent run's transcript and exchange messages between runs — for example, between a parent orchestrator and its [child agents](/platform/orchestration/multi-agent-runs/). + +Retrieve a conversation transcript by its ID: + +```sh +oz run conversation get +``` + +List and read the messages in a run's inbox: + +```sh +# List inbox message headers +oz run message list +oz run message list --unread --since 2026-01-01T00:00:00Z --limit 100 + +# Read one message body +oz run message read + +# Stream new messages as they arrive (resume reconnects with --since-sequence) +oz run message watch +oz run message watch --since-sequence 42 +``` + +Send a message from one run to one or more recipient runs, then mark it delivered once handled: + +```sh +oz run message send \ + --sender-run-id \ + --to \ + --subject "build status" \ + --body "tests are green" + +oz run message mark-delivered +``` + +Repeat `--to` to fan a message out to multiple recipient runs. + ### `oz model list` List all available models: