@hagicode/cli 0.1.0-dev.41.1.8543fd3 → 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-C3T3Iu-a.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-C3T3Iu-a.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.41.1.8543fd3",
+  "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": {

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

@@ -140,6 +140,24 @@ hagi proposal messages --session-id <session-id> --last 1 --json
 - `--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.

package/skills/hagi/references/proposal-flow.md

@@ -173,6 +173,33 @@ npx @hagicode/cli proposal complete --session-id <session-id>
 npx @hagicode/cli proposal send --session-id <session-id> --content "Please continue"
 ```
 
+## Session metadata
+
+`proposal create` accepts `--metadata key=value` (repeatable) and `--metadata-json <file|->` (a JSON object of string values; `-` reads stdin). Use them to mark the sessions of one orchestrated run: a master marker on the orchestrator and worker markers on each proposal, so the run can find its sessions again.
+
+```bash
+MASTER_ID=$(hagi chat create --title "Batch master" --project-id <project-id> --metadata role=master --metadata batch=2026-11-07 --json | json_field '.session.sessionId')
+
+hagi proposal create \
+  --project-id <project-id> \
+  --chief-complaint "Repository scope
+Writable repositories:
+- repos/web
+Read-only repositories:
+- none
+
+Tighten the settings page copy" \
+  --default-title \
+  --metadata role=worker \
+  --metadata master="$MASTER_ID" \
+  --json
+```
+
+- Keys: 1 to 64 characters matching `^[a-z][a-z0-9._-]{0,63}$`. Values: 1 to 512 characters with no control characters. At most 16 entries. The backend checks these and its message is shown as it is.
+- Each key appears once across both options. A repeat, a missing `=`, or a non-string JSON value exits `2` with no request sent.
+- Metadata is write-once and visible to every reader of the session. Do not put secrets in it.
+- The output `session` object carries `userMetadata` when the session has entries. Read it to confirm the markers were stored.
+
 ## Validation focus
 
 After each lifecycle step: