@hagicode/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,190 +1,555 @@
 # HagiCode CLI
 
-`repos/cli` contains the npm-based `hagi` command for proposal session management.
+[![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/)
+
+`@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
 ```
 
-Run the built CLI with:
+### Project-local install
 
 ```bash
-npx hagi --help
-node ./dist/cli.js --help
+npm install @hagicode/cli
+npx @hagicode/cli proposal list --json
 ```
 
-For local development without building:
+### Optional global install
 
 ```bash
-cd repos/cli
-npm run dev -- proposal list --json
+npm install -g @hagicode/cli
+hagi --help
 ```
 
-## Release automation
+## Quick Start
 
-`repos/cli/.github/workflows/release-drafter.yml` maintains the next GitHub draft release for `@hagicode/cli`.
-`repos/cli/.github/workflows/npm-publish.yml` remains the stable publish entrypoint, and only strict `vX.Y.Z` tags publish to npm with GitHub Actions OIDC plus provenance.
+The examples below use `hagi ...` after the package is available on your `PATH`. For one-off execution, replace `hagi` with `npx @hagicode/cli`.
 
-### Draft release flow
+```bash
+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
+```
 
-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.
+## Embedded Skills
 
-Release Drafter manages draft release metadata only. It does not publish the package, change the stable tag verification commands, or replace the existing npm publish path.
+If you are integrating Hagi CLI into an agent workflow, start from the embedded skill package in this repository:
 
-### Current label coverage
+- [`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
 
-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:
+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.
 
-- `major`
-- `minor`
-- `patch`
-- `breaking-change`
-- `feature`
-- `docs`
-- `chore`
-- `dependencies`
-- `skip-changelog`
+## Shared Runtime Flags
 
-### Trusted Publisher prerequisites
+Every command family supports the same global runtime flags:
 
-Before the first automated release, an npm package owner must bind the package to the repository workflow:
+- `--base-url <url>`
+- `--token <token>`
+- `--lang <lang>`
+- `--json`
 
-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.
+Example:
 
-The workflow requests `contents: read` and `id-token: write`. It does not use a long-lived `NPM_TOKEN`.
+```bash
+hagi --base-url https://api.example.com --token "$HAGI_TOKEN" project list --json
+```
 
-### Local release verification
+## Connection Setup
 
-Run the same stable release gates locally before pushing a stable tag:
+Every operation command resolves the backend base URL on each invocation, in this order:
 
-```bash
-cd repos/cli
-npm run publish:verify-release -- v0.1.0
-npm run build
-npm run typecheck
-npm test
-npm run pack:check
+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
+
+```json
+{
+  "baseUrl": "https://hagicode.example.com"
+}
 ```
 
-`publish:verify-release` fails unless the supplied tag exactly matches `package.json#version`.
-`pack:check` runs `npm pack --dry-run --json` and rejects missing entrypoints or unexpected published files.
+If none of the three is set, the command exits with code `2` and sends no backend request.
 
-### Stable tag flow
+Operation commands send requests without a credential by default. Pass `--token` (or set `HAGI_API_TOKEN`) only when your backend requires one.
 
-1. Update `package.json` to the intended stable version such as `0.1.0`.
-2. Make sure the draft release maintained by Release Drafter already reflects the intended tag such as `v0.1.0`.
-3. Run the local verification commands above.
-4. Commit the release-ready source tree.
-5. Push a strict stable tag such as `v0.1.0`.
-6. Confirm the GitHub Actions summary shows build, typecheck, test, package inspection, and `npm publish --tag latest --provenance --access public`.
+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.
 
-## Environment Variables
+```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.
 
-The CLI resolves runtime settings centrally before every command. Explicit flags always override environment variables.
+$ echo $?
+60
+```
 
-| 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. |
+## 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
+```
 
-Global flags:
+## Example Setup
 
-- `--base-url <url>`
-- `--token <token>`
-- `--lang <lang>`
-- `--json`
+The examples in the family sections run in order against a local backend. They assume:
+
+- the backend listens on `http://127.0.0.1:35167`
+- `hagi` is on `PATH`
+- `json_field` reads one field from `--json` output
+
+```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"; }
+
+mkdir -p /tmp/cli-examples/repos/cli
+PROJECT_ID=$(hagi project create --name "CLI Examples" --path /tmp/cli-examples --json | json_field '.project.id')
+```
 
-## Generate the API Client
+## Project Commands
 
-The CLI owns its own OpenAPI configuration in `openapi-ts.config.json`.
+List projects through the aggregation endpoint:
 
 ```bash
-cd repos/cli
-npm run generate:api
-npm run generate:api:once
+hagi project list
+hagi project list --json
 ```
 
-Default Swagger source:
+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:
 
-- `http://127.0.0.1:35168/swagger/v1/swagger.json`
+```bash
+hagi project repositories --id "$PROJECT_ID"
+hagi project repositories --id "$PROJECT_ID" --json
+```
 
-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.
+Create a project. The backend creates the directory if it does not exist. The new id is read from `project.id`:
 
-`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
+DEMO_PROJECT_ID=$(hagi project create \
+  --name "CLI Demo" \
+  --path /tmp/cli-demo \
+  --description "Automation sandbox" \
+  --json | json_field '.project.id')
+```
 
-## Proposal Commands
+Update only part of a project record. The CLI resolves current project data first so omitted fields are preserved:
 
-`proposal list` queries proposal sessions through `GET /api/Sessions` with `type=Proposal`.
+```bash
+hagi project update --id "$DEMO_PROJECT_ID" --description "Updated description"
+hagi project update --id "$DEMO_PROJECT_ID" --name "CLI Demo renamed"
+```
+
+Delete the demo project:
 
 ```bash
-hagi proposal list --project-id <project-id>
-hagi proposal list --include-archived --json
+hagi project delete --id "$DEMO_PROJECT_ID"
 ```
 
-`proposal create` only creates the proposal session. It does not trigger any later lifecycle API.
+## Proposal Commands
+
+List proposal sessions for the example project:
 
 ```bash
-hagi proposal create \
-  --project-id <project-id> \
-  --chief-complaint "Add npm commands for proposal APIs" \
-  --default-title
+hagi proposal list --project-id "$PROJECT_ID"
+hagi proposal list --include-archived --json
 ```
 
-`proposal generate-name` only generates the proposal name for an existing session.
+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
-hagi proposal generate-name --session-id <session-id>
+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')
 ```
 
-`proposal generate` only starts proposal generation.
+Update status and send a follow-up message:
 
 ```bash
-hagi proposal generate --session-id <session-id> --enable-explore-mode
-hagi proposal generate --session-id <session-id> --hero-id <hero-id>
+hagi proposal status --session-id "$PROPOSAL_ID" --status Reviewing
+hagi proposal send --session-id "$PROPOSAL_ID" --content "Please continue"
 ```
 
-`proposal execute` only starts proposal execution.
+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 execute --session-id <session-id>
+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"
 ```
 
-## Explicit Lifecycle Sequence
+### Explicit Lifecycle Sequence
 
-The CLI keeps proposal lifecycle actions explicit and non-interactive:
+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 generate-name`
-4. `hagi proposal generate`
-5. `hagi proposal execute`
+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
+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')
+```
+
+List registered vaults:
+
+```bash
+hagi vault list
+hagi vault list --json
+```
+
+Update only part of a vault record. The CLI resolves the current vault snapshot first so omitted fields are preserved:
+
+```bash
+hagi vault update --id "$VAULT_ID" --name "Renamed Vault"
+```
+
+Browse vault files and preview supported content:
+
+```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
+```
+
+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')
+```
+
+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"
+  }
+}
+```
 
-Each command maps to one backend action. The CLI prints the suggested next command, but it never chains later lifecycle APIs automatically.
+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
 
@@ -198,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 |