overlord-cli 0.2605121033.0 → 0.2605131058.0

package/README.md

@@ -121,7 +121,7 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `record-change-rationales` - persist structured change rationales without a normal progress update
 - `ask` - post a blocking question and move the ticket to review
 - `permission-request` - notify Overlord that the agent is requesting tool permission
-- `hook-event` - record lifecycle hook events such as `UserPromptSubmit` without a session key
+- `hook-event` - record lifecycle hook events such as `UserPromptSubmit` / Cursor `beforeSubmitPrompt` without a session key
 - `read-context` - read shared persistent context for this ticket
 - `write-context` - write shared persistent context for future sessions
 - `deliver` - create a local JJ/Git checkpoint when available, send artifacts/rationales, and move the ticket to review
@@ -130,6 +130,8 @@ Agents can find docs here: https://www.ovld.ai/docs/for-agents
 - `attachment-download-url` - get a signed download URL for an existing objective attachment
 - `attachment-upload-file` - prepare, upload, and finalize a local objective attachment in one command
 
+`ovld protocol deliver` accepts either discrete flags like `--summary` / `--artifacts-json`, an inline full payload with `--payload-json '{"summary":"...","artifacts":[...],"changeRationales":[...]}'`, or a file/stdin payload with `--payload-file <path|->`.
+
 ## License
 
 Permission is granted to use this software for any purpose, free of charge. You may not modify, distribute, sublicense, or sell copies of the software without explicit permission from the author.

package/bin/_cli/protocol.mjs

@@ -1122,14 +1122,28 @@ async function protocolDeliver(args) {
   const { sessionKey, ticketId } = resolveSessionFlags(flags);
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
   if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
+  if (flags['payload-file'] && flags['payload-json']) {
+    throw new Error('Use either --payload-file or --payload-json, not both');
+  }
   const deliverPayload = flags['payload-file']
     ? await readJsonFileOrStdin(String(flags['payload-file']), '--payload-file')
-    : null;
-  const summary =
-    deliverPayload?.summary ??
-    (flags['summary-file']
+    : flags['payload-json']
+      ? parseJsonFlag('--payload-json', flags['payload-json'])
+      : null;
+  if (deliverPayload && (flags.summary || flags['summary-file'])) {
+    throw new Error('Use either payload input or --summary/--summary-file, not both');
+  }
+  const summary = deliverPayload
+    ? (() => {
+        const value = deliverPayload.summary;
+        if (typeof value !== 'string' || !value.trim()) {
+          throw new Error('payload input must include a non-empty summary');
+        }
+        return value;
+      })()
+    : flags['summary-file']
       ? await readTextFileOrStdin(String(flags['summary-file']), '--summary-file')
-      : requireFlag(flags, 'summary', undefined));
+      : requireFlag(flags, 'summary', undefined);
 
   const { platformUrl, bearerToken, localSecret, organizationId } =
     await resolveProtocolAuthForFlags(flags, ticketId);
@@ -1137,10 +1151,10 @@ async function protocolDeliver(args) {
 
   let artifacts = deliverPayload?.artifacts ?? [];
   if (deliverPayload && flags['artifacts-file']) {
-    throw new Error('Use either --payload-file or --artifacts-file, not both');
+    throw new Error('Use either payload input or --artifacts-file, not both');
   }
   if (deliverPayload && flags['artifacts-json']) {
-    throw new Error('Use either --payload-file or --artifacts-json, not both');
+    throw new Error('Use either payload input or --artifacts-json, not both');
   }
   if (flags['artifacts-file']) {
     artifacts = await readJsonFileOrStdin(String(flags['artifacts-file']), '--artifacts-file');
@@ -1149,7 +1163,7 @@ async function protocolDeliver(args) {
   }
 
   if (deliverPayload && (flags['change-rationales-file'] || flags['change-rationales-json'])) {
-    throw new Error('Use either --payload-file or change-rationale flags, not both');
+    throw new Error('Use either payload input or change-rationale flags, not both');
   }
 
   const changeRationales =
@@ -1943,6 +1957,7 @@ deliver:
     --session-key <key>
     --ticket-id <ticket_id>
     --summary <text> or --summary-file <path|->
+    or: --payload-json <json>
     or: --payload-file <path|-> containing { summary, artifacts, changeRationales }
   Optional:
     --artifacts-json <json>
@@ -1951,9 +1966,10 @@ deliver:
     --change-rationales-file <path|->
     --skip-file-change-check  Bypass local git vs changeRationales validation
   Notes:
+    Use --payload-json when the full delivery JSON fits comfortably inline.
     Use --payload-file - to read the full delivery JSON from stdin without creating a scratch file.
     Use --summary-file - to pipe just the summary text via stdin (avoids shell special-char issues).
-    Do not combine --payload-file with --artifacts-json/--artifacts-file or change-rationale flags.
+    Do not combine --payload-json/--payload-file with --summary/--summary-file, --artifacts-json/--artifacts-file, or change-rationale flags.
     In a git workspace, deliver validates that changed files are represented by changeRationales unless skipped.
 
 prompt:
@@ -2089,6 +2105,7 @@ Examples:
   ovld protocol attachment-download-url --session-key <key> --ticket-id <ticket_id> --attachment-id <attachment-id>
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done"
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done" --artifacts-file ./artifacts.json
+  ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-json '{"summary":"Done","artifacts":[{"type":"note","label":"Delivery","content":"..."}]}'
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-file ./deliver.json
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --payload-file -
   ovld protocol deliver --session-key <key> --ticket-id <ticket_id> --summary "Done" --skip-file-change-check

package/bin/_cli/setup.mjs

@@ -88,7 +88,7 @@ If you receive a prompt with a specified ticket ID, adhere to the following. If
      --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
    \`\`\`
 
-   For larger or quote-sensitive deliveries, prefer a single JSON payload on stdin:
+   Use \`--payload-json\` when the full delivery object fits comfortably inline. For larger or quote-sensitive deliveries, prefer a single JSON payload on stdin:
    \`\`\`bash
    ovld protocol deliver --session-key <sessionKey> --ticket-id $TICKET_ID --payload-file -
    \`\`\`
@@ -261,7 +261,7 @@ When done, deliver with artifacts and change rationales:
 \`\`\`bash
 ovld protocol deliver --session-key <sessionKey> --ticket-id $TICKET_ID --summary "Narrative: what you did, next steps." --artifacts-json '[{"type":"next_steps","label":"Next steps","content":"..."}]' --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 \`\`\`
-For larger delivery JSON, prefer \`--payload-file -\` with stdin so no scratch file needs to be created or removed. If you use a JSON file for delivery transport, keep it ephemeral scratch data outside the repository and remove it after the protocol call.
+Use \`--payload-json\` for compact inline delivery objects. For larger delivery JSON, prefer \`--payload-file -\` with stdin so no scratch file needs to be created or removed. If you use a JSON file for delivery transport, keep it ephemeral scratch data outside the repository and remove it after the protocol call.
 
 Rules:
 - Always attach first and deliver last.
@@ -809,10 +809,57 @@ function cursorPaths() {
       'plugin.json'
     ),
     rulesFile: path.join(base, 'rules', 'overlord-local.mdc'),
-    settingsFile: path.join(base, 'settings.json')
+    settingsFile: path.join(base, 'settings.json'),
+    hooksFile: path.join(base, 'hooks.json')
   };
 }
 
+const CURSOR_USER_PROMPT_HOOK_RELATIVE = 'plugins/local/overlord/hooks/overlord-user-prompt-submit.sh';
+
+function isOverlordCursorBeforeSubmitHook(entry) {
+  if (!entry || typeof entry !== 'object') return false;
+  const cmd = typeof entry.command === 'string' ? entry.command : '';
+  return cmd.includes('overlord-user-prompt-submit');
+}
+
+function mergeCursorBeforeSubmitHook(paths) {
+  const hooksFile = paths.hooksFile;
+  const base = fs.existsSync(hooksFile)
+    ? readJsonFile(hooksFile)
+    : { version: 1, hooks: {} };
+  const hooks = base.hooks && typeof base.hooks === 'object' && !Array.isArray(base.hooks) ? base.hooks : {};
+  const existing = Array.isArray(hooks.beforeSubmitPrompt) ? hooks.beforeSubmitPrompt : [];
+  hooks.beforeSubmitPrompt = [
+    ...existing.filter(entry => !isOverlordCursorBeforeSubmitHook(entry)),
+    { command: CURSOR_USER_PROMPT_HOOK_RELATIVE }
+  ];
+  writeJsonFile(hooksFile, {
+    ...base,
+    version: typeof base.version === 'number' ? base.version : 1,
+    hooks
+  });
+}
+
+function removeCursorBeforeSubmitHook(paths) {
+  const hooksFile = paths.hooksFile;
+  if (!fs.existsSync(hooksFile)) return;
+  const base = readJsonFile(hooksFile);
+  const hooks = base.hooks && typeof base.hooks === 'object' && !Array.isArray(base.hooks) ? base.hooks : {};
+  if (!Array.isArray(hooks.beforeSubmitPrompt)) return;
+  hooks.beforeSubmitPrompt = hooks.beforeSubmitPrompt.filter(
+    entry => !isOverlordCursorBeforeSubmitHook(entry)
+  );
+  if (hooks.beforeSubmitPrompt.length === 0) {
+    delete hooks.beforeSubmitPrompt;
+  }
+  if (Object.keys(hooks).length === 0) {
+    delete base.hooks;
+  } else {
+    base.hooks = hooks;
+  }
+  writeJsonFile(hooksFile, base);
+}
+
 function geminiPaths() {
   const base = path.join(os.homedir(), '.gemini');
   return {
@@ -945,6 +992,7 @@ function installCodex() {
 
 function installCursor() {
   const paths = cursorPaths();
+  const backups = [];
   const sourceDir = cursorSourcePluginDir();
   fs.mkdirSync(path.dirname(paths.pluginDir), { recursive: true });
   fs.rmSync(paths.pluginDir, { recursive: true, force: true });
@@ -961,6 +1009,14 @@ function installCursor() {
     for (const filePath of removedLegacySlash.removedFiles) console.log(`      ${filePath}`);
   }
 
+  const hooksBackup = backupFile(paths.hooksFile);
+  if (hooksBackup) {
+    backups.push(hooksBackup);
+    console.log(`  ✓ Backed up: ${paths.hooksFile} → ${path.basename(hooksBackup)}`);
+  }
+  mergeCursorBeforeSubmitHook(paths);
+  console.log(`  ✓ Registered Cursor beforeSubmitPrompt hook: ${paths.hooksFile}`);
+
   const existingSettings = readJsonFile(paths.settingsFile);
   const permissions =
     existingSettings.permissions && typeof existingSettings.permissions === 'object'
@@ -983,11 +1039,11 @@ function installCursor() {
     version: pluginVersion(paths.pluginManifest) ?? '0.0.0',
     contentHash: currentContentHashForAgent('cursor'),
     installedAt: new Date().toISOString(),
-    files: [...listFilesRecursive(paths.pluginDir), paths.settingsFile]
+    files: [...listFilesRecursive(paths.pluginDir), paths.settingsFile, paths.hooksFile]
   };
   writeManifest(manifest);
 
-  return { ok: true };
+  return { ok: true, backups };
 }
 
 function installGemini() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "0.2605121033.0",
+  "version": "0.2605131058.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "homepage": "https://www.ovld.ai/docs/",
   "type": "module",

package/plugins/claude/scripts/user-prompt-submit-hook.sh

@@ -1,18 +1,53 @@
 #!/bin/bash
 # Overlord UserPromptSubmit hook — fires before Claude processes each user turn.
+# Claude Code does not expose turn_number in the hook body; we persist the last
+# posted turnIndex per session_id and send (last + 1). The first submit is
+# turnIndex 0 (initial injected ticket/objective prompt), which
+# POST /api/protocol/hook-event skips — same contract as the Cursor hook.
 
 BODY=$(cat -)
 OVERLORD_BASE_URL="${CLAUDE_PLUGIN_OPTION_OVERLORD_URL:-$OVERLORD_URL}"
 OVERLORD_TOKEN="${CLAUDE_PLUGIN_OPTION_AGENT_TOKEN:-${CLAUDE_PLUGIN_OPTION_OVERLORD_ACCESS_TOKEN:-$OVERLORD_ACCESS_TOKEN}}"
 OVERLORD_LOCAL_SECRET="${OVERLORD_LOCAL_SECRET:-}"
 
-TURN=$(printf '%s' "$BODY" | python3 -c "import json,sys; print(json.load(sys.stdin).get('turn_number', 0))" 2>/dev/null || echo "0")
-if [ "$TURN" = "0" ]; then
-  exit 0
-fi
-
 if [ -n "$OVERLORD_BASE_URL" ] && [ -n "$OVERLORD_TOKEN" ] && [ -n "$TICKET_ID" ]; then
-  PAYLOAD=$(printf '%s' "$BODY" | python3 -c "import json,sys; body=json.load(sys.stdin); print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': __import__('os').environ['TICKET_ID'], 'prompt': body.get('prompt', ''), 'turnIndex': body.get('turn_number', 0)}))" 2>/dev/null || echo '')
+  PAYLOAD=$(
+    printf '%s' "$BODY" | python3 -c "
+import hashlib
+import json
+import os
+import sys
+
+try:
+    body = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+
+text = (body.get('prompt') or '').strip()
+if not text:
+    sys.exit(0)
+
+sid = body.get('session_id') or 'unknown'
+state_dir = os.path.join(os.path.expanduser('~'), '.ovld', 'claude-user-prompt-hook')
+os.makedirs(state_dir, exist_ok=True)
+path = os.path.join(state_dir, hashlib.sha256(sid.encode()).hexdigest())
+last_posted = -1
+try:
+    with open(path, encoding='utf-8') as handle:
+        raw = (handle.read() or '').strip()
+        if raw != '':
+            last_posted = int(raw)
+except Exception:
+    last_posted = -1
+
+turn_index = last_posted + 1
+with open(path, 'w', encoding='utf-8') as handle:
+    handle.write(str(turn_index))
+
+tid = os.environ.get('TICKET_ID', '')
+print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': tid, 'prompt': text, 'turnIndex': turn_index}))
+" 2>/dev/null
+  )
   if [ -n "$PAYLOAD" ]; then
     curl -sf -m 5 \
       -X POST "$OVERLORD_BASE_URL/api/protocol/hook-event" \

package/plugins/claude/skills/overlord-ticket/SKILL.md

@@ -75,7 +75,7 @@ ovld protocol deliver --session-key <sessionKey> \
   --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 ```
 
-`ovld protocol deliver` automatically creates a local checkpoint before the API request when the workspace is JJ- or Git-managed; use `--skip-checkpoint` only when intentionally bypassing local provenance. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If the summary contains special characters, use `--summary-file -` and pipe via a single-quoted heredoc (`<<'EOF'`) to prevent shell expansion. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+`ovld protocol deliver` automatically creates a local checkpoint before the API request when the workspace is JJ- or Git-managed; use `--skip-checkpoint` only when intentionally bypassing local provenance. Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If the summary contains special characters, use `--summary-file -` and pipe via a single-quoted heredoc (`<<'EOF'`) to prevent shell expansion. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
 
 ## Mode 2: Asked From Chat To Use Overlord
 
@@ -99,7 +99,7 @@ Always include `changeRationales` when delivering. Optionally include them on up
 
 Before delivering, make sure every meaningful git-tracked file change is represented in `changeRationales`; do not send `file_changes` as an artifact.
 
-These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. For larger full delivery payloads, prefer `--payload-file -` so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file. Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
+These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. Use `--payload-json` for compact full delivery payloads, or `--payload-file -` when the JSON is larger or quote-sensitive so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file. Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
 
 ```bash
 ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \
@@ -182,4 +182,4 @@ The `attach` and `load-context` responses already include `attachments` and `obj
 - Do not add or commit changes unless the user explicitly asks you to commit.
 - Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
 
-<!-- version: 0.4.8 -->
+<!-- version: 0.4.9 -->

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local Overlord workflow plugin for Cursor terminal agents.",
   "author": {
     "name": "Cooperativ",

package/plugins/cursor/hooks/overlord-user-prompt-submit.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Overlord Cursor beforeSubmitPrompt hook — posts user composer prompts to the ticket activity feed.
+# Cursor does not expose Claude's turn_number; we persist the last posted turnIndex per conversation_id
+# and send (last + 1). The first submit is turnIndex 0 (initial injected ticket/objective prompt), which
+# POST /api/protocol/hook-event skips — same contract as Claude's turn_number 0.
+
+BODY=$(cat -)
+
+OVERLORD_BASE_URL="${OVERLORD_URL:-${OVERLORD_CONNECTOR_URL:-}}"
+OVERLORD_TOKEN="${OVERLORD_ACCESS_TOKEN:-}"
+TICKET_ID="${TICKET_ID:-}"
+OVERLORD_LOCAL_SECRET="${OVERLORD_LOCAL_SECRET:-}"
+
+if [ -n "$OVERLORD_BASE_URL" ] && [ -n "$OVERLORD_TOKEN" ] && [ -n "$TICKET_ID" ]; then
+  PAYLOAD=$(
+    printf '%s' "$BODY" | python3 -c "
+import hashlib
+import json
+import os
+import sys
+
+try:
+    body = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+
+text = (body.get('prompt') or body.get('message') or '').strip()
+if not text:
+    sys.exit(0)
+
+cid = body.get('conversation_id') or 'unknown'
+state_dir = os.path.join(os.path.expanduser('~'), '.ovld', 'cursor-user-prompt-hook')
+os.makedirs(state_dir, exist_ok=True)
+path = os.path.join(state_dir, hashlib.sha256(cid.encode()).hexdigest())
+last_posted = -1
+try:
+    with open(path, encoding='utf-8') as handle:
+        raw = (handle.read() or '').strip()
+        if raw != '':
+            last_posted = int(raw)
+except Exception:
+    last_posted = -1
+
+turn_index = last_posted + 1
+with open(path, 'w', encoding='utf-8') as handle:
+    handle.write(str(turn_index))
+
+tid = os.environ.get('TICKET_ID', '')
+print(json.dumps({'hookType': 'UserPromptSubmit', 'ticketId': tid, 'prompt': text, 'turnIndex': turn_index}))
+" 2>/dev/null
+  )
+  if [ -n "$PAYLOAD" ]; then
+    curl -sf -m 5 \
+      -X POST "$OVERLORD_BASE_URL/api/protocol/hook-event" \
+      -H "Authorization: Bearer $OVERLORD_TOKEN" \
+      -H "X-Overlord-Local-Secret: $OVERLORD_LOCAL_SECRET" \
+      -H "Content-Type: application/json" \
+      -d "$PAYLOAD" \
+      >/dev/null 2>&1 &
+    disown
+  fi
+fi
+
+printf '%s\n' '{"continue":true}'
+exit 0

package/plugins/cursor/skills/overlord-ticket/SKILL.md

@@ -13,7 +13,7 @@ Use this skill whenever Cursor needs to work with Overlord, whether the session
 2. Keep the returned `session.sessionKey` for all follow-up calls.
 3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
 4. Post updates while working with `ovld protocol update --phase execute`.
-5. If the user sends a follow-up message after the initial ticket, publish it immediately with `--event-type user_follow_up`.
+5. Follow-up messages after the initial ticket are captured automatically by the installed Cursor `beforeSubmitPrompt` hook (see `~/.cursor/hooks.json`). Do not post `user_follow_up` manually unless the hook is unavailable.
 6. If blocked, call `ovld protocol ask` and stop.
 7. Deliver last with `ovld protocol deliver`, including `changeRationales` for each meaningful behavioral file change.
 
@@ -42,7 +42,7 @@ Supported `--phase` values:
 
 Event types:
 - `update` for standard progress updates
-- `user_follow_up` for human follow-up messages after the initial ticket
+- `user_follow_up` — only when the Cursor `beforeSubmitPrompt` hook is unavailable; the hook normally posts follow-ups to the activity feed
 - `alert` for warnings or non-blocking issues
 
 Ask when blocked:
@@ -61,7 +61,7 @@ ovld protocol deliver --session-key <sessionKey> \
   --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 ```
 
-`ovld protocol deliver` automatically creates a local checkpoint before the API request when the workspace is JJ- or Git-managed; use `--skip-checkpoint` only when intentionally bypassing local provenance. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed.
+`ovld protocol deliver` automatically creates a local checkpoint before the API request when the workspace is JJ- or Git-managed; use `--skip-checkpoint` only when intentionally bypassing local provenance. Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed.
 
 ## Mode 2: Asked From Chat To Use Overlord
 
@@ -152,4 +152,4 @@ Objective attachment uploads also expose two-step variants — `attachment-prepa
 - If you must run `ovld auth login`, always include `--organization-id <id>` — use the organization ID from the ticket prompt context to select the organization non-interactively and avoid a blocking TTY prompt.
 - Delivery is the concluding step. After delivering, stop unless the user follows up or the ticket is reopened.
 
-<!-- version: 0.4.7 -->
+<!-- version: 0.4.9 -->

package/plugins/overlord/skills/overlord-ticket/SKILL.md

@@ -65,7 +65,7 @@ ovld protocol deliver --session-key <sessionKey> \
   --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 ```
 
-`ovld protocol deliver` automatically creates a local checkpoint before the API request when the workspace is JJ- or Git-managed; use `--skip-checkpoint` only when intentionally bypassing local provenance. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
+`ovld protocol deliver` automatically creates a local checkpoint before the API request when the workspace is JJ- or Git-managed; use `--skip-checkpoint` only when intentionally bypassing local provenance. Use `--payload-json` when the full delivery object fits comfortably inline. For larger delivery payloads, prefer `--payload-file -` and stream the full JSON on stdin so no scratch file needs to be created or removed. If you use `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery.
 
 ## Mode 2: Asked From Chat To Use Overlord
 
@@ -111,7 +111,7 @@ Always include `changeRationales` when delivering. Optionally include them on up
 
 Before delivering, make sure every meaningful git-tracked file change is represented in `changeRationales`; do not send `file_changes` as an artifact.
 
-These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. For larger full delivery payloads, prefer `--payload-file -` so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file. Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
+These are structured protocol payloads that Overlord stores as first-class rows in the `file_changes` table. Prefer inline JSON or the dedicated command below. Use `--payload-json` for compact full delivery payloads, or `--payload-file -` when the JSON is larger or quote-sensitive so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file. Ordinary deliver artifacts should use `next_steps`, `test_results`, `migration`, `note`, `url`, or `decision`.
 
 ```bash
 ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \
@@ -158,4 +158,4 @@ The `attach` and `load-context` responses already include `attachments` and `obj
 - If a protocol or MCP call fails with auth/session errors, run `ovld auth repair` yourself before asking the user to log in again or proceed without Overlord updates.
 - If you must run `ovld auth login`, always include `--organization-id <id>` — use the organization ID from the ticket prompt context to select the organization non-interactively and avoid a blocking TTY prompt.
 
-<!-- version: 0.4.8 -->
+<!-- version: 0.4.9 -->