autark-cli 0.1.4 → 0.1.6

package/README.md

@@ -18,47 +18,53 @@ autark login send your@email.com
 autark login verify your@email.com --code 123456
 ```
 
-## Use
+## Runbook use
 
 Autark is ID-first. Use `product list` / `context` to discover IDs, then pass IDs for writes. `slug/H01` remains a convenience alias.
 
 ```sh
-# products
 autark product upsert --slug chrome-relay --name "Chrome Relay" --tagline "..."
 autark product list   # prints slug, visibility, id, name
 autark context chrome-relay
 
-autark context --product-id <product_id>
-
-# hypotheses
 autark hypothesis create --product-id <product_id> --md @./H01.md --code H01 --title "..."
-autark context --hypothesis-id <hypothesis_id>
-autark hypothesis status --hypothesis-id <hypothesis_id> --status active   # active|inactive|dead
-
-# aliases still work
-autark hypothesis create --product chrome-relay --md @./H01.md --code H01
-autark context chrome-relay/H01
-autark hypothesis status chrome-relay/H01 --status inactive
-
-# runs
 autark run start --hypothesis-id <hypothesis_id>
+autark log action --run-id <run_id> --channel github --title "..." --url https://github.com/...
 autark run finish --run-id <run_id> --narrative @./narrative.md
+```
 
-# actions (anything the agent did during a run)
-autark log action --run-id <run_id> --channel email --title "..." \
-  --recipient person@example.com --agentmail-thread-id <thread_id>
-autark log action --run-id <run_id> --channel github --title "..." --url https://github.com/...
+## Mail use
 
-autark me
-autark logout
+`autark mail` covers the AgentMail surface Autark needs. It does not require a separate AgentMail CLI login.
+
+```sh
+autark mail setup --prefix laksh
+
+autark mail send --run-id <run_id> \
+  --to person@example.com \
+  --subject "Subject" \
+  --text @./body.txt
+
+autark mail reply --run-id <run_id> --message-id <message_id> --text @./reply.txt
+
+autark mail threads --limit 20
+autark mail thread <thread_id>
+autark mail messages --limit 20
+autark mail message <message_id>
+autark mail raw <message_id>
+autark mail attachment --message-id <message_id> --attachment-id <attachment_id> --out file.bin
 ```
 
+Mail sends/replies call AgentMail directly with the user's inbox-scoped key from `~/.autark/credentials.json`, then log an Autark `email` action containing `agentmail_thread_id` and `agentmail_inbox_id`.
+
 ## ENV
 
 - `AUTARK_API_URL` — override the default Worker URL (`https://autark-api.kushalsokke.workers.dev`)
+- `AGENTMAIL_API_URL` — override AgentMail API base
+- `AGENTMAIL_API_KEY`, `AGENTMAIL_EMAIL`, `AGENTMAIL_INBOX_ID` — override local mail credentials for debugging
 
 ## Architecture
 
 The CLI is a thin HTTP client over a Cloudflare Worker that holds the InstantDB admin token. Magic-link auth via InstantDB. Token saved to `~/.autark/credentials.json` after login.
 
-The web at autark.kushalsm.com reads from InstantDB. Writes should go through the Worker/CLI path; dashboard direct writes are being phased out.
+The Worker uses the AgentMail org key only for provisioning and dashboard thread reads. Local mail send/reply uses the user's inbox-scoped key.

package/autark.mjs

@@ -1,11 +1,9 @@
 #!/usr/bin/env node
 // autark CLI — thin HTTP client over the autark-api Worker.
 //
-// Auth: magic-link flow saves a refresh_token to ~/.autark/credentials.json.
-// Every subsequent command sends it as `Authorization: Bearer <token>`.
-//
-// The CLI is ID-first: once a product/hypothesis/run exists, use its id.
-// slug/Hxx remains as a convenience alias for humans.
+// The runbook API is ID-first. slug/Hxx remains as a convenience alias.
+// Mail commands call AgentMail directly with the user's inbox-scoped key;
+// autark-api uses the org key only for provisioning and dashboard thread reads.
 
 import fs from 'node:fs'
 import os from 'node:os'
@@ -13,6 +11,7 @@ import path from 'node:path'
 import process from 'node:process'
 
 const API = process.env.AUTARK_API_URL || 'https://autark-api.kushalsokke.workers.dev'
+const AGENTMAIL_API = process.env.AGENTMAIL_API_URL || 'https://api.agentmail.to/v0'
 const CREDS_PATH = path.join(os.homedir(), '.autark', 'credentials.json')
 
 const args = process.argv.slice(2)
@@ -36,17 +35,27 @@ async function main() {
   if (group === 'product') {
     if (command === 'upsert') return productUpsert(rest)
     if (command === 'list')   return productList()
+    if (!command || command === '--help' || command === '-h') return productUsage()
   }
   if (group === 'hypothesis') {
     if (command === 'create') return hypothesisCreate(rest)
     if (command === 'status') return hypothesisStatus(rest)
+    if (!command || command === '--help' || command === '-h') return hypothesisUsage()
   }
   if (group === 'run') {
     if (command === 'start')  return runStart(rest)
     if (command === 'finish') return runFinish(rest)
+    if (!command || command === '--help' || command === '-h') return runUsage()
+  }
+  if (group === 'log') {
+    if (command === 'action') return logAction(rest)
+    if (!command || command === '--help' || command === '-h') return logUsage()
   }
-  if (group === 'log' && command === 'action') return logAction(rest)
-  if (group === 'context') return context([command, ...rest].filter(Boolean))
+  if (group === 'context') {
+    if (!command || command === '--help' || command === '-h') return contextUsage()
+    return context([command, ...rest].filter(Boolean))
+  }
+  if (group === 'mail') return mail(command, rest)
 
   usage()
   process.exit(1)
@@ -69,6 +78,7 @@ async function loginVerify(rest) {
   const result = await api('POST', '/v1/auth/login/verify', { email, code }, { auth: false })
   if (!result.token) throw new Error('verify succeeded but no token returned')
   saveCredentials({
+    ...loadCredentials(),
     user_id: result.user.id,
     email:   result.user.email,
     token:   result.token,
@@ -194,15 +204,235 @@ async function logAction(rest) {
   const result = await api('POST', `/v1/runs/${encodeURIComponent(run)}/actions`, {
     channel,
     title,
-    url:                 opts.url || undefined,
-    agentmail_thread_id: opts['agentmail-thread-id'] || opts['thread-id'] || opts.thread_id || undefined,
-    recipient:           opts.recipient || undefined,
-    metadata:            opts.metadata ? JSON.parse(readValue(opts.metadata)) : undefined,
-    occurred_at:         opts['occurred-at'] || opts.occurred_at || undefined,
+    url:                  opts.url || undefined,
+    agentmail_thread_id:  opts['agentmail-thread-id'] || opts['thread-id'] || opts.thread_id || undefined,
+    agentmail_inbox_id:   opts['agentmail-inbox-id'] || opts.inbox_id || opts.agentmail_inbox_id || undefined,
+    recipient:            opts.recipient || undefined,
+    metadata:             opts.metadata ? JSON.parse(readValue(opts.metadata)) : undefined,
+    occurred_at:          opts['occurred-at'] || opts.occurred_at || undefined,
   })
   console.log(result.id)
 }
 
+// ============================================================ mail
+
+async function mail(command, rest) {
+  if (!command || command === '--help' || command === 'help') return mailUsage()
+  if (command === 'setup')     return mailSetup(rest)
+  if (command === 'send')      return mailSend(rest)
+  if (command === 'reply')     return mailReply(rest, 'reply')
+  if (command === 'reply-all') return mailReply(rest, 'reply-all')
+  if (command === 'forward')   return mailForward(rest)
+  if (command === 'threads')   return mailThreads(rest)
+  if (command === 'thread')    return mailThread(rest)
+  if (command === 'messages')  return mailMessages(rest)
+  if (command === 'message')   return mailMessage(rest)
+  if (command === 'raw')       return mailRaw(rest)
+  if (command === 'attachment') return mailAttachment(rest)
+  if (command === 'request')   return mailRequest(rest)
+  mailUsage()
+  process.exit(1)
+}
+
+async function mailSetup(rest) {
+  const opts = parseArgs(rest)
+  const existing = loadCredentials() || {}
+  if (existing.agentmail_token && existing.agentmail_email && !opts.force) {
+    console.log(existing.agentmail_email)
+    return
+  }
+  const prefix = required(opts.prefix || defaultInboxPrefix(existing.email), '--prefix')
+  const result = await api('POST', '/v1/onboard/agentmail', {
+    prefix,
+    display_name: opts['display-name'] || opts.display_name || existing.email || prefix,
+    purpose: opts.purpose || 'runner',
+  })
+  saveCredentials({
+    ...existing,
+    agentmail_email:      result.agentmail_email || result.email,
+    agentmail_inbox_id:   result.agentmail_inbox_id || result.inbox_id || result.email,
+    agentmail_api_key_id: result.agentmail_api_key_id || result.api_key_id,
+    agentmail_token:      result.agentmail_token,
+    agentmail_saved_at:   new Date().toISOString(),
+  })
+  console.log(result.agentmail_email || result.email)
+}
+
+async function mailSend(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const to = listOpt(opts.to, '--to')
+  const subject = opts.subject || ''
+  const body = mailBody(opts, { to, subject })
+  const result = await agentmailRequest('POST', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/send`, body)
+  const action = await maybeLogMailAction(opts, {
+    kind: 'send',
+    defaultTitle: opts.title || `Email: ${subject || to.join(', ')}`,
+    recipient: to.join(','),
+    subject,
+    response: result,
+  })
+  printJson({ ...result, autark_action_id: action?.id })
+}
+
+async function mailReply(rest, mode) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id || opts._[0], '--message-id')
+  const body = mailBody(opts)
+  const endpoint = mode === 'reply-all' ? 'reply-all' : 'reply'
+  const result = await agentmailRequest('POST', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}/${endpoint}`, body)
+  const action = await maybeLogMailAction(opts, {
+    kind: mode,
+    defaultTitle: opts.title || `${mode === 'reply-all' ? 'Reply-all' : 'Reply'}: ${messageId}`,
+    recipient: listOpt(opts.to).join(','),
+    response: result,
+    metadata: { message_id: messageId },
+  })
+  printJson({ ...result, autark_action_id: action?.id })
+}
+
+async function mailForward(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id || opts._[0], '--message-id')
+  const to = listOpt(opts.to, '--to')
+  const body = mailBody(opts, { to, subject: opts.subject || '' })
+  const result = await agentmailRequest('POST', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}/forward`, body)
+  const action = await maybeLogMailAction(opts, {
+    kind: 'forward',
+    defaultTitle: opts.title || `Forward: ${opts.subject || messageId}`,
+    recipient: to.join(','),
+    response: result,
+    metadata: { message_id: messageId },
+  })
+  printJson({ ...result, autark_action_id: action?.id })
+}
+
+async function mailThreads(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const qs = queryString({ limit: opts.limit, page_token: opts['page-token'] || opts.page_token })
+  printJson(await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/threads${qs}`))
+}
+
+async function mailThread(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const threadId = required(opts['thread-id'] || opts.thread_id || opts._[0], 'thread_id')
+  printJson(await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/threads/${encodeURIComponent(threadId)}`))
+}
+
+async function mailMessages(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const qs = queryString({ limit: opts.limit, page_token: opts['page-token'] || opts.page_token })
+  printJson(await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages${qs}`))
+}
+
+async function mailMessage(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id || opts._[0], 'message_id')
+  printJson(await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}`))
+}
+
+async function mailRaw(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id || opts._[0], 'message_id')
+  const raw = await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}/raw`, undefined, { parseJson: false })
+  process.stdout.write(raw)
+}
+
+async function mailAttachment(rest) {
+  const opts = parseArgs(rest)
+  const creds = requireAgentmailCredentials()
+  const messageId = required(opts['message-id'] || opts.message_id, '--message-id')
+  const attachmentId = required(opts['attachment-id'] || opts.attachment_id, '--attachment-id')
+  const body = await agentmailRequest('GET', `/inboxes/${encodeURIComponent(creds.inboxId)}/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`, undefined, { parseJson: false })
+  if (opts.out) fs.writeFileSync(opts.out, body)
+  else process.stdout.write(body)
+}
+
+async function mailRequest(rest) {
+  const opts = parseArgs(rest)
+  const method = (opts.method || opts._[0] || 'GET').toUpperCase()
+  const requestPath = required(opts.path || opts._[1], '--path')
+  const body = opts.body ? JSON.parse(readValue(opts.body)) : undefined
+  const parseJson = opts.raw ? false : true
+  const result = await agentmailRequest(method, requestPath.startsWith('/') ? requestPath : `/${requestPath}`, body, { parseJson })
+  if (parseJson) printJson(result)
+  else process.stdout.write(result)
+}
+
+function mailBody(opts, base = {}) {
+  const body = { ...base }
+  if (opts.text !== undefined) body.text = readValue(opts.text)
+  if (opts.html !== undefined) body.html = readValue(opts.html)
+  if (opts.subject !== undefined) body.subject = opts.subject
+  for (const key of ['cc', 'bcc', 'reply-to', 'label', 'attachment']) {
+    const snake = key.replaceAll('-', '_')
+    const value = opts[key] ?? opts[snake]
+    if (value !== undefined) body[snake] = listOpt(value)
+  }
+  if (opts.headers !== undefined) body.headers = JSON.parse(readValue(opts.headers))
+  return body
+}
+
+async function maybeLogMailAction(opts, { kind, defaultTitle, recipient, subject, response, metadata = {} }) {
+  const runId = opts['run-id'] || opts.run_id || opts.run
+  if (!runId) return null
+  const creds = requireAgentmailCredentials()
+  const threadId = response?.thread_id
+  if (!threadId) throw new Error('AgentMail response missing thread_id; refusing to log email action')
+  return api('POST', `/v1/runs/${encodeURIComponent(runId)}/actions`, {
+    channel: 'email',
+    title: opts.title || defaultTitle,
+    recipient: recipient || undefined,
+    agentmail_thread_id: threadId,
+    agentmail_inbox_id: creds.inboxId,
+    metadata: compact({
+      kind,
+      subject,
+      message_id: response?.message_id,
+      ...metadata,
+    }),
+  })
+}
+
+async function agentmailRequest(method, pathStr, body, { parseJson = true } = {}) {
+  const creds = requireAgentmailCredentials()
+  const res = await fetch(AGENTMAIL_API + pathStr, {
+    method,
+    headers: {
+      authorization: `Bearer ${creds.token}`,
+      'content-type': 'application/json',
+    },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  })
+  const text = await res.text()
+  let data = text
+  if (parseJson) {
+    try { data = text ? JSON.parse(text) : null } catch { data = { raw: text } }
+  }
+  if (!res.ok) {
+    const msg = parseJson ? (data?.error || data?.message || JSON.stringify(data)) : text
+    throw new Error(`AgentMail ${res.status}: ${msg}`)
+  }
+  return data
+}
+
+function requireAgentmailCredentials() {
+  const creds = loadCredentials()
+  const token = process.env.AGENTMAIL_API_KEY || creds?.agentmail_token
+  const email = process.env.AGENTMAIL_EMAIL || creds?.agentmail_email
+  const inboxId = process.env.AGENTMAIL_INBOX_ID || creds?.agentmail_inbox_id || email
+  if (!token) throw new Error('missing agentmail_token. run: autark mail setup --prefix <name>')
+  if (!inboxId) throw new Error('missing agentmail_inbox_id. run: autark mail setup --prefix <name>')
+  return { token, email, inboxId }
+}
+
 // ============================================================ context
 
 async function context(rest) {
@@ -223,12 +453,8 @@ async function context(rest) {
   const productSlug = parts[0]
   const code = parts[1]
 
-  if (!code) {
-    return printProductContext(await api('GET', `/v1/context/${encodeURIComponent(productSlug)}`))
-  }
-
-  const result = await api('GET', `/v1/context/${encodeURIComponent(productSlug)}/${encodeURIComponent(code)}`)
-  return printHypothesisContext(result)
+  if (!code) return printProductContext(await api('GET', `/v1/context/${encodeURIComponent(productSlug)}`))
+  return printHypothesisContext(await api('GET', `/v1/context/${encodeURIComponent(productSlug)}/${encodeURIComponent(code)}`))
 }
 
 function printProductContext(r) {
@@ -264,9 +490,7 @@ function printHypothesisContext(result) {
         console.log(`  [${a.channel}] ${a.title}${pointer ? `  →  ${pointer}` : ''}`)
       }
     }
-    if (run.narrative_md) {
-      console.log(`\n${run.narrative_md}`)
-    }
+    if (run.narrative_md) console.log(`\n${run.narrative_md}`)
   }
 }
 
@@ -301,14 +525,10 @@ function saveCredentials(creds) {
 
 function loadCredentials() {
   if (!fs.existsSync(CREDS_PATH)) return null
-  try {
-    return JSON.parse(fs.readFileSync(CREDS_PATH, 'utf8'))
-  } catch {
-    return null
-  }
+  try { return JSON.parse(fs.readFileSync(CREDS_PATH, 'utf8')) } catch { return null }
 }
 
-// ============================================================ arg parsing
+// ============================================================ utilities
 
 function parseArgs(list) {
   const opts = { _: [] }
@@ -320,12 +540,11 @@ function parseArgs(list) {
     }
     const key = arg.slice(2)
     const next = list[i + 1]
-    if (!next || next.startsWith('--')) {
-      opts[key] = true
-    } else {
-      opts[key] = next
-      i++
-    }
+    const value = (!next || next.startsWith('--')) ? true : next
+    if (value !== true) i++
+    if (opts[key] === undefined) opts[key] = value
+    else if (Array.isArray(opts[key])) opts[key].push(value)
+    else opts[key] = [opts[key], value]
   }
   return opts
 }
@@ -338,12 +557,43 @@ function required(value, label) {
 }
 
 function readValue(value) {
-  if (typeof value === 'string' && value.startsWith('@')) {
-    return fs.readFileSync(value.slice(1), 'utf8')
-  }
+  if (typeof value === 'string' && value.startsWith('@')) return fs.readFileSync(value.slice(1), 'utf8')
   return String(value)
 }
 
+function listOpt(value, label) {
+  if (value === undefined || value === null || value === '') {
+    if (label) throw new Error(`${label} is required`)
+    return []
+  }
+  const values = Array.isArray(value) ? value : [value]
+  return values.flatMap(v => String(v).split(',')).map(v => v.trim()).filter(Boolean)
+}
+
+function queryString(params) {
+  const q = new URLSearchParams()
+  for (const [k, v] of Object.entries(params)) if (v !== undefined && v !== null && v !== '') q.set(k, v)
+  const s = q.toString()
+  return s ? `?${s}` : ''
+}
+
+function defaultInboxPrefix(email) {
+  if (!email) return ''
+  return String(email).split('@')[0].toLowerCase().replace(/[^a-z0-9._-]/g, '').replace(/^[._-]+/, '').slice(0, 30)
+}
+
+function compact(obj) {
+  const out = {}
+  for (const [k, v] of Object.entries(obj || {})) {
+    if (v !== undefined && v !== null && v !== '' && !(Array.isArray(v) && !v.length)) out[k] = v
+  }
+  return out
+}
+
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2))
+}
+
 function splitHypothesisRef(ref) {
   const m = String(ref).match(/^([\w.-]+)\/(H\d{2})$/)
   if (!m) throw new Error(`expected product/Hxx, got ${ref}`)
@@ -353,36 +603,105 @@ function splitHypothesisRef(ref) {
 // ============================================================ usage
 
 function loginUsage() {
-  console.log(`autark login send <email>
-autark login verify <email> --code <6-digit-code>`)
+  console.log(`autark login send <email>\nautark login verify <email> --code <6-digit-code>`)
+}
+
+function mailUsage() {
+  console.log(`autark mail
+
+  setup       --prefix <name> [--force]
+  send        --to <email[,email]> --subject <s> --text @body.txt [--run-id <id>]
+  reply       --message-id <id> --text @reply.txt [--run-id <id>]
+  reply-all   --message-id <id> --text @reply.txt [--run-id <id>]
+  forward     --message-id <id> --to <email> [--text @body.txt] [--run-id <id>]
+  threads     [--limit N]
+  thread      <thread_id>
+  messages    [--limit N]
+  message     <message_id>
+  raw         <message_id>
+  attachment  --message-id <id> --attachment-id <id> [--out file]
+  request     <METHOD> <path> [--body @json] [--raw]
+
+Mail uses the inbox-scoped token in ~/.autark/credentials.json.`)
 }
 
 function usage() {
   console.log(`autark — agent runbook CLI
 
-  autark login send <email>                                send a magic code
-  autark login verify <email> --code <code>                complete login
-  autark logout                                            clear local credentials
-  autark me                                                show signed-in user
+  login send|verify          sign in / complete magic code
+  logout                     clear local credentials
+  me                         show signed-in user
+
+  product upsert|list        create/edit/list products
+  hypothesis create|status   create or update hypotheses
+  run start|finish           start / finish a run
+  log action                 record one outreach touch
+  context [<slug>|...]       pull product or hypothesis context
+
+  mail setup|send|reply|...  send/read mail via your AgentMail inbox
 
-  autark product upsert --slug <slug> --name <name> [--url <url>] [--tagline <text>] [--brief @./brief.md] [--visibility private|public]
-  autark product list                                      prints slug, visibility, id, name
+For details on any group:  autark <group> --help
+Examples:                   autark product --help
+                            autark mail --help`)
+}
+
+function productUsage() {
+  console.log(`autark product
+
+  upsert --slug <slug> --name <name> [--url <url>] [--tagline <text>]
+         [--brief @./brief.md] [--visibility private|public]
+
+  list                       prints slug, visibility, id, name
+
+The brief is the markdown the agent reads at the top of every run
+to understand what the product is and who it might serve.`)
+}
 
-  autark hypothesis create --product-id <id> --md @./hyp.md [--code H01] [--title <t>]
-  autark hypothesis create --product <slug> --md @./hyp.md [--code H01] [--title <t>]   # alias
-  autark hypothesis status --hypothesis-id <id> --status active|inactive|dead
-  autark hypothesis status <slug>/<H01> --status active|inactive|dead                  # alias
+function hypothesisUsage() {
+  console.log(`autark hypothesis
+
+  create --product-id <id>   --md @./hyp.md [--code H01] [--title <t>] [--status active|inactive|dead]
+  create --product <slug>    --md @./hyp.md [--code H01] [--title <t>]    # slug alias
+
+  status --hypothesis-id <id>      --status active|inactive|dead
+  status <slug>/<H01>              --status active|inactive|dead          # slug/code alias
+
+Hypotheses are frozen on create. Only --status changes after.
+If --code is omitted, autark picks the next H## for the product.`)
+}
+
+function runUsage() {
+  console.log(`autark run
+
+  start  --hypothesis-id <id>
+  start  --hypothesis <slug>/<H01>                                # slug/code alias
+         → prints RUN_ID to stdout
+
+  finish --run-id <id> --narrative @./run.md
+         → seals the run with the narrative blob`)
+}
+
+function logUsage() {
+  console.log(`autark log
+
+  action --run-id <id> --channel <c> --title <t>
+         [--url <u>]                          # github / reddit / hn / blog / gist / linkedin
+         [--agentmail-thread-id <uuid>]       # email
+         [--agentmail-inbox-id <email>]       # email — defaults to your inbox
+         [--recipient <email>]                # email
+         [--metadata @./meta.json]            # any channel-specific extras
+
+One row per external touch. Body content stays in AgentMail/GitHub/etc;
+this just records the pointer + the title agents see on the dashboard.`)
+}
 
-  autark run start --hypothesis-id <id>
-  autark run start --hypothesis <slug>/<H01>                                           # alias
-  autark run finish --run-id <id> --narrative @./run.md
+function contextUsage() {
+  console.log(`autark context
 
-  autark log action --run-id <id> --channel <c> --title <t> [--url <u>]
-                    [--agentmail-thread-id <uuid>] [--recipient <email>]
-                    [--metadata @./meta.json]
+  <slug>                     product brief + every hypothesis (active/inactive/dead)
+  <slug>/<H01>               one hypothesis: text + every run + every action
+  --product-id <id>          product brief + every hypothesis
+  --hypothesis-id <id>       one hypothesis: text + every run + every action
 
-  autark context --product-id <id>
-  autark context --hypothesis-id <id>
-  autark context <slug>
-  autark context <slug>/<H01>`)
+Use product-level first to pick which H## to drill into.`)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autark-cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "CLI for autark — hypothesis-driven product runbooks. Track products, hypotheses, runs, and actions from the terminal.",
   "type": "module",
   "license": "MIT",