--- name: setup description: Check and finish the ModelPlan Codex plugin's setup - after it is installed or upgraded, or whenever the user asks why ModelPlan quota hints or the task-start brief do not appear. Reports each part (plugin, its own CLI, hook, hints) on its own and says what to do about what is not ready. --- Codex may run this after the plugin is installed; the user can also ask for it at any time ("check ModelPlan setup"). A user's question always gets a full answer, whatever the automatic notices did before. Keep it short and in the user's language. To turn automatic hints off or on, run `sh "/hooks/automatic-hints.sh" off` or `on` only when the user requests that choice. Check with `sh "/hooks/automatic-hints.sh" status` and refresh `get_model_dashboard`. Default is **on**; the setting persists in `~/.config/modelplan/codex/automatic-hints`. Off silences all UserPromptSubmit output, including notices and the task-start brief. Explicit tools, slash commands and the panel continue to work; do not ask to re-enable hints. 1. Check, and report each part on its own line: - **Plugin**: answering if `get_model_dashboard` works; its `structuredContent.setup` has the rest. - **CLI** (`setup.cli.status`): the plugin brings its own, the release pinned in `cli-pin.json`, fetched in the background into `~/.cache/modelplan-cli` and used only if its SHA-256 matches the pinned one. `ok` (`source` plugin, or user for one the user installed), `fetching`, `failed` (with `fetchError` or `error`), `outdated` (the user's own older copy while the plugin's is missing), `missing` (`MODELPLAN_PLUGIN_CLI=off` and none installed) or `unsupported` (Windows). Without the tool: `sh "/hooks/find-cli.sh"`, then ` version`. - **Hook**: `setup.hook.lastRun` empty means Codex has not run it yet, normally because it is not trusted. - **Automatic hints**: `setup.automaticHints` is the saved on/off preference, default on. When false, say “off by choice”; this is not a setup failure. - **Hints**: when automatic hints are on, ready when the CLI is `ok` (or `outdated`) and the hook's last run computed them. - **Other plans** (optional, `setup.codexbar`): off when `enabled` is empty; otherwise each enabled provider's `status` (`ok`, or why not and `needs`). Null means the CLI is not ready or predates it. Never call a part done because a command was run; only what the check shows. 2. CLI not ready: nothing to install or agree to; installing or updating the plugin is enough. `fetching`: it lands within a minute or so, hints start with the next message after that. `failed`: say why; the dashboard's **Retry** fetches again, or run `sh "/hooks/fetch-cli.sh"`, which prints the error if it fails (`download failed`: network, proxy or GitHub; `checksum mismatch`: nothing was installed, retry later and report it if it persists). `unsupported`: point to https://github.com/modelplan/modelplan/releases for a `modelplan` on PATH. 3. Skip hook-trust troubleshooting when automatic hints are off, unless the user asks. Otherwise: hook not run (`setup.hook.lastRun` empty), its definition changed (`setup.hook.current` false), or its last run failed (`setup.hook.result` starts with `failed`, with the exit code and error; `lastSuccess` is the last good run). These records are this machine's, from any chat; plugins cannot see trust, so never say the hook is trusted, only when it last ran and how. Codex runs plugin hooks only after the user allows them. The review lists it as "UserPromptSubmit · Hook 1", source `Plugin - modelplan-codex@modelplan`, command `sh "$PLUGIN_ROOT/hooks/modelplan-quota-hints.sh"`, timeout 5 s. It reads the local quota and the cached publication and only adds context; it downloads and changes nothing (the plugin's server fetches the CLI). To allow it: in the desktop app, the hook icon with a yellow dot next to the input, source `modelplan-codex`; in the CLI, `/hooks`. It starts with the next message, and a changed definition needs allowing again. Hints arrive with a prompt only, not during a long turn. Do not change hook trust yourself. 4. Other plans through CodexBar (optional, off by default). If `setup.codexbar.enabled` is empty, mention once, in one sentence, that the dashboard can also show GitHub Copilot, Cursor, Z.ai / GLM Coding Plan, Kiro or OpenCode Go usage, and ask which of these the user has; do not push it. Before enabling, say plainly what it means: ModelPlan then runs CodexBar (an open-source, MIT-licensed CLI, https://github.com/steipete/CodexBar), fetched on first use at the release pinned in the CLI and checked against its SHA-256, into the modelplan cache (`codexbar/`; on macOS `~/Library/Caches/modelplan`); CodexBar reads each enabled vendor's own sign-in on this machine (browser cookies or the app's token for Cursor, an API key the user stores in CodexBar's config for Z.ai, Copilot and OpenCode Go, `kiro-cli login` for Kiro) and asks that vendor for the usage. ModelPlan itself never reads those credentials; it keeps only the percentages and reset times, and nothing is uploaded. Only after the user names providers and agrees, run `"" codexbar enable ` (ids: `copilot`, `cursor`, `zai`, `kiro`, `opencodego`) and show its output; `"" codexbar disable [ids…]` turns them off again. A minute later `"" codexbar` (or the dashboard) shows each provider: for one that is not `ok`, give its `needs` line as the next step, for the user to run in their own terminal (outside Codex, so no key lands in the conversation). Never type, paste or store a key or token yourself, and never open browser or Keychain data. 5. Offer the dashboard (`open_model_dashboard`); it shows the same setup lines. For a full check: `node "/doctor.cjs" --lang zh`. Never switch the model, effort or Fast, and never redeem a reset credit; those stay the user's.