@hagicode/cli 0.1.0-dev.39.1.c7a4f44 → 0.1.0-dev.42.1.b13f8d2

package/dist/cli.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("./chunks/main-DZ0mAAOh.js");s.runCli().then(e=>{e!==0&&(process.exitCode=e)}).catch(e=>{const n=e instanceof Error?e.stack??e.message:String(e);process.stderr.write(`${n}
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("./chunks/main-CGAPe6tb.js");s.runCli().then(e=>{e!==0&&(process.exitCode=e)}).catch(e=>{const n=e instanceof Error?e.stack??e.message:String(e);process.stderr.write(`${n}
 `),process.exitCode=s.EXIT_CODES.UNKNOWN});

package/dist/main.js

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./chunks/main-DZ0mAAOh.js");exports.createCliApp=e.createCliApp;exports.runCli=e.runCli;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./chunks/main-CGAPe6tb.js");exports.createCliApp=e.createCliApp;exports.runCli=e.runCli;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hagicode/cli",
-  "version": "0.1.0-dev.39.1.c7a4f44",
+  "version": "0.1.0-dev.42.1.b13f8d2",
   "description": "HagiCode CLI for project, proposal, vault, chat, and AutoTask management.",
   "homepage": "https://github.com/HagiCode-org/cli#readme",
   "bugs": {
@@ -16,7 +16,8 @@
   "main": "./dist/main.js",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skills"
   ],
   "packageManager": "pnpm@12.16.1",
   "engines": {

package/skills/README.md

@@ -0,0 +1,51 @@
+# Embedded Skills
+
+`repos/cli/skills/` is the repository-level discovery entrypoint for Hagi CLI skills.
+Use this directory when you need the canonical agent-facing contract for the published `@hagicode/cli` package and the installed `hagi` command.
+
+## Package-first usage
+
+Treat the published package as the default execution path:
+
+```bash
+npx @hagicode/cli --help
+npx @hagicode/cli proposal list --json
+```
+
+If `@hagicode/cli` is already installed, the same contract is available through:
+
+```bash
+hagi --help
+```
+
+Repository-local commands under `repos/cli` are maintainer workflows only.
+
+## Available skill packages
+
+- [`hagi/SKILL.md`](hagi/SKILL.md) - canonical Hagi CLI skill entrypoint
+- [`hagi/agents/openai.yaml`](hagi/agents/openai.yaml) - agent display and invocation metadata
+- [`hagi/references/cli-usage.md`](hagi/references/cli-usage.md) - published package usage and runtime flags
+- [`hagi/references/session-data.md`](hagi/references/session-data.md) - inside a HagiCode session: read-only data commands and the actions that need an explicit request
+- [`hagi/references/proposal-flow.md`](hagi/references/proposal-flow.md) - explicit proposal lifecycle guidance
+- [`hagi/references/openspec-workflow.md`](hagi/references/openspec-workflow.md) - the OpenSpec stage each proposal command starts and how to follow a run
+- [`hagi/references/super-commit.md`](hagi/references/super-commit.md) - Super Commit through the CLI: prompt-id start, options, result and explicit-request rule
+- [`hagi/references/local-development.md`](hagi/references/local-development.md) - maintainer-only source-tree workflows
+- [`hagi/references/validation.md`](hagi/references/validation.md) - post-change validation steps
+
+## Canonical writable source
+
+Update `repos/cli/skills/**` when the Hagi CLI skill contract changes.
+
+## Built-in copy
+
+The server also ships this folder as its built-in skill `hagi`. The copy lives in `repos/built-in-skills/content/hagi/` and is an exact byte copy of `repos/cli/skills/hagi/`. Edit this folder, then recopy and rehash the built-in copy.
+
+## Skill installation and discovery
+
+If an agent runtime or skill loader needs the Hagi skill source, point it at `repos/cli/skills/hagi/`.
+Start discovery from this README, then open `repos/cli/skills/hagi/SKILL.md`.
+
+## Maintainer note
+
+When you are editing the CLI itself, use the maintainer-only workflows in `hagi/references/local-development.md`.
+For normal usage and automation, stay package-first.

package/skills/hagi/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: hagi
+description: Use when the user wants to run, verify, or update the HagiCode CLI against the Hagi API, or asks about their own projects, proposals, chat sessions, vaults, scheduled plans, or installed skills, including user skills versus built-in skills, and enabling or disabling a built-in skill. Also covers the OpenSpec workflow behind proposal commands and Super Commit, which commits a code repository through a HagiTask session. Keep package-first command guidance primary, then follow the proposal flow, local development, and validation references as needed. Inside a HagiCode session, read the session-data reference first for questions about the user's own data.
+---
+
+# Hagi
+
+Use this skill when the user asks to:
+
+- answer questions about their own projects, proposals, chat sessions, vaults, scheduled plans, or installed skills
+- list which installed skills are user skills and which are built-in skills, or which built-in skills are enabled
+- enable or disable a built-in skill
+- run or verify the `hagi` CLI
+- explain or execute `project`, `proposal`, `chat`, `hagitask`, `vault`, `plan`, or `skills` commands
+- explain the OpenSpec workflow behind `proposal` commands, which stage each command starts, or how to follow a run until it settles
+- run, explain or check a Super Commit, which commits the uncommitted changes of a code repository through a HagiTask session
+- inspect CLI flags, environment variables, exit codes, or JSON automation behavior
+- validate proposal-session flows against a backend API
+- modify or debug the CLI implementation in `repos/cli`
+
+## Core rules
+
+- Prefer `npx @hagicode/cli ...` for normal usage and package-level verification.
+- Use `hagi ...` only when `@hagicode/cli` is already installed and on `PATH`.
+- Run repository-local install, build, and test commands with the working directory set to `repos/cli`.
+- Never run `pnpm install`, `pnpm run`, or other build commands at the monorepo root.
+- Prioritize API invocation guidance over codebase tours unless the user explicitly wants implementation work.
+- Built-in skills can be enabled or disabled with `hagi skills local enable --skill-name <name>` and `hagi skills local disable --skill-name <name>`. They cannot be uninstalled or updated through the CLI. A change applies to agent runs that start afterwards; a run already in progress keeps the skills it started with.
+- Every proposal names its writable repositories and its read-only repositories, in a `Repository scope` section at the start of `--chief-complaint`. Both lists are always present, and an empty list is written as `none`. Take the paths from `hagi project repositories --id <project-id> --json`. When neither the user's request nor the session gives the scope, ask the user and offer those repositories as the choices; never guess a scope or widen the writable list. Details: [`references/proposal-flow.md`](references/proposal-flow.md#repository-scope).
+
+## Choose the workflow
+
+1. Published package usage -> read [`references/cli-usage.md`](references/cli-usage.md)
+2. Explicit proposal lifecycle work -> read [`references/proposal-flow.md`](references/proposal-flow.md)
+3. Which OpenSpec stage a proposal command starts, or following a run to its end -> read [`references/openspec-workflow.md`](references/openspec-workflow.md)
+4. Super Commit, committing a code repository through a HagiTask session -> read [`references/super-commit.md`](references/super-commit.md)
+5. Source-tree development in `repos/cli` -> read [`references/local-development.md`](references/local-development.md)
+6. Post-change validation -> read [`references/validation.md`](references/validation.md)
+7. The user's own data, inside a HagiCode session -> read [`references/session-data.md`](references/session-data.md)
+
+When `hagi` is loaded as a built-in skill inside a HagiCode session, read item 7 first for any question about the user's own data or skills, before the other references.
+
+## Runtime configuration
+
+Shared runtime flags:
+
+- `--base-url <url>`
+- `--token <token>`
+- `--lang <lang>`
+- `--json`
+
+Equivalent environment variables:
+
+- `HAGI_API_BASE_URL`
+- `HAGI_API_TOKEN`
+- `HAGI_API_LANG`
+
+A base URL can also come from `"baseUrl"` in `$XDG_CONFIG_HOME/hagi/config.json`, or `~/.config/hagi/config.json` when `XDG_CONFIG_HOME` is unset.
+
+Precedence: flag, then `HAGI_API_BASE_URL`, then the config file. The base URL has no default. When none of the three is set, the CLI exits with code `2`.
+
+Inside a HagiCode session, the server can add four runtime variables to an agent run. They are present only while the built-in `hagi` skill is installed and enabled, and only on Claude Code, Pi, OpenCode, GitHub Copilot and omp:
+
+| Variable | Carries |
+| --- | --- |
+| `HAGI_API_BASE_URL` | Address of the backend that started the session |
+| `HAGI_VERSION` | Version of the HagiCode server |
+| `HAGI_DEPLOYMENT_TYPE` | Deployment type of the server |
+| `HAGI_API_LANG` | Effective AI language: `zh-CN` or `en-US`, sent as `Accept-Language` |
+
+A variable the server cannot determine is left out, and the run still starts. Report an absent variable as absent; do not guess a value. Conditions and the rest of the session rules are in [`references/session-data.md`](references/session-data.md).
+
+## Command surface
+
+The current top-level command families are:
+
+- `project`
+- `proposal`
+- `vault`
+- `chat`
+- `hagitask`
+- `plan`
+- `skills`
+
+`project repositories --id <project-id>` is read-only. It lists one project's repositories with each path relative to the project root (for example `repos/cli`). Those paths are the values a proposal's `Repository scope` names; see [`references/proposal-flow.md`](references/proposal-flow.md#repository-scope).
+
+Scheduled plans (`hagi plan`) save a proposal or HagiTask input with a schedule. `list`, `get`, `create`, `update`, `enable`, `disable`, `delete` and `run` manage them; `run --background` returns the accepted plan id before the session exists. A manual run never changes a plan's state or next run time. See [`references/cli-usage.md`](references/cli-usage.md#plan-commands) for the action list and a plan document example.
+
+HagiTask sessions (`hagi hagitask`) run a preset task with a structured input. `list` shows the active tasks, `schema --task-id <id>` shows one task's scope, commands, parameters and required marks, and `create --task-id <id> --input <file>` creates the session. Read the schema first, write the input from it, then create. `send` posts a follow-up message; `--steer` (or `HAGI_SEND_STEER=1`) inserts it into a running turn instead, and `queued` means no running task took it. The backend rejects any input key the schema does not list. See [`references/cli-usage.md`](references/cli-usage.md#hagitask-commands) for the flow and an input example, and [`references/cli-usage.md`](references/cli-usage.md#steer-for-send-commands) for the Steer options.
+
+Each family also reads one session by id. `proposal get` and `hagitask get` read a session; with `--wait` they poll until its status settles, so a run can be followed without guessing. `proposal messages` and `hagitask messages` read a session's messages, and `--last 1` reads the final message of a run. The stage behind each proposal command is in [`references/openspec-workflow.md`](references/openspec-workflow.md). Super Commit is started with `hagitask create --prompt-id auto-compose-commit.<locale>`; see [`references/super-commit.md`](references/super-commit.md).
+
+## Source of truth
+
+- Canonical writable skill source: `repos/cli/skills/hagi/`
+- The server ships a byte-for-byte copy of this folder as its built-in skill `hagi`; edit here, never in the copy
+
+## References
+
+- [`references/cli-usage.md`](references/cli-usage.md) - package-first installation, quick start, runtime flags, and exit codes
+- [`references/session-data.md`](references/session-data.md) - inside a HagiCode session: read-only data commands, state-changing actions that need an explicit request, and failure handling
+- [`references/proposal-flow.md`](references/proposal-flow.md) - explicit proposal lifecycle sequence and command examples
+- [`references/openspec-workflow.md`](references/openspec-workflow.md) - the OpenSpec stage each proposal command starts, stage boundaries, who drives each step, and the monitoring rule
+- [`references/super-commit.md`](references/super-commit.md) - Super Commit: starting it by prompt id, its options, result reading and the explicit-request rule
+- [`references/local-development.md`](references/local-development.md) - maintainer-only development, build, and repository internals
+- [`references/validation.md`](references/validation.md) - targeted verification after documentation or code changes

package/skills/hagi/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Hagi CLI"
+  short_description: "Answer questions about your HagiCode data and skills, operate the hagi CLI, follow the OpenSpec workflow, and run a Super Commit."
+  default_prompt: "Use $hagi to look up your projects, proposals, sessions, vaults, plans, or skills, to follow the OpenSpec workflow of a proposal, to run a Super Commit, to enable or disable a built-in skill, or to inspect, run, or update the HagiCode CLI in repos/cli."
+
+policy:
+  allow_implicit_invocation: true

package/skills/hagi/references/cli-usage.md

@@ -0,0 +1,300 @@
+# CLI Usage
+
+Use the published package contract first.
+The repository exists to build and maintain `@hagicode/cli`, but normal command execution should start from the package surface rather than the source tree.
+
+## Installation paths
+
+### Zero-install
+
+```bash
+npx @hagicode/cli --help
+npx @hagicode/cli project list --json
+```
+
+### Project-local install
+
+```bash
+npm install @hagicode/cli
+npx @hagicode/cli proposal list --json
+```
+
+### Optional global install
+
+```bash
+npm install -g @hagicode/cli
+hagi --help
+```
+
+## Quick start
+
+When `@hagicode/cli` is already available on `PATH`, these examples work as `hagi ...`.
+For one-off execution, replace `hagi` with `npx @hagicode/cli`.
+
+```bash
+hagi --help
+hagi project list --json
+hagi proposal list --json
+hagi chat list --json
+hagi hagitask list --json
+hagi hagitask create --title "Auto commit" --project-id <project-id> --prompt-id auto-compose-commit.en-US
+```
+
+## Shared runtime flags
+
+Every command family supports the same runtime flags:
+
+- `--base-url <url>`
+- `--token <token>`
+- `--lang <lang>`
+- `--json`
+
+Example:
+
+```bash
+hagi --base-url https://api.example.com --token "$HAGI_TOKEN" project list --json
+```
+
+## Environment variables
+
+The CLI resolves runtime settings centrally before every command.
+Explicit flags always override environment variables.
+
+| Variable | Purpose |
+| --- | --- |
+| `HAGI_API_BASE_URL` | Backend base URL, used when `--base-url` is not given. Overrides the config file. |
+| `HAGI_API_TOKEN` | Bearer token attached as `Authorization: Bearer <token>`. |
+| `HAGI_API_LANG` | Shared `Accept-Language` header value. |
+| `HAGI_SEND_STEER` | Turns Steer on (`1`, `true`, `yes`, `on`) or off (`0`, `false`, `no`, `off`) for `chat`, `proposal` and `hagitask send`. Any other value exits with code `2`. See [Steer for send commands](#steer-for-send-commands). |
+
+## Config file
+
+The base URL can also be stored in a local config file:
+
+```json
+{ "baseUrl": "https://api.example.com", "steer": false }
+```
+
+The file is `$XDG_CONFIG_HOME/hagi/config.json`, or `~/.config/hagi/config.json` when `XDG_CONFIG_HOME` is unset. The `steer` key must be `true` or `false`; any other value exits with code `2` and names the file.
+
+Base URL precedence, highest first: `--base-url`, then `HAGI_API_BASE_URL`, then `baseUrl` in the config file.
+There is no default. When none of the three is set, the CLI exits with code `2` and names all three sources.
+
+## Command overview
+
+```text
+hagi
+|-- project   list | repositories | create | update | delete
+|   `-- monospecs show | init | set | validate | reload | clone | remove-checkout
+|-- proposal  list | create | optimize-description | generate | annotate | execute | archive | status | complete | send | get | messages
+|-- vault     list | create | update | delete
+|   `-- files list | preview
+|-- chat      list | create | archive | delete | send
+|-- hagitask  list | schema | create | send | get | messages
+|-- plan      list | get | create | update | enable | disable | delete | run
+`-- skills    local list | enable | disable | uninstall
+              gallery search | detail | install
+              trusted list | upsert | delete | reset
+```
+
+## Project repositories
+
+`project repositories --id <project-id>` is read-only. It reads the same aggregation snapshot as `project list` and prints one project's repositories: name, path relative to the project root (for example `repos/cli`), display name, type and branch, with the project's MonoSpecs flag. The `path` values are the ones a proposal's `Repository scope` names.
+
+```bash
+npx @hagicode/cli project repositories --id <project-id> --json
+```
+
+An unknown project id exits with code `24` and prints no list.
+
+## MonoSpecs commands
+
+`project monospecs` manages a project's MonoSpecs configuration (`monospecs.yaml`) and the local checkouts of its repositories. The CLI only sends requests; the backend reads and writes files and runs Git on its own host.
+
+- `show --id <id>` prints the document: version, repo directory, config path, commit-when-archive, and one row per repository with its local Git state. A repository that is not a valid Git checkout is marked `missing or not a Git repository`. `--yaml` adds the YAML preview; `--json` emits the same fields plus `code` and `metadata`.
+- `init --id <id>` initializes the configuration; an already initialized project returns its document.
+- `set --id <id>` changes the document. Options: `--version`, `--repo-directory`, `--commit-when-archive <true|false>`, repeatable `--add-repository <path>` and `--remove-repository <path>`, `--clone`. `--url`, `--name`, `--display-name` and `--type` require exactly one `--add-repository`. `--clone` needs at least one addition. The CLI reads the document, applies the change and saves the complete document; it strips local Git state fields before saving. Duplicate additions and unknown removals fail before any save.
+- `validate --id <id>` validates the configuration. It exits `30` when the backend reports it invalid, after printing every error.
+- `reload --id <id>` rereads `monospecs.yaml` on the backend host and refreshes Git state.
+- `clone --id <id>` clones missing repositories. Repeat `--path <path>` to select some; `--include-optional` adds optional repositories when no `--path` is given. Every result row is printed; any `failed` row exits `30`.
+- `remove-checkout --id <id> --path <path>` deletes one configured repository's local checkout. Dirty, unpushed or no-upstream checkouts are refused (exit `29`); the hint suggests `--force` when the refusal can be overridden. The configuration file is not changed.
+
+Only configured repositories can be cloned or removed, and the backend confines paths to the project root. Exit codes: `2` usage (no request sent), `20` backend validation with field errors, `24` project not found, `29` conflict, `30` invalid configuration or failed clone.
+
+```bash
+hagi project monospecs show --id <project-id> --json
+hagi project monospecs set --id <project-id> --add-repository repos/api --url <git-url> --clone
+hagi project monospecs remove-checkout --id <project-id> --path repos/api --force
+```
+
+## Proposal commands
+
+`proposal get` reads one proposal session. With `--wait` it polls until the status settles, so a stage can be followed without guessing. `proposal messages` reads its messages, newest first.
+
+```bash
+hagi proposal get --session-id <session-id> --wait --timeout 900 --json
+hagi proposal messages --session-id <session-id> --last 1 --json
+```
+
+- `--wait` settles on any status other than Optimizing, Openspecing, Executing or Archiving. WaitingForReply counts as settled, because a person must answer.
+- `--timeout`, `--interval` and `--grace` are seconds and need `--wait`. `--interval` must be less than `--timeout`. A timeout exits `31`.
+- Which stage each command starts, and how to follow a run, is in [openspec-workflow.md](openspec-workflow.md).
+
+## Session metadata
+
+`chat create` and `proposal create` take write-once metadata entries. An orchestrator marks the sessions it starts with them, for example a master marker and worker markers, and finds them again through `userMetadata`.
+
+```bash
+hagi chat create --title "Master" --project-id <project-id> --metadata role=master --metadata batch=2026-11-07 --json
+hagi chat create --title "Worker 1" --project-id <project-id> --metadata role=worker --metadata master=<master-session-id> --json
+printf '{"role":"worker","master":"<master-session-id>"}' | hagi chat create --title "Worker 2" --project-id <project-id> --metadata-json - --json
+hagi proposal create --project-id <project-id> --chief-complaint "<text>" --default-title --metadata role=worker --metadata master=<master-session-id> --json
+```
+
+- `--metadata key=value` is repeatable. The text is split at the first `=`, so a value may contain `=`.
+- `--metadata-json <file|->` reads a JSON object of string values from a file, or from stdin with `-`. It is repeatable.
+- A key may appear once across both options. A missing `=`, an empty key, a repeated key, or JSON that is not an object of string values exits `2` before any request is sent.
+- Backend limits: at most 16 entries; a key of 1 to 64 characters matching `^[a-z][a-z0-9._-]{0,63}$`; a value of 1 to 512 characters with no control characters. The backend's message is printed as it is, and the session is not created.
+- Write-once: the entries are set at creation and cannot be changed later. Do not put secrets in them: every reader of the session can see them.
+- Output: `--json` of `chat create`, `chat list`, `proposal create` and `proposal get` carries `userMetadata` (an object of string values) when the session has entries. The human output adds one `userMetadata` line, keys sorted. A session without entries has no `userMetadata` field.
+
+## HagiTask commands
+
+A HagiTask is a preset task with a structured input. Use the schema-first flow: list the tasks, read one task's schema, write the input file from the schema, then create the session.
+
+```bash
+hagi hagitask list --json
+hagi hagitask schema --task-id <task-id>
+hagi hagitask schema --task-id <task-id> --json
+hagi hagitask create --title "<title>" --project-id <project-id> --task-id <task-id> --input input.json --json
+hagi hagitask get --session-id <session-id> --wait --json
+hagi hagitask messages --session-id <session-id> --last 1 --json
+hagi hagitask send --session-id <session-id> --content "Retry with a smaller diff"
+```
+
+`hagi hagitask get` and `hagi hagitask messages` take the same options as the proposal commands above.
+
+Super Commit is a prompt, not a preset task, so it has no schema and takes no `--input`. Start it with a prompt id:
+
+```bash
+hagi hagitask create --title "Commit the CLI changes" --project-id <project-id> --prompt-id auto-compose-commit.en-US --json
+```
+
+Start one only when the user asked for it. See [super-commit.md](super-commit.md) for its options, its result and when to start it.
+
+- `schema` (human view) lists the target scope, commands and parameters, with each required parameter marked `yes`, then the requirements, scenes, endpoint and an example command. `--json` adds the input JSON Schema and the example request body.
+- `create` needs `--title`, `--project-id`, and either `--task-id` or `--prompt-id`. `--input <file|->` needs `--task-id`. The input must be a JSON object. The CLI does not check its keys; the backend does, and it rejects a key that the schema does not list and a missing required value. A rejection is printed unchanged and no session is reported.
+- `create --json` prints `{ session, presetTaskId, promptId, requested }`. Read the session id from `session.sessionId`.
+
+Example `input.json` for a task with one required input:
+
+```json
+{
+  "inputs": {
+    "commitScope": "cli"
+  }
+}
+```
+
+Migration: `hagi hagitask create` and `hagi hagitask send` replace the former `autotask` commands. There is no alias, so `hagi autotask` fails as an unknown command.
+
+## Steer for send commands
+
+`hagi chat send`, `hagi proposal send` and `hagi hagitask send` have two delivery modes. A normal send waits behind the running turn, as before. A Steer inserts the text into the running turn through one `SteerSession` call. Steer is off by default.
+
+Options: `--steer` requests Steer for one call; `--no-steer` forces a normal send for one call. Without either flag, the first set source decides: `HAGI_SEND_STEER` (values above), then the `steer` config key, then `false`. `--no-steer` overrides `HAGI_SEND_STEER=1`.
+
+Outcomes:
+
+- `steered`: a running task took the message. It is not proof the text was used; the backend can requeue it when the run ends.
+- `queued`: no running task took it, so it was sent as the next message. Exit code `0`. An idle session also answers `queued`, and the message then starts a run at once, so do not read `queued` as "waiting".
+
+```bash
+hagi chat send --session-id <session-id> --content "Check the diff" --steer --json
+```
+
+The `--json` output keeps `sessionId`, `message` and `requested`, and adds a `steer` object: `{ requested, source, effective, outcome?, messageId?, reason? }`. `source` is `flag`, `env`, `config` or `default`. On the Steer path `message` is `Steered` or `Queued`. `reason` appears only when Steer was requested but not used.
+
+Conflicts and fallback:
+
+- `--steer` with `--mode` or `--executor-type` exits with code `2` and sends nothing.
+- Steer from `HAGI_SEND_STEER` or the config file, combined with `--mode` or `--executor-type`, sends a normal message with those options and sets `reason`.
+- Steer from `HAGI_SEND_STEER` or the config file, against a backend without `SteerSession`, sends a normal message with the reason `the backend does not support Steer`. An explicit `--steer` returns the backend error instead.
+
+A queued Steer is always sent in `Edit` mode. To keep another mode, use `--no-steer --mode <mode>`.
+
+For unattended session-to-session messages, set `HAGI_SEND_STEER=1` in the orchestrator's environment. Use `--no-steer` on a single call that must take the normal queue.
+
+## Plan commands
+
+Scheduled plans save a proposal or HagiTask input with a schedule and, for HagiTask plans, an agent pool.
+
+```text
+hagi plan
+|-- list
+|-- get      --id <id>
+|-- create   --input <file|-> [--name <name>] [--hero-id <id>] [--disabled]
+|-- update   --id <id> [--input <file|->] [--name <name>] [--hero-id <id>] [--enabled | --disabled]
+|-- enable   --id <id>
+|-- disable  --id <id>
+|-- delete   --id <id>
+`-- run      --id <id> [--background]
+```
+
+- `create` enables the plan unless the document sets `enabled` or `--disabled` is passed.
+- `update`, `enable` and `disable` read the current plan and send it back whole, so unchanged fields are kept. `update --input` replaces each top-level key it contains as a whole value.
+- `run` creates a session now and waits for it. `run --background` returns `{ planId, accepted: true }` once the backend accepts the run, before the session exists.
+- A manual run does not change the plan's state or next run time, and works for disabled and completed plans.
+
+A one-time proposal plan document for `plan create --input`:
+
+```json
+{
+  "type": "proposal",
+  "name": "Weekly triage",
+  "enabled": true,
+  "schedule": { "mode": "once", "runAt": "2026-06-12T10:30:00Z" },
+  "payload": {
+    "title": "Weekly triage",
+    "chiefComplaint": "Triage the open issues and propose the next sprint",
+    "projectId": "<project-id>"
+  }
+}
+```
+
+The README's `## Plan Commands` section has a recurring HagiTask example and the full `update`, `enable`, `disable` and `delete` workflow.
+
+## Skills commands
+
+`skills local list` shows each installed skill with its origin (`user` or `built-in`), its enabled state for built-in skills (`yes` or `no`, shown as `-` for user skills), its version, scope, agents and path. `--json` returns the same data with the `origin` and `builtIn` fields.
+
+```bash
+hagi skills local list
+hagi skills local list --json
+hagi skills local enable --skill-name hagi
+hagi skills local disable --skill-name hagi --json
+```
+
+- `enable` and `disable` take `--skill-name` and change one built-in skill. They apply to agent runs that start afterwards.
+- `uninstall` removes a user skill. Built-in skills cannot be uninstalled; use `disable` to stop one from loading.
+- Skill recommendation and install progress streaming are not part of the CLI. `skills gallery search`, `detail` and `install` are the discovery and install path.
+- `skills gallery detail` adds skills.sh audit ratings. `--json` keeps the detail fields and adds `audit: { providers: [...] }`, one entry per provider with `provider` and, when supplied, `risk`, `alerts`, `score` and `analyzedAt`. Human output appends one `skills.sh audit (<provider>)` line per provider, with `--` for missing values. If the audit fails or has no data, the command still exits `0` and `audit.providers` is `[]`. A detail failure fails the command as before. The audit never changes the install command preview or installability.
+
+## Exit codes
+
+Stable non-zero exits used by the CLI. The HTTP numbers are the equivalents of the gRPC status the backend answered with:
+
+| Exit code | Meaning |
+| --- | --- |
+| `2` | CLI usage or validation failure |
+| `20` | HTTP 400 |
+| `21` | HTTP 401 |
+| `23` | HTTP 403 |
+| `24` | HTTP 404 |
+| `29` | HTTP 409 |
+| `30` | Operation failed: the backend returned a refusal, for example `skills local enable` or `disable` on a name that is not a built-in skill, an invalid MonoSpecs configuration, or a failed MonoSpecs clone |
+| `31` | Wait timed out: `--wait` on `proposal get` or `hagitask get` reached `--timeout` before the session settled. The last status is printed. Not a success, and not a backend error |
+| `40` | Other HTTP 4xx |
+| `50` | HTTP 5xx |
+| `60` | Transport or connection failure |
+| `70` | Unknown error |

package/skills/hagi/references/local-development.md

@@ -0,0 +1,79 @@
+# Local Development
+
+This document is maintainer-only.
+Use it when you are editing or validating the CLI source tree inside `repos/cli`.
+Normal users should stay on the published package path.
+
+## Working directory rule
+
+Always change into `repos/cli` before running install, build, or test commands.
+Do not run npm commands at the monorepo root.
+
+```bash
+cd repos/cli
+```
+
+## Development modes
+
+### Source-level development
+
+Use the TypeScript entrypoint directly while changing behavior:
+
+```bash
+cd repos/cli
+pnpm run dev proposal list --json
+pnpm run dev chat list --json
+```
+
+### Release-style verification
+
+Build the local distribution and run the bundled CLI:
+
+```bash
+cd repos/cli
+pnpm run build
+node ./dist/cli.js --help
+node ./dist/cli.js proposal --help
+```
+
+## Repository map
+
+Inspect these areas when implementation details matter:
+
+- `src/commands/` - command registration, flags, and request shaping
+- `src/runtime/` - API runtime, shared context, and error handling
+- `src/formatters/` - human-readable and JSON output formatting
+- `buildTools/` - gRPC stub generation and DTO type generation scripts
+- `scripts/verify-package.mjs` - publish-surface verification
+
+## API client generation
+
+The CLI calls the backend over gRPC-Web (`<base-url>/grpc`). The stubs in `src/generated/grpc` come from the proto contracts in `repos/hagicode-core/protos`.
+Use these commands when a proto changes:
+
+```bash
+cd repos/cli
+pnpm run generate:grpc
+pnpm run generate:grpc:check
+```
+
+`HAGICODE_PROTO_DIR` points generation at another checkout of the protos.
+
+The DTO types in `src/generated/api/models` are committed and maintained by hand (types only, no REST client). They are no longer
+generated: the backend's OpenAPI document now lists only the retained REST routes, so regenerating from it would delete the
+types of every removed route. When a proto DTO changes, edit or add the matching type there.
+
+## Release automation
+
+GitHub workflows under `.github/workflows/` handle release drafting and npm publishing.
+For a stable release dry run, use:
+
+```bash
+cd repos/cli
+version="$(pnpm run --silent publish:verify-release -- v0.1.0)"
+npm version --no-git-tag-version "$version"
+pnpm run build
+pnpm run typecheck
+pnpm test
+pnpm run pack:check
+```