@hagicode/cli 0.1.2 → 0.2.0

package/README.md

@@ -1,199 +1,555 @@
 # HagiCode CLI
 
-[![npm version](https://img.shields.io/npm/v/%40hagicode%2Fcli?logo=npm)](https://www.npmjs.com/package/@hagicode/cli)
+[![npm version](https://img.shields.io/npm/v/%40hagicode%2Fcli?logo=npm&color=cb3837)](https://www.npmjs.com/package/@hagicode/cli)
+[![npm downloads](https://img.shields.io/npm/dm/%40hagicode%2Fcli?logo=npm&color=2d8cf0)](https://www.npmjs.com/package/@hagicode/cli)
+[![license](https://img.shields.io/npm/l/%40hagicode%2Fcli?color=ffd43b)](https://www.npmjs.com/package/@hagicode/cli)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D24.0.0-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 
-`repos/cli` contains the npm-based `hagi` command for proposal session management.
+`@hagicode/cli` provides the published `hagi` command, which lets you drive a HagiCode backend from a terminal, scripts, or an AI agent without opening the app. Manage projects, proposals (generate, execute, archive, and send), vaults and their files, chat sessions, HagiTasks, scheduled plans, and skills (local list, enable, disable and uninstall, gallery search and install, and trusted providers). Every command supports a shared `--json` output for scripting, and an embedded Hagi skill under [`skills/`](skills/) guides agent workflows.
 
 ## Requirements
 
-- Node.js 20+
-- npm compatible with `10.9.2`
+- Node.js 24+
 - Access to a HagiCode backend API
 
 ## Installation
 
+Use the published npm package for normal CLI usage. You do not need to clone this repository to run `hagi`.
+
+### Zero-install usage
+
 ```bash
-cd repos/cli
-npm install
-npm run build
+npx @hagicode/cli --help
+npx @hagicode/cli project list --json
 ```
 
-`npm run build` now performs a Vite 8 production bundle for Node 20+ and emits the publish contract at `dist/cli.js`, `dist/main.js`, plus any runtime-required shared chunks under `dist/chunks/`.
-Release builds are minified, tree-shaken, and exclude `.map` files.
+### Project-local install
+
+```bash
+npm install @hagicode/cli
+npx @hagicode/cli proposal list --json
+```
 
-Run the built CLI with:
+### Optional global install
 
 ```bash
-npx hagi --help
-node ./dist/cli.js --help
+npm install -g @hagicode/cli
+hagi --help
 ```
 
-For local development without building:
+## Quick Start
+
+The examples below use `hagi ...` after the package is available on your `PATH`. For one-off execution, replace `hagi` with `npx @hagicode/cli`.
 
 ```bash
-cd repos/cli
-npm run dev -- proposal list --json
+hagi --help
+hagi project list --json
+hagi proposal list --json
+hagi vault list --json
+hagi chat list --json
+hagi hagitask list
+hagi hagitask create --title "Auto commit" --project-id <project-id> --prompt-id auto-compose-commit.en-US
 ```
 
-## Release automation
+## Embedded Skills
 
-`repos/cli/.github/workflows/release-drafter.yml` maintains the next GitHub draft release for `@hagicode/cli`.
-`repos/cli/.github/workflows/npm-publish.yml` now publishes two channels with GitHub Actions OIDC plus provenance:
+If you are integrating Hagi CLI into an agent workflow, start from the embedded skill package in this repository:
 
-- pushes to `main` publish a unique development prerelease under the npm `dev` dist-tag
-- only published GitHub Releases for strict `vX.Y.Z` tags publish the stable package under the npm `latest` dist-tag
+- [`skills/README.md`](skills/README.md) - repository-level discovery entrypoint
+- [`skills/hagi/SKILL.md`](skills/hagi/SKILL.md) - canonical Hagi skill contract
+- [`skills/hagi/references/`](skills/hagi/references/) - focused package usage, session data, proposal flow, maintainer, and validation guidance
 
-### Draft release flow
+The same folder is also shipped as the HagiCode server's built-in skill `hagi`, so an agent running inside a HagiCode session can answer questions about the user's own projects, proposals, sessions, vaults and plans without setup. Edit `skills/hagi/` here; the built-in copy is recopied from it.
 
-1. Label each PR with one semantic version label: `major`, `minor`, or `patch`.
-2. Add at least one release note category label:
-   - `breaking-change` for breaking release note callouts
-   - `feature` or `enhancement` for the `Features` section
-   - `bug` for the `Fixes` section
-   - `docs` or `documentation` for the `Documentation` section
-   - `chore` or `dependencies` for the `Maintenance` section
-3. Add `skip-changelog` only when the PR should stay out of the draft notes entirely, such as pure CI noise or internal housekeeping.
-4. Merge the labeled PR into `main`, or update the PR while it is open.
-5. Let Release Drafter refresh the GitHub draft release name, tag, and categorized notes.
-6. Review the draft release in GitHub before creating the next stable tag.
+## Shared Runtime Flags
 
-Release Drafter manages draft release metadata only. Draft review and publish remain native GitHub Release operations.
+Every command family supports the same global runtime flags:
 
-### Current label coverage
+- `--base-url <url>`
+- `--token <token>`
+- `--lang <lang>`
+- `--json`
 
-At implementation time, the public `HagiCode-org/cli` label set already included `bug`, `documentation`, and `enhancement`.
-The following planned release labels were still missing and should be created before maintainers rely on the full contract:
+Example:
 
-- `major`
-- `minor`
-- `patch`
-- `breaking-change`
-- `feature`
-- `docs`
-- `chore`
-- `dependencies`
-- `skip-changelog`
+```bash
+hagi --base-url https://api.example.com --token "$HAGI_TOKEN" project list --json
+```
 
-### Trusted Publisher prerequisites
+## Connection Setup
 
-Before the first automated release, an npm package owner must bind the package to the repository workflow:
+Every operation command resolves the backend base URL on each invocation, in this order:
 
-1. Open the npm package settings for `@hagicode/cli`.
-2. Add a Trusted Publisher for the GitHub repository `HagiCode-org/cli`.
-3. Set the workflow file to `.github/workflows/npm-publish.yml`.
-4. Keep the package access level public so `npm publish --access public` can succeed.
+1. `--base-url <url>` flag
+2. `HAGI_API_BASE_URL` environment variable
+3. `baseUrl` in the local config file: `$XDG_CONFIG_HOME/hagi/config.json`, or `~/.config/hagi/config.json` when `XDG_CONFIG_HOME` is unset
 
-The workflow requests `contents: read` and `id-token: write`. It does not use a long-lived `NPM_TOKEN`.
+```json
+{
+  "baseUrl": "https://hagicode.example.com"
+}
+```
 
-### Local release verification
+If none of the three is set, the command exits with code `2` and sends no backend request.
 
-Run the same stable release gates locally before publishing a GitHub Release:
+Operation commands send requests without a credential by default. Pass `--token` (or set `HAGI_API_TOKEN`) only when your backend requires one.
 
-```bash
-cd repos/cli
-version="$(npm run --silent publish:verify-release -- v0.1.0)"
-npm version --no-git-tag-version "$version"
-npm run build
-npm run typecheck
-npm test
-npm run pack:check
+When the backend cannot be reached, the CLI names the base URL and exits with code `60`. A backend HTTP error is reported differently: it prints the HTTP status and the backend error message, and exits with a status-mapped code.
+
+```text
+$ hagi --base-url http://127.0.0.1:1 project list
+Cannot reach HagiCode backend at http://127.0.0.1:1. Check that the backend is running and the base URL is correct.
+
+$ echo $?
+60
 ```
 
-`publish:verify-release` validates the strict stable tag format and resolves the stable package version that CI will stamp into `package.json` immediately before build and publish.
-`pack:check` runs `npm pack --dry-run --json` and rejects missing bundled entrypoints, `.map` files, and legacy source-mirrored output such as `dist/runtime/**` or `dist/generated/api/models/**`.
-`publish:resolve-dev-version` derives the CI-only prerelease version used for `main` branch publishes, for example `0.1.0-dev.<run>.<attempt>.<sha>`.
+## Command Overview
+
+```text
+hagi
+|-- project   list | repositories | create | update | delete
+|-- proposal  list | create | optimize-description | generate | annotate | execute | archive | status | complete | send
+|-- vault     list | create | update | delete
+|   `-- files list | preview
+|-- chat      list | create | archive | delete | send
+|-- hagitask  list | schema | create | send
+|-- plan      list | get | create | update | enable | disable | delete | run
+`-- skills    local list | enable | disable | uninstall
+              gallery search | detail | install
+              trusted list | upsert | delete | reset
+```
 
-### Stable release flow
+## Example Setup
 
-1. Make sure the draft release maintained by Release Drafter already reflects the intended tag such as `v0.1.0`.
-2. Run the local verification commands above.
-3. Commit and push the release-ready source tree.
-4. Publish the matching GitHub draft release for the stable tag.
-5. Confirm the GitHub Actions summary shows build, typecheck, test, package inspection, version stamping, and `npm publish --tag latest --provenance --access public`.
+The examples in the family sections run in order against a local backend. They assume:
 
-## Environment Variables
+- the backend listens on `http://127.0.0.1:35167`
+- `hagi` is on `PATH`
+- `json_field` reads one field from `--json` output
 
-The CLI resolves runtime settings centrally before every command. Explicit flags always override environment variables.
+```bash
+export HAGI_API_BASE_URL=http://127.0.0.1:35167
+json_field() { node -pe "JSON.parse(require('node:fs').readFileSync(0, 'utf8'))$1"; }
 
-| Variable | Purpose |
-| --- | --- |
-| `HAGI_API_BASE_URL` | Backend base URL. Defaults to `http://127.0.0.1:35168` when unset. |
-| `HAGI_API_TOKEN` | Bearer token attached as `Authorization: Bearer <token>`. |
-| `HAGI_API_LANG` | Shared `Accept-Language` header value. |
+mkdir -p /tmp/cli-examples/repos/cli
+PROJECT_ID=$(hagi project create --name "CLI Examples" --path /tmp/cli-examples --json | json_field '.project.id')
+```
 
-Global flags:
+## Project Commands
 
-- `--base-url <url>`
-- `--token <token>`
-- `--lang <lang>`
-- `--json`
+List projects through the aggregation endpoint:
 
-## Generate the API Client
+```bash
+hagi project list
+hagi project list --json
+```
+
+List the repositories of one project. The read-only command prints each repository's name, path relative to the project root, display name, type and branch. These paths are the values a proposal's repository scope names:
+
+```bash
+hagi project repositories --id "$PROJECT_ID"
+hagi project repositories --id "$PROJECT_ID" --json
+```
 
-The CLI owns its own OpenAPI configuration in `openapi-ts.config.json`.
+Create a project. The backend creates the directory if it does not exist. The new id is read from `project.id`:
 
 ```bash
-cd repos/cli
-npm run generate:api
-npm run generate:api:once
+DEMO_PROJECT_ID=$(hagi project create \
+  --name "CLI Demo" \
+  --path /tmp/cli-demo \
+  --description "Automation sandbox" \
+  --json | json_field '.project.id')
 ```
 
-Default Swagger source:
+Update only part of a project record. The CLI resolves current project data first so omitted fields are preserved:
 
-- `http://127.0.0.1:35168/swagger/v1/swagger.json`
+```bash
+hagi project update --id "$DEMO_PROJECT_ID" --description "Updated description"
+hagi project update --id "$DEMO_PROJECT_ID" --name "CLI Demo renamed"
+```
 
-When the backend cannot export Swagger in the current environment, keep `src/generated/api/**` aligned with the same controller contract used by `repos/web`, then regenerate when Swagger becomes available again.
+Delete the demo project:
 
-`generate:api:once` matches the frontend workflow: it reuses an existing Swagger host when one is already up, otherwise it starts `repos/hagicode-core/src/PCode.SwaggerHost/PCode.SwaggerHost.csproj`, waits for Swagger readiness, runs the normal generator once, then stops the temporary host.
+```bash
+hagi project delete --id "$DEMO_PROJECT_ID"
+```
 
 ## Proposal Commands
 
-`proposal list` queries proposal sessions through `GET /api/Sessions` with `type=Proposal`.
+List proposal sessions for the example project:
 
 ```bash
-hagi proposal list --project-id <project-id>
+hagi proposal list --project-id "$PROJECT_ID"
 hagi proposal list --include-archived --json
 ```
 
-`proposal create` only creates the proposal session. It does not trigger any later lifecycle API.
+Every proposal names its writable repositories and its read-only repositories. Take the paths from `hagi project repositories --id "$PROJECT_ID" --json`, and begin the chief complaint with a `Repository scope` section: a `Writable repositories:` list and a `Read-only repositories:` list, one `- <path>` entry per line, with `- none` for an empty list. The scope is a text convention in the chief complaint; `proposal create` has no scope flags. The format and a worked example are in [`skills/hagi/references/proposal-flow.md`](skills/hagi/references/proposal-flow.md#repository-scope).
+
+Create a proposal session only. The new id is read from `session.sessionId`:
+
+```bash
+PROPOSAL_ID=$(hagi proposal create \
+  --project-id "$PROJECT_ID" \
+  --chief-complaint "Repository scope
+Writable repositories:
+- repos/cli
+Read-only repositories:
+- none
+
+Add CLI completion for session workflows" \
+  --default-title \
+  --json | json_field '.session.sessionId')
+```
+
+Update status and send a follow-up message:
+
+```bash
+hagi proposal status --session-id "$PROPOSAL_ID" --status Reviewing
+hagi proposal send --session-id "$PROPOSAL_ID" --content "Please continue"
+```
+
+The next steps are AI lifecycle actions and need a backend with an AI executor. `optimize-description` writes the optimized title, description, and proposal name to the session in one backend step, and `generate` needs that name. Without the AI executor, or before the name exists, the backend answers with a 400 that names the missing state:
 
 ```bash
-hagi proposal create \
-  --project-id <project-id> \
-  --chief-complaint "Add npm commands for proposal APIs" \
-  --default-title
+hagi proposal optimize-description --session-id "$PROPOSAL_ID" --description "Add CLI completion for session workflows" --default-title
+hagi proposal generate --session-id "$PROPOSAL_ID" --proposal-content-language en-US --enable-explore-mode
+
+cat > annotations.json <<'EOF'
+{"files":[{"fileName":"proposal.md","filePath":"proposal.md"}]}
+EOF
+hagi proposal annotate --session-id "$PROPOSAL_ID" --input annotations.json
+cat annotations.json | hagi proposal annotate --session-id "$PROPOSAL_ID" --input - --json
+
+hagi proposal execute --session-id "$PROPOSAL_ID"
+hagi proposal complete --session-id "$PROPOSAL_ID"
+hagi proposal archive --session-id "$PROPOSAL_ID"
 ```
 
-`proposal generate-name` only generates the proposal name for an existing session.
+### Explicit Lifecycle Sequence
+
+The CLI keeps proposal lifecycle actions explicit and non-interactive. Each command maps to one backend action:
+
+1. `hagi proposal list`
+2. `hagi proposal create`
+3. `hagi proposal optimize-description --session-id <session-id> --description <text>` (sets the title, description, and proposal name)
+4. `hagi proposal generate --session-id <session-id> --proposal-content-language <language>` (optionally `--enable-explore-mode`)
+5. `hagi proposal annotate --session-id <session-id> --input <file>` (optional review loop)
+6. `hagi proposal execute --session-id <session-id>`
+7. `hagi proposal complete --session-id <session-id>`
+8. `hagi proposal archive --session-id <session-id>`
+
+The CLI may suggest a next command, but it never chains later lifecycle APIs automatically.
+
+Each command maps to one backend action. The CLI may suggest a next command, but it never chains later lifecycle APIs automatically.
+
+## Vault Commands
+
+Create a vault with a local folder to browse. The new id is read from `vault.id`:
 
 ```bash
-hagi proposal generate-name --session-id <session-id>
+mkdir -p /tmp/cli-vault-notes/docs
+printf '# Notes\n' > /tmp/cli-vault-notes/docs/readme.md
+
+VAULT_ID=$(hagi vault create \
+  --name "Main Notes" \
+  --type folder \
+  --physical-path /tmp/cli-vault-notes \
+  --json | json_field '.vault.id')
 ```
 
-`proposal generate` only starts proposal generation.
+List registered vaults:
 
 ```bash
-hagi proposal generate --session-id <session-id> --enable-explore-mode
-hagi proposal generate --session-id <session-id> --hero-id <hero-id>
+hagi vault list
+hagi vault list --json
 ```
 
-`proposal execute` only starts proposal execution.
+Update only part of a vault record. The CLI resolves the current vault snapshot first so omitted fields are preserved:
 
 ```bash
-hagi proposal execute --session-id <session-id>
+hagi vault update --id "$VAULT_ID" --name "Renamed Vault"
 ```
 
-## Explicit Lifecycle Sequence
+Browse vault files and preview supported content:
 
-The CLI keeps proposal lifecycle actions explicit and non-interactive:
+```bash
+hagi vault files list --id "$VAULT_ID"
+hagi vault files list --id "$VAULT_ID" --path docs --json
+hagi vault files preview --id "$VAULT_ID" --path docs/readme.md
+```
 
-1. `hagi proposal list`
-2. `hagi proposal create`
-3. `hagi proposal generate-name`
-4. `hagi proposal generate`
-5. `hagi proposal execute`
+Delete a vault and request backend cleanup of its local files:
+
+```bash
+hagi vault delete --id "$VAULT_ID" --delete-local-files --json
+```
+
+## Chat Commands
+
+Create a chat session. The new id is read from `session.sessionId`:
+
+```bash
+CHAT_ID=$(hagi chat create \
+  --title "Repository Q&A" \
+  --project-id "$PROJECT_ID" \
+  --json | json_field '.session.sessionId')
+```
 
-Each command maps to one backend action. The CLI prints the suggested next command, but it never chains later lifecycle APIs automatically.
+List chat sessions:
+
+```bash
+hagi chat list --active-only
+hagi chat list --include-archived --json
+```
+
+Send a message, archive, and delete:
+
+```bash
+hagi chat send --session-id "$CHAT_ID" --content "Summarize the current diff"
+hagi chat archive --session-id "$CHAT_ID"
+hagi chat delete --session-id "$CHAT_ID"
+```
+
+## HagiTask Commands
+
+A HagiTask is a preset task with a structured input. Read its schema first, write the input from the schema, then create the session. `hagitask list` shows the active tasks:
+
+```bash
+hagi hagitask list
+hagi hagitask list --json
+```
+
+`hagitask schema` shows one task's target scope, commands, parameters, requirements and scenes. Each required parameter is marked `yes`. The `--json` output adds the input JSON Schema and an example request body:
+
+```bash
+hagi hagitask schema --task-id compose-commit
+hagi hagitask schema --task-id compose-commit --json
+```
+
+Write the input file. Its keys are the parameter keys the schema lists under `inputs`, plus the `targets` and `targetScopes` keys when the schema's scope lists targets. For example, `input.json` for a task with one required input:
+
+```json
+{
+  "inputs": {
+    "commitScope": "cli"
+  }
+}
+```
+
+Create the session from that task and input. The new id is read from `session.sessionId`:
+
+```bash
+HAGITASK_ID=$(hagi hagitask create \
+  --title "Auto compose commit" \
+  --project-id "$PROJECT_ID" \
+  --task-id compose-commit \
+  --input input.json \
+  --repository-path repos/cli \
+  --need-push \
+  --target-branch-mode new-custom \
+  --target-branch-name feature/cli-completion \
+  --json | json_field '.session.sessionId')
+```
+
+Use `--prompt-id` instead of `--task-id` for a prompt template with no structured input. `--input` needs `--task-id`. Input is read from a file, or from stdin with `--input -`. The CLI only checks that the input is a JSON object. The backend checks the keys and values. It rejects a key that the schema does not list, and a missing required value. Its error is printed unchanged, and no session is reported as created. `--hero-selection-mode` takes `first` (the default) or `random`.
+
+The backend must have a hero available for the task's script. Without one, `hagitask create` fails with a 400 whose error is `no-executable-hero`.
+
+Send a follow-up message to the HagiTask session:
+
+```bash
+hagi hagitask send --session-id "$HAGITASK_ID" --content "Retry with a smaller diff"
+```
+
+**Migration from AutoTask:** `hagi hagitask create` and `hagi hagitask send` replace `hagi autotask create` and `hagi autotask send`. There is no `autotask` alias, so an `autotask` command now fails as an unknown command. Read the task schema with `hagitask schema` to find the input keys that replace the old flags.
+
+## Plan Commands
+
+A scheduled plan saves a proposal or HagiTask input with a schedule and an agent pool. The backend runs it on that schedule. `plan list` and `plan get` show the plans that exist:
+
+```bash
+hagi plan list
+hagi plan list --json
+hagi plan get --id "$PLAN_ID"
+hagi plan get --id "$PLAN_ID" --json | jq .plan
+```
+
+`plan list` prints one row per plan with its schedule summary, and an explicit message when there are none. `--json` prints `{ "plans": [...] }`, where each entry carries `id`, `type`, `name`, `enabled`, `state`, `nextRunAt`, `schedule`, `agentPool` and `payload` exactly as the backend returns them. `plan get --json` prints `{ "plan": {...} }` with the same fields.
+
+### Create a plan
+
+`plan create` reads a plan document with `--input <file>` or `--input -` for stdin. A recurring HagiTask plan:
+
+```json
+{
+  "type": "hagitask",
+  "name": "Nightly review",
+  "enabled": true,
+  "schedule": {
+    "mode": "recurring",
+    "timeZone": "Asia/Shanghai",
+    "startDate": "2026-05-01",
+    "endDate": "2026-05-31",
+    "timeOfDay": "02:00",
+    "repeat": { "rule": "daily", "weekdays": [] }
+  },
+  "agentPool": { "strategy": "random", "agents": [ { "heroId": "5de02573-0000-4000-8000-000000000001" } ] },
+  "payload": {
+    "projectId": "11111111-2222-3333-4444-555555555555",
+    "presetTaskId": "nightly-review"
+  }
+}
+```
+
+A one-time proposal plan runs once at `runAt` and has no time zone or repeat fields:
+
+```json
+{
+  "type": "proposal",
+  "name": "Weekly triage",
+  "schedule": { "mode": "once", "runAt": "2026-06-12T10:30:00Z" },
+  "payload": {
+    "title": "Weekly triage",
+    "chiefComplaint": "Triage the open issues and propose the next sprint",
+    "projectId": "11111111-2222-3333-4444-555555555555"
+  }
+}
+```
+
+```bash
+hagi plan create --input nightly-review.json
+hagi plan create --input weekly-triage.json --disabled
+PLAN_ID=$(hagi plan create --input nightly-review.json --json | json_field '.plan.id')
+```
+
+A plan is **enabled by default**. `create` sends `enabled: true` unless the document sets `enabled` or you pass `--disabled`. `--name` and `--hero-id` replace the document's `name` and agent pool, and `--hero-id` builds the single-agent `random` pool. Server-owned fields (`id`, `createdAt`, `updatedAt`, `state`, `nextRunAt`) in the document are ignored.
+
+### Update, enable, disable and delete
+
+`plan update` reads the current plan, applies your changes and sends the full plan back, so fields you do not mention keep their values:
+
+```bash
+hagi plan update --id "$PLAN_ID" --name "Nightly review (EU)"
+hagi plan update --id "$PLAN_ID" --input changes.json
+hagi plan update --id "$PLAN_ID" --hero-id 5de02573-0000-4000-8000-000000000002 --enabled
+```
+
+`--input` on update is a **shallow merge** over the top-level keys of the plan (`type`, `name`, `enabled`, `schedule`, `agentPool`, `payload`). Each key in the file replaces the current value as a whole, and keys missing from the file are kept. A `schedule` in the file replaces the whole current schedule, so write the complete object, without the fields you want removed (for example `endDate`). Passing `--enabled` and `--disabled` together is a usage error, and so is an update with no change.
+
+`enable` and `disable` change only the enabled flag. When the plan already has that flag, nothing is sent and the output says so:
+
+```bash
+hagi plan disable --id "$PLAN_ID"
+hagi plan enable --id "$PLAN_ID" --json
+```
+
+Delete a plan. It never runs again:
+
+```bash
+hagi plan delete --id "$PLAN_ID"
+hagi plan delete --id "$PLAN_ID" --json
+```
+
+To change a plan with a text editor, take the current document, edit it and feed it back. Server-owned fields are dropped automatically:
+
+```bash
+hagi plan get --id "$PLAN_ID" --json | jq .plan > plan.json
+# edit plan.json, then:
+hagi plan update --id "$PLAN_ID" --input plan.json
+```
+
+When the backend rejects a plan with 400 (exit code `20`), the CLI prints the summary and then one line per problem, naming its field:
+
+```text
+Scheduled plan is invalid. (status=400)
+  - agentPool: A HagiTask plan needs an agent pool with one agent.
+```
+
+Use `--json` to get the full backend body under `error.details`.
+
+### Run a plan now
+
+`plan run` creates a session from the plan's stored inputs immediately, without waiting for the schedule. It waits for the session and prints its summary, or `{ "session": {...} }` with `--json`:
+
+```bash
+hagi plan run --id "$PLAN_ID"
+```
+
+`plan run --background` starts the same run and returns as soon as the backend accepts it, before the session exists. It prints the plan id and `accepted: true`. The session shows up in the normal session list:
+
+```bash
+hagi plan run --id "$PLAN_ID" --background --json
+```
+
+A manual run does not change the plan's state or next run time. It works for disabled and completed plans, and the next automatic run still happens on the original schedule.
+
+## Skills Commands
+
+List installed local skills. The table shows each skill's origin (`user` or `built-in`), whether a built-in skill is enabled, its version, scope, agents and path. A user skill shows `-` in the Enabled column, because availability does not apply to it:
+
+```bash
+hagi skills local list
+hagi skills local list --json
+```
+
+Turn a built-in skill on or off by name. The change applies to agent runs that start afterwards; a run already in progress keeps its skills. A name that is not a built-in skill exits with code `30`, and the output carries the backend message:
+
+```bash
+hagi skills local enable --skill-name hagi
+hagi skills local disable --skill-name hagi --json
+```
+
+Built-in skills cannot be uninstalled. Use `skills local disable` to stop one from loading. Remove a user skill by name:
+
+```bash
+SKILL_NAME=demo-skill
+hagi skills local uninstall --skill-name "$SKILL_NAME"
+```
+
+The uninstall result reports a status such as `Succeeded` or `PrerequisiteMissing`, with the backend message. Passing a built-in skill's name returns the backend's refusal unchanged.
+
+Skill recommendation and install progress streaming are not part of the CLI. `skills gallery search`, `detail` and `install` are the discovery and install path.
+
+Search the gallery and read one skill:
+
+```bash
+hagi skills gallery search --query react
+hagi skills gallery search --query react --json
+hagi skills gallery detail --id vercel-react-best-practices --source vercel-labs/agent-skills
+```
+
+Start a managed install of a gallery skill. This writes the skill into your local skill directories, so run it only when you intend to install it:
+
+```bash
+hagi skills gallery install \
+  --id vercel-react-best-practices \
+  --source vercel-labs/agent-skills \
+  --skill-slug vercel-react-best-practices
+```
+
+Manage the trusted provider directory. `upsert` reads a JSON document from `--input <file>` or `--input -`:
+
+```bash
+hagi skills trusted list
+cat > provider.json <<'EOF'
+{"providerId":"example-provider","displayName":"Example","isEnabled":true,"sortOrder":50,"matchRules":[{"matchType":"owner","value":"example"}]}
+EOF
+hagi skills trusted upsert --input provider.json
+cat provider.json | hagi skills trusted upsert --input - --json
+hagi skills trusted delete --provider-id example-provider
+hagi skills trusted reset
+```
+
+## 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. Required when neither is set. |
+| `HAGI_API_TOKEN` | Bearer token attached as `Authorization: Bearer <token>`. |
+| `HAGI_API_LANG` | Shared `Accept-Language` header value. |
 
 ## Exit Codes
 
@@ -207,6 +563,7 @@ Stable non-zero exits used by the CLI:
 | `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 |
 | `40` | Other HTTP 4xx |
 | `50` | HTTP 5xx |
 | `60` | Transport or connection failure |