@sixb/cli-core 0.1.8 → 0.1.10

package/src/commands/memory.ts

@@ -0,0 +1,358 @@
+import { lstat, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { isHelp } from "../arguments"
+import {
+  AGENT_MEMORY_ENTRY,
+  AGENT_MEMORY_MANIFEST,
+  AGENT_MEMORY_STARTER,
+  type AgentMemoryManifest,
+  type AgentMemoryManifestRepo,
+  type AgentMemoryRepo,
+  agentMemoryFileHash,
+} from "../memory"
+import { CliError, EXIT_API, fail, writeJson, writeText } from "../output"
+import { createInstanceApiClient, type SandboxInstanceCliMode } from "../run"
+import { asRecord, isFileError } from "./shared"
+
+const HELP = `Usage:
+  sixb memory save <repo> -m <message>   Save local edits as one revision
+  sixb memory pull [repo]                Bring the local copy up to the latest revision
+
+<repo> is user or project. Files live under $SIXB_MEMORY_DIR/<repo>/.
+
+A save is rejected for files another conversation changed since they were loaded. Their
+current contents are written next to yours as <file>.theirs: merge each into its file, delete
+it, then save again. Changes others made to other files are brought in by save and pull.`
+
+interface RemoteRepo {
+  readonly revision: number
+  readonly files: ReadonlyMap<string, string>
+}
+
+interface MemoryConflict {
+  readonly path: string
+  /** Where their version was written, or `null` when another save deleted the file. */
+  readonly theirs: string | null
+}
+
+const THEIRS = ".theirs"
+const CONFLICT_HINT = "Merge each .theirs file into its file, delete it, then save again."
+
+export async function memory(args: readonly string[], mode: SandboxInstanceCliMode): Promise<void> {
+  const [sub, ...rest] = args
+  if (!sub || isHelp(sub) || rest.some(isHelp)) return writeText(HELP)
+  const local = localMemory()
+  if (sub === "save") return save(local, rest, mode)
+  if (sub === "pull") return pull(local, rest, mode)
+  fail(`Unknown memory command '${sub}'. Run 'sixb memory --help'.`)
+}
+
+async function save(
+  local: LocalMemory,
+  args: readonly string[],
+  mode: SandboxInstanceCliMode
+): Promise<void> {
+  const { repo, message } = parseSaveArgs(args)
+  const manifest = await local.readManifest()
+  const loaded = manifest.repos[repo]
+  if (!loaded)
+    fail(
+      `Memory repo '${repo}' is not installed.`,
+      "invalid_arguments",
+      `Run 'sixb memory pull ${repo}'.`
+    )
+  const files = await local.readRepo(repo)
+  const unresolved = [...files.keys()].filter((path) => path.endsWith(THEIRS))
+  if (unresolved.length > 0) {
+    fail(`Resolve ${unresolved.join(", ")} first.`, "unresolved_conflicts", CONFLICT_HINT)
+  }
+  const changes = [...new Set([...files.keys(), ...Object.keys(loaded.files)])]
+    .sort()
+    .flatMap((path) => {
+      const contents = files.get(path)
+      const changed =
+        (contents === undefined ? undefined : agentMemoryFileHash(contents)) !== loaded.files[path]
+      return changed ? [{ path, contents: contents ?? null }] : []
+    })
+  if (changes.length === 0) {
+    return writeJson({
+      repo,
+      saved: false,
+      changed: [],
+      hint: "No file changed since it was loaded.",
+    })
+  }
+
+  const api = createInstanceApiClient(mode)
+  let saved: Record<string, unknown>
+  try {
+    saved = asRecord(
+      await api.post(`/api/agent-memory/${repo}/revisions`, {
+        baseRevision: loaded.revision,
+        message,
+        changes,
+      })
+    )
+  } catch (error) {
+    if (!(error instanceof CliError) || error.body.status !== 409) throw error
+    const { revision, conflicts } = await update(local, repo, manifest, await fetchRepo(api, repo))
+    process.exitCode = 1
+    return writeJson({ repo, saved: false, revision, conflicts, hint: CONFLICT_HINT })
+  }
+
+  // The saved files are now what the repo holds, so updating does not report them as conflicts.
+  const savedFiles = { ...loaded.files }
+  for (const change of changes) {
+    if (change.contents === null) delete savedFiles[change.path]
+    else savedFiles[change.path] = agentMemoryFileHash(change.contents)
+  }
+  const after: AgentMemoryManifest = {
+    repos: { ...manifest.repos, [repo]: { ...loaded, files: savedFiles } },
+  }
+  const { revision, conflicts } = await update(local, repo, after, await fetchRepo(api, repo))
+  const warnings = Array.isArray(saved.warnings) ? saved.warnings : []
+  writeJson({
+    repo,
+    saved: true,
+    revision,
+    changed: changes.map((change) => change.path),
+    ...(warnings.length > 0 ? { warnings } : {}),
+    ...(conflicts.length > 0 ? { conflicts, hint: CONFLICT_HINT } : {}),
+  })
+}
+
+async function pull(
+  local: LocalMemory,
+  args: readonly string[],
+  mode: SandboxInstanceCliMode
+): Promise<void> {
+  if (args.length > 1) fail("Invalid arguments for 'memory pull'.")
+  const manifest = await local.readManifest()
+  const repos = args[0] === undefined ? installedRepos(manifest) : [parseRepo(args[0])]
+  if (repos.length === 0) {
+    fail("No memory repo is installed.", "invalid_arguments", "Run 'sixb memory pull user'.")
+  }
+
+  const api = createInstanceApiClient(mode)
+  let current = manifest
+  for (const repo of repos) {
+    const result = await update(local, repo, current, await fetchRepo(api, repo))
+    current = result.manifest
+    writeJson({
+      repo,
+      revision: result.revision,
+      updated: result.updated,
+      conflicts: result.conflicts,
+      ...(result.conflicts.length > 0 ? { hint: CONFLICT_HINT } : {}),
+    })
+  }
+}
+
+/**
+ * Bring the local copy of `repo` to `remote`, three ways against the manifest: a file only the
+ * repo changed is updated, a file only this copy changed is kept, and a file both changed gets
+ * the repo's version next to it as `.theirs`. The manifest then records `remote`, so the next save
+ * sends what this copy holds against the latest revision.
+ */
+async function update(
+  local: LocalMemory,
+  repo: AgentMemoryRepo,
+  manifest: AgentMemoryManifest,
+  remote: RemoteRepo
+): Promise<{
+  readonly manifest: AgentMemoryManifest
+  readonly revision: number
+  readonly updated: readonly string[]
+  readonly conflicts: readonly MemoryConflict[]
+}> {
+  const base = manifest.repos[repo]?.files ?? {}
+  const files = await local.readRepo(repo)
+  const updated: string[] = []
+  const conflicts: MemoryConflict[] = []
+
+  for (const path of [
+    ...new Set([...files.keys(), ...remote.files.keys(), ...Object.keys(base)]),
+  ].sort()) {
+    if (path.endsWith(THEIRS)) continue
+    const mine = files.get(path)
+    const theirs = remote.files.get(path)
+    const mineHash = mine === undefined ? undefined : agentMemoryFileHash(mine)
+    const theirsHash = theirs === undefined ? undefined : agentMemoryFileHash(theirs)
+    if (theirsHash === base[path] || theirsHash === mineHash) continue
+    if (mineHash === base[path]) {
+      await local.write(repo, path, theirs)
+      updated.push(path)
+    } else if (theirs === undefined) {
+      conflicts.push({ path, theirs: null })
+    } else {
+      await local.write(repo, `${path}${THEIRS}`, theirs)
+      conflicts.push({ path, theirs: `${path}${THEIRS}` })
+    }
+  }
+  if (
+    !remote.files.has(AGENT_MEMORY_ENTRY) &&
+    !(await local.readRepo(repo)).has(AGENT_MEMORY_ENTRY)
+  ) {
+    await local.write(repo, AGENT_MEMORY_ENTRY, AGENT_MEMORY_STARTER)
+  }
+
+  const next: AgentMemoryManifest = {
+    repos: {
+      ...manifest.repos,
+      [repo]: {
+        revision: remote.revision,
+        files: Object.fromEntries(
+          [...remote.files].map(([path, contents]) => [path, agentMemoryFileHash(contents)])
+        ),
+      },
+    },
+  }
+  await local.writeManifest(next)
+  return { manifest: next, revision: remote.revision, updated, conflicts }
+}
+
+async function fetchRepo(
+  api: ReturnType<typeof createInstanceApiClient>,
+  repo: AgentMemoryRepo
+): Promise<RemoteRepo> {
+  const body = asRecord(await api.get(`/api/agent-memory/${repo}`))
+  const files = Array.isArray(body.files) ? body.files.map(asRecord) : null
+  if (
+    typeof body.revision !== "number" ||
+    !files?.every((file) => typeof file.path === "string" && typeof file.contents === "string")
+  ) {
+    throw new CliError(
+      { code: "invalid_api_response", message: "The Sixb API returned an invalid memory repo." },
+      EXIT_API
+    )
+  }
+  return {
+    revision: body.revision,
+    files: new Map(files.map((file) => [String(file.path), String(file.contents)])),
+  }
+}
+
+interface LocalMemory {
+  readManifest(): Promise<AgentMemoryManifest>
+  writeManifest(manifest: AgentMemoryManifest): Promise<void>
+  /** Every file of the local copy, by path from the repo root. */
+  readRepo(repo: AgentMemoryRepo): Promise<Map<string, string>>
+  /** `undefined` deletes the file. */
+  write(repo: AgentMemoryRepo, path: string, contents: string | undefined): Promise<void>
+}
+
+function localMemory(): LocalMemory {
+  const root = process.env.SIXB_MEMORY_DIR
+  const contextDir = process.env.SIXB_CONTEXT_DIR
+  if (!root || !contextDir) {
+    fail("Agent memory is not available in this run.", "runtime_unavailable")
+  }
+  const manifestPath = join(contextDir, ...AGENT_MEMORY_MANIFEST.split("/"))
+  const fileOf = (repo: AgentMemoryRepo, path: string) => join(root, repo, ...path.split("/"))
+
+  return {
+    async readManifest() {
+      let text: string
+      try {
+        text = await readFile(manifestPath, "utf8")
+      } catch (error) {
+        if (isFileError(error, "ENOENT")) return { repos: {} }
+        throw error
+      }
+      try {
+        return parseManifest(JSON.parse(text))
+      } catch {
+        fail(`Memory manifest '${manifestPath}' is not valid.`, "invalid_json")
+      }
+    },
+
+    async writeManifest(manifest) {
+      await mkdir(dirname(manifestPath), { recursive: true })
+      await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+    },
+
+    async readRepo(repo) {
+      const files = new Map<string, string>()
+      const walk = async (directory: string, prefix: string): Promise<void> => {
+        let entries: string[]
+        try {
+          entries = await readdir(directory)
+        } catch (error) {
+          if (isFileError(error, "ENOENT")) return
+          throw error
+        }
+        for (const name of entries) {
+          const path = prefix ? `${prefix}/${name}` : name
+          const stats = await lstat(join(directory, name))
+          if (stats.isDirectory()) await walk(join(directory, name), path)
+          else if (stats.isFile()) files.set(path, await readFile(join(directory, name), "utf8"))
+          else fail(`Memory file '${repo}/${path}' is not a regular file.`)
+        }
+      }
+      await walk(join(root, repo), "")
+      return files
+    },
+
+    async write(repo, path, contents) {
+      const file = fileOf(repo, path)
+      if (contents === undefined) {
+        await rm(file, { force: true })
+        return
+      }
+      await mkdir(dirname(file), { recursive: true })
+      await writeFile(file, contents)
+    },
+  }
+}
+
+function parseSaveArgs(args: readonly string[]): { repo: AgentMemoryRepo; message: string } {
+  const positionals: string[] = []
+  let message: string | undefined
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index] ?? ""
+    if (argument === "-m" || argument === "--message") {
+      if (message !== undefined) fail(`${argument} may only be provided once.`)
+      message = args[++index]
+      if (!message) fail(`${argument} requires a value.`)
+    } else if (argument.startsWith("-")) {
+      fail(`Unknown memory save option '${argument}'.`)
+    } else {
+      positionals.push(argument)
+    }
+  }
+  if (positionals.length !== 1) fail("Invalid arguments for 'memory save'.")
+  if (message === undefined || message.trim().length === 0) {
+    fail("memory save requires -m <what you learned>.")
+  }
+  return { repo: parseRepo(positionals[0] ?? ""), message }
+}
+
+function parseRepo(value: string): AgentMemoryRepo {
+  if (value === "user" || value === "project") return value
+  fail(`Unknown memory repo '${value}'. Use 'user' or 'project'.`)
+}
+
+function installedRepos(manifest: AgentMemoryManifest): AgentMemoryRepo[] {
+  return (["user", "project"] as const).filter((repo) => manifest.repos[repo] !== undefined)
+}
+
+function parseManifest(value: unknown): AgentMemoryManifest {
+  const repos = asRecord(asRecord(value).repos)
+  const parsed: Partial<Record<AgentMemoryRepo, AgentMemoryManifestRepo>> = {}
+  for (const repo of ["user", "project"] as const) {
+    if (repos[repo] === undefined) continue
+    const entry = asRecord(repos[repo])
+    const files = asRecord(entry.files)
+    if (
+      typeof entry.revision !== "number" ||
+      !Object.values(files).every((digest) => typeof digest === "string")
+    ) {
+      throw new Error("invalid memory manifest")
+    }
+    parsed[repo] = {
+      revision: entry.revision,
+      files: files as Record<string, string>,
+    }
+  }
+  return { repos: parsed }
+}

package/src/commands/metadata.ts

@@ -5,17 +5,17 @@ import {
   DEFAULT_TELEMETRY_ORDER,
 } from "../policies"
 
-const SANDBOX_MAIN_HELP = `Sixb agent CLI
+const SANDBOX_MAIN_HELP = `Sixb CLI
 
 Usage:
   sixb <command> [options]
 
-The CLI uses the run-scoped SIXB_API_BASE_URL. Do not configure authentication or another origin.
+The CLI uses the run's SIXB_API_BASE_URL, which adds its credentials. Do not configure authentication or another origin.
 API commands emit JSON. Help, version, and examples emit text. Downloads write to --output and
 emit a JSON receipt.
 
 Discovery:
-  sixb doctor                         Check the sandbox and API gateway
+  sixb status                         Check the sandbox and its API access
   sixb context                        Print the current run context
   sixb project show                   Show project metadata
   sixb ontology list                  Compact visible type and relationship catalog
@@ -28,6 +28,8 @@ Objects:
   sixb objects inspect <type> <id>    Inspect an object and its related graph in one command
   sixb objects list [options]         Browse materialized objects
   sixb objects get <type> <id>...     Exact lookup through opaque object references
+  sixb objects get-by <type> <property> <value>
+                                      The object holding a value of a unique property
   sixb objects search <text>          Search visible objects by id prefix and full text
   sixb objects search <text> --type <type>
                                       Semantic search through the type's vector profile
@@ -48,28 +50,29 @@ Actions and workflows:
   sixb workflows list|get|start ...
   sixb workflow-runs list|get ...
 
+Data:
+  sixb datasets list|get|versions|rows ...
+  sixb syncs list|get ...             Syncs you may run, each with its latest run
+  sixb sync-runs list ...
+  sixb pipelines list|get ...         Pipelines you may run, each with its latest run
+  sixb pipeline-runs list|get ...
+
 Files:
   sixb files upload|download ...
 
+Members:
+  sixb users search <text>            Find members by name or email
+  sixb users list|get ...
+
+A user parameter or property is {"type":"user","id":"<user-id>"}. Find the id with
+\`sixb users search <name>\`.
+
 Run \`sixb <group> --help\` or \`sixb <group> <command> --help\` for exact arguments.
 For query IR, run \`sixb objects query --help\` and \`sixb objects query --example list\`.`
 
-const LOCAL_MAIN_HELP = SANDBOX_MAIN_HELP.replace("Sixb agent CLI", "Sixb instance CLI")
-  .replace(
-    "The CLI uses the run-scoped SIXB_API_BASE_URL. Do not configure authentication or another origin.",
-    "The CLI uses the selected local profile and its API credentials."
-  )
-  .replace(
-    "  sixb doctor                         Check the sandbox and API gateway\n  sixb context                        Print the current run context\n",
-    ""
-  )
-  .replace(
-    "\nWhen you do not know a type's properties or links, read its file under $SIXB_ONTOLOGY_DIR. Use\n`sixb ontology get` for a type that has no file there.\n",
-    ""
-  )
-
-export function renderInstanceHelp(mode: "local" | "sandbox"): string {
-  return mode === "sandbox" ? SANDBOX_MAIN_HELP : LOCAL_MAIN_HELP
+/** The sandbox CLI's help, which the agent's prompt includes. People's comes from @sixb/cli. */
+export function renderInstanceHelp(): string {
+  return SANDBOX_MAIN_HELP
 }
 
 const SEARCH_DETAILS = `Without --type, search matches primary-id prefixes and full-text fields across visible types.
@@ -87,10 +90,19 @@ profiles.
 
 ${SEARCH_DETAILS}`
 
+export const GET_BY_HELP = `Usage:
+  sixb objects get-by <object-type> <property> <value> [--json]
+
+Prints the object of exactly <object-type> holding <value> for a property marked unique in its
+ontology doc, or null when no visible object holds it. Values match exactly, case included.
+The value is a string; with --json it is parsed as JSON, for an integer (42) or a user
+reference ({"type":"user","id":"usr_1"}).`
+
 export const OBJECTS_HELP = `Usage:
   sixb objects inspect <object-type> <primary-id> [options]
   sixb objects list [options]
   sixb objects get <object-type> <primary-id>...
+  sixb objects get-by <object-type> <property> <value> [--json]
   sixb objects search <text> [--type <object-type> [--vector-profile <name>]] [--limit <n>]
   sixb objects query --file <path|-> [--include-total|--no-total]
   sixb objects query --example <name>
@@ -158,7 +170,7 @@ Query nodes compose through input:
   limit     {"kind":"limit","input":<query>,"limit":${CLI_LIMITS.list.default}}
   page      {"kind":"page","input":<query>,"pageSize":${CLI_LIMITS.list.default},"pageToken":"from nextPageToken"}
   project   {"kind":"project","input":<query>,"properties":["name","status"]}
-  expand    {"kind":"expand","input":<query>,"expansions":[{"linkId":"link","direction":"outgoing","limit":5}]}
+  expand    {"kind":"expand","input":<query>,"expansions":[{"linkId":"link","direction":"outgoing","limit":5}],"users":["assignee"]}
   vector    {"kind":"vector","input":<start|filter>,"vector":"text","profile":"name","k":10}
   rerank    {"kind":"rerank","input":<vector>,"model":{"provider":"provider","modelId":"model"}}
 
@@ -169,11 +181,16 @@ Predicates use op, not kind:
   {"op":"in","propertyId":"status","values":["open","blocked"]}
   {"op":"exists","propertyId":"dueDate","value":true}
   {"op":"contains","propertyId":"tags","value":"urgent"}
+  {"op":"eq","propertyId":"assignee","value":{"type":"currentUser"}}  the caller, on a user reference: neq, in, contains too
 
 Every field shown is required except includeSubtypes, fields, pageToken, properties, a sort
-direction, and an expansion's limit. Sort by relevance after text or vector with
+direction, an expansion's limit, and users. Sort by relevance after text or vector with
 {"kind":"relevance"}. Wrap the outermost node in project to return only the properties you need.
 
+An expand's users, or an expansion's, lists user-reference properties: each row then carries the
+members' profiles under users (id, email, displayName, avatarUrl, status). Without access to the
+member directory, users is empty.
+
 Traversal and expansion directions are outgoing or incoming. For incoming relationships, the link
 is declared on the child/source type; add sourceObjectTypeId when needed to disambiguate it.
 
@@ -185,7 +202,7 @@ Vector profile names are the keys of the type's search.vectors. Vector input is
 optionally under filters; k bounds the ranked matches and results carry a score.`
 
 export const GROUP_HELP = {
-  doctor: "Usage: sixb doctor",
+  status: "Usage: sixb status",
   context: "Usage: sixb context",
   project: "Usage: sixb project show",
   ontology: `Usage:
@@ -209,7 +226,8 @@ History options:
 \`actions get\` includes inputSchema, the exact JSON shape accepted by the Action. The JSON file
 contains that parameter object; use - to read standard input. \`actions request\` runs the Action
 and prints its finished run, with its status and any error. It waits at most 25 seconds: a run that
-takes longer keeps running, and the error names the run to read with \`action-runs get\`.`,
+takes longer keeps running, and the error names the run to read with \`action-runs get\`. A request
+that waits for the user's approval prints \`"status": "awaiting_approval"\` and exits with code 4.`,
   "action-runs": `Usage:
   sixb action-runs list [options]
   sixb action-runs get <run-id>
@@ -226,13 +244,54 @@ List options:
   files: `Usage:
   sixb files upload <local-path> [--logical-path <path>]
   sixb files download object <type> <id> --path <json-pointer> --output <local-path>
-  sixb files download action-run|workflow-run <run-id> --path <json-pointer> --output <local-path>`,
+  sixb files download action-run|workflow-run <run-id> --path <json-pointer> --output <local-path>
+  sixb files download url <content-url> --output <local-path>`,
   workflows: `Usage:
   sixb workflows list
   sixb workflows get <workflow-id>
-  sixb workflows start <workflow-id> [--file <path|->]
+  sixb workflows start <workflow-id> [--file <path|->] [--run-id <id>]
+
+The JSON file contains the workflow input object. Use - to read standard input. A start that waits
+for the user's approval prints \`"status": "awaiting_approval"\` and exits with code 4.`,
+  users: `Usage:
+  sixb users list [options]
+  sixb users search <text> [options]
+  sixb users get <user-id|email>
+
+Options:
+  --status active|suspended|all       Defaults to active
+  --limit <1-${CLI_LIMITS.users.maximum}>                     Defaults to ${CLI_LIMITS.users.default}
+  --offset <n>                        Non-negative; defaults to 0
 
-The JSON file contains the workflow input object. Use - to read standard input.`,
+\`users search\` matches part of a display name or email, ignoring case; \`users get\` takes an
+exact email, ignoring case, and finds suspended members too. Each member is
+{"id","email","displayName","avatarUrl","status"}; a user parameter takes
+{"type":"user","id":"<id>"}. Reading members requires can.view(project.users).`,
+  models: `Usage:
+  sixb models list [--kind language|image|speech|transcription]
+  sixb models get <model> [--kind <kind>]
+  sixb models text "<prompt>"|--file <path|-> [--model <tier|model>] [--instructions <text>]
+                   [--max-output-tokens <n>] [--reasoning <level>]
+  sixb models image "<prompt>" --output <path> [--model <model>] [--n <n>]
+                    [--size <size>] [--aspect-ratio <ratio>] [--quality <q>] [--style <s>]
+                    [--seed <n>] [--image <file>]...
+  sixb models speech "<text>" --output <path> [--model <model>] [--voice <voice>]
+                     [--format mp3|wav|ogg|aac|flac] [--instructions <text>]
+                     [--speed <n>] [--language <code>]
+  sixb models transcribe <file> [--model <model>]
+  sixb models calls files <call-id> [--output <path>]
+
+<model> is a model id, or provider:model-id when two providers share one; without --model, the
+kind's default answers. \`list\` shows each model's kind, default, description and price; \`get\`
+adds the sizes, voices and other options a request can use. Prices are in USD.
+
+\`text\` also takes a tier (light, standard or heavy) for --model, and reads a long prompt from
+--file: a path, or - for standard input.
+
+--output is a file, numbered when a call returns several, or a directory ending in /. The
+extension follows the file's type, and the result lists the paths written. --image uploads a
+reference image; repeat it for several. \`calls files\` lists a past call's files, or downloads
+them again.`,
   "workflow-runs": `Usage:
   sixb workflow-runs list [options]
   sixb workflow-runs get <run-id>
@@ -244,6 +303,56 @@ List options:
   --limit <1-${CLI_LIMITS.list.maximum}>              Defaults to ${CLI_LIMITS.list.default}
   --offset <n>                  Non-negative; defaults to 0
   --order <asc|desc>            Started-time order; defaults to ${DEFAULT_LIST_ORDER}`,
+  datasets: `Usage:
+  sixb datasets list
+  sixb datasets get <dataset-id>
+  sixb datasets versions <dataset-id> [--limit <1-${CLI_LIMITS.datasetVersions.maximum}>]
+  sixb datasets rows <dataset-id> [options]
+
+Rows options:
+  --version <version-id>        Defaults to the latest version
+  --columns <a,b,...>           Defaults to every column
+  --limit <1-${CLI_LIMITS.datasetRows.maximum}>              Defaults to ${CLI_LIMITS.datasetRows.default}
+  --offset <n>                  Non-negative; defaults to 0
+
+\`list\` and \`get\` show a dataset's schema, its latest version, and the syncs and pipelines you
+may run that read or write it. \`versions\` lists the newest first. \`rows\` leaves out the
+columns your clearances do not cover and names them under redactions.`,
+  syncs: `Usage:
+  sixb syncs list
+  sixb syncs get <sync-id>
+
+Lists the syncs you may run, each with its latest run. \`sixb sync-runs list\` shows the history.`,
+  "sync-runs": `Usage:
+  sixb sync-runs list [options]
+
+List options:
+  --sync <sync-id>
+  --dataset <dataset-id>
+  --status queued|running|succeeded|failed|cancelled
+  --started-after|--started-before <RFC3339>
+  --limit <1-${CLI_LIMITS.list.maximum}>              Defaults to ${CLI_LIMITS.list.default}
+  --offset <n>                  Non-negative; defaults to 0
+  --order <asc|desc>            Started-time order; defaults to ${DEFAULT_LIST_ORDER}`,
+  pipelines: `Usage:
+  sixb pipelines list
+  sixb pipelines get <pipeline-id>
+
+Lists the pipelines you may run, each with its latest run. \`sixb pipeline-runs\` shows the
+history and each run's steps.`,
+  "pipeline-runs": `Usage:
+  sixb pipeline-runs list [options]
+  sixb pipeline-runs get <run-id>
+
+List options:
+  --pipeline <pipeline-id>
+  --status queued|running|succeeded|failed|cancelled
+  --started-after|--started-before <RFC3339>
+  --limit <1-${CLI_LIMITS.list.maximum}>              Defaults to ${CLI_LIMITS.list.default}
+  --offset <n>                  Non-negative; defaults to 0
+  --order <asc|desc>            Started-time order; defaults to ${DEFAULT_LIST_ORDER}
+
+\`get\` includes the run's steps.`,
 } as const
 
 export const QUERY_EXAMPLES: Readonly<Record<string, string>> = {
@@ -254,10 +363,12 @@ export const QUERY_EXAMPLES: Readonly<Record<string, string>> = {
   not: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Customer"},"predicate":{"op":"not","item":{"op":"eq","propertyId":"status","value":"churned"}}},"limit":${CLI_LIMITS.list.default}}`,
   in: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Customer"},"predicate":{"op":"in","propertyId":"status","values":["active","trial"]}},"limit":${CLI_LIMITS.list.default}}`,
   exists: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Customer"},"predicate":{"op":"exists","propertyId":"accountManager","value":false}},"limit":${CLI_LIMITS.list.default}}`,
+  mine: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Task"},"predicate":{"op":"eq","propertyId":"assignee","value":{"type":"currentUser"}}},"limit":${CLI_LIMITS.list.default}}`,
   project: `{"kind":"project","input":{"kind":"limit","input":{"kind":"start","objectTypeId":"Customer"},"limit":${CLI_LIMITS.list.default}},"properties":["name","status"]}`,
   incoming:
     '{"kind":"traverse","input":{"kind":"refs","refs":[{"objectTypeId":"RepositoryIssue","primaryId":"github:issue:owner/repo#297"}]},"linkId":"issue","direction":"incoming","sourceObjectTypeId":"RepositoryComment"}',
   expand: `{"kind":"expand","input":{"kind":"refs","refs":[{"objectTypeId":"RepositoryIssue","primaryId":"github:issue:owner/repo#297"}]},"expansions":[{"linkId":"issue","direction":"incoming","sourceObjectTypeId":"RepositoryComment","limit":${CLI_LIMITS.list.default}}]}`,
+  users: `{"kind":"expand","input":{"kind":"limit","input":{"kind":"start","objectTypeId":"Task"},"limit":${CLI_LIMITS.list.default}},"expansions":[],"users":["assignee"]}`,
   sort: `{"kind":"limit","input":{"kind":"sort","input":{"kind":"start","objectTypeId":"Customer"},"fields":[{"kind":"property","propertyId":"name","direction":"asc"}]},"limit":${CLI_LIMITS.list.default}}`,
   page: `{"kind":"page","input":{"kind":"start","objectTypeId":"Customer"},"pageSize":${CLI_LIMITS.list.default}}`,
   vector: `{"kind":"vector","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Product"},"predicate":{"op":"eq","propertyId":"status","value":"active"}},"vector":"waterproof trail shoes","profile":"content","k":${CLI_LIMITS.search.default}}`,