@ted-galago/wave-cli 0.1.17 → 0.1.19

package/README.md

@@ -129,6 +129,7 @@ wave osmd agent read "projects/Wave Tools" notes.md
 wave osmd agent create "projects/Wave Tools" notes.md --content "Working notes"
 wave osmd wiki read index.md
 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 append-log --content "Observed durable event"
@@ -315,6 +316,7 @@ Commands:
 - `wave osmd agent create <parent-ref> notes.md (--content <markdown> | --file <path> | stdin)`
 - `wave osmd agent update <parent-ref> notes.md (--content <markdown> | --file <path> | stdin)`
 - `wave osmd wiki status <path>`
+- `wave osmd wiki init`
 - `wave osmd wiki read <path>`
 - `wave osmd wiki children [path]`
 - `wave osmd wiki create <path> (--content <markdown> | --file <path> | stdin)`
@@ -327,6 +329,7 @@ GraphQL mapping:
 - `osmd read` / `osmd agent read` / `osmd wiki read` -> `agentMarkdownFile`
 - `osmd children` / `osmd wiki children` -> `agentMarkdownChildren`
 - `osmd agent init` -> `initAgentMarkdown`
+- `osmd wiki init` -> `initAgentMarkdown` with backend path `Agent Wiki`
 - `osmd agent create` / `osmd wiki create` -> `createAgentMarkdownFile`
 - `osmd agent update` / `osmd wiki update` -> `updateAgentMarkdownFile`
 - `osmd wiki append-log` -> `recordAgentMarkdownLog`
@@ -341,17 +344,63 @@ Path and permission rules:
 - Agent Wiki index paths may be `index.md` or `Agent Wiki/index.md`; the CLI normalizes these to `Agent Wiki/index.md`.
 - 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 `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 `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`.
 - 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.
 - `update` fails when `exists` is false.
 - `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"`.
 
+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
@@ -368,7 +417,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,
@@ -392,6 +445,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

package/dist/index.cjs

@@ -6156,6 +6156,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 +6166,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,
@@ -6216,6 +6220,8 @@ var AGENT_MARKDOWN_FILE_SELECTION = `{
   canCreate
   canUpdate
   canAppend
+  wikiRole
+  formatVersion
   parentRef
   agentChildrenAllowed
   suggestedAction
@@ -6228,6 +6234,8 @@ 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",
@@ -6632,7 +6640,7 @@ function writePreflightError(status, action) {
     if (!status.exists) {
       return {
         code: "agent_file_not_found",
-        message: `Agent markdown file does not exist: ${status.path}`,
+        message: status.suggestedAction === "init" ? `Agent Wiki log is not initialized. Run wave osmd wiki init before append-log.` : `Agent markdown file does not exist: ${status.path}`,
         suggestedAction: status.suggestedAction,
         status: 404
       };
@@ -6891,6 +6899,19 @@ function registerOsmdCommands(program) {
     }
   );
   const wiki = osmd.command("wiki").description("Agent Wiki files writable by agents; supports index.md 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({
+      command: "osmd.wiki.init",
+      operationName: "InitAgentMarkdown",
+      runtimeOptions,
+      field: "init_agent_markdown",
+      variables: {
+        organization_id: organizationId,
+        path: "Agent Wiki"
+      }
+    });
+  });
   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({

package/dist/index.js

@@ -6155,6 +6155,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 +6165,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,
@@ -6215,6 +6219,8 @@ var AGENT_MARKDOWN_FILE_SELECTION = `{
   canCreate
   canUpdate
   canAppend
+  wikiRole
+  formatVersion
   parentRef
   agentChildrenAllowed
   suggestedAction
@@ -6227,6 +6233,8 @@ 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",
@@ -6631,7 +6639,7 @@ function writePreflightError(status, action) {
     if (!status.exists) {
       return {
         code: "agent_file_not_found",
-        message: `Agent markdown file does not exist: ${status.path}`,
+        message: status.suggestedAction === "init" ? `Agent Wiki log is not initialized. Run wave osmd wiki init before append-log.` : `Agent markdown file does not exist: ${status.path}`,
         suggestedAction: status.suggestedAction,
         status: 404
       };
@@ -6890,6 +6898,19 @@ function registerOsmdCommands(program) {
     }
   );
   const wiki = osmd.command("wiki").description("Agent Wiki files writable by agents; supports index.md 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({
+      command: "osmd.wiki.init",
+      operationName: "InitAgentMarkdown",
+      runtimeOptions,
+      field: "init_agent_markdown",
+      variables: {
+        organization_id: organizationId,
+        path: "Agent Wiki"
+      }
+    });
+  });
   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({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ted-galago/wave-cli",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "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,31 +1228,78 @@ 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"
   });
 
+  if (wikiLogStatus.parsed?.data?.exists === false) {
+    const missingWikiLogAppend = runWave(
+      ["osmd", "wiki", "append-log", "--content", `CLI live verify log ${verifyStamp}`],
+      env
+    );
+    results.push(missingWikiLogAppend);
+    osmdVerificationFailures += recordExactCheck({
+      lines: osmdVerificationLines,
+      label: "osmd.wiki append-log missing log returns init guidance",
+      result: missingWikiLogAppend,
+      ok:
+        missingWikiLogAppend.parsed?.ok === false &&
+        missingWikiLogAppend.parsed?.status === 404 &&
+        missingWikiLogAppend.parsed?.error?.code === "agent_file_not_found" &&
+        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"
+    });
+  } else {
+    osmdVerificationLines.push(
+      "PASS | status=n/a | err=skipped_existing_log | reason=missing_log_init_guidance_skipped | osmd.wiki append-log missing log returns init guidance"
+    );
+  }
+
+  const wikiInit = runWave(["osmd", "wiki", "init"], env);
+  results.push(wikiInit);
+  const wikiInitFiles = firstArrayValue(wikiInit.parsed, [["data", "files"]]);
+  osmdVerificationFailures += recordExactCheck({
+    lines: osmdVerificationLines,
+    label: "osmd.wiki init creates Agent Wiki system files",
+    result: wikiInit,
+    ok:
+      wikiInit.parsed?.ok === true &&
+      wikiInitFiles.some(
+        (file) =>
+          file?.path === "Agent Wiki/log.md" &&
+          file?.access === "append_only" &&
+          file?.wikiRole === "log" &&
+          typeof file?.formatVersion === "string" &&
+          file?.exists === true &&
+          file?.canAppend === true
+      ),
+    reason: "agent_wiki_init"
+  });
+
   const wikiLogAppend = runWave(
     ["osmd", "wiki", "append-log", "--content", `CLI live verify log ${verifyStamp}`],
     env
   );
   results.push(wikiLogAppend);
-  const logAppendAllowed =
-    wikiLogStatus.parsed?.data?.exists === true &&
-    wikiLogStatus.parsed?.data?.access === "append_only" &&
-    wikiLogStatus.parsed?.data?.canAppend === true;
   osmdVerificationFailures += recordExactCheck({
     lines: osmdVerificationLines,
-    label: "osmd.wiki append-log follows backend canAppend",
+    label: "osmd.wiki append-log succeeds after init",
     result: wikiLogAppend,
-    ok: logAppendAllowed
-      ? wikiLogAppend.parsed?.ok === true &&
-        wikiLogAppend.parsed?.data?.path === "Agent Wiki/log.md" &&
-        wikiLogAppend.parsed?.data?.access === "append_only"
-      : wikiLogAppend.parsed?.ok === false &&
-        wikiLogAppend.parsed?.data?.path === "Agent Wiki/log.md" &&
-        wikiLogAppend.parsed?.data?.canAppend === false,
-    reason: "agent_wiki_log_append"
+    ok:
+      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"
   });
 
   if (wikiStatus.parsed?.data?.exists === false) {
@@ -1297,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"
   });
@@ -1310,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"
   });
@@ -1328,6 +1386,8 @@ 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"
   });