@theplato/tiro-cli 0.4.0 → 0.5.0

package/AGENTS.md

@@ -89,26 +89,15 @@ Two ways to authenticate:
 The CLI never prints tokens to stdout. `tiro auth status` shows only the
 first 4 characters of the access token.
 
-## Security regression suite (pre-deploy contract)
-
-Every release MUST keep `npm run test:security` green. The suite pins the
-following defenses; if any test breaks, the corresponding attack surface
-has reopened — do not publish.
-
-| ID | Surface | What the test guards |
-|---|---|---|
-| **C1** | `lib/config.ts` `validateHostname` | Rejects non-https/non-loopback hostnames so `TIRO_HOSTNAME` / `--hostname` cannot redirect OAuth + API traffic to an attacker. |
-| **H1** | `lib/auth/pkce.ts` `verifyState` | Constant-time OAuth state CSRF compare. |
-| **H2** | `lib/auth/loopback.ts` | OAuth redirect listener is GET-only, single-shot, `Connection: close` — local processes can't race or replay a callback. |
-| **H3** | `lib/api/client.ts` `buildApiUrl` | API path must be relative to the configured hostname — refuses absolute / protocol-relative input that would leak the bearer token. |
-| **H4** | `lib/config.ts` `getOauthClientId` | DCR `client_id` cache is bound to the hostname it was registered against; a swapped hostname misses the cache. |
-| **M1** | `lib/output/file.ts` `assertSafeOutputPath` | `--output` rejects `..` segments unless `--force`; an agent forwarding untrusted input cannot escape its scope. |
-| **M2** | `lib/auth/token.ts` `decodeJwtPayload` | Documented as display-only — claims must never gate auth, scope, identity, or expiry decisions. |
-
-Pre-deploy checklist:
-
-1. `npm run typecheck`
-2. `npm run test:security` (regression gate)
-3. `npm test` (full suite)
-4. `npm run build`
-5. Smoke: `node dist/bin/tiro.js auth status`
+## Security posture (summary)
+
+- OAuth uses Authorization Code + PKCE with a CSRF-checked loopback
+  redirect. Tokens are held in the OS keychain or `TIRO_TOKEN` only —
+  never written to stdout, stderr, or disk in any other form.
+- `TIRO_HOSTNAME` / `--hostname` are validated against an `https://` (or
+  loopback) allowlist before any OAuth or API request runs.
+- `--output` paths that escape the working tree require `--force`.
+- A dedicated regression suite (`npm run test:security`) pins these
+  surfaces and runs in `prepublishOnly` — a broken defense blocks publish.
+
+Always run on the latest released version; older versions are deprecated.

package/README.md

@@ -46,6 +46,7 @@ The CLI is **not a replacement for MCP**. It's the same data through a different
 - 🔐 **OAuth Authorization Code + PKCE** — no copy-paste tokens, no secrets in shell history. Tokens live in OS Keychain.
 - 📁 **`--output` writes to disk** — stdout becomes a single line of metadata. Agents stay context-light.
 - 🪞 **Same JSON shape as MCP** — `tiro notes transcript --format json` mirrors `get_note_transcript` exactly. Switch surfaces without changing parsers.
+- 🕸️ **Workspace wiki** — `tiro wiki search / page / mentions / graph` read the auto-extracted knowledge graph; `--workspace` targets a specific workspace.
 - 🧵 **NDJSON streams by default** — pipe to `jq`, `head`, `xargs`. No buffer-in-memory surprises.
 - 🤖 **Agent-aware** — TTY detection auto-selects pretty vs JSON. `error.suggestion` field for auto-recovery.
 - 🚫 **No voice in v1** — intentionally matches MCP feature parity (audio uploads belong elsewhere).
@@ -108,7 +109,7 @@ tiro notes list
 ```bash
 tiro notes list                                              # pretty table in TTY
 tiro notes list --json                                       # NDJSON for pipes
-tiro notes list --keyword "OKR" --since 30d                  # OpenSearch reorder by keyword
+tiro notes list --keyword "OKR" --since 30d                  # Reorder by keyword relevance
 tiro notes list --folder <id> --limit 100 --cursor <token>
 ```
 
@@ -150,6 +151,28 @@ header instead of being attached to every speaker line. Use
 
 `--format json` returns the exact shape MCP's `get_note_transcript` emits (`{noteGuid, title, participants, createdAt, recordingDurationSeconds, paragraphs[]}` with each paragraph carrying `segments[]` of `{content, speaker:{label,name}|null}`).
 
+### Explore the workspace wiki
+
+The wiki is Tiro's auto-extracted knowledge graph (entities, concepts, and their
+links) over your notes. These commands are **read-only** and mirror the MCP wiki
+tools. Wiki is a paid, opt-in feature — calls against an ineligible or
+not-activated workspace return the backend's upgrade message and a non-zero exit.
+
+```bash
+tiro wiki workspaces                                         # which workspaces? (guid + wiki on/off)
+tiro wiki search "Ontology" --workspace <guid>               # find pages by keyword
+tiro wiki page <pageGuid> --workspace <guid>                 # body + mentions + links
+tiro wiki mentions <pageGuid> --workspace <guid>             # where the page is grounded in notes
+tiro wiki graph <pageGuid> --mode around --workspace <guid>  # neighborhood graph
+tiro wiki graph --mode seed --type CONCEPT --workspace <guid> # overview graph (no pageGuid)
+```
+
+`--workspace` is optional — omit it to use the default workspace for your API
+key. If your account belongs to multiple workspaces, run `tiro wiki workspaces`
+first and pass the `guid` of the one whose wiki is enabled. `graph` results are
+capped (default 50 nodes); a `truncated: true` flag signals you to narrow the
+query.
+
 ### Connect to Claude Code (MCP)
 ```bash
 tiro mcp install
@@ -287,7 +310,7 @@ The CLI sits on the public Tiro API alongside the MCP server, sharing the same O
 
 ```
                     ┌──────────────────────────────┐
-                    │ Tiro Backend (Kotlin)         │
+                    │ Tiro Backend                  │
                     │  /v1/external/* + /v1/mcp/*   │
                     └──────────────┬────────────────┘
                                    │
@@ -325,7 +348,7 @@ See [`SPEC.md`](./SPEC.md) for the full v1 design and [`CHANGELOG.md`](./CHANGEL
 
 ## Contributing
 
-This repo is currently private alpha. Feedback and bug reports go to the internal Slack `#tiro-backend` channel; once we open up, this section will list public contribution guidelines.
+This repo is currently private alpha. Feedback and bug reports can be sent to [yeoul@theplato.io](mailto:yeoul@theplato.io); once we open up, this section will list public contribution guidelines.
 
 ---
 

package/dist/bin/tiro.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/bin/tiro.ts
-import { Command as Command13 } from "commander";
+import { Command as Command19 } from "commander";
 
 // src/lib/version.ts
 import { readFileSync } from "fs";
@@ -43,6 +43,7 @@ var TiroError = class extends Error {
   errorType;
   httpStatus;
   requestId;
+  details;
   exitCode;
   constructor(payload, exitCode = ExitCode.Generic) {
     super(payload.message);
@@ -52,6 +53,7 @@ var TiroError = class extends Error {
     this.errorType = payload.errorType;
     this.httpStatus = payload.httpStatus;
     this.requestId = payload.requestId;
+    this.details = payload.details;
     this.exitCode = exitCode;
   }
   toJSON() {
@@ -63,7 +65,8 @@ var TiroError = class extends Error {
         ...this.suggestion !== void 0 && { suggestion: this.suggestion },
         ...this.errorType !== void 0 && { errorType: this.errorType },
         ...this.httpStatus !== void 0 && { httpStatus: this.httpStatus },
-        ...this.requestId !== void 0 && { requestId: this.requestId }
+        ...this.requestId !== void 0 && { requestId: this.requestId },
+        ...this.details !== void 0 && { details: this.details }
       }
     };
   }
@@ -461,6 +464,7 @@ var config = new Conf({
     oauthClientId: null,
     oauthClientIdRegisteredAt: null,
     oauthClientHostname: null,
+    oauthClientRedirectUri: null,
     defaultOutputDir: null
   }
 });
@@ -518,25 +522,40 @@ function getHostname(override) {
   if (env) return validateHostname(env);
   return validateHostname(config.get("hostname"));
 }
-function getOauthClientId(hostname) {
+function getOauthClientId(hostname, currentRedirectUri) {
   const id = config.get("oauthClientId");
   const registeredAt = config.get("oauthClientIdRegisteredAt");
   const cachedHostname = config.get("oauthClientHostname");
+  const cachedRedirectUri = config.get("oauthClientRedirectUri");
   if (!id || !registeredAt) return null;
   if (cachedHostname !== hostname) return null;
+  if (!cachedRedirectUri) return null;
+  if (!sameRedirectTarget(cachedRedirectUri, currentRedirectUri)) return null;
   const ttlMs = 29 * 24 * 60 * 60 * 1e3;
   if (Date.now() - registeredAt > ttlMs) return null;
   return id;
 }
-function setOauthClientId(clientId, hostname) {
+function setOauthClientId(clientId, hostname, redirectUri) {
   config.set("oauthClientId", clientId);
   config.set("oauthClientIdRegisteredAt", Date.now());
   config.set("oauthClientHostname", hostname);
+  config.set("oauthClientRedirectUri", redirectUri);
 }
 function clearOauthClientId() {
   config.set("oauthClientId", null);
   config.set("oauthClientIdRegisteredAt", null);
   config.set("oauthClientHostname", null);
+  config.set("oauthClientRedirectUri", null);
+}
+function sameRedirectTarget(a, b) {
+  let pa, pb;
+  try {
+    pa = new URL(a);
+    pb = new URL(b);
+  } catch {
+    return false;
+  }
+  return pa.protocol === pb.protocol && pa.hostname === pb.hostname && pa.pathname === pb.pathname;
 }
 function stripTrailingSlash(s) {
   return s.endsWith("/") ? s.slice(0, -1) : s;
@@ -617,7 +636,7 @@ ${authorizeUrl}`);
   }
 }
 async function ensureOauthClient(hostname, redirectUri) {
-  const cached = getOauthClientId(hostname);
+  const cached = getOauthClientId(hostname, redirectUri);
   if (cached) return cached;
   const url = `${hostname}/v1/mcp/oauth/register`;
   let res;
@@ -670,7 +689,7 @@ async function ensureOauthClient(hostname, redirectUri) {
       ExitCode.Generic
     );
   }
-  setOauthClientId(parsed.data.client_id, hostname);
+  setOauthClientId(parsed.data.client_id, hostname, redirectUri);
   return parsed.data.client_id;
 }
 function buildAuthorizeUrl(input) {
@@ -971,6 +990,116 @@ var ApiErrorSchema = z2.object({
     detail: z2.string().nullable().optional()
   })
 });
+var WorkspaceMeSchema = z2.object({
+  guid: z2.string()
+}).passthrough();
+var WorkspaceItemSchema = z2.object({
+  guid: z2.string(),
+  name: z2.string(),
+  isWikiEnabled: z2.boolean()
+}).passthrough();
+var WorkspacesListSchema = z2.object({
+  workspaces: z2.array(WorkspaceItemSchema)
+}).passthrough();
+var WikiSearchPageSchema = z2.object({
+  guid: z2.string(),
+  wikiId: z2.number(),
+  canonicalName: z2.string(),
+  pageType: z2.string(),
+  entitySubtype: z2.string().nullable().optional(),
+  score: z2.number()
+}).passthrough();
+var WikiSearchPagesResponseSchema = z2.object({
+  items: z2.array(WikiSearchPageSchema)
+}).passthrough();
+var WikiMentionSchema = z2.object({
+  guid: z2.string(),
+  noteId: z2.number(),
+  paragraphId: z2.number().nullable().optional(),
+  paragraphUuid: z2.string().nullable().optional(),
+  kind: z2.string(),
+  sourceUserId: z2.number(),
+  extractedText: z2.string(),
+  confidence: z2.number().nullable().optional(),
+  createdAt: z2.string()
+}).passthrough();
+var WikiAliasSchema = z2.object({
+  guid: z2.string(),
+  alias: z2.string(),
+  source: z2.string(),
+  sourceMentionGuid: z2.string().nullable().optional(),
+  sourceUserId: z2.number().nullable().optional(),
+  createdAt: z2.string()
+}).passthrough();
+var WikiLinkSchema = z2.object({
+  guid: z2.string(),
+  sourcePageGuid: z2.string(),
+  sourcePageName: z2.string().nullable().optional(),
+  targetPageGuid: z2.string(),
+  targetPageName: z2.string().nullable().optional(),
+  linkType: z2.string(),
+  linkTypeDisplayKo: z2.string().optional(),
+  linkTypeDisplayEn: z2.string().optional(),
+  isDirectional: z2.boolean(),
+  source: z2.string().optional(),
+  creatorUserId: z2.number().nullable().optional(),
+  createdAt: z2.string().optional(),
+  updatedAt: z2.string().optional()
+}).passthrough();
+var WikiPageDetailSchema = z2.object({
+  guid: z2.string(),
+  wikiId: z2.number(),
+  canonicalName: z2.string(),
+  description: z2.string().nullable().optional(),
+  descriptionStatus: z2.string().nullable().optional(),
+  regenerationAvailable: z2.boolean().nullable().optional(),
+  pageType: z2.string(),
+  entitySubtype: z2.string().nullable().optional(),
+  extractionStatus: z2.string(),
+  mentionCountVisible: z2.number(),
+  mentions: z2.array(WikiMentionSchema),
+  aliases: z2.array(WikiAliasSchema),
+  links: z2.array(WikiLinkSchema),
+  lastUpdatedVisible: z2.string().nullable().optional(),
+  createdAt: z2.string(),
+  updatedAt: z2.string()
+}).passthrough();
+var WikiMentionListResponseSchema = z2.object({
+  items: z2.array(WikiMentionSchema),
+  nextCursorCreatedAt: z2.string().nullable(),
+  nextCursorId: z2.number().nullable()
+}).passthrough();
+var WikiGraphNodeSchema = z2.object({
+  guid: z2.string(),
+  canonicalName: z2.string(),
+  pageType: z2.string(),
+  entitySubtype: z2.string().nullable().optional(),
+  extractionStatus: z2.string(),
+  mentionCountVisible: z2.number()
+}).passthrough();
+var WikiGraphEdgeSchema = z2.object({
+  guid: z2.string(),
+  sourcePageGuid: z2.string(),
+  targetPageGuid: z2.string(),
+  linkType: z2.string(),
+  linkTypeDisplayKo: z2.string().optional(),
+  linkTypeDisplayEn: z2.string().optional(),
+  isDirectional: z2.boolean()
+}).passthrough();
+var WikiGraphResponseSchema = z2.object({
+  nodes: z2.array(WikiGraphNodeSchema),
+  edges: z2.array(WikiGraphEdgeSchema)
+}).passthrough();
+var WikiPlanRequiredSchema = z2.object({
+  // Two gate kinds, relayed verbatim:
+  //   WIKI_PLAN_REQUIRED → plan ineligible (upsell; required_plans set)
+  //   WIKI_NOT_ACTIVATED → eligible plan, wiki not activated by an admin (required_plans null)
+  error_code: z2.enum(["WIKI_PLAN_REQUIRED", "WIKI_NOT_ACTIVATED"]),
+  message: z2.string(),
+  current_plan: z2.string().nullable().optional(),
+  required_plans: z2.array(z2.string()).nullable().optional(),
+  action_url: z2.string().nullable().optional()
+}).passthrough();
 
 // src/lib/api/client.ts
 var TiroApiClient = class {
@@ -1062,6 +1191,10 @@ var TiroApiClient = class {
 async function mapHttpError(res, method, path) {
   const requestId = res.headers.get("x-request-id") ?? void 0;
   const exitCode = res.status === 401 ? ExitCode.AuthRequired : ExitCode.Generic;
+  if (res.status === 402) {
+    const gate = await tryParsePlanGate(res);
+    if (gate) return planGateError(gate, requestId);
+  }
   const apiError = await tryParseApiError(res);
   if (apiError) {
     return new TiroError(
@@ -1092,6 +1225,7 @@ async function mapHttpError(res, method, path) {
 function httpStatusToErrorType(status) {
   if (status === 400) return "bad_request";
   if (status === 401) return "unauthorized";
+  if (status === 402) return "payment_required";
   if (status === 403) return "forbidden";
   if (status === 404) return "not_found";
   if (status === 409) return "conflict";
@@ -1109,6 +1243,31 @@ async function tryParseApiError(res) {
     return null;
   }
 }
+async function tryParsePlanGate(res) {
+  try {
+    const json = await res.clone().json();
+    const parsed = WikiPlanRequiredSchema.safeParse(json);
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+function planGateError(gate, requestId) {
+  const actionUrl = gate.action_url ?? null;
+  return new TiroError(
+    {
+      // Relay the backend's discriminator (WIKI_PLAN_REQUIRED / WIKI_NOT_ACTIVATED) verbatim.
+      code: gate.error_code,
+      message: gate.message,
+      errorType: "payment_required",
+      httpStatus: 402,
+      ...actionUrl ? { suggestion: `Upgrade: ${actionUrl}` } : {},
+      ...requestId !== void 0 && { requestId },
+      details: { ...gate }
+    },
+    ExitCode.Generic
+  );
+}
 function buildApiUrl(hostname, path, params) {
   if (!path.startsWith("/") || path.startsWith("//") || path.startsWith("/\\")) {
     throw new TiroError(
@@ -1198,17 +1357,18 @@ Examples:
   tiro notes list --folder <id> --limit 50
 
 Keyword matching:
-  --keyword reorders results by OpenSearch relevance (case-insensitive,
-  full-text against note title and paragraph content). When --keyword is
-  set, nextCursor is always null. Without --keyword, results are ordered
-  by createdAt desc.
+  --keyword reorders results by full-text relevance over title and
+  paragraph content (case-insensitive), with createdAt desc as tiebreaker
+  when scores are close. When --keyword is set, nextCursor is always null.
+  Without --keyword, results are ordered by recording time desc (falls back
+  to createdAt for memo-only notes).
 
 Note: placeholder notes (title='Untitled' or sourceType='onboarding') are
 filtered out by default. A page of N may return fewer than N visible notes \u2014
 keep paginating to fetch more, or pass --include-untitled to surface them.
 `;
 function registerNotesList(parent) {
-  parent.command("list").description("List notes (lightweight metadata).").option("--keyword <text>", 'Reorder by OpenSearch relevance for this keyword (e.g. "OKR")').option("--folder <id>", "Restrict to a folder and its descendants").option(
+  parent.command("list").description("List notes (lightweight metadata).").option("--keyword <text>", 'Reorder by full-text relevance for this keyword (e.g. "OKR")').option("--folder <id>", "Restrict to a folder and its descendants").option(
     "--since <date>",
     "Inclusive lower bound on createdAt (ISO-8601 or relative: 7d, 24h, 30m)"
   ).option("--until <date>", "Exclusive upper bound on createdAt").option(
@@ -1248,7 +1408,7 @@ function clampLimit(raw) {
   if (!Number.isFinite(n) || n <= 0) return DEFAULT_PAGE_SIZE;
   return Math.min(n, MAX_PAGE_SIZE);
 }
-function printPretty(notes, nextCursor, opts) {
+function printPretty(notes, nextCursor2, opts) {
   if (notes.length === 0) {
     process.stdout.write(`${color("(no notes)", "gray", opts)}
 `);
@@ -1264,10 +1424,10 @@ function printPretty(notes, nextCursor, opts) {
 `
     );
   }
-  if (nextCursor) {
+  if (nextCursor2) {
     process.stdout.write(
       `${color(`
-  next: --cursor ${nextCursor}`, "gray", opts)}
+  next: --cursor ${nextCursor2}`, "gray", opts)}
 `
     );
   }
@@ -1307,12 +1467,16 @@ Examples:
   tiro notes search "release" --since 2026-04-01 --until 2026-05-01
 
 Keyword matching:
-  Full-text against note title + paragraph content via OpenSearch.
-  Case-insensitive. Multi-word keywords are tokenized \u2014 "OKR planning"
-  matches notes containing both terms. The deep search variant (this
-  command) hydrates each result with its primary documents (one-pager,
-  custom) so an MCP/LLM client can read content alongside metadata in
-  one call.
+  Full-text search against note title + paragraph content. Case-insensitive.
+  Multi-word keywords are tokenized \u2014 "OKR planning" matches notes containing
+  both terms. The deep search variant (this command) hydrates each result
+  with its primary documents (one-pager, custom) so an MCP/LLM client can
+  read content alongside metadata in one call.
+
+Ordering:
+  Results are sorted by full-text relevance, then createdAt desc as
+  tiebreaker. Without --limit, the server returns 50 results (capped
+  at 200). Pass --limit to override.
 
 Note: placeholder notes (title='Untitled' or sourceType='onboarding') are
 filtered out by default. Pass --include-untitled to surface them.
@@ -1392,7 +1556,7 @@ function clampLimit2(raw) {
   if (!Number.isFinite(n) || n <= 0) return DEFAULT_PAGE_SIZE2;
   return Math.min(n, MAX_PAGE_SIZE2);
 }
-function printPretty2(notes, nextCursor, opts) {
+function printPretty2(notes, nextCursor2, opts) {
   if (notes.length === 0) {
     process.stdout.write(`${color("(no matches)", "gray", opts)}
 `);
@@ -1405,10 +1569,10 @@ function printPretty2(notes, nextCursor, opts) {
 `
     );
   }
-  if (nextCursor) {
+  if (nextCursor2) {
     process.stdout.write(
       `${color(`
-  next: --cursor ${nextCursor}`, "gray", opts)}
+  next: --cursor ${nextCursor2}`, "gray", opts)}
 `
     );
   }
@@ -1902,6 +2066,413 @@ function registerNotes(program) {
   registerNotesTranscript(notes);
 }
 
+// src/commands/wiki/index.ts
+import "commander";
+
+// src/commands/wiki/search.ts
+import "commander";
+
+// src/lib/api/workspace.ts
+var cache = /* @__PURE__ */ new WeakMap();
+async function resolveWorkspaceGuid(client) {
+  const cached = cache.get(client);
+  if (cached) return cached;
+  const promise = client.getJson("/v1/external/workspaces/me", WorkspaceMeSchema).then((res) => res.guid);
+  cache.set(client, promise);
+  return promise;
+}
+async function listWorkspaces(client) {
+  const res = await client.getJson("/v1/external/workspaces", WorkspacesListSchema);
+  return res.workspaces;
+}
+
+// src/commands/wiki/search.ts
+var MAX_SIZE = 100;
+var MAX_QUERY_LENGTH = 500;
+var HELP_AFTER3 = `
+Examples:
+  tiro wiki search "onboarding"
+  tiro wiki search "payment gateway" --size 50 --json
+  tiro wiki search "billing" --workspace <guid>
+
+The workspace defaults to the one implicit in your API key. Pass --workspace
+to target a specific workspace (get guids from 'tiro wiki workspaces').
+Results are ranked wiki pages (pageGuid, name, type, relevance). Pass a
+pageGuid to 'tiro wiki page', 'tiro wiki mentions', or 'tiro wiki graph'.
+`;
+function registerWikiSearch(parent) {
+  parent.command("search <query>").description("Search the workspace wiki for pages matching a keyword.").option("--size <n>", `Max results (default: backend default, max ${MAX_SIZE})`).option("--workspace <guid>", "Target a specific workspace (from `tiro wiki workspaces`); defaults to your default workspace").addHelpText("after", HELP_AFTER3).action(async (query, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const keyword = query.trim();
+    if (!keyword) {
+      throw new TiroError(
+        {
+          code: "missing_query",
+          message: "wiki search requires a query.",
+          errorType: "bad_request",
+          suggestion: 'tiro wiki search "onboarding"'
+        },
+        ExitCode.Usage
+      );
+    }
+    const client = createApiClient({
+      ...globalOpts.hostname !== void 0 && { hostnameOverride: globalOpts.hostname }
+    });
+    const workspaceGuid = opts.workspace ?? await resolveWorkspaceGuid(client);
+    const clampedKeyword = keyword.length > MAX_QUERY_LENGTH ? keyword.slice(0, MAX_QUERY_LENGTH) : keyword;
+    const params = { q: clampedKeyword };
+    const size = clampSize(opts.size);
+    if (size !== void 0) params["size"] = size;
+    const res = await client.getJson(
+      // Fix 1: encode workspaceGuid so path-traversal sequences (../, ?, #) are neutralised.
+      `/v1/external/workspaces/${encodeURIComponent(workspaceGuid)}/wiki/search/pages`,
+      WikiSearchPagesResponseSchema,
+      params
+    );
+    const mode = resolveOutputMode(globalOpts);
+    if (mode === "json") {
+      for (const item of res.items) printNdjson(item);
+    } else {
+      printPretty3(res.items, globalOpts);
+    }
+  });
+}
+function clampSize(raw) {
+  if (!raw) return void 0;
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) return void 0;
+  return Math.min(n, MAX_SIZE);
+}
+function printPretty3(items, opts) {
+  if (items.length === 0) {
+    process.stdout.write(`${color("(no matches)", "gray", opts)}
+`);
+    return;
+  }
+  for (const it of items) {
+    const score = it.score.toFixed(2);
+    process.stdout.write(
+      `${color(score, "cyan", opts)}  ${color(it.guid, "dim", opts)}  ${color(it.pageType, "gray", opts)}  ${it.canonicalName}
+`
+    );
+  }
+}
+
+// src/commands/wiki/page.ts
+import "commander";
+var HELP_AFTER4 = `
+Examples:
+  tiro wiki page <pageGuid>
+  tiro wiki page <pageGuid> --json
+  tiro wiki page <pageGuid> --workspace <guid>
+
+Returns the page body (per-user description) plus metadata, mentions,
+aliases, and links. The workspace defaults to the one implicit in your API
+key; pass --workspace to target a specific workspace (from 'tiro wiki workspaces').
+`;
+function registerWikiPage(parent) {
+  parent.command("page <pageGuid>").description("Get a single wiki page: body, metadata, mentions, aliases, and links.").option("--workspace <guid>", "Target a specific workspace (from `tiro wiki workspaces`); defaults to your default workspace").addHelpText("after", HELP_AFTER4).action(async (pageGuid, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const client = createApiClient({
+      ...globalOpts.hostname !== void 0 && { hostnameOverride: globalOpts.hostname }
+    });
+    const workspaceGuid = opts.workspace ?? await resolveWorkspaceGuid(client);
+    const page = await client.getJson(
+      `/v1/external/workspaces/${encodeURIComponent(workspaceGuid)}/wiki/pages/${encodeURIComponent(pageGuid)}`,
+      WikiPageDetailSchema
+    );
+    const mode = resolveOutputMode(globalOpts);
+    if (mode === "json") {
+      printOutput({ ok: true, data: page }, globalOpts);
+    } else {
+      printPretty4(page, globalOpts);
+    }
+  });
+}
+function printPretty4(page, opts) {
+  const w = process.stdout.write.bind(process.stdout);
+  w(`${color(page.canonicalName, "bold", opts)}  ${color(`(${page.pageType})`, "gray", opts)}
+`);
+  w(`${color(page.guid, "dim", opts)}
+
+`);
+  if (page.description) {
+    w(`${page.description}
+
+`);
+  } else {
+    const status = page.descriptionStatus ?? "none";
+    w(`${color(`(no description \u2014 status: ${status})`, "gray", opts)}
+
+`);
+  }
+  w(
+    `${color("mentions", "gray", opts)} ${page.mentionCountVisible}  ${color("aliases", "gray", opts)} ${page.aliases.length}  ${color("links", "gray", opts)} ${page.links.length}
+`
+  );
+}
+
+// src/commands/wiki/mentions.ts
+import "commander";
+var MAX_LIMIT = 200;
+var HELP_AFTER5 = `
+Examples:
+  tiro wiki mentions <pageGuid>
+  tiro wiki mentions <pageGuid> --limit 100 --json
+  tiro wiki mentions <pageGuid> --workspace <guid>
+
+Lists the note paragraphs that reference a wiki page. In JSON mode a trailing
+{_cursor: ...} object is emitted when more pages are available; pass the
+cursor token back via --cursor to fetch the next page. The workspace defaults
+to the one implicit in your API key; pass --workspace to target a specific
+workspace (from 'tiro wiki workspaces').
+`;
+function registerWikiMentions(parent) {
+  parent.command("mentions <pageGuid>").description("List the note mentions that reference a single wiki page.").option("--limit <n>", `Max mentions per page (max ${MAX_LIMIT})`).option("--cursor <token>", "Continue from a previous page's cursor token.").option("--workspace <guid>", "Target a specific workspace (from `tiro wiki workspaces`); defaults to your default workspace").addHelpText("after", HELP_AFTER5).action(async (pageGuid, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const client = createApiClient({
+      ...globalOpts.hostname !== void 0 && { hostnameOverride: globalOpts.hostname }
+    });
+    const workspaceGuid = opts.workspace ?? await resolveWorkspaceGuid(client);
+    const params = {};
+    const limit = clampLimit3(opts.limit);
+    if (limit !== void 0) params["limit"] = limit;
+    if (opts.cursor) params["cursor"] = opts.cursor;
+    const res = await client.getJson(
+      `/v1/external/workspaces/${encodeURIComponent(workspaceGuid)}/wiki/pages/${encodeURIComponent(pageGuid)}/mentions`,
+      WikiMentionListResponseSchema,
+      params
+    );
+    const mode = resolveOutputMode(globalOpts);
+    if (mode === "json") {
+      for (const item of res.items) printNdjson(item);
+      const next = nextCursor(res.nextCursorCreatedAt, res.nextCursorId);
+      if (next) printNdjson({ _cursor: next });
+    } else {
+      printPretty5(res.items, globalOpts);
+    }
+  });
+}
+function clampLimit3(raw) {
+  if (!raw) return void 0;
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) return void 0;
+  return Math.min(n, MAX_LIMIT);
+}
+function nextCursor(createdAt, id) {
+  if (createdAt === null || id === null) return null;
+  const millis = Date.parse(createdAt);
+  if (Number.isNaN(millis)) return null;
+  return `${millis}_${id}`;
+}
+function printPretty5(items, opts) {
+  if (items.length === 0) {
+    process.stdout.write(`${color("(no mentions)", "gray", opts)}
+`);
+    return;
+  }
+  for (const m of items) {
+    const date = m.createdAt.slice(0, 10);
+    process.stdout.write(
+      `${color(date, "gray", opts)}  ${color(m.kind, "cyan", opts)}  ${m.extractedText}
+`
+    );
+  }
+}
+
+// src/commands/wiki/graph.ts
+import "commander";
+var MODES = ["seed", "expand", "around", "links"];
+var MAX_QUERY_LENGTH2 = 500;
+var GRAPH_CAP_DEFAULT = 50;
+var HELP_AFTER6 = `
+Modes (--mode, default: around):
+  around   Neighborhood around <pageGuid> (--radius hops, default 2)
+  expand   Outward expansion from <pageGuid> (--depth hops, default 1)
+  links    Links among <pageGuid> + each --page <guid> (repeatable)
+  seed     Overview seed graph (no <pageGuid> required; --query, --type, --since)
+
+Examples:
+  tiro wiki graph <pageGuid>                         # around, radius 2
+  tiro wiki graph <pageGuid> --mode expand --depth 2
+  tiro wiki graph <pageGuid> --mode links --page <g2> --page <g3>
+  tiro wiki graph --mode seed --query "billing"
+  tiro wiki graph <pageGuid> --workspace <guid>
+
+Returns a node+edge slice of the workspace wiki graph. The workspace defaults
+to the one implicit in your API key; pass --workspace to target a specific
+workspace (from 'tiro wiki workspaces').
+`;
+function registerWikiGraph(parent) {
+  parent.command("graph [pageGuid]").description("Get a node+edge slice of the wiki link graph around a page.").option("--mode <mode>", `Graph mode: ${MODES.join(" | ")} (default: around)`).option("--depth <n>", "expand mode: link-hops to traverse outward (default 1)").option("--radius <n>", "around mode: neighborhood radius in hops (default 2)").option("--limit <n>", "Max nodes to return (max 200)").option("--page <guid>", "links mode: additional page guid (repeatable)", collect, []).option("--type <type>", "seed mode: restrict to a page type (CONCEPT|DECISION|ENTITY)").option("--since <date>", "seed mode: only pages updated at/after this date").option("--query <keyword>", "seed mode: keyword to seed the overview graph").option("--workspace <guid>", "Target a specific workspace (from `tiro wiki workspaces`); defaults to your default workspace").addHelpText("after", HELP_AFTER6).action(async (pageGuid, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const mode = parseMode(opts.mode);
+    if ((mode === "expand" || mode === "around") && !pageGuid) {
+      throw new TiroError(
+        {
+          code: "missing_page_guid",
+          message: `--mode ${mode} requires a <pageGuid> positional argument.`,
+          errorType: "bad_request",
+          suggestion: `tiro wiki graph <pageGuid> --mode ${mode}`
+        },
+        ExitCode.Usage
+      );
+    }
+    const client = createApiClient({
+      ...globalOpts.hostname !== void 0 && { hostnameOverride: globalOpts.hostname }
+    });
+    const workspaceGuid = opts.workspace ?? await resolveWorkspaceGuid(client);
+    const effectiveLimit = mode === "links" ? void 0 : clampInt(opts.limit, 200) ?? GRAPH_CAP_DEFAULT;
+    const raw = await fetchGraph(client, workspaceGuid, mode, pageGuid ?? "", opts, effectiveLimit);
+    const res = applyGraphCap(raw, effectiveLimit ?? raw.nodes.length);
+    const mode2 = resolveOutputMode(globalOpts);
+    if (mode2 === "json") {
+      printOutput({ ok: true, data: res }, globalOpts);
+    } else {
+      printPretty6(res, globalOpts);
+    }
+  });
+}
+async function fetchGraph(client, workspaceGuid, mode, pageGuid, opts, limit) {
+  const base = `/v1/external/workspaces/${encodeURIComponent(workspaceGuid)}/wiki/graph`;
+  if (mode === "expand") {
+    return client.getJson(`${base}/expand`, WikiGraphResponseSchema, {
+      pageGuid,
+      depth: clampInt(opts.depth, 200),
+      limit
+    });
+  }
+  if (mode === "around") {
+    return client.getJson(`${base}/around`, WikiGraphResponseSchema, {
+      pageGuid,
+      radius: clampInt(opts.radius, 200),
+      limit
+    });
+  }
+  if (mode === "links") {
+    const guids = [pageGuid, ...opts.page ?? []].filter((g) => g && g.length > 0);
+    return client.getJson(`${base}/links`, WikiGraphResponseSchema, {
+      pageGuids: guids.join(",")
+    });
+  }
+  const rawQuery = opts.query;
+  const clampedQuery = rawQuery && rawQuery.length > MAX_QUERY_LENGTH2 ? rawQuery.slice(0, MAX_QUERY_LENGTH2) : rawQuery;
+  return client.getJson(`${base}/seed`, WikiGraphResponseSchema, {
+    type: opts.type,
+    since: opts.since ? parseDate(opts.since) : void 0,
+    q: clampedQuery,
+    limit
+  });
+}
+function parseMode(raw) {
+  if (!raw) return "around";
+  const m = raw.toLowerCase();
+  if (MODES.includes(m)) return m;
+  throw new TiroError(
+    {
+      code: "invalid_mode",
+      message: `Invalid --mode "${raw}". Allowed: ${MODES.join(", ")}.`,
+      errorType: "bad_request",
+      suggestion: "tiro wiki graph <pageGuid> --mode around"
+    },
+    ExitCode.Usage
+  );
+}
+function clampInt(raw, max) {
+  if (!raw) return void 0;
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n <= 0) return void 0;
+  return Math.min(n, max);
+}
+function collect(value, prev) {
+  return [...prev, value];
+}
+function applyGraphCap(graph, limit) {
+  const keptNodes = graph.nodes.slice(0, limit);
+  const keptGuids = new Set(keptNodes.map((n) => n.guid));
+  const keptEdges = graph.edges.filter(
+    (e) => keptGuids.has(e.sourcePageGuid) && keptGuids.has(e.targetPageGuid)
+  );
+  const truncated = graph.nodes.length > limit || keptEdges.length < graph.edges.length;
+  return { ...graph, nodes: keptNodes, edges: keptEdges, truncated };
+}
+function printPretty6(res, opts) {
+  const w = process.stdout.write.bind(process.stdout);
+  w(
+    `${color("nodes", "gray", opts)} ${res.nodes.length}  ${color("edges", "gray", opts)} ${res.edges.length}
+`
+  );
+  if (res.truncated) {
+    w(
+      `${color(`(truncated \u2014 showing first ${res.nodes.length} nodes; narrow with --query / --type / smaller --radius)`, "gray", opts)}
+`
+    );
+  }
+  w("\n");
+  for (const n of res.nodes) {
+    w(`${color("\u25CF", "cyan", opts)} ${color(n.guid, "dim", opts)}  ${n.canonicalName}
+`);
+  }
+  if (res.edges.length > 0) w("\n");
+  for (const e of res.edges) {
+    const arrow = e.isDirectional ? "\u2192" : "\u2014";
+    w(
+      `${color(e.sourcePageGuid, "dim", opts)} ${arrow} ${color(e.targetPageGuid, "dim", opts)}  ${color(e.linkType, "gray", opts)}
+`
+    );
+  }
+}
+
+// src/commands/wiki/workspaces.ts
+import "commander";
+var HELP_AFTER7 = `
+Examples:
+  tiro wiki workspaces
+  tiro wiki workspaces --json
+
+Lists all workspaces you are a member of. Use the guid with --workspace on
+any other wiki command to target a non-default workspace.
+`;
+function registerWikiWorkspaces(parent) {
+  parent.command("workspaces").description("List all workspaces you are a member of (use guid with --workspace).").addHelpText("after", HELP_AFTER7).action(async (_opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const client = createApiClient({
+      ...globalOpts.hostname !== void 0 && { hostnameOverride: globalOpts.hostname }
+    });
+    const workspaces = await listWorkspaces(client);
+    const mode = resolveOutputMode(globalOpts);
+    if (mode === "json") {
+      for (const ws of workspaces) printNdjson(ws);
+    } else {
+      printPretty7(workspaces, globalOpts);
+    }
+  });
+}
+function printPretty7(workspaces, opts) {
+  if (workspaces.length === 0) {
+    process.stdout.write(`${color("(no workspaces)", "gray", opts)}
+`);
+    return;
+  }
+  for (const ws of workspaces) {
+    const wikiStatus = ws.isWikiEnabled ? color("wiki:on", "green", opts) : color("wiki:off", "gray", opts);
+    process.stdout.write(
+      `${color(ws.guid, "dim", opts)}  ${wikiStatus}  ${ws.name}
+`
+    );
+  }
+}
+
+// src/commands/wiki/index.ts
+function registerWiki(program) {
+  const wiki = program.command("wiki").description("Search and explore the workspace wiki (pages, mentions, link graph)");
+  registerWikiSearch(wiki);
+  registerWikiPage(wiki);
+  registerWikiMentions(wiki);
+  registerWikiGraph(wiki);
+  registerWikiWorkspaces(wiki);
+}
+
 // src/commands/mcp/index.ts
 import "commander";
 
@@ -2024,6 +2595,8 @@ EXAMPLES
   $ tiro notes get <guid> --output ./meeting.md --include transcript
   $ tiro notes transcript <guid> --format md --output ./transcript.md
   $ tiro notes transcript <guid> --format md --no-timestamps --output ./clean.md
+  $ tiro wiki search "onboarding" --json
+  $ tiro wiki graph <pageGuid> --mode around --radius 2
   $ tiro mcp install                  # one-line setup for Claude Code
 
 ENVIRONMENT
@@ -2036,11 +2609,12 @@ DOCS
   https://api-docs.tiro.ooo/cli
 `;
 function buildProgram() {
-  const program = new Command13();
+  const program = new Command19();
   program.name("tiro").description("Tiro AI notes & transcripts \u2014 agent-first command line").version(VERSION, "-v, --version", "Print version").option("--hostname <url>", "API base URL (default: https://api.tiro.ooo)").option("--json", "Force JSON output").option("--pretty", "Force pretty (human) output").option("--quiet", "Suppress non-error output").option("--verbose", "Verbose logging to stderr").option("--no-color", "Disable ANSI colors").addHelpText("after", EXAMPLES);
   program.showHelpAfterError("(run `tiro --help` for available commands)");
   registerAuth(program);
   registerNotes(program);
+  registerWiki(program);
   registerMcp(program);
   return program;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theplato/tiro-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Tiro AI notes & transcripts — agent-first command line",
   "type": "module",
   "bin": {
@@ -22,7 +22,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:security": "vitest run --testNamePattern \"\\\\((C|H|M)[0-9]+\\\\)\"",
+    "test:security": "vitest run --testNamePattern \"\\\\((C|H|M|X)[0-9]+\\\\)\"",
     "prepublishOnly": "npm run typecheck && npm test && npm run build"
   },
   "keywords": [