@ted-galago/wave-cli 0.1.19 → 0.1.22

package/README.md

@@ -120,6 +120,7 @@ wave markdown-tree resolve --tool-key projects --node-key tasks --parent-id 123
 wave markdown-tree children --tool-key directory --node-key members --record-id 67
 wave markdown-tree subtree --tool-key knowledge --node-key knowledge --content-type processes --depth 2
 wave osmd tree
+wave osmd search "Wave Tools" --scope combined --limit 10
 wave osmd read "projects/Wave Tools"
 wave osmd children "projects/Wave Tools"
 wave osmd status "projects/Wave Tools/.agent/notes.md" --parent-ref "projects/Wave Tools"
@@ -132,6 +133,8 @@ wave osmd wiki read log.md
 wave osmd wiki init
 wave osmd wiki create index.md --content "# Agent Wiki"
 wave osmd wiki update "Agent Wiki/index.md" --file ./agent-wiki-index.md
+wave osmd wiki create "concepts/customer-health.md" --content "# Customer Health"
+wave osmd wiki update "decisions/use-agent-wiki.md" --content "# Use Agent Wiki"
 wave osmd wiki append-log --content "Observed durable event"
 wave find "Ted"
 wave open "Ted Martinez"
@@ -307,6 +310,7 @@ The `osmd` command group is the write-capable agent interface for canonical OSMD
 Commands:
 
 - `wave osmd tree [--depth <n>] [--tree-view]`
+- `wave osmd search "<query>" [--scope os-only|agent-overlay-only|agent-wiki-only|combined] [--limit <n>]`
 - `wave osmd read <path> [--parent-ref <canonicalPath>]`
 - `wave osmd children [path] [--parent-ref <canonicalPath>] [--source canonical_osmd|agent_overlay|agent_wiki]`
 - `wave osmd status <path> [--parent-ref <canonicalPath>]`
@@ -326,6 +330,7 @@ Commands:
 GraphQL mapping:
 
 - `osmd status` / `osmd agent status` / `osmd wiki status` -> `agentMarkdownStatus`
+- `osmd search` -> `osMdSearch`
 - `osmd read` / `osmd agent read` / `osmd wiki read` -> `agentMarkdownFile`
 - `osmd children` / `osmd wiki children` -> `agentMarkdownChildren`
 - `osmd agent init` -> `initAgentMarkdown`
@@ -342,13 +347,16 @@ Path and permission rules:
 - `.agent` first slice supports only `notes.md`.
 - `osmd agent init <parent-ref>` is idempotent for default `.agent` files.
 - Agent Wiki index paths may be `index.md` or `Agent Wiki/index.md`; the CLI normalizes these to `Agent Wiki/index.md`.
+- Controlled Agent Wiki page paths may be `concepts/<name>.md`, `playbooks/<name>.md`, `decisions/<name>.md`, `org-summaries/<name>.md`, or the same forms prefixed with `Agent Wiki/`.
 - Agent Wiki log paths may be `log.md` or `Agent Wiki/log.md`; the CLI normalizes these to `Agent Wiki/log.md`.
-- Agent Wiki first-slice agents should use `index.md` for broad writable wiki memory and `log.md` for append-only event memory.
+- Agent Wiki agents should use `index.md` for broad writable wiki memory, controlled folders for durable typed pages, and `log.md` for append-only event memory.
 - Agent Wiki `init` initializes backend-owned system files, including append-only `log.md`, through `initAgentMarkdown` at path `Agent Wiki`.
-- Agent Wiki `create` and `update` support only `index.md`; `log.md` cannot be overwritten.
+- Agent Wiki `create` and `update` support `index.md`, `concepts/*.md`, `playbooks/*.md`, `decisions/*.md`, and `org-summaries/*.md`; `log.md` cannot be created or overwritten by these commands.
 - Agent Wiki `append-log` supports only `log.md` and calls status first before appending.
 - The CLI uses backend GraphQL metadata directly and does not derive S3 paths, SHA paths, or backend storage conventions.
 - Atlas should inspect `path`, `source`, `access`, `owner`, `parentRef`, `exists`, `canCreate`, `canUpdate`, `canAppend`, `wikiRole`, `formatVersion`, `suggestedAction`, and `errorCode`.
+- `osmd search` scopes map to backend `source` values: `os-only` -> `canonical_osmd`, `agent-overlay-only` -> `agent_overlay`, `agent-wiki-only` -> `agent_wiki`, and `combined` -> backend merged search.
+- `osmd search` returns backend candidates with `path`, `source`, `access`, `owner`, `wikiRole`, `formatVersion`, `parentRef`, `exists`, `agentChildrenAllowed`, `title`, `label`, `snippet`, `rank`, `matchReason`, `toolKey`, `nodeKey`, and `nodeKind` where the backend provides them.
 - Reads never create files.
 - Create/update/append-log flows call status first and inspect `exists`, `canCreate`, `canUpdate`, `canAppend`, `suggestedAction`, and `errorCode`.
 - `create` fails when `exists` is true.
@@ -356,6 +364,7 @@ Path and permission rules:
 - `append-log` fails unless status reports `exists: true`, `access: "append_only"`, and `canAppend: true`.
 - When `Agent Wiki/log.md` is missing and status reports `suggestedAction: "init"`, `append-log` returns a JSON error telling Atlas to run `wave osmd wiki init`.
 - Missing `Agent Wiki/index.md` is create-ready when status returns `exists: false`, `canCreate: true`, `canUpdate: false`, and `suggestedAction: "create"`.
+- Missing controlled pages are create-ready when backend status returns `exists: false`, `canCreate: true`, `canUpdate: false`, and `suggestedAction: "create"`.
 
 Atlas Agent Wiki log flow:
 
@@ -377,6 +386,22 @@ wave osmd wiki read index.md
 wave osmd wiki update index.md --content "# Agent Wiki\n\n## Entity Notes\n\n- directory/Wave Tools Team -> .agent/notes.md"
 ```
 
+Create or update controlled Agent Wiki pages. Atlas should call `status` first, then choose `create` or `update` from backend `canCreate`, `canUpdate`, and `suggestedAction`:
+
+```bash
+wave osmd wiki status concepts/customer-health.md
+wave osmd wiki create concepts/customer-health.md --content "# Customer Health\n\nDurable definition and usage notes."
+
+wave osmd wiki status decisions/use-agent-wiki.md
+wave osmd wiki update decisions/use-agent-wiki.md --content "# Use Agent Wiki\n\nDecision: store broad agent memory in controlled Agent Wiki pages."
+
+wave osmd wiki status playbooks/customer-review.md
+wave osmd wiki create playbooks/customer-review.md --content "# Customer Review\n\n1. Read the customer summary.\n2. Review recent notes.\n3. Append the maintenance log."
+
+wave osmd wiki status org-summaries/galago.md
+wave osmd wiki update org-summaries/galago.md --content "# Galago\n\nCurrent durable organization summary."
+```
+
 Append a parseable log entry. Use a stable fenced block so Atlas or backend jobs can parse the chronology later:
 
 ````bash
@@ -429,6 +454,44 @@ OSMD command envelopes keep the global CLI envelope and put the file metadata di
 }
 ```
 
+Merged OSMD search keeps the same envelope and returns backend-ranked candidates:
+
+```json
+{
+  "ok": true,
+  "command": "osmd.search",
+  "status": 200,
+  "data": {
+    "query": "Wave Tools",
+    "scope": "combined",
+    "count": 3,
+    "candidates": [
+      {
+        "path": "directory/Wave Tools Team/.agent/notes.md",
+        "source": "agent_overlay",
+        "access": "read_write",
+        "owner": "atlas",
+        "wikiRole": "notes",
+        "formatVersion": "agent_markdown_v1",
+        "parentRef": "directory/Wave Tools Team",
+        "exists": true,
+        "agentChildrenAllowed": false,
+        "title": "notes.md",
+        "label": "notes.md",
+        "snippet": "...",
+        "rank": 1,
+        "matchReason": "content",
+        "toolKey": "agent_overlay",
+        "nodeKey": "notes",
+        "nodeKind": "agent_overlay_file"
+      }
+    ]
+  },
+  "error": null,
+  "meta": { "requestId": "req_125" }
+}
+```
+
 On write preflight errors, `data` contains the status metadata and `error.suggestedAction` mirrors backend guidance:
 
 ```json
@@ -482,6 +545,12 @@ These wrap backend-owned markdown-tree primitives:
 Discovery, ranking, canonical paths, and narrowing are backend-owned.
 An empty `find` result (`candidates: []`) means no evidence for that exact query/scope, not confirmed global absence.
 `markdownTreeFind` remains canonical-focused. Agent overlay and Agent Wiki files are discoverable through `osmd tree`, `osmd children`, and `osmd status`, not through `find`.
+Use `wave osmd search "<query>" --scope combined` when Atlas needs merged canonical OSMD, `.agent`, and Agent Wiki search. Use narrower scopes for targeted memory lookup:
+
+- `--scope os-only` searches canonical OSMD only.
+- `--scope agent-overlay-only` searches entity-specific `.agent` files.
+- `--scope agent-wiki-only` searches broad Agent Wiki files, including `index.md`, controlled pages, and append-only `log.md`.
+- `--scope combined` searches the backend merged OSMD surface.
 
 Ambiguity contract:
 

package/dist/index.cjs

@@ -6143,10 +6143,26 @@ var agentMarkdownErrorCodeSchema = import_zod16.z.enum([
 var agentMarkdownErrorCodeFieldSchema = agentMarkdownErrorCodeSchema.nullable().catch(null);
 var nonEmptyString3 = import_zod16.z.string().min(1);
 var nonNegativeInt3 = import_zod16.z.coerce.number().int().min(0);
+var positiveInt = import_zod16.z.coerce.number().int().min(1);
 var supportedAgentOverlayFile = "notes.md";
 var supportedWikiIndexFile = "index.md";
 var supportedWikiLogFile = "log.md";
+var supportedWikiControlledFolders = [
+  "concepts",
+  "playbooks",
+  "decisions",
+  "org-summaries"
+];
+var supportedWikiControlledPatterns = supportedWikiControlledFolders.map(
+  (folder) => `${folder}/*.md`
+);
 var agentOverlayFileSchema = import_zod16.z.enum([supportedAgentOverlayFile]);
+var osmdSearchScopeSchema = import_zod16.z.enum([
+  "os-only",
+  "agent-overlay-only",
+  "agent-wiki-only",
+  "combined"
+]);
 var agentMarkdownFileSchema = import_zod16.z.object({
   path: import_zod16.z.string(),
   source: sourceSchema,
@@ -6178,6 +6194,47 @@ var agentMarkdownMutationDataSchema = import_zod16.z.union([
   agentMarkdownFileSchema,
   import_zod16.z.object({ files: agentMarkdownFilesSchema })
 ]);
+var osmdSearchCandidateSchema = import_zod16.z.preprocess(
+  normalizeAgentMarkdownJsonKeys,
+  import_zod16.z.object({
+    path: import_zod16.z.string(),
+    source: sourceSchema,
+    access: accessSchema,
+    owner: ownerSchema,
+    wikiRole: import_zod16.z.string().nullable().optional(),
+    formatVersion: import_zod16.z.string().nullable().optional(),
+    parentRef: import_zod16.z.string().nullable().optional(),
+    exists: import_zod16.z.boolean(),
+    agentChildrenAllowed: import_zod16.z.boolean(),
+    title: import_zod16.z.string(),
+    label: import_zod16.z.string(),
+    snippet: import_zod16.z.string().nullable().optional(),
+    rank: import_zod16.z.number().int(),
+    matchReason: import_zod16.z.string().nullable().optional(),
+    toolKey: import_zod16.z.string().nullable().optional(),
+    nodeKey: import_zod16.z.string().nullable().optional(),
+    nodeKind: import_zod16.z.string().nullable().optional()
+  }).transform((value) => ({
+    ...value,
+    wikiRole: value.wikiRole ?? null,
+    formatVersion: value.formatVersion ?? null,
+    parentRef: value.parentRef ?? null,
+    snippet: value.snippet ?? null,
+    matchReason: value.matchReason ?? null,
+    toolKey: value.toolKey ?? null,
+    nodeKey: value.nodeKey ?? null,
+    nodeKind: value.nodeKind ?? null
+  }))
+);
+var osmdSearchResultSchema = import_zod16.z.preprocess(
+  normalizeAgentMarkdownJsonKeys,
+  import_zod16.z.object({
+    query: import_zod16.z.string(),
+    scope: import_zod16.z.string(),
+    count: import_zod16.z.number().int().min(0),
+    candidates: import_zod16.z.array(osmdSearchCandidateSchema)
+  })
+);
 var mutationPayloadSchema = import_zod16.z.object({
   ok: import_zod16.z.boolean(),
   status: import_zod16.z.number(),
@@ -6229,6 +6286,30 @@ var AGENT_MARKDOWN_FILE_SELECTION = `{
   content
   url
 }`;
+var OSMD_SEARCH_SELECTION = `{
+  query
+  scope
+  count
+  candidates {
+    path
+    source
+    access
+    owner
+    wikiRole
+    formatVersion
+    parentRef
+    exists
+    agentChildrenAllowed
+    title
+    label
+    snippet
+    rank
+    matchReason
+    toolKey
+    nodeKey
+    nodeKind
+  }
+}`;
 var MUTATION_RESULT_SELECTION = "{ ok status errorCode data errors }";
 var AGENT_JSON_KEY_ALIASES = {
   can_create: "canCreate",
@@ -6239,7 +6320,11 @@ var AGENT_JSON_KEY_ALIASES = {
   parent_ref: "parentRef",
   agent_children_allowed: "agentChildrenAllowed",
   suggested_action: "suggestedAction",
-  error_code: "errorCode"
+  error_code: "errorCode",
+  match_reason: "matchReason",
+  tool_key: "toolKey",
+  node_key: "nodeKey",
+  node_kind: "nodeKind"
 };
 function isSupportedAgentMarkdownFile(file) {
   if (file.source !== "agent_overlay") {
@@ -6391,6 +6476,22 @@ async function requestAgentMarkdownChildren(params) {
     schema: agentMarkdownFilesSchema
   });
 }
+async function requestOsmdSearch(params) {
+  return requestOsmdQuery({
+    command: params.command,
+    operationName: "OsMdSearch",
+    runtimeOptions: params.runtimeOptions,
+    field: "os_md_search",
+    variables: {
+      organization_id: params.organizationId,
+      query: params.query,
+      source: backendSearchSourceForScope(params.scope),
+      limit: params.limit
+    },
+    selectionSet: OSMD_SEARCH_SELECTION,
+    schema: osmdSearchResultSchema
+  });
+}
 async function runAgentMarkdownMutation(params) {
   const result = await graphqlRequest({
     config: getConfig(params.runtimeOptions),
@@ -6448,41 +6549,113 @@ function normalizeAgentFilePath(file) {
   }
   return `.agent/${parsed.data}`;
 }
-function supportedWikiFilesMessage(files) {
-  return `Agent Wiki file commands support only ${files.join(" and ")} in this CLI slice.`;
+function formatHumanList(items) {
+  if (items.length <= 1) {
+    return items[0] ?? "";
+  }
+  if (items.length === 2) {
+    return `${items[0]} and ${items[1]}`;
+  }
+  return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
+}
+function supportedWikiPathsMessage(options = {}) {
+  const allowed = allowedWikiPathLabels(options);
+  return `Agent Wiki file commands support only ${formatHumanList(allowed)} in this CLI slice.`;
+}
+function allowedWikiPathLabels(options = {}) {
+  const allowIndex = options.allowIndex ?? true;
+  const allowLog = options.allowLog ?? true;
+  const allowControlledPages = options.allowControlledPages ?? true;
+  const labels = [];
+  if (options.allowRoot) {
+    labels.push("Agent Wiki");
+  }
+  if (allowIndex) {
+    labels.push(supportedWikiIndexFile);
+  }
+  if (allowLog) {
+    labels.push(supportedWikiLogFile);
+  }
+  if (allowControlledPages) {
+    labels.push(...supportedWikiControlledPatterns);
+  }
+  if (options.allowControlledFolders) {
+    labels.push(...supportedWikiControlledFolders);
+  }
+  return labels;
+}
+function rejectUnsupportedWikiPath(options) {
+  throw new CliError({
+    message: supportedWikiPathsMessage(options),
+    kind: "invalid_args",
+    status: 400,
+    exitCode: EXIT_CODES.invalidArgs,
+    details: { supportedPaths: allowedWikiPathLabels(options) }
+  });
+}
+function isControlledWikiFolder(value) {
+  return supportedWikiControlledFolders.includes(
+    value
+  );
+}
+function isMarkdownLeafFileName(value) {
+  return value.endsWith(".md") && value.length > ".md".length;
 }
 function normalizeWikiPath(path, options = {}) {
-  const supportedFiles = options.supportedFiles ?? [supportedWikiIndexFile, supportedWikiLogFile];
+  const normalizedOptions = {
+    allowIndex: options.allowIndex ?? true,
+    allowLog: options.allowLog ?? true,
+    allowControlledPages: options.allowControlledPages ?? true,
+    allowRoot: options.allowRoot ?? false,
+    allowControlledFolders: options.allowControlledFolders ?? false
+  };
   const trimmed = nonEmptyString3.parse(path).trim().replace(/^\/+/, "");
   if (trimmed.localeCompare("Agent Wiki", void 0, { sensitivity: "accent" }) === 0) {
-    if (options.allowRoot) {
+    if (normalizedOptions.allowRoot) {
       return "Agent Wiki";
     }
-    throw new CliError({
-      message: supportedWikiFilesMessage(supportedFiles),
-      kind: "invalid_args",
-      status: 400,
-      exitCode: EXIT_CODES.invalidArgs,
-      details: { supportedFiles }
-    });
+    return rejectUnsupportedWikiPath(normalizedOptions);
   }
   const fileName = trimmed.toLowerCase().startsWith("agent wiki/") ? trimmed.slice("Agent Wiki/".length) : trimmed;
-  if (!supportedFiles.includes(fileName)) {
-    throw new CliError({
-      message: supportedWikiFilesMessage(supportedFiles),
-      kind: "invalid_args",
-      status: 400,
-      exitCode: EXIT_CODES.invalidArgs,
-      details: { supportedFiles }
-    });
+  if (fileName.includes("\\") || fileName.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+    return rejectUnsupportedWikiPath(normalizedOptions);
+  }
+  if (fileName === supportedWikiIndexFile) {
+    if (normalizedOptions.allowIndex) {
+      return `Agent Wiki/${fileName}`;
+    }
+    return rejectUnsupportedWikiPath(normalizedOptions);
+  }
+  if (fileName === supportedWikiLogFile) {
+    if (normalizedOptions.allowLog) {
+      return `Agent Wiki/${fileName}`;
+    }
+    return rejectUnsupportedWikiPath(normalizedOptions);
+  }
+  if (isControlledWikiFolder(fileName)) {
+    if (normalizedOptions.allowControlledFolders) {
+      return `Agent Wiki/${fileName}`;
+    }
+    return rejectUnsupportedWikiPath(normalizedOptions);
+  }
+  const parts = fileName.split("/");
+  if (parts.length === 2 && isControlledWikiFolder(parts[0] ?? "") && isMarkdownLeafFileName(parts[1] ?? "")) {
+    if (normalizedOptions.allowControlledPages) {
+      return `Agent Wiki/${fileName}`;
+    }
+    return rejectUnsupportedWikiPath(normalizedOptions);
   }
-  return `Agent Wiki/${fileName}`;
+  return rejectUnsupportedWikiPath(normalizedOptions);
 }
-function normalizeWikiIndexPath(path) {
-  return normalizeWikiPath(path, { supportedFiles: [supportedWikiIndexFile] });
+function normalizeWikiWritablePath(path) {
+  return normalizeWikiPath(path, { allowLog: false });
 }
 function normalizeWikiLogPath(path = supportedWikiLogFile) {
-  return normalizeWikiPath(path, { supportedFiles: [supportedWikiLogFile] });
+  return normalizeWikiPath(path, {
+    allowIndex: false,
+    allowLog: true,
+    allowControlledPages: false
+  });
 }
 function parseOptionalParentRef(value) {
   return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
@@ -6503,6 +6676,46 @@ function parseOptionalSource(value) {
   }
   return parsed.data;
 }
+function parseOsmdSearchScope(value) {
+  const raw = typeof value === "string" && value.trim() !== "" ? value.trim() : "combined";
+  const parsed = osmdSearchScopeSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new CliError({
+      message: "Invalid OSMD search scope. Use os-only, agent-overlay-only, agent-wiki-only, or combined.",
+      kind: "invalid_args",
+      status: 400,
+      exitCode: EXIT_CODES.invalidArgs,
+      details: { supportedScopes: osmdSearchScopeSchema.options }
+    });
+  }
+  return parsed.data;
+}
+function backendSearchSourceForScope(scope) {
+  if (scope === "os-only") {
+    return "canonical_osmd";
+  }
+  if (scope === "agent-overlay-only") {
+    return "agent_overlay";
+  }
+  if (scope === "agent-wiki-only") {
+    return "agent_wiki";
+  }
+  return "combined";
+}
+function parseSearchLimit(value) {
+  const raw = value === void 0 || value === null || value === "" ? "10" : value;
+  const parsed = positiveInt.safeParse(raw);
+  if (!parsed.success) {
+    throw new CliError({
+      message: "Invalid OSMD search limit. Use a positive integer.",
+      kind: "invalid_args",
+      status: 400,
+      exitCode: EXIT_CODES.invalidArgs,
+      details: { issues: parsed.error.issues }
+    });
+  }
+  return parsed.data;
+}
 function parseDepth(value) {
   if (value === void 0 || value === null || value === "") {
     return 1;
@@ -6792,7 +7005,7 @@ function registerOsmdCommands(program) {
       })
     });
   });
-  osmd.command("children [path]").description("List backend-supported agent markdown children; search remains canonical-only").option("--parent-ref <parentRef>", "Canonical OSMD parent ref for .agent files").option("--source <source>", "Filter by canonical_osmd, agent_overlay, or agent_wiki").action(async (path, opts, cmd) => {
+  osmd.command("children [path]").description("List backend-supported agent markdown children").option("--parent-ref <parentRef>", "Canonical OSMD parent ref for .agent files").option("--source <source>", "Filter by canonical_osmd, agent_overlay, or agent_wiki").action(async (path, opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
     const result = await requestAgentMarkdownChildren({
       command: "osmd.children",
@@ -6811,6 +7024,25 @@ function registerOsmdCommands(program) {
       })
     });
   });
+  osmd.command("search <query>").description("Search merged OSMD, .agent overlays, and Agent Wiki through backend OSMD search").option("--scope <scope>", "os-only, agent-overlay-only, agent-wiki-only, or combined", "combined").option("--limit <limit>", "Maximum number of results", "10").action(async (query, opts, cmd) => {
+    const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
+    const result = await requestOsmdSearch({
+      command: "osmd.search",
+      runtimeOptions,
+      organizationId,
+      query: nonEmptyString3.parse(query).trim(),
+      scope: parseOsmdSearchScope(opts.scope),
+      limit: parseSearchLimit(opts.limit)
+    });
+    return printEnvelopeAndExit({
+      envelope: buildSuccessEnvelope({
+        command: "osmd.search",
+        status: result.status,
+        data: result.data,
+        requestId: result.requestId
+      })
+    });
+  });
   const agent = osmd.command("agent").description(".agent overlay memory attached to canonical OSMD parents; supports notes.md");
   agent.command("status <parent-ref> <file>").description("Show .agent notes.md metadata without creating files").action(async (parentRef, file, _opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
@@ -6898,7 +7130,7 @@ function registerOsmdCommands(program) {
       });
     }
   );
-  const wiki = osmd.command("wiki").description("Agent Wiki files writable by agents; supports index.md and append-only log.md");
+  const wiki = osmd.command("wiki").description("Agent Wiki files writable by agents; supports index.md, controlled pages, and append-only log.md");
   wiki.command("init").description("Idempotently initialize Agent Wiki system files").action(async function() {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(this);
     return runAgentMarkdownMutation({
@@ -6912,7 +7144,7 @@ function registerOsmdCommands(program) {
       }
     });
   });
-  wiki.command("status <path>").description("Show Agent Wiki index.md or log.md metadata without creating files").action(async (path, _opts, cmd) => {
+  wiki.command("status <path>").description("Show Agent Wiki index.md, log.md, or controlled page metadata without creating files").action(async (path, _opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
     const result = await requestAgentMarkdownStatus({
       command: "osmd.wiki.status",
@@ -6929,7 +7161,7 @@ function registerOsmdCommands(program) {
       })
     });
   });
-  wiki.command("read <path>").description("Read Agent Wiki index.md or log.md without creating files").action(async (path, _opts, cmd) => {
+  wiki.command("read <path>").description("Read Agent Wiki index.md, log.md, or controlled pages without creating files").action(async (path, _opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
     const result = await requestAgentMarkdownFile({
       command: "osmd.wiki.read",
@@ -6952,7 +7184,7 @@ function registerOsmdCommands(program) {
       command: "osmd.wiki.children",
       runtimeOptions,
       organizationId,
-      path: typeof path === "string" && path.trim() !== "" ? normalizeWikiPath(path, { allowRoot: true }) : "Agent Wiki",
+      path: typeof path === "string" && path.trim() !== "" ? normalizeWikiPath(path, { allowRoot: true, allowControlledFolders: true }) : "Agent Wiki",
       source: "agent_wiki"
     });
     return printEnvelopeAndExit({
@@ -6965,7 +7197,7 @@ function registerOsmdCommands(program) {
     });
   });
   addContentOptions(
-    wiki.command("create <path>").description("Create Agent Wiki index.md after status/permission preflight")
+    wiki.command("create <path>").description("Create Agent Wiki index.md or controlled pages after status/permission preflight")
   ).action(async (path, opts, cmd) => {
     const globals = cmd.optsWithGlobals();
     const content = await resolveContentInput(opts, globals);
@@ -6975,12 +7207,12 @@ function registerOsmdCommands(program) {
       action: "create",
       runtimeOptions,
       organizationId,
-      path: normalizeWikiIndexPath(path),
+      path: normalizeWikiWritablePath(path),
       content
     });
   });
   addContentOptions(
-    wiki.command("update <path>").description("Update Agent Wiki index.md after status/permission preflight")
+    wiki.command("update <path>").description("Update Agent Wiki index.md or controlled pages after status/permission preflight")
   ).action(async (path, opts, cmd) => {
     const globals = cmd.optsWithGlobals();
     const content = await resolveContentInput(opts, globals);
@@ -6990,7 +7222,7 @@ function registerOsmdCommands(program) {
       action: "update",
       runtimeOptions,
       organizationId,
-      path: normalizeWikiIndexPath(path),
+      path: normalizeWikiWritablePath(path),
       content
     });
   });

package/dist/index.js

@@ -6142,10 +6142,26 @@ var agentMarkdownErrorCodeSchema = z16.enum([
 var agentMarkdownErrorCodeFieldSchema = agentMarkdownErrorCodeSchema.nullable().catch(null);
 var nonEmptyString3 = z16.string().min(1);
 var nonNegativeInt3 = z16.coerce.number().int().min(0);
+var positiveInt = z16.coerce.number().int().min(1);
 var supportedAgentOverlayFile = "notes.md";
 var supportedWikiIndexFile = "index.md";
 var supportedWikiLogFile = "log.md";
+var supportedWikiControlledFolders = [
+  "concepts",
+  "playbooks",
+  "decisions",
+  "org-summaries"
+];
+var supportedWikiControlledPatterns = supportedWikiControlledFolders.map(
+  (folder) => `${folder}/*.md`
+);
 var agentOverlayFileSchema = z16.enum([supportedAgentOverlayFile]);
+var osmdSearchScopeSchema = z16.enum([
+  "os-only",
+  "agent-overlay-only",
+  "agent-wiki-only",
+  "combined"
+]);
 var agentMarkdownFileSchema = z16.object({
   path: z16.string(),
   source: sourceSchema,
@@ -6177,6 +6193,47 @@ var agentMarkdownMutationDataSchema = z16.union([
   agentMarkdownFileSchema,
   z16.object({ files: agentMarkdownFilesSchema })
 ]);
+var osmdSearchCandidateSchema = z16.preprocess(
+  normalizeAgentMarkdownJsonKeys,
+  z16.object({
+    path: z16.string(),
+    source: sourceSchema,
+    access: accessSchema,
+    owner: ownerSchema,
+    wikiRole: z16.string().nullable().optional(),
+    formatVersion: z16.string().nullable().optional(),
+    parentRef: z16.string().nullable().optional(),
+    exists: z16.boolean(),
+    agentChildrenAllowed: z16.boolean(),
+    title: z16.string(),
+    label: z16.string(),
+    snippet: z16.string().nullable().optional(),
+    rank: z16.number().int(),
+    matchReason: z16.string().nullable().optional(),
+    toolKey: z16.string().nullable().optional(),
+    nodeKey: z16.string().nullable().optional(),
+    nodeKind: z16.string().nullable().optional()
+  }).transform((value) => ({
+    ...value,
+    wikiRole: value.wikiRole ?? null,
+    formatVersion: value.formatVersion ?? null,
+    parentRef: value.parentRef ?? null,
+    snippet: value.snippet ?? null,
+    matchReason: value.matchReason ?? null,
+    toolKey: value.toolKey ?? null,
+    nodeKey: value.nodeKey ?? null,
+    nodeKind: value.nodeKind ?? null
+  }))
+);
+var osmdSearchResultSchema = z16.preprocess(
+  normalizeAgentMarkdownJsonKeys,
+  z16.object({
+    query: z16.string(),
+    scope: z16.string(),
+    count: z16.number().int().min(0),
+    candidates: z16.array(osmdSearchCandidateSchema)
+  })
+);
 var mutationPayloadSchema = z16.object({
   ok: z16.boolean(),
   status: z16.number(),
@@ -6228,6 +6285,30 @@ var AGENT_MARKDOWN_FILE_SELECTION = `{
   content
   url
 }`;
+var OSMD_SEARCH_SELECTION = `{
+  query
+  scope
+  count
+  candidates {
+    path
+    source
+    access
+    owner
+    wikiRole
+    formatVersion
+    parentRef
+    exists
+    agentChildrenAllowed
+    title
+    label
+    snippet
+    rank
+    matchReason
+    toolKey
+    nodeKey
+    nodeKind
+  }
+}`;
 var MUTATION_RESULT_SELECTION = "{ ok status errorCode data errors }";
 var AGENT_JSON_KEY_ALIASES = {
   can_create: "canCreate",
@@ -6238,7 +6319,11 @@ var AGENT_JSON_KEY_ALIASES = {
   parent_ref: "parentRef",
   agent_children_allowed: "agentChildrenAllowed",
   suggested_action: "suggestedAction",
-  error_code: "errorCode"
+  error_code: "errorCode",
+  match_reason: "matchReason",
+  tool_key: "toolKey",
+  node_key: "nodeKey",
+  node_kind: "nodeKind"
 };
 function isSupportedAgentMarkdownFile(file) {
   if (file.source !== "agent_overlay") {
@@ -6390,6 +6475,22 @@ async function requestAgentMarkdownChildren(params) {
     schema: agentMarkdownFilesSchema
   });
 }
+async function requestOsmdSearch(params) {
+  return requestOsmdQuery({
+    command: params.command,
+    operationName: "OsMdSearch",
+    runtimeOptions: params.runtimeOptions,
+    field: "os_md_search",
+    variables: {
+      organization_id: params.organizationId,
+      query: params.query,
+      source: backendSearchSourceForScope(params.scope),
+      limit: params.limit
+    },
+    selectionSet: OSMD_SEARCH_SELECTION,
+    schema: osmdSearchResultSchema
+  });
+}
 async function runAgentMarkdownMutation(params) {
   const result = await graphqlRequest({
     config: getConfig(params.runtimeOptions),
@@ -6447,41 +6548,113 @@ function normalizeAgentFilePath(file) {
   }
   return `.agent/${parsed.data}`;
 }
-function supportedWikiFilesMessage(files) {
-  return `Agent Wiki file commands support only ${files.join(" and ")} in this CLI slice.`;
+function formatHumanList(items) {
+  if (items.length <= 1) {
+    return items[0] ?? "";
+  }
+  if (items.length === 2) {
+    return `${items[0]} and ${items[1]}`;
+  }
+  return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
+}
+function supportedWikiPathsMessage(options = {}) {
+  const allowed = allowedWikiPathLabels(options);
+  return `Agent Wiki file commands support only ${formatHumanList(allowed)} in this CLI slice.`;
+}
+function allowedWikiPathLabels(options = {}) {
+  const allowIndex = options.allowIndex ?? true;
+  const allowLog = options.allowLog ?? true;
+  const allowControlledPages = options.allowControlledPages ?? true;
+  const labels = [];
+  if (options.allowRoot) {
+    labels.push("Agent Wiki");
+  }
+  if (allowIndex) {
+    labels.push(supportedWikiIndexFile);
+  }
+  if (allowLog) {
+    labels.push(supportedWikiLogFile);
+  }
+  if (allowControlledPages) {
+    labels.push(...supportedWikiControlledPatterns);
+  }
+  if (options.allowControlledFolders) {
+    labels.push(...supportedWikiControlledFolders);
+  }
+  return labels;
+}
+function rejectUnsupportedWikiPath(options) {
+  throw new CliError({
+    message: supportedWikiPathsMessage(options),
+    kind: "invalid_args",
+    status: 400,
+    exitCode: EXIT_CODES.invalidArgs,
+    details: { supportedPaths: allowedWikiPathLabels(options) }
+  });
+}
+function isControlledWikiFolder(value) {
+  return supportedWikiControlledFolders.includes(
+    value
+  );
+}
+function isMarkdownLeafFileName(value) {
+  return value.endsWith(".md") && value.length > ".md".length;
 }
 function normalizeWikiPath(path, options = {}) {
-  const supportedFiles = options.supportedFiles ?? [supportedWikiIndexFile, supportedWikiLogFile];
+  const normalizedOptions = {
+    allowIndex: options.allowIndex ?? true,
+    allowLog: options.allowLog ?? true,
+    allowControlledPages: options.allowControlledPages ?? true,
+    allowRoot: options.allowRoot ?? false,
+    allowControlledFolders: options.allowControlledFolders ?? false
+  };
   const trimmed = nonEmptyString3.parse(path).trim().replace(/^\/+/, "");
   if (trimmed.localeCompare("Agent Wiki", void 0, { sensitivity: "accent" }) === 0) {
-    if (options.allowRoot) {
+    if (normalizedOptions.allowRoot) {
       return "Agent Wiki";
     }
-    throw new CliError({
-      message: supportedWikiFilesMessage(supportedFiles),
-      kind: "invalid_args",
-      status: 400,
-      exitCode: EXIT_CODES.invalidArgs,
-      details: { supportedFiles }
-    });
+    return rejectUnsupportedWikiPath(normalizedOptions);
   }
   const fileName = trimmed.toLowerCase().startsWith("agent wiki/") ? trimmed.slice("Agent Wiki/".length) : trimmed;
-  if (!supportedFiles.includes(fileName)) {
-    throw new CliError({
-      message: supportedWikiFilesMessage(supportedFiles),
-      kind: "invalid_args",
-      status: 400,
-      exitCode: EXIT_CODES.invalidArgs,
-      details: { supportedFiles }
-    });
+  if (fileName.includes("\\") || fileName.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+    return rejectUnsupportedWikiPath(normalizedOptions);
+  }
+  if (fileName === supportedWikiIndexFile) {
+    if (normalizedOptions.allowIndex) {
+      return `Agent Wiki/${fileName}`;
+    }
+    return rejectUnsupportedWikiPath(normalizedOptions);
+  }
+  if (fileName === supportedWikiLogFile) {
+    if (normalizedOptions.allowLog) {
+      return `Agent Wiki/${fileName}`;
+    }
+    return rejectUnsupportedWikiPath(normalizedOptions);
+  }
+  if (isControlledWikiFolder(fileName)) {
+    if (normalizedOptions.allowControlledFolders) {
+      return `Agent Wiki/${fileName}`;
+    }
+    return rejectUnsupportedWikiPath(normalizedOptions);
+  }
+  const parts = fileName.split("/");
+  if (parts.length === 2 && isControlledWikiFolder(parts[0] ?? "") && isMarkdownLeafFileName(parts[1] ?? "")) {
+    if (normalizedOptions.allowControlledPages) {
+      return `Agent Wiki/${fileName}`;
+    }
+    return rejectUnsupportedWikiPath(normalizedOptions);
   }
-  return `Agent Wiki/${fileName}`;
+  return rejectUnsupportedWikiPath(normalizedOptions);
 }
-function normalizeWikiIndexPath(path) {
-  return normalizeWikiPath(path, { supportedFiles: [supportedWikiIndexFile] });
+function normalizeWikiWritablePath(path) {
+  return normalizeWikiPath(path, { allowLog: false });
 }
 function normalizeWikiLogPath(path = supportedWikiLogFile) {
-  return normalizeWikiPath(path, { supportedFiles: [supportedWikiLogFile] });
+  return normalizeWikiPath(path, {
+    allowIndex: false,
+    allowLog: true,
+    allowControlledPages: false
+  });
 }
 function parseOptionalParentRef(value) {
   return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
@@ -6502,6 +6675,46 @@ function parseOptionalSource(value) {
   }
   return parsed.data;
 }
+function parseOsmdSearchScope(value) {
+  const raw = typeof value === "string" && value.trim() !== "" ? value.trim() : "combined";
+  const parsed = osmdSearchScopeSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new CliError({
+      message: "Invalid OSMD search scope. Use os-only, agent-overlay-only, agent-wiki-only, or combined.",
+      kind: "invalid_args",
+      status: 400,
+      exitCode: EXIT_CODES.invalidArgs,
+      details: { supportedScopes: osmdSearchScopeSchema.options }
+    });
+  }
+  return parsed.data;
+}
+function backendSearchSourceForScope(scope) {
+  if (scope === "os-only") {
+    return "canonical_osmd";
+  }
+  if (scope === "agent-overlay-only") {
+    return "agent_overlay";
+  }
+  if (scope === "agent-wiki-only") {
+    return "agent_wiki";
+  }
+  return "combined";
+}
+function parseSearchLimit(value) {
+  const raw = value === void 0 || value === null || value === "" ? "10" : value;
+  const parsed = positiveInt.safeParse(raw);
+  if (!parsed.success) {
+    throw new CliError({
+      message: "Invalid OSMD search limit. Use a positive integer.",
+      kind: "invalid_args",
+      status: 400,
+      exitCode: EXIT_CODES.invalidArgs,
+      details: { issues: parsed.error.issues }
+    });
+  }
+  return parsed.data;
+}
 function parseDepth(value) {
   if (value === void 0 || value === null || value === "") {
     return 1;
@@ -6791,7 +7004,7 @@ function registerOsmdCommands(program) {
       })
     });
   });
-  osmd.command("children [path]").description("List backend-supported agent markdown children; search remains canonical-only").option("--parent-ref <parentRef>", "Canonical OSMD parent ref for .agent files").option("--source <source>", "Filter by canonical_osmd, agent_overlay, or agent_wiki").action(async (path, opts, cmd) => {
+  osmd.command("children [path]").description("List backend-supported agent markdown children").option("--parent-ref <parentRef>", "Canonical OSMD parent ref for .agent files").option("--source <source>", "Filter by canonical_osmd, agent_overlay, or agent_wiki").action(async (path, opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
     const result = await requestAgentMarkdownChildren({
       command: "osmd.children",
@@ -6810,6 +7023,25 @@ function registerOsmdCommands(program) {
       })
     });
   });
+  osmd.command("search <query>").description("Search merged OSMD, .agent overlays, and Agent Wiki through backend OSMD search").option("--scope <scope>", "os-only, agent-overlay-only, agent-wiki-only, or combined", "combined").option("--limit <limit>", "Maximum number of results", "10").action(async (query, opts, cmd) => {
+    const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
+    const result = await requestOsmdSearch({
+      command: "osmd.search",
+      runtimeOptions,
+      organizationId,
+      query: nonEmptyString3.parse(query).trim(),
+      scope: parseOsmdSearchScope(opts.scope),
+      limit: parseSearchLimit(opts.limit)
+    });
+    return printEnvelopeAndExit({
+      envelope: buildSuccessEnvelope({
+        command: "osmd.search",
+        status: result.status,
+        data: result.data,
+        requestId: result.requestId
+      })
+    });
+  });
   const agent = osmd.command("agent").description(".agent overlay memory attached to canonical OSMD parents; supports notes.md");
   agent.command("status <parent-ref> <file>").description("Show .agent notes.md metadata without creating files").action(async (parentRef, file, _opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
@@ -6897,7 +7129,7 @@ function registerOsmdCommands(program) {
       });
     }
   );
-  const wiki = osmd.command("wiki").description("Agent Wiki files writable by agents; supports index.md and append-only log.md");
+  const wiki = osmd.command("wiki").description("Agent Wiki files writable by agents; supports index.md, controlled pages, and append-only log.md");
   wiki.command("init").description("Idempotently initialize Agent Wiki system files").action(async function() {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(this);
     return runAgentMarkdownMutation({
@@ -6911,7 +7143,7 @@ function registerOsmdCommands(program) {
       }
     });
   });
-  wiki.command("status <path>").description("Show Agent Wiki index.md or log.md metadata without creating files").action(async (path, _opts, cmd) => {
+  wiki.command("status <path>").description("Show Agent Wiki index.md, log.md, or controlled page metadata without creating files").action(async (path, _opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
     const result = await requestAgentMarkdownStatus({
       command: "osmd.wiki.status",
@@ -6928,7 +7160,7 @@ function registerOsmdCommands(program) {
       })
     });
   });
-  wiki.command("read <path>").description("Read Agent Wiki index.md or log.md without creating files").action(async (path, _opts, cmd) => {
+  wiki.command("read <path>").description("Read Agent Wiki index.md, log.md, or controlled pages without creating files").action(async (path, _opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
     const result = await requestAgentMarkdownFile({
       command: "osmd.wiki.read",
@@ -6951,7 +7183,7 @@ function registerOsmdCommands(program) {
       command: "osmd.wiki.children",
       runtimeOptions,
       organizationId,
-      path: typeof path === "string" && path.trim() !== "" ? normalizeWikiPath(path, { allowRoot: true }) : "Agent Wiki",
+      path: typeof path === "string" && path.trim() !== "" ? normalizeWikiPath(path, { allowRoot: true, allowControlledFolders: true }) : "Agent Wiki",
       source: "agent_wiki"
     });
     return printEnvelopeAndExit({
@@ -6964,7 +7196,7 @@ function registerOsmdCommands(program) {
     });
   });
   addContentOptions(
-    wiki.command("create <path>").description("Create Agent Wiki index.md after status/permission preflight")
+    wiki.command("create <path>").description("Create Agent Wiki index.md or controlled pages after status/permission preflight")
   ).action(async (path, opts, cmd) => {
     const globals = cmd.optsWithGlobals();
     const content = await resolveContentInput(opts, globals);
@@ -6974,12 +7206,12 @@ function registerOsmdCommands(program) {
       action: "create",
       runtimeOptions,
       organizationId,
-      path: normalizeWikiIndexPath(path),
+      path: normalizeWikiWritablePath(path),
       content
     });
   });
   addContentOptions(
-    wiki.command("update <path>").description("Update Agent Wiki index.md after status/permission preflight")
+    wiki.command("update <path>").description("Update Agent Wiki index.md or controlled pages after status/permission preflight")
   ).action(async (path, opts, cmd) => {
     const globals = cmd.optsWithGlobals();
     const content = await resolveContentInput(opts, globals);
@@ -6989,7 +7221,7 @@ function registerOsmdCommands(program) {
       action: "update",
       runtimeOptions,
       organizationId,
-      path: normalizeWikiIndexPath(path),
+      path: normalizeWikiWritablePath(path),
       content
     });
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ted-galago/wave-cli",
-  "version": "0.1.19",
+  "version": "0.1.22",
   "type": "module",
   "bin": {
     "wave": "dist/index.js"

package/scripts/verify-dev-api.mjs

@@ -1330,6 +1330,124 @@ function runOsmdLiveVerification() {
     );
   }
 
+  const controlledWikiSearchTerm = `CLI live controlled wiki ${verifyStamp}`;
+  const controlledWikiPages = [
+    {
+      path: `concepts/cli-live-concept-${verifyStamp}.md`,
+      fullPath: `Agent Wiki/concepts/cli-live-concept-${verifyStamp}.md`,
+      wikiRole: "concept",
+      title: "concept"
+    },
+    {
+      path: `playbooks/cli-live-playbook-${verifyStamp}.md`,
+      fullPath: `Agent Wiki/playbooks/cli-live-playbook-${verifyStamp}.md`,
+      wikiRole: "playbook",
+      title: "playbook"
+    },
+    {
+      path: `decisions/cli-live-decision-${verifyStamp}.md`,
+      fullPath: `Agent Wiki/decisions/cli-live-decision-${verifyStamp}.md`,
+      wikiRole: "decision",
+      title: "decision"
+    },
+    {
+      path: `org-summaries/cli-live-org-summary-${verifyStamp}.md`,
+      fullPath: `Agent Wiki/org-summaries/cli-live-org-summary-${verifyStamp}.md`,
+      wikiRole: "org_summary",
+      title: "org_summary"
+    }
+  ];
+
+  for (const page of controlledWikiPages) {
+    const controlledStatus = runWave(["osmd", "wiki", "status", page.path], env);
+    results.push(controlledStatus);
+    osmdVerificationFailures += recordExactCheck({
+      lines: osmdVerificationLines,
+      label: `osmd.wiki status controlled ${page.title}`,
+      result: controlledStatus,
+      ok:
+        controlledStatus.parsed?.ok === true &&
+        controlledStatus.parsed?.data?.path === page.fullPath &&
+        controlledStatus.parsed?.data?.source === "agent_wiki" &&
+        controlledStatus.parsed?.data?.access === "read_write" &&
+        controlledStatus.parsed?.data?.wikiRole === page.wikiRole &&
+        controlledStatus.parsed?.data?.formatVersion === "agent_markdown_v1" &&
+        controlledStatus.parsed?.data?.exists === false &&
+        controlledStatus.parsed?.data?.canCreate === true &&
+        controlledStatus.parsed?.data?.canUpdate === false &&
+        controlledStatus.parsed?.data?.canAppend === false &&
+        controlledStatus.parsed?.data?.suggestedAction === "create",
+      reason: "agent_wiki_controlled_status"
+    });
+
+    const createContent = `# CLI Live ${page.title}\n\n${controlledWikiSearchTerm} create ${page.title}`;
+    const controlledCreate = runWave(["osmd", "wiki", "create", page.path, "--content", createContent], env);
+    results.push(controlledCreate);
+    osmdVerificationFailures += recordExactCheck({
+      lines: osmdVerificationLines,
+      label: `osmd.wiki create controlled ${page.title}`,
+      result: controlledCreate,
+      ok:
+        controlledCreate.parsed?.ok === true &&
+        controlledCreate.parsed?.data?.path === page.fullPath &&
+        controlledCreate.parsed?.data?.source === "agent_wiki" &&
+        controlledCreate.parsed?.data?.wikiRole === page.wikiRole &&
+        controlledCreate.parsed?.data?.formatVersion === "agent_markdown_v1" &&
+        controlledCreate.parsed?.data?.exists === true &&
+        controlledCreate.parsed?.data?.canUpdate === true &&
+        controlledCreate.parsed?.data?.canAppend === false &&
+        controlledCreate.parsed?.data?.content === createContent,
+      reason: "agent_wiki_controlled_create"
+    });
+
+    const updateContent = `# CLI Live ${page.title}\n\n${controlledWikiSearchTerm} update ${page.title}`;
+    const controlledUpdate = runWave(["osmd", "wiki", "update", page.path, "--content", updateContent], env);
+    results.push(controlledUpdate);
+    osmdVerificationFailures += recordExactCheck({
+      lines: osmdVerificationLines,
+      label: `osmd.wiki update controlled ${page.title}`,
+      result: controlledUpdate,
+      ok:
+        controlledUpdate.parsed?.ok === true &&
+        controlledUpdate.parsed?.data?.path === page.fullPath &&
+        controlledUpdate.parsed?.data?.source === "agent_wiki" &&
+        controlledUpdate.parsed?.data?.wikiRole === page.wikiRole &&
+        controlledUpdate.parsed?.data?.formatVersion === "agent_markdown_v1" &&
+        controlledUpdate.parsed?.data?.exists === true &&
+        controlledUpdate.parsed?.data?.canUpdate === true &&
+        controlledUpdate.parsed?.data?.canAppend === false &&
+        controlledUpdate.parsed?.data?.content === updateContent,
+      reason: "agent_wiki_controlled_update"
+    });
+  }
+
+  const logUpdateRejected = runWave(["osmd", "wiki", "update", "log.md", "--content", "verify forbidden"], env);
+  osmdVerificationFailures += recordExactCheck({
+    lines: osmdVerificationLines,
+    label: "osmd.wiki update rejects log locally",
+    result: logUpdateRejected,
+    ok:
+      logUpdateRejected.parsed?.ok === false &&
+      logUpdateRejected.parsed?.status === 400 &&
+      logUpdateRejected.parsed?.error?.code === "invalid_args",
+    reason: "agent_wiki_log_update_local_reject"
+  });
+
+  const arbitraryWikiRejected = runWave(
+    ["osmd", "wiki", "create", "random/cli-live-random.md", "--content", "verify forbidden"],
+    env
+  );
+  osmdVerificationFailures += recordExactCheck({
+    lines: osmdVerificationLines,
+    label: "osmd.wiki create rejects arbitrary wiki path locally",
+    result: arbitraryWikiRejected,
+    ok:
+      arbitraryWikiRejected.parsed?.ok === false &&
+      arbitraryWikiRejected.parsed?.status === 400 &&
+      arbitraryWikiRejected.parsed?.error?.code === "invalid_args",
+    reason: "agent_wiki_arbitrary_path_local_reject"
+  });
+
   const parentRef = resolveOsmdAgentParentRef();
   if (!parentRef) {
     osmdVerificationLines.push(
@@ -1392,6 +1510,174 @@ function runOsmdLiveVerification() {
     reason: "agent_overlay_update"
   });
 
+  const searchCandidates = (result) => firstArrayValue(result.parsed, [["data", "candidates"]]);
+  const hasOwn = (candidate, key) => Object.prototype.hasOwnProperty.call(candidate ?? {}, key);
+  const hasSearchMetadata = (candidate, expectedSource) =>
+    candidate &&
+    typeof candidate.path === "string" &&
+    candidate.source === expectedSource &&
+    typeof candidate.access === "string" &&
+    typeof candidate.owner === "string" &&
+    hasOwn(candidate, "wikiRole") &&
+    hasOwn(candidate, "formatVersion") &&
+    hasOwn(candidate, "parentRef") &&
+    typeof candidate.exists === "boolean";
+
+  const canonicalSearch = runWave(["osmd", "search", "Wave Tools", "--scope", "os-only", "--limit", "5"], env);
+  results.push(canonicalSearch);
+  const canonicalSearchCandidates = searchCandidates(canonicalSearch);
+  osmdVerificationFailures += recordExactCheck({
+    lines: osmdVerificationLines,
+    label: "osmd.search canonical results include OS metadata",
+    result: canonicalSearch,
+    ok:
+      canonicalSearch.parsed?.ok === true &&
+      canonicalSearch.parsed?.command === "osmd.search" &&
+      typeof canonicalSearch.parsed?.meta?.requestId === "string" &&
+      canonicalSearch.parsed?.data?.scope === "canonical_osmd" &&
+      canonicalSearchCandidates.some(
+        (candidate) =>
+          hasSearchMetadata(candidate, "canonical_osmd") &&
+          candidate.access === "read_only" &&
+          candidate.owner === "system"
+      ),
+    reason: "osmd_search_canonical"
+  });
+
+  const wikiSearch = runWave(["osmd", "search", "Agent Wiki", "--scope", "agent-wiki-only", "--limit", "10"], env);
+  results.push(wikiSearch);
+  const wikiSearchCandidates = searchCandidates(wikiSearch);
+  osmdVerificationFailures += recordExactCheck({
+    lines: osmdVerificationLines,
+    label: "osmd.search Agent Wiki results include index and log metadata",
+    result: wikiSearch,
+    ok:
+      wikiSearch.parsed?.ok === true &&
+      wikiSearch.parsed?.data?.scope === "agent_wiki" &&
+      wikiSearchCandidates.some(
+        (candidate) =>
+          hasSearchMetadata(candidate, "agent_wiki") &&
+          candidate.path === "Agent Wiki/index.md" &&
+          candidate.wikiRole === "index"
+      ) &&
+      wikiSearchCandidates.some(
+        (candidate) =>
+          hasSearchMetadata(candidate, "agent_wiki") &&
+          candidate.path === "Agent Wiki/log.md" &&
+          candidate.wikiRole === "log" &&
+          candidate.access === "append_only"
+      ),
+    reason: "osmd_search_agent_wiki"
+  });
+
+  const controlledWikiSearch = runWave(
+    ["osmd", "search", controlledWikiSearchTerm, "--scope", "agent-wiki-only", "--limit", "10"],
+    env
+  );
+  results.push(controlledWikiSearch);
+  const controlledWikiSearchCandidates = searchCandidates(controlledWikiSearch);
+  osmdVerificationFailures += recordExactCheck({
+    lines: osmdVerificationLines,
+    label: "osmd.search Agent Wiki controlled pages",
+    result: controlledWikiSearch,
+    ok:
+      controlledWikiSearch.parsed?.ok === true &&
+      controlledWikiSearch.parsed?.data?.scope === "agent_wiki" &&
+      controlledWikiPages.every((page) =>
+        controlledWikiSearchCandidates.some(
+          (candidate) =>
+            hasSearchMetadata(candidate, "agent_wiki") &&
+            candidate.path === page.fullPath &&
+            candidate.wikiRole === page.wikiRole &&
+            candidate.access === "read_write"
+        )
+      ),
+    reason: "osmd_search_agent_wiki_controlled_pages"
+  });
+
+  const controlledCombinedSearch = runWave(
+    ["osmd", "search", controlledWikiSearchTerm, "--scope", "combined", "--limit", "10"],
+    env
+  );
+  results.push(controlledCombinedSearch);
+  const controlledCombinedSearchCandidates = searchCandidates(controlledCombinedSearch);
+  osmdVerificationFailures += recordExactCheck({
+    lines: osmdVerificationLines,
+    label: "osmd.search combined includes controlled Agent Wiki pages",
+    result: controlledCombinedSearch,
+    ok:
+      controlledCombinedSearch.parsed?.ok === true &&
+      controlledCombinedSearch.parsed?.data?.scope === "combined" &&
+      controlledWikiPages.some((page) =>
+        controlledCombinedSearchCandidates.some(
+          (candidate) =>
+            hasSearchMetadata(candidate, "agent_wiki") &&
+            candidate.path === page.fullPath &&
+            candidate.wikiRole === page.wikiRole
+        )
+      ),
+    reason: "osmd_search_combined_controlled_pages"
+  });
+
+  const logSearch = runWave(
+    ["osmd", "search", `CLI live verify log ${verifyStamp}`, "--scope", "agent-wiki-only", "--limit", "5"],
+    env
+  );
+  results.push(logSearch);
+  const logSearchCandidates = searchCandidates(logSearch);
+  osmdVerificationFailures += recordExactCheck({
+    lines: osmdVerificationLines,
+    label: "osmd.search Agent Wiki log content result",
+    result: logSearch,
+    ok:
+      logSearch.parsed?.ok === true &&
+      logSearchCandidates.some(
+        (candidate) =>
+          hasSearchMetadata(candidate, "agent_wiki") &&
+          candidate.path === "Agent Wiki/log.md" &&
+          candidate.wikiRole === "log"
+      ),
+    reason: "osmd_search_agent_wiki_log"
+  });
+
+  const notesSearch = runWave(
+    ["osmd", "search", notesContent, "--scope", "agent-overlay-only", "--limit", "5"],
+    env
+  );
+  results.push(notesSearch);
+  const notesSearchCandidates = searchCandidates(notesSearch);
+  osmdVerificationFailures += recordExactCheck({
+    lines: osmdVerificationLines,
+    label: "osmd.search agent overlay notes content result",
+    result: notesSearch,
+    ok:
+      notesSearch.parsed?.ok === true &&
+      notesSearch.parsed?.data?.scope === "agent_overlay" &&
+      notesSearchCandidates.some(
+        (candidate) =>
+          hasSearchMetadata(candidate, "agent_overlay") &&
+          candidate.path.endsWith("/.agent/notes.md") &&
+          candidate.wikiRole === "notes" &&
+          candidate.parentRef === parentRef
+      ),
+    reason: "osmd_search_agent_overlay_notes"
+  });
+
+  const combinedSearch = runWave(["osmd", "search", "Wave", "--scope", "combined", "--limit", "3"], env);
+  results.push(combinedSearch);
+  osmdVerificationFailures += recordExactCheck({
+    lines: osmdVerificationLines,
+    label: "osmd.search combined scope returns stable envelope",
+    result: combinedSearch,
+    ok:
+      combinedSearch.parsed?.ok === true &&
+      combinedSearch.parsed?.command === "osmd.search" &&
+      combinedSearch.parsed?.data?.scope === "combined" &&
+      Array.isArray(combinedSearch.parsed?.data?.candidates) &&
+      typeof combinedSearch.parsed?.meta?.requestId === "string",
+    reason: "osmd_search_combined"
+  });
+
 }
 
 runOsmdLiveVerification();