@ted-galago/wave-cli 0.1.18 → 0.1.20

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"
@@ -307,6 +308,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 +328,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`
@@ -348,7 +351,9 @@ Path and permission rules:
 - Agent Wiki `create` and `update` support only `index.md`; `log.md` cannot be overwritten.
 - 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`, `suggestedAction`, and `errorCode`.
+- 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.
@@ -357,6 +362,50 @@ Path and permission rules:
 - 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"`.
 
+Atlas Agent Wiki log flow:
+
+1. `status_log`: run `wave osmd wiki status log.md`.
+2. If `data.exists === false` and `data.suggestedAction === "init"`, run `wave osmd wiki init`.
+3. `status_log`: run `wave osmd wiki status log.md` again and require `data.canAppend === true`.
+4. `append_log`: run `wave osmd wiki append-log --content "<markdown log entry>"`.
+
+Atlas must not skip the status checks. `append-log` never initializes files implicitly; backend `initAgentMarkdown` via `wave osmd wiki init` is the only supported initialization flow for Agent Wiki system files.
+
+Atlas maintenance examples:
+
+Update `Agent Wiki/index.md` after an entity `.agent/notes.md` change. Atlas should read the current index, compose the complete replacement markdown in memory, then update `index.md`; the CLI does not patch partial content:
+
+```bash
+wave osmd agent update "directory/Wave Tools Team" notes.md --content "## Working notes\n\n- New durable entity note."
+wave osmd wiki status index.md
+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"
+```
+
+Append a parseable log entry. Use a stable fenced block so Atlas or backend jobs can parse the chronology later:
+
+````bash
+wave osmd wiki append-log --content "```yaml
+event: entity_note_updated
+parentRef: directory/Wave Tools Team
+agentFile: .agent/notes.md
+wikiPath: Agent Wiki/index.md
+summary: Added durable working notes for the Wave Tools Team.
+```"
+````
+
+`append-log` accepts multi-line markdown from `--content`, `--file`, or stdin. Use `--file` for larger structured entries:
+
+```bash
+wave osmd wiki append-log --file ./agent-wiki-log-entry.md
+```
+
+When not using `--token-stdin` or `--auth-json-stdin`, stdin may also provide the log body:
+
+````bash
+printf '%s\n' '```yaml' 'event: wiki_maintenance' 'summary: Refreshed Agent Wiki index.' '```' | wave osmd wiki append-log
+````
+
 OSMD command envelopes keep the global CLI envelope and put the file metadata directly in `data`:
 
 ```json
@@ -373,7 +422,11 @@ OSMD command envelopes keep the global CLI envelope and put the file metadata di
     "canCreate": false,
     "canUpdate": true,
     "canAppend": false,
+    "wikiRole": "notes",
+    "formatVersion": "agent_markdown_v1",
     "parentRef": "projects/Wave Tools",
+    "suggestedAction": "update",
+    "errorCode": null,
     "content": "..."
   },
   "error": null,
@@ -381,6 +434,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
@@ -397,6 +488,8 @@ On write preflight errors, `data` contains the status metadata and `error.sugges
     "canCreate": true,
     "canUpdate": false,
     "canAppend": false,
+    "wikiRole": "index",
+    "formatVersion": "agent_markdown_v1",
     "parentRef": null,
     "suggestedAction": "create",
     "errorCode": null
@@ -432,6 +525,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` and append-only `log.md`.
+- `--scope combined` searches the backend merged OSMD surface.
 
 Ambiguity contract:
 

package/dist/index.cjs

@@ -6143,10 +6143,17 @@ 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 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,
@@ -6156,6 +6163,8 @@ var agentMarkdownFileSchema = import_zod16.z.object({
   canCreate: import_zod16.z.boolean(),
   canUpdate: import_zod16.z.boolean(),
   canAppend: import_zod16.z.boolean(),
+  wikiRole: import_zod16.z.string().nullable().optional(),
+  formatVersion: import_zod16.z.string().nullable().optional(),
   parentRef: import_zod16.z.string().nullable().optional(),
   agentChildrenAllowed: import_zod16.z.boolean(),
   suggestedAction: suggestedActionSchema,
@@ -6164,6 +6173,8 @@ var agentMarkdownFileSchema = import_zod16.z.object({
   url: import_zod16.z.string().nullable().optional()
 }).transform((value) => ({
   ...value,
+  wikiRole: value.wikiRole ?? null,
+  formatVersion: value.formatVersion ?? null,
   parentRef: value.parentRef ?? null,
   errorCode: value.errorCode ?? null,
   content: value.content ?? null,
@@ -6174,6 +6185,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(),
@@ -6216,6 +6268,8 @@ var AGENT_MARKDOWN_FILE_SELECTION = `{
   canCreate
   canUpdate
   canAppend
+  wikiRole
+  formatVersion
   parentRef
   agentChildrenAllowed
   suggestedAction
@@ -6223,15 +6277,45 @@ 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",
   can_update: "canUpdate",
   can_append: "canAppend",
+  wiki_role: "wikiRole",
+  format_version: "formatVersion",
   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") {
@@ -6383,6 +6467,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),
@@ -6495,6 +6595,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;
@@ -6784,7 +6924,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",
@@ -6803,6 +6943,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);

package/dist/index.js

@@ -6142,10 +6142,17 @@ 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 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,
@@ -6155,6 +6162,8 @@ var agentMarkdownFileSchema = z16.object({
   canCreate: z16.boolean(),
   canUpdate: z16.boolean(),
   canAppend: z16.boolean(),
+  wikiRole: z16.string().nullable().optional(),
+  formatVersion: z16.string().nullable().optional(),
   parentRef: z16.string().nullable().optional(),
   agentChildrenAllowed: z16.boolean(),
   suggestedAction: suggestedActionSchema,
@@ -6163,6 +6172,8 @@ var agentMarkdownFileSchema = z16.object({
   url: z16.string().nullable().optional()
 }).transform((value) => ({
   ...value,
+  wikiRole: value.wikiRole ?? null,
+  formatVersion: value.formatVersion ?? null,
   parentRef: value.parentRef ?? null,
   errorCode: value.errorCode ?? null,
   content: value.content ?? null,
@@ -6173,6 +6184,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(),
@@ -6215,6 +6267,8 @@ var AGENT_MARKDOWN_FILE_SELECTION = `{
   canCreate
   canUpdate
   canAppend
+  wikiRole
+  formatVersion
   parentRef
   agentChildrenAllowed
   suggestedAction
@@ -6222,15 +6276,45 @@ 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",
   can_update: "canUpdate",
   can_append: "canAppend",
+  wiki_role: "wikiRole",
+  format_version: "formatVersion",
   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") {
@@ -6382,6 +6466,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),
@@ -6494,6 +6594,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;
@@ -6783,7 +6923,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",
@@ -6802,6 +6942,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);

package/package.json

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

package/scripts/verify-dev-api.mjs

@@ -1182,6 +1182,8 @@ function runOsmdLiveVerification() {
       wikiStatus.parsed?.ok === true &&
       wikiStatus.parsed?.data?.path === "Agent Wiki/index.md" &&
       wikiStatus.parsed?.data?.source === "agent_wiki" &&
+      wikiStatus.parsed?.data?.wikiRole === "index" &&
+      typeof wikiStatus.parsed?.data?.formatVersion === "string" &&
       (wikiStatus.parsed?.data?.exists !== false ||
         (wikiStatus.parsed?.data?.canCreate === true &&
           wikiStatus.parsed?.data?.canUpdate === false &&
@@ -1210,6 +1212,8 @@ function runOsmdLiveVerification() {
       wikiLogStatus.parsed?.data?.path === "Agent Wiki/log.md" &&
       wikiLogStatus.parsed?.data?.source === "agent_wiki" &&
       wikiLogStatus.parsed?.data?.access === "append_only" &&
+      wikiLogStatus.parsed?.data?.wikiRole === "log" &&
+      typeof wikiLogStatus.parsed?.data?.formatVersion === "string" &&
       typeof wikiLogStatus.parsed?.data?.canAppend === "boolean",
     reason: "agent_wiki_log_status"
   });
@@ -1224,6 +1228,8 @@ function runOsmdLiveVerification() {
       wikiLogRead.parsed?.ok === true &&
       wikiLogRead.parsed?.data?.path === "Agent Wiki/log.md" &&
       wikiLogRead.parsed?.data?.access === "append_only" &&
+      wikiLogRead.parsed?.data?.wikiRole === "log" &&
+      typeof wikiLogRead.parsed?.data?.formatVersion === "string" &&
       wikiLogRead.parsed?.data?.exists === wikiLogStatus.parsed?.data?.exists,
     reason: "agent_wiki_log_read"
   });
@@ -1245,6 +1251,8 @@ function runOsmdLiveVerification() {
         missingWikiLogAppend.parsed?.error?.suggestedAction === "init" &&
         String(missingWikiLogAppend.parsed?.error?.message ?? "").includes("wave osmd wiki init") &&
         missingWikiLogAppend.parsed?.data?.path === "Agent Wiki/log.md" &&
+        missingWikiLogAppend.parsed?.data?.wikiRole === "log" &&
+        typeof missingWikiLogAppend.parsed?.data?.formatVersion === "string" &&
         missingWikiLogAppend.parsed?.data?.canAppend === false,
       reason: "agent_wiki_log_missing_init_guidance"
     });
@@ -1267,6 +1275,8 @@ function runOsmdLiveVerification() {
         (file) =>
           file?.path === "Agent Wiki/log.md" &&
           file?.access === "append_only" &&
+          file?.wikiRole === "log" &&
+          typeof file?.formatVersion === "string" &&
           file?.exists === true &&
           file?.canAppend === true
       ),
@@ -1286,6 +1296,8 @@ function runOsmdLiveVerification() {
       wikiLogAppend.parsed?.ok === true &&
       wikiLogAppend.parsed?.data?.path === "Agent Wiki/log.md" &&
       wikiLogAppend.parsed?.data?.access === "append_only" &&
+      wikiLogAppend.parsed?.data?.wikiRole === "log" &&
+      typeof wikiLogAppend.parsed?.data?.formatVersion === "string" &&
       wikiLogAppend.parsed?.data?.canAppend === true,
     reason: "agent_wiki_log_append_after_init"
   });
@@ -1336,6 +1348,8 @@ function runOsmdLiveVerification() {
     ok:
       agentStatus.parsed?.ok === true &&
       agentStatus.parsed?.data?.source === "agent_overlay" &&
+      agentStatus.parsed?.data?.wikiRole === "notes" &&
+      typeof agentStatus.parsed?.data?.formatVersion === "string" &&
       agentStatus.parsed?.data?.parentRef === parentRef,
     reason: "agent_overlay_status"
   });
@@ -1349,7 +1363,12 @@ function runOsmdLiveVerification() {
     result: agentInit,
     ok:
       agentInit.parsed?.ok === true &&
-      (initFiles.some((file) => file?.path?.endsWith("/.agent/notes.md")) ||
+      (initFiles.some(
+        (file) =>
+          file?.path?.endsWith("/.agent/notes.md") &&
+          file?.wikiRole === "notes" &&
+          typeof file?.formatVersion === "string"
+      ) ||
         agentInit.parsed?.data?.path?.endsWith("/.agent/notes.md")),
     reason: "agent_overlay_init"
   });
@@ -1367,10 +1386,131 @@ function runOsmdLiveVerification() {
     ok:
       agentUpdate.parsed?.ok === true &&
       agentUpdate.parsed?.data?.access === "read_write" &&
+      agentUpdate.parsed?.data?.wikiRole === "notes" &&
+      typeof agentUpdate.parsed?.data?.formatVersion === "string" &&
       agentUpdate.parsed?.data?.content === notesContent,
     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 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();