@ted-galago/wave-cli 0.1.18 → 0.1.19

package/README.md

@@ -348,7 +348,7 @@ 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`.
 - 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 +357,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 +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,
@@ -397,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",

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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ted-galago/wave-cli",
-  "version": "0.1.18",
+  "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,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,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"
   });