@ted-galago/wave-cli 0.1.15 → 0.1.17

package/dist/index.cjs

@@ -181,6 +181,22 @@ function graphqlOperationName(command) {
 function toCamelCase(value) {
   return value.replace(/_([a-z])/g, (_, char) => char.toUpperCase());
 }
+function capitalizeFirst(value) {
+  return value.length === 0 ? value : value[0].toUpperCase() + value.slice(1);
+}
+var MUTATION_PARAMS_INPUT_TYPE_OVERRIDES = {
+  createOpenAiRealtimeClientSecret: "OpenAiRealtimeClientSecretInput",
+  createOpenAiRealtimeSession: "OpenAiRealtimeSessionInput",
+  createOpenAiTranscription: "OpenAiTranscriptionInput",
+  finalizeOpenAiTranscription: "OpenAiFinalizeTranscriptionInput"
+};
+function inferMutationParamsInputType(input) {
+  if (input.operationType !== "mutation") {
+    return null;
+  }
+  const graphqlField = toCamelCase(input.field);
+  return MUTATION_PARAMS_INPUT_TYPE_OVERRIDES[graphqlField] ?? `${capitalizeFirst(graphqlField)}ParamsInput`;
+}
 function inferStatusFromGraphqlErrors(errors) {
   if (!Array.isArray(errors) || errors.length === 0) {
     return 400;
@@ -413,7 +429,7 @@ function buildFeedbackFindRequestBody(command, identity) {
       page: 1,
       per: 1
     },
-    selectionSet: "{ data { id type attributes } count currentPage totalPages }"
+    selectionSet: "{ data { id type attributes { id name slug year quarter organizationId memberIds } } count currentPage totalPages }"
   });
 }
 async function requestGraphqlHttp(params) {
@@ -484,7 +500,13 @@ function graphqlTypeForValue(value) {
   }
   return "JSON";
 }
-function graphqlTypeForVariable(name, value) {
+function graphqlTypeForVariable(input, name, value) {
+  if (name === "params") {
+    const paramsInputType = inferMutationParamsInputType(input);
+    if (paramsInputType) {
+      return paramsInputType;
+    }
+  }
   if (name === "id" || name.endsWith("Id")) {
     return "ID";
   }
@@ -528,7 +550,7 @@ function buildGraphqlBody(input) {
   const variableDecl = variableEntries.map(([name, value]) => {
     const overriddenType = graphqlVariableTypes[name];
     const hasOverriddenType = typeof overriddenType === "string" && overriddenType.trim().length > 0;
-    const typeName = hasOverriddenType ? overriddenType.trim() : graphqlTypeForVariable(name, value);
+    const typeName = hasOverriddenType ? overriddenType.trim() : graphqlTypeForVariable(input, name, value);
     return `$${name}: ${hasOverriddenType ? typeName : withNonNull(typeName)}`;
   }).join(", ");
   const fieldArgs = variableEntries.map(([name]) => `${name}: $${name}`).join(", ");
@@ -823,8 +845,7 @@ var RESOURCE_QUERY_FIELDS = {
     "memberIds",
     "leadMemberId",
     "organizationId",
-    "responsibilities",
-    "keyMetric"
+    "responsibilities"
   ],
   member: [
     "slug",
@@ -1280,16 +1301,16 @@ function defaultQuerySelectionSet(field, isList) {
   const canonicalField = RESOURCE_FIELD_ALIASES[field] ?? field;
   const explicitFields = RESOURCE_QUERY_FIELDS[canonicalField];
   if (explicitFields) {
+    const attributes = explicitFields.length > 0 ? `attributes { ${Array.from(/* @__PURE__ */ new Set(["id", ...explicitFields])).join(" ")} }` : "attributes";
     if (isList) {
-      return "{ data { id type attributes } count currentPage totalPages }";
+      return `{ data { id type ${attributes} } count currentPage totalPages }`;
     }
-    const fields = Array.from(/* @__PURE__ */ new Set(["id", "type", ...explicitFields, "attributes"])).join(" ");
-    return `{ ${fields} }`;
+    return `{ id type ${attributes} }`;
   }
   if (isList) {
-    return "{ data { id type attributes } count currentPage totalPages }";
+    return "{ data { id type } count currentPage totalPages }";
   }
-  return "{ id type attributes }";
+  return "{ id type }";
 }
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -2594,7 +2615,10 @@ var idSchema3 = import_zod4.z.string().min(1);
 var projectCreateDataJsonHelp = buildDataJsonHelp("project", "create") ?? 'JSON object for project or {"project": {...}}';
 var projectUpdateDataJsonHelp = buildDataJsonHelp("project", "update") ?? 'JSON object for project or {"project": {...}}';
 var projectsIndexMinimalSelectionSet = "{ count currentPage totalPages data { id type attributes { name slug status priority } } }";
-var projectShowFullSelectionSet = "{ id type name slug description status priority createdAt updatedAt startDate targetDate archivedAt memberId organizationId teamIds emoji { id name memberId } backgroundImage { backgroundType gradientStart gradientEnd gradientDegrees color imageUrl image { url lowUrl } } favorites { id memberId } resources { ...ResourceSummaryFull } displayPreference { id type attributes viewType favorite groupingField groupToggleState memberId focusMemberId focusTeamId displayableId displayableType preferenceType agendaItemId } filterPreferences { id type attributes filterType filter memberId focusMemberId focusTeamId filterableId filterableType preferenceType agendaItemId } healthUpdates { id type value memberId status createdAt updatedAt updatableType updatableId parentUpdateId emojis { id name memberId } resources { ...ResourceSummaryFull } replies { id type value memberId createdAt updatedAt commentType commentableId commentableType parentCommentId emojis { id name memberId } resources { ...ResourceSummaryFull } replies { id type } } } } fragment ResourceSummaryFull on ResourceSummary { id resourceType slug url skillId skill { id name slug emoji scope description } metadata { urlName imageUrl siteName providerName mediaType skillId skillName skillSlug skillScope skillEmoji skillDescription } attachment { id fileKey filename url } content { id name slug type firstChildSlug childCount } }";
+var displayPreferenceAttributesSelectionSet = "attributes { id viewType favorite groupingField groupToggleState memberId focusMemberId focusTeamId displayableId displayableType preferenceType agendaItemId }";
+var filterPreferenceAttributesSelectionSet = "attributes { id filterType filter memberId focusMemberId focusTeamId filterableId filterableType preferenceType agendaItemId }";
+var healthUpdateSummarySelectionSet = "id type value memberId status createdAt updatedAt updatableType updatableId parentUpdateId emojis { id name memberId } resources { ...ResourceSummaryFull }";
+var projectShowFullSelectionSet = `{ id type name slug description status priority createdAt updatedAt startDate targetDate archivedAt memberId organizationId teamIds emoji { id name memberId } backgroundImage { backgroundType gradientStart gradientEnd gradientDegrees color imageUrl image { url lowUrl } } favorites { id memberId } resources { ...ResourceSummaryFull } displayPreference { id type ${displayPreferenceAttributesSelectionSet} viewType favorite groupingField groupToggleState memberId focusMemberId focusTeamId displayableId displayableType preferenceType agendaItemId } filterPreferences { id type ${filterPreferenceAttributesSelectionSet} filterType filter memberId focusMemberId focusTeamId filterableId filterableType preferenceType agendaItemId } healthUpdates { ${healthUpdateSummarySelectionSet} replies { ${healthUpdateSummarySelectionSet} replies { id type } } } } fragment ResourceSummaryFull on ResourceSummary { id resourceType slug url skillId skill { id name slug emoji scope description } metadata { urlName imageUrl siteName providerName mediaType skillId skillName skillSlug skillScope skillEmoji skillDescription } attachment { id fileKey filename url } content { id name slug type firstChildSlug childCount } }`;
 function asRecord2(value) {
   return value && typeof value === "object" ? value : null;
 }
@@ -3999,7 +4023,7 @@ function registerSystemToolCommands(program) {
         page: 1,
         per: 200
       },
-      selectionSet: "{ data { id type slug summary description memberId status rank createdAt updatedAt headlineType teamIds meetingId labelIds attributes } count currentPage totalPages }",
+      selectionSet: "{ data { id type slug summary description memberId status rank createdAt updatedAt headlineType teamIds meetingId labelIds attributes { id slug summary description memberId status rank createdAt updatedAt headlineType teamIds meetingId labelIds } } count currentPage totalPages }",
       transformData: (value) => {
         if (!value || typeof value !== "object") {
           return null;
@@ -4616,7 +4640,13 @@ function registerFoundationCommands(program) {
 var import_zod12 = require("zod");
 var idSchema11 = import_zod12.z.string().min(1);
 var jsonObjectSchema = import_zod12.z.record(import_zod12.z.string(), import_zod12.z.unknown());
-var childListMinimalSelectionSet = "{ data { id type attributes } count currentPage totalPages }";
+function buildChildListSelectionSet(parentField, extraFields = []) {
+  const fields = Array.from(
+    /* @__PURE__ */ new Set(["id", "type", "name", "status", "priority", "rank", "dueDate", "memberId", parentField, ...extraFields])
+  );
+  const attributeFields = fields.filter((field) => field !== "type");
+  return `{ data { ${fields.join(" ")} attributes { ${attributeFields.join(" ")} } } count currentPage totalPages }`;
+}
 function parseJsonObject2(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -4821,7 +4851,7 @@ function registerChildEntityCommands(program) {
     createOperationName: "SubtasksCreate",
     updateOperationName: "SubtasksUpdate",
     destroyOperationName: "SubtasksDestroy",
-    listSelectionSet: childListMinimalSelectionSet,
+    listSelectionSet: buildChildListSelectionSet("taskId"),
     listParentTypedField: "taskId",
     normalizeCreateBody: normalizeSubtaskCreateBody
   });
@@ -4840,7 +4870,7 @@ function registerChildEntityCommands(program) {
     createOperationName: "MilestonesCreate",
     updateOperationName: "MilestonesUpdate",
     destroyOperationName: "MilestonesDestroy",
-    listSelectionSet: childListMinimalSelectionSet
+    listSelectionSet: buildChildListSelectionSet("rockId")
   });
   registerChildCommands(program, {
     command: "subitems",
@@ -4857,7 +4887,7 @@ function registerChildEntityCommands(program) {
     createOperationName: "SubitemsCreate",
     updateOperationName: "SubitemsUpdate",
     destroyOperationName: "SubitemsDestroy",
-    listSelectionSet: childListMinimalSelectionSet,
+    listSelectionSet: buildChildListSelectionSet("listItemId"),
     listParentTypedField: "listItemId"
   });
   registerChildCommands(program, {
@@ -4875,7 +4905,7 @@ function registerChildEntityCommands(program) {
     createOperationName: "SubtodosCreate",
     updateOperationName: "SubtodosUpdate",
     destroyOperationName: "SubtodosDestroy",
-    listSelectionSet: childListMinimalSelectionSet,
+    listSelectionSet: buildChildListSelectionSet("todoId"),
     listParentTypedField: "todoId"
   });
   registerChildCommands(program, {
@@ -4893,7 +4923,7 @@ function registerChildEntityCommands(program) {
     createOperationName: "SubissuesCreate",
     updateOperationName: "SubissuesUpdate",
     destroyOperationName: "SubissuesDestroy",
-    listSelectionSet: childListMinimalSelectionSet,
+    listSelectionSet: buildChildListSelectionSet("issueId"),
     listParentTypedField: "issueId"
   });
   registerChildCommands(program, {
@@ -4911,7 +4941,7 @@ function registerChildEntityCommands(program) {
     createOperationName: "TalkingPointsCreate",
     updateOperationName: "TalkingPointsUpdate",
     destroyOperationName: "TalkingPointsDestroy",
-    listSelectionSet: childListMinimalSelectionSet,
+    listSelectionSet: buildChildListSelectionSet("meetingId", ["description", "creatorId", "slug"]),
     listParentTypedField: "meetingId"
   });
 }
@@ -4920,6 +4950,7 @@ function registerChildEntityCommands(program) {
 var import_zod13 = require("zod");
 var idSchema12 = import_zod13.z.string().min(1);
 var nonEmptyString = import_zod13.z.string().min(1);
+var contentAttributesSelection = "attributes { id type name slug content firstChildSlug rootParentSlug status contentType lastEdited organizationId memberId focusMemberId focusTeamId teamId creatorId createdAt updatedAt childCount assignmentType contentableId contentableSlug contentableType votesTotal labelIds rootContentId parentContentId }";
 function assertUpdateFields(params) {
   if (!params.name && !params.content && !params.status) {
     throw new CliError({
@@ -4967,7 +4998,7 @@ function registerContentCommands(program) {
         per: opts.per
       }),
       isList: true,
-      selectionSet: "{ count currentPage totalPages data { id type attributes } }"
+      selectionSet: `{ count currentPage totalPages data { id type ${contentAttributesSelection} } }`
     });
   });
   content.command("show").requiredOption("--id <id>").action(async (opts, cmd) => {
@@ -4984,7 +5015,7 @@ function registerContentCommands(program) {
         id
       }),
       isShow: true,
-      selectionSet: "{ id type name slug firstChildSlug rootParentSlug status contentType lastEdited organizationId memberId focusMemberId focusTeamId teamId creatorId createdAt updatedAt childCount assignmentType contentableId contentableSlug contentableType votesTotal labelIds rootContentId parentContentId attributes }"
+      selectionSet: `{ id type resources { id resourceType slug url } ${contentAttributesSelection} }`
     });
   });
   content.command("update").requiredOption("--id <id>").option("--name <name>").option("--body <body>").option("--status <status>").action(async (opts, cmd) => {
@@ -6088,7 +6119,7 @@ function registerMutationCapabilityCommands(program) {
 var import_promises = require("fs/promises");
 var import_zod16 = require("zod");
 var sourceSchema = import_zod16.z.enum(["canonical_osmd", "agent_overlay", "agent_wiki"]);
-var accessSchema = import_zod16.z.enum(["read_only", "read_write", "append_only"]);
+var accessSchema = import_zod16.z.enum(["read_only", "read_write", "append_only"]).catch("read_write");
 var ownerSchema = import_zod16.z.enum(["system", "atlas"]);
 var suggestedActionSchema = import_zod16.z.enum([
   "read",
@@ -6098,7 +6129,7 @@ var suggestedActionSchema = import_zod16.z.enum([
   "append",
   "forbidden",
   "invalid_parent"
-]);
+]).catch("update");
 var agentMarkdownErrorCodeSchema = import_zod16.z.enum([
   "canonical_osmd_read_only",
   "agent_parent_not_found",
@@ -6109,9 +6140,13 @@ var agentMarkdownErrorCodeSchema = import_zod16.z.enum([
   "unsupported_agent_file",
   "invalid_agent_wiki_path"
 ]);
+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 agentOverlayFileSchema = import_zod16.z.enum(["notes.md", "log.md"]);
+var supportedAgentOverlayFile = "notes.md";
+var supportedWikiIndexFile = "index.md";
+var supportedWikiLogFile = "log.md";
+var agentOverlayFileSchema = import_zod16.z.enum([supportedAgentOverlayFile]);
 var agentMarkdownFileSchema = import_zod16.z.object({
   path: import_zod16.z.string(),
   source: sourceSchema,
@@ -6124,7 +6159,7 @@ var agentMarkdownFileSchema = import_zod16.z.object({
   parentRef: import_zod16.z.string().nullable().optional(),
   agentChildrenAllowed: import_zod16.z.boolean(),
   suggestedAction: suggestedActionSchema,
-  errorCode: agentMarkdownErrorCodeSchema.nullable().optional(),
+  errorCode: agentMarkdownErrorCodeFieldSchema.optional(),
   content: import_zod16.z.string().nullable().optional(),
   url: import_zod16.z.string().nullable().optional()
 }).transform((value) => ({
@@ -6198,6 +6233,21 @@ var AGENT_JSON_KEY_ALIASES = {
   suggested_action: "suggestedAction",
   error_code: "errorCode"
 };
+function isSupportedAgentMarkdownFile(file) {
+  if (file.source !== "agent_overlay") {
+    return true;
+  }
+  return file.path === `.agent/${supportedAgentOverlayFile}` || file.path.endsWith(`/.agent/${supportedAgentOverlayFile}`);
+}
+function filterSupportedAgentMarkdownData(data) {
+  if (isRecord5(data) && Array.isArray(data.files)) {
+    return {
+      ...data,
+      files: data.files.filter(isSupportedAgentMarkdownFile)
+    };
+  }
+  return data;
+}
 var contentStdinPromise = null;
 function isRecord5(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -6370,7 +6420,7 @@ async function runAgentMarkdownMutation(params) {
     envelope: buildSuccessEnvelope({
       command: params.command,
       status: mutationPayload.status,
-      data: parsedData.data,
+      data: filterSupportedAgentMarkdownData(parsedData.data),
       requestId: result.envelope.meta.requestId
     })
   });
@@ -6381,24 +6431,50 @@ function normalizeAgentFilePath(file) {
   const parsed = agentOverlayFileSchema.safeParse(fileName);
   if (!parsed.success) {
     throw new CliError({
-      message: ".agent supports only notes.md and log.md in this CLI slice.",
+      message: ".agent supports only notes.md in this CLI slice.",
       kind: "invalid_args",
       status: 400,
       exitCode: EXIT_CODES.invalidArgs,
-      details: { supportedFiles: ["notes.md", "log.md"] }
+      details: { supportedFiles: [supportedAgentOverlayFile] }
     });
   }
   return `.agent/${parsed.data}`;
 }
-function normalizeWikiPath(path) {
+function supportedWikiFilesMessage(files) {
+  return `Agent Wiki file commands support only ${files.join(" and ")} in this CLI slice.`;
+}
+function normalizeWikiPath(path, options = {}) {
+  const supportedFiles = options.supportedFiles ?? [supportedWikiIndexFile, supportedWikiLogFile];
   const trimmed = nonEmptyString3.parse(path).trim().replace(/^\/+/, "");
   if (trimmed.localeCompare("Agent Wiki", void 0, { sensitivity: "accent" }) === 0) {
-    return "Agent Wiki";
+    if (options.allowRoot) {
+      return "Agent Wiki";
+    }
+    throw new CliError({
+      message: supportedWikiFilesMessage(supportedFiles),
+      kind: "invalid_args",
+      status: 400,
+      exitCode: EXIT_CODES.invalidArgs,
+      details: { supportedFiles }
+    });
   }
-  if (trimmed.toLowerCase().startsWith("agent wiki/")) {
-    return `Agent Wiki/${trimmed.slice("Agent Wiki/".length)}`;
+  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 }
+    });
   }
-  return `Agent Wiki/${trimmed}`;
+  return `Agent Wiki/${fileName}`;
+}
+function normalizeWikiIndexPath(path) {
+  return normalizeWikiPath(path, { supportedFiles: [supportedWikiIndexFile] });
+}
+function normalizeWikiLogPath(path = supportedWikiLogFile) {
+  return normalizeWikiPath(path, { supportedFiles: [supportedWikiLogFile] });
 }
 function parseOptionalParentRef(value) {
   return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
@@ -6508,6 +6584,14 @@ function writePreflightError(status, action) {
       status: 403
     };
   }
+  if (status.access === "append_only" && action !== "append") {
+    return {
+      code: "append_only_violation",
+      message: `Agent markdown file is append-only and cannot be overwritten: ${status.path}`,
+      suggestedAction: status.suggestedAction,
+      status: 403
+    };
+  }
   if (action === "create") {
     if (status.exists) {
       return {
@@ -6519,7 +6603,7 @@ function writePreflightError(status, action) {
     }
     if (!status.canCreate) {
       return {
-        code: status.access === "append_only" ? "append_only_violation" : "agent_path_forbidden",
+        code: "agent_path_forbidden",
         message: `Create is not allowed for ${status.path}.`,
         suggestedAction: status.suggestedAction,
         status: 403
@@ -6537,7 +6621,7 @@ function writePreflightError(status, action) {
     }
     if (!status.canUpdate) {
       return {
-        code: status.access === "append_only" ? "append_only_violation" : "agent_path_forbidden",
+        code: "agent_path_forbidden",
         message: `Update is not allowed for ${status.path}.`,
         suggestedAction: status.suggestedAction,
         status: 403
@@ -6553,7 +6637,7 @@ function writePreflightError(status, action) {
         status: 404
       };
     }
-    if (!status.canAppend) {
+    if (status.access !== "append_only" || !status.canAppend) {
       return {
         code: "append_only_violation",
         message: `Append is not allowed for ${status.path}.`,
@@ -6606,21 +6690,26 @@ async function runWriteFlow(params) {
       field: "update_agent_markdown_file"
     },
     append: {
-      operationName: "AppendAgentMarkdownFile",
-      field: "append_agent_markdown_file"
+      operationName: "RecordAgentMarkdownLog",
+      field: "record_agent_markdown_log"
     }
   }[params.action];
+  const variables = params.action === "append" ? {
+    organization_id: params.organizationId,
+    path: status.data.path,
+    content: params.content
+  } : {
+    organization_id: params.organizationId,
+    path: status.data.path,
+    parent_ref: status.data.parentRef ?? params.parentRef,
+    content: params.content
+  };
   return runAgentMarkdownMutation({
     command: params.command,
     operationName: mutation.operationName,
     runtimeOptions: params.runtimeOptions,
     field: mutation.field,
-    variables: {
-      organization_id: params.organizationId,
-      path: status.data.path,
-      parent_ref: status.data.parentRef ?? params.parentRef,
-      content: params.content
-    }
+    variables
   });
 }
 function addContentOptions(command) {
@@ -6714,8 +6803,8 @@ function registerOsmdCommands(program) {
       })
     });
   });
-  const agent = osmd.command("agent").description(".agent overlay files writable by agents; supports notes.md and log.md");
-  agent.command("status <parent-ref> <file>").action(async (parentRef, file, _opts, cmd) => {
+  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);
     const result = await requestAgentMarkdownStatus({
       command: "osmd.agent.status",
@@ -6733,7 +6822,7 @@ function registerOsmdCommands(program) {
       })
     });
   });
-  agent.command("init <parent-ref>").action(async (parentRef, _opts, cmd) => {
+  agent.command("init <parent-ref>").description("Idempotently initialize supported .agent files for a canonical OSMD parent").action(async (parentRef, _opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
     return runAgentMarkdownMutation({
       command: "osmd.agent.init",
@@ -6747,7 +6836,7 @@ function registerOsmdCommands(program) {
       }
     });
   });
-  agent.command("read <parent-ref> <file>").action(async (parentRef, file, _opts, cmd) => {
+  agent.command("read <parent-ref> <file>").description("Read .agent notes.md without creating files").action(async (parentRef, file, _opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
     const result = await requestAgentMarkdownFile({
       command: "osmd.agent.read",
@@ -6765,7 +6854,9 @@ function registerOsmdCommands(program) {
       })
     });
   });
-  addContentOptions(agent.command("create <parent-ref> <file>")).action(
+  addContentOptions(
+    agent.command("create <parent-ref> <file>").description("Create .agent notes.md after status/permission preflight")
+  ).action(
     async (parentRef, file, opts, cmd) => {
       const globals = cmd.optsWithGlobals();
       const content = await resolveContentInput(opts, globals);
@@ -6781,7 +6872,9 @@ function registerOsmdCommands(program) {
       });
     }
   );
-  addContentOptions(agent.command("update <parent-ref> <file>")).action(
+  addContentOptions(
+    agent.command("update <parent-ref> <file>").description("Update .agent notes.md after status/permission preflight")
+  ).action(
     async (parentRef, file, opts, cmd) => {
       const globals = cmd.optsWithGlobals();
       const content = await resolveContentInput(opts, globals);
@@ -6797,24 +6890,8 @@ function registerOsmdCommands(program) {
       });
     }
   );
-  addContentOptions(agent.command("append <parent-ref> <file>")).action(
-    async (parentRef, file, opts, cmd) => {
-      const globals = cmd.optsWithGlobals();
-      const content = await resolveContentInput(opts, globals);
-      const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
-      return runWriteFlow({
-        command: "osmd.agent.append",
-        action: "append",
-        runtimeOptions,
-        organizationId,
-        path: normalizeAgentFilePath(file),
-        parentRef: nonEmptyString3.parse(parentRef).trim(),
-        content
-      });
-    }
-  );
-  const wiki = osmd.command("wiki").description("Agent Wiki files writable by agents; first slice should use index.md and log.md");
-  wiki.command("status <path>").action(async (path, _opts, cmd) => {
+  const wiki = osmd.command("wiki").description("Agent Wiki files writable by agents; supports index.md and append-only log.md");
+  wiki.command("status <path>").description("Show Agent Wiki index.md or log.md metadata without creating files").action(async (path, _opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
     const result = await requestAgentMarkdownStatus({
       command: "osmd.wiki.status",
@@ -6831,7 +6908,7 @@ function registerOsmdCommands(program) {
       })
     });
   });
-  wiki.command("read <path>").action(async (path, _opts, cmd) => {
+  wiki.command("read <path>").description("Read Agent Wiki index.md or log.md without creating files").action(async (path, _opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
     const result = await requestAgentMarkdownFile({
       command: "osmd.wiki.read",
@@ -6848,13 +6925,13 @@ function registerOsmdCommands(program) {
       })
     });
   });
-  wiki.command("children [path]").action(async (path, _opts, cmd) => {
+  wiki.command("children [path]").description("List Agent Wiki children through backend metadata").action(async (path, _opts, cmd) => {
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
     const result = await requestAgentMarkdownChildren({
       command: "osmd.wiki.children",
       runtimeOptions,
       organizationId,
-      path: typeof path === "string" && path.trim() !== "" ? normalizeWikiPath(path) : "Agent Wiki",
+      path: typeof path === "string" && path.trim() !== "" ? normalizeWikiPath(path, { allowRoot: true }) : "Agent Wiki",
       source: "agent_wiki"
     });
     return printEnvelopeAndExit({
@@ -6866,7 +6943,9 @@ function registerOsmdCommands(program) {
       })
     });
   });
-  addContentOptions(wiki.command("create <path>")).action(async (path, opts, cmd) => {
+  addContentOptions(
+    wiki.command("create <path>").description("Create Agent Wiki index.md after status/permission preflight")
+  ).action(async (path, opts, cmd) => {
     const globals = cmd.optsWithGlobals();
     const content = await resolveContentInput(opts, globals);
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
@@ -6875,11 +6954,13 @@ function registerOsmdCommands(program) {
       action: "create",
       runtimeOptions,
       organizationId,
-      path: normalizeWikiPath(path),
+      path: normalizeWikiIndexPath(path),
       content
     });
   });
-  addContentOptions(wiki.command("update <path>")).action(async (path, opts, cmd) => {
+  addContentOptions(
+    wiki.command("update <path>").description("Update Agent Wiki index.md after status/permission preflight")
+  ).action(async (path, opts, cmd) => {
     const globals = cmd.optsWithGlobals();
     const content = await resolveContentInput(opts, globals);
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
@@ -6888,20 +6969,22 @@ function registerOsmdCommands(program) {
       action: "update",
       runtimeOptions,
       organizationId,
-      path: normalizeWikiPath(path),
+      path: normalizeWikiIndexPath(path),
       content
     });
   });
-  addContentOptions(wiki.command("append <path>")).action(async (path, opts, cmd) => {
+  addContentOptions(
+    wiki.command("append-log [path]").description("Append to Agent Wiki log.md after status/permission preflight")
+  ).action(async (path, opts, cmd) => {
     const globals = cmd.optsWithGlobals();
     const content = await resolveContentInput(opts, globals);
     const { organizationId, runtimeOptions } = await resolveOsmdContext(cmd);
     return runWriteFlow({
-      command: "osmd.wiki.append",
+      command: "osmd.wiki.append-log",
       action: "append",
       runtimeOptions,
       organizationId,
-      path: normalizeWikiPath(path),
+      path: normalizeWikiLogPath(typeof path === "string" && path.trim() !== "" ? path : void 0),
       content
     });
   });
@@ -6951,23 +7034,21 @@ function buildCli(options) {
 
 // src/index.ts
 function printCliFailure(params) {
-  printEnvelopeAndExit({
-    envelope: {
-      ok: false,
-      command: "cli",
-      status: params.status,
-      data: null,
-      error: {
-        code: params.code,
-        message: params.message,
-        details: params.details ?? {}
-      },
-      meta: {
-        requestId: "local_error"
-      }
+  printEnvelope({
+    ok: false,
+    command: "cli",
+    status: params.status,
+    data: null,
+    error: {
+      code: params.code,
+      message: params.message,
+      details: params.details ?? {}
     },
-    exitCode: params.exitCode
+    meta: {
+      requestId: "local_error"
+    }
   });
+  process.exitCode = params.exitCode;
 }
 async function main() {
   const program = buildCli();