#519 [docs] スラッシュコマンド・provider・排他関係・環境変数の文書を実装に合わせる

docs/guide/README.md

@@ -29,8 +29,9 @@ Recommended route / 推奨順路:
   conflicts
 - [Plan YAML editing](en/plan-yaml.md) — commented templates, offline
   validation, next commands, and recovery diffs
-- [Slash commands](en/slash-commands.md) — all 24 accepted command names,
-  inline flags, file expansion, and profile inference
+- [Slash commands](en/slash-commands.md) — all 24 accepted command names in the
+  general registry, plus the Gate 3/4 dedicated `/directive` and
+  `/confirm-directive`, inline flags, file expansion, and profile inference
 - [Configuration](en/configuration.md) — precedence, presets, paths, legacy
   files, and environment variables
 - [Providers](en/providers.md) — Ollama, LM Studio, OpenAI, and Gemini setup
@@ -55,8 +56,9 @@ walkthrough. Read the [security model](../../SECURITY.md) before enabling
 - [CLI リファレンス](ja/cli-reference.md) — 公開されている全 66 フラグ、既定値、排他関係
 - [Plan YAML の編集](ja/plan-yaml.md) — コメント付き template、offline 検証、次コマンド、
   recovery 差分
-- [スラッシュコマンド](ja/slash-commands.md) — 受け付ける全 24 コマンド名、インラインフラグ、
-  ファイル展開、プロファイル推論
+- [スラッシュコマンド](ja/slash-commands.md) — 一般レジストリで受け付ける全 24 コマンド名と
+  Gate 3/4 専用の `/directive`・`/confirm-directive`、インラインフラグ、ファイル展開、
+  プロファイル推論
 - [設定](ja/configuration.md) — 優先順位、preset、探索パス、旧形式ファイル、環境変数
 - [プロバイダ](ja/providers.md) — Ollama、LM Studio、OpenAI、Gemini のセットアップ
 - [トラブルシューティング](ja/troubleshooting.md) — 起動時、プロバイダ、TUI の一般的な問題

docs/guide/en/cli-reference.md

@@ -10,15 +10,17 @@ authority: use `commandagent --help` when its version differs from this checkout
 ## Invocation
 
 Use one of the action-selector flags for a direct command, or omit all of them
-for the TUI. The action selectors are `--prompt`, `--plan-steps`, `--plan-run`,
-`--run-plan`, `--ultra-plan`, `--ultra-plan-run`, `--run-ultra-plan`,
-`--validate-plan`, `--setup-interaction-probe`, `--runs`, `--ux-demo`, `--model-probe`,
-`--doctor`, and `--extensions`. The offline pack actions `--packs`, `--pack-verify`, and
-`--pack-pin`, generated-artifact actions `--completions` and `--generate-man`,
-config action `--init-config`, and delegated manifest actions
-`--validate-manifest` and `--init-profile` are displayed in the same
-`Actions (use one)` help group. CommandAgent rejects combinations whose action
-contracts are mutually exclusive.
+for the TUI. The action selectors are `--workflow`, `--prompt`, `--plan-steps`,
+`--plan-run`, `--run-plan`, `--ultra-plan`, `--ultra-plan-run`,
+`--run-ultra-plan`, `--validate-plan`, `--setup-interaction-probe`, `--runs`,
+`--ux-demo`, `--model-probe`, `--doctor`, and `--extensions`. The offline pack
+actions `--packs`, `--pack-verify`, and `--pack-pin`, generated-artifact actions
+`--completions` and `--generate-man`, config action `--init-config`, and
+delegated manifest actions `--validate-manifest` and `--init-profile` are
+displayed in the same `Actions (use one)` help group. CommandAgent rejects
+combinations whose action contracts are mutually exclusive, either in Clap
+before parsing finishes or in the resolved configuration after parsing; see
+[Conflicts and combinations](#conflicts-and-combinations).
 
 Clap also generates `-h`/`--help` and `-V`/`--version`. They are not part of the
 66 application flags below. The hidden `--completion-contract-json <PATH>` is an
@@ -112,6 +114,14 @@ least eight hexadecimal digits, such as `/confirm sha256:77cd5e23`. Set
 full hash. Prefixes are expanded to the frozen full hash before confirmation is
 persisted.
 
+`/provider` switches only among the four built-in providers `ollama`,
+`lm-studio`, `openai`, and `gemini`. The generic `openai-compatible` provider,
+including its base URL and key variable, is configured before startup with
+`--provider`, `--base-url`, and `--api-key-env`, or a preset; change it there
+and restart CommandAgent instead of using `/provider`. When the executor
+provider is OpenAI, `/model <id>` and a `/provider openai` switch reject the
+ambiguous `gpt-5.6` alias with the same check the CLI applies at startup.
+
 REPL history is isolated beneath `--state-dir` at
 `workspace-history/<sha256-of-canonical-workspace>.txt`. Only the active
 workspace file is loaded, and history hints require two entered characters and
@@ -143,27 +153,45 @@ See [Configuration](configuration.md) for the exact per-field layers.
 - `--allow` accepts `read`, `write`, and `bash:verify` as repeated or
   comma-separated values. Once supplied, omitted tool classes are blocked;
   `--yes` is the backward-compatible all-tools alias.
-- Only one action selector may be used. This is checked after parsing and fails
-  with `only one action selector can be used at a time`.
+- Clap rejects some combinations while parsing: `--workflow` conflicts with
+  `--intent`; `--origin` requires `--workflow`; the `--doctor`/`--extensions`/
+  `--runs` JSON group and the pack direct-action group accept only one member
+  each. For example, `--doctor --runs` is a Clap-level conflict.
+- After parsing, the resolved configuration accepts exactly one action selector
+  and fails with `only one action selector can be used at a time`. For example,
+  `--prompt x --ux-demo` reaches that check because each flag is a valid
+  selector on its own. `--workflow` without `--origin` also fails here, with
+  `--workflow requires --origin`.
 - `--completions` and `--generate-man` are Clap-level conflicts with every other
   action selector and with a trailing goal, so a combined invocation is rejected
   before generation begins.
 - Pre-run argument and configuration rejections exit `2` before a run starts and
   produce no run summary; see [headless execution](../../user/headless.md).
+  `--doctor` is the exception: it follows its diagnostic path, records the
+  failed Configuration check in its report (including JSON), and exits `1`
+  instead of `2`. For example, `--ux-demo --doctor --json` exits `1` with the
+  JSON report rather than the usual exit `2`.
 - `--packs`, `--pack-verify`, and `--pack-pin` are Clap-level direct actions.
   They conflict with one another, run action selectors, `--pack`, and
   `--pack-hash`. Listing allows `--extension-root`, while verify and pin take
   their target directory directly.
 - `--extensions` is read-only and accepts `--extension-root`; when omitted,
-  it resolves the top-level `extension_root` setting. `--json` is accepted
-  with either `--extensions` or `--doctor`.
+  it resolves the top-level `extension_root` setting. `--json` applies to
+  `--doctor`, `--extensions`, and `--runs`; using `--json` without one of those
+  targets is rejected.
 - `--plan-steps`, `--plan-run`, `--ultra-plan`, and `--ultra-plan-run` require a
   trailing goal.
 - `--validate-plan` is an offline, read-only action and conflicts with every
   execution or generated-artifact action. It accepts step-plan, UltraPlan, and
   recovery UltraPlan YAML; see [Plan YAML editing](plan-yaml.md).
 - A different `--planner-provider` requires an explicit or preset
   `planner_model`; otherwise startup fails.
+- A role that resolves to the generic provider needs its base URL: pass
+  `--base-url` or set preset `base_url` when the executor, planner, or
+  classifier is `openai-compatible`, including a preset that sets only the
+  classifier to the generic provider. With no `openai-compatible` role,
+  `--base-url` and `--api-key-env` are rejected by the resolved configuration.
+  These are not Clap `requires` relationships.
 - `--think` requires at least one resolved provider role to use Ollama. When
   both roles use another provider, startup fails instead of ignoring the flag.
 - For direct minimal-loop prompts, `--fresh-session` takes precedence over

docs/guide/en/configuration.md

@@ -259,12 +259,22 @@ variables also affect normal user-visible behavior:
 | `XDG_STATE_HOME` | Changes the base used by the default state directory. |
 | `HOME` | Supplies user config paths and the fallback state-directory home. |
 | `LC_ALL`, then `LANG` | Determines whether the spinner uses UTF-8 frames. |
+| `COMMANDAGENT_STEP_WALL_CLOCK_CAP_MS` / `ANVIL_STEP_WALL_CLOCK_CAP_MS` | Sets the operational per-step wall-clock cap in milliseconds. A `RunSessionOptions` value takes precedence over the environment. The value is trimmed and parsed as a `u64`; an unset or unparsable value uses the 15-minute default, and `0` is accepted by the parser. |
+| `COMMANDAGENT_PACK_DIRECTORY` | Internal handoff for the selected pack directory. Configure it with `--pack` or a preset instead of setting it by hand. |
+| `COMMANDAGENT_PACK_ID` | Internal handoff for the selected pack ID. Configure it with `--pack` or a preset instead of setting it by hand. |
+| `COMMANDAGENT_PACK_VERSION` | Internal handoff for the selected pack version. Configure it with `--pack` or a preset instead of setting it by hand. |
+| `COMMANDAGENT_PACK_HASH` | Internal handoff for the selected pack exact-byte hash. Configure it with `--pack` or a preset instead of setting it by hand. |
+| `COMMANDAGENT_UX_DEMO_FAST` / `ANVIL_UX_DEMO_FAST` | Speeds up the `--ux-demo` presentation waits for development and demos. The variable's presence, not its value, is tested. |
 
 For `COMMANDAGENT_*` entries, the current name wins. The matching `ANVIL_*`
 name is used only when the current name is absent, and emits a one-time
 deprecation warning. The legacy names in the table are nevertheless the exact
 currently supported spellings.
 
+The four `COMMANDAGENT_PACK_*` names are the exception: they are read directly
+and have no `ANVIL_*` legacy name. They are an internal handoff for the selected
+pack, not a user-configured setting; use `--pack` or a preset to select a pack.
+
 ## Inspect the effective configuration
 
 Start the TUI and run `/status`. The startup banner and status card show key

docs/guide/en/providers.md

@@ -108,6 +108,13 @@ snapshot-qualified ID when repeatable comparisons matter. CommandAgent records
 the requested and returned model IDs plus `system_fingerprint` in the provider
 turn event so endpoint drift can be audited without exposing credentials.
 
+The `gpt-5.6` alias rejection applies to every role that uses the built-in
+OpenAI provider: executor, planner, and classifier. It is a check on the
+built-in OpenAI provider only and is not applied to the generic
+`openai-compatible` transport, which forwards the model ID unchanged. In the
+REPL, `/model <id>` and a `/provider openai` switch run the executor check again
+before the new selection is applied.
+
 OpenAI Chat Completions reasoning effort is opt-in. Set
 `COMMANDAGENT_OPENAI_REASONING_EFFORT` in the process environment only when an
 explicit effort value is required. If it is unset or empty, CommandAgent omits
@@ -180,6 +187,12 @@ LM Studio uses this same transport with its existing `lm-studio`,
 `--lm-studio-host`, and `LM_STUDIO_API_TOKEN` names. Those settings remain
 backward compatible and are not automatically rewritten to the generic form.
 
+The interactive `/provider` command accepts only `ollama`, `lm-studio`,
+`openai`, and `gemini`, so it cannot select this generic provider. Configure it
+for a role with `--provider`, `--base-url`, and `--api-key-env`, or a preset,
+and restart CommandAgent to change it. Whenever the executor, planner, or
+classifier resolves to `openai-compatible`, its base URL is required.
+
 ## Ollama host and models
 
 Ollama requires a running HTTP server and a locally available model. Local API

docs/guide/en/slash-commands.md

@@ -8,16 +8,18 @@ source of truth for the installed binary.
 
 ## Command reference
 
-The registry contains 23 primary entries. `/quit` is a separately accepted
-command name and an alias of `/exit`, giving 24 accepted names in total.
+The general command registry contains 23 primary entries. `/quit` is a separately
+accepted command name and an alias of `/exit`, giving 24 accepted names in total.
+Two more names, `/directive` and `/confirm-directive`, are handled outside this
+registry; see the Gate 3/4 dedicated commands section below.
 
 | Command name | Usage shown by `/help` | Behavior |
 | --- | --- | --- |
 | `/help` | `/help [command]` | Show grouped commands, or detailed usage and an example for one command. |
 | `/confirm` | `/confirm <hash>` | Persist the reviewed Gate 1 card and immediately execute its request. A matching `sha256:` prefix needs at least eight hexadecimal digits unless strict confirmation is enabled. |
 | `/status` | `/status` | Show current execution first, followed by effective session configuration and readiness. |
-| `/model` | `/model <id>` | Set the executor model used by new Gate 1 cards in this REPL session. |
-| `/provider` | `/provider <name>` | Set the executor provider used by new Gate 1 cards in this REPL session. |
+| `/model` | `/model <id>` | Set the executor model used by new Gate 1 cards in this REPL session. An OpenAI model ID is validated with the same policy as startup. |
+| `/provider` | `/provider <name>` | Set the executor provider used by new Gate 1 cards in this REPL session. Accepts only `ollama`, `lm-studio`, `openai`, and `gemini`; the generic `openai-compatible` provider is not selectable here. |
 | `/profile` | `/profile <name>` | Set the explicit profile used by new Gate 1 cards in this REPL session. |
 | `/clear` | `/clear` | Clear the terminal screen without discarding the most recent result. |
 | `/last` | `/last` | Render the most recent REPL result again. |
@@ -51,6 +53,29 @@ The full hash is always accepted. By default, a canonical `sha256:` prefix of
 latest pending Gate 1 card. `COMMANDAGENT_STRICT_CONFIRM=1` restores full-hash
 matching. The full frozen hash, never the prefix, is persisted and emitted.
 
+`/provider` switches only among the four built-in providers (`ollama`,
+`lm-studio`, `openai`, and `gemini`). The generic `openai-compatible` provider
+—including its base URL and key variable—is configured before startup with the
+`--provider`, `--base-url`, and `--api-key-env` flags or a preset. To change it,
+adjust the configuration and restart CommandAgent rather than using `/provider`.
+
+## Gate 3/4 dedicated commands
+
+`/directive` and `/confirm-directive` are handled outside the general command
+registry. `/help`, `/help <command>`, and the command table above therefore do
+not list them. They are available only after a confirmed terminal run reaches
+Gate 3 or Gate 4; at any other time the REPL refuses them.
+
+- `/directive <instruction>` proposes a bounded human directive for the current
+  Gate 3 or Gate 4 terminal run. The REPL prints the proposal with its directive
+  hash and instructs you to confirm it.
+- `/confirm-directive <hash>` confirms a pending directive by its exact,
+  complete hash and prepares the continuation.
+
+The exact displayed directive hash is required. The Gate 1 `sha256:` prefix
+matching described above does not apply to directives, and a directive is not
+dispatched before this confirmation.
+
 ## Inline flags
 
 Slash input recognizes these overrides before it joins the remaining words into

docs/guide/en/troubleshooting.md

@@ -94,10 +94,15 @@ terminal can clear a scroll region left by the terminal emulator.
 ## Model ID does not exist
 
 CommandAgent normally passes model IDs to the selected provider without a
-cross-provider catalog. The one guarded alias is OpenAI executor ID `gpt-5.6`,
-which is rejected before dispatch; use exact `gpt-5.6-luna` or an available
-snapshot-qualified Luna/Sol ID. Other nonexistent, unavailable, or unauthorized
-models fail at provider-call time.
+cross-provider catalog. The one guarded alias is the built-in OpenAI model ID
+`gpt-5.6`, which is rejected before dispatch for every OpenAI role — executor,
+planner, and classifier. Use an exact `gpt-5.6-luna`, `gpt-5.6-terra`, or
+`gpt-5.6-sol` ID, or an available snapshot-qualified Luna/Sol ID. This check
+applies only to the built-in OpenAI provider, not to the generic
+`openai-compatible` transport, which forwards the model ID unchanged. In the
+REPL, `/model <id>` and a `/provider openai` switch repeat the executor check.
+Other nonexistent, unavailable, or unauthorized models fail at provider-call
+time.
 
 ### What the failure looks like