@ted-galago/wave-cli 0.1.15 → 0.1.17

package/README.md

@@ -127,10 +127,11 @@ wave osmd agent init "projects/Wave Tools"
 wave osmd agent status "projects/Wave Tools" notes.md
 wave osmd agent read "projects/Wave Tools" notes.md
 wave osmd agent create "projects/Wave Tools" notes.md --content "Working notes"
-wave osmd agent append "projects/Wave Tools" log.md --content "Investigated project context"
 wave osmd wiki read index.md
+wave osmd wiki read log.md
 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"
 wave find "Ted"
 wave open "Ted Martinez"
 wave ls --path "directory/Members/Ted Martinez"
@@ -300,7 +301,7 @@ Backend error codes are surfaced explicitly from GraphQL `errors[].extensions.co
 
 ## OSMD Agent Markdown
 
-The `osmd` command group is the write-capable agent interface for the merged OSMD + agent overlay model. Canonical OSMD files are read-only. Agents must write either `.agent` overlay files attached to a canonical OSMD parent, or top-level Agent Wiki files.
+The `osmd` command group is the write-capable agent interface for canonical OSMD, `.agent` overlays, and Agent Wiki files. Canonical OSMD files are read-only. Agents must write either entity-specific `.agent` overlay memory attached to a canonical OSMD parent, or broad Agent Wiki knowledge.
 
 Commands:
 
@@ -308,18 +309,17 @@ Commands:
 - `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>]`
-- `wave osmd agent status <parent-ref> <notes.md|log.md>`
+- `wave osmd agent status <parent-ref> notes.md`
 - `wave osmd agent init <parent-ref>`
-- `wave osmd agent read <parent-ref> <notes.md|log.md>`
-- `wave osmd agent create <parent-ref> <notes.md|log.md> (--content <markdown> | --file <path> | stdin)`
-- `wave osmd agent update <parent-ref> <notes.md|log.md> (--content <markdown> | --file <path> | stdin)`
-- `wave osmd agent append <parent-ref> <notes.md|log.md> (--content <markdown> | --file <path> | stdin)`
+- `wave osmd agent read <parent-ref> notes.md`
+- `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 read <path>`
 - `wave osmd wiki children [path]`
 - `wave osmd wiki create <path> (--content <markdown> | --file <path> | stdin)`
 - `wave osmd wiki update <path> (--content <markdown> | --file <path> | stdin)`
-- `wave osmd wiki append <path> (--content <markdown> | --file <path> | stdin)`
+- `wave osmd wiki append-log [log.md] (--content <markdown> | --file <path> | stdin)`
 
 GraphQL mapping:
 
@@ -329,22 +329,28 @@ GraphQL mapping:
 - `osmd agent init` -> `initAgentMarkdown`
 - `osmd agent create` / `osmd wiki create` -> `createAgentMarkdownFile`
 - `osmd agent update` / `osmd wiki update` -> `updateAgentMarkdownFile`
-- `osmd agent append` / `osmd wiki append` -> `appendAgentMarkdownFile`
+- `osmd wiki append-log` -> `recordAgentMarkdownLog`
 
 Path and permission rules:
 
 - Canonical OSMD reads use backend `path` values from tree/status/file responses.
 - Canonical OSMD writes are blocked before mutation when status reports `source: "canonical_osmd"` or `access: "read_only"`.
 - `.agent` commands require a canonical `parent-ref`; the CLI passes it as `parentRef` and never derives storage paths.
-- `.agent` first slice supports only `notes.md` (`read_write`) and `log.md` (`append_only`).
+- `.agent` first slice supports only `notes.md`.
 - `osmd agent init <parent-ref>` is idempotent for default `.agent` files.
-- Agent Wiki command paths may be `index.md`, `log.md`, or `Agent Wiki/index.md`; the CLI normalizes these to backend paths under `Agent Wiki`.
-- Agent Wiki first-slice agents should use `index.md` and `log.md`.
+- 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 `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`.
 - Reads never create files.
-- Create/update/append flows call status first and inspect `exists`, `canCreate`, `canUpdate`, `canAppend`, `suggestedAction`, and `errorCode`.
+- 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` only proceeds when `canAppend` is true.
+- `append-log` fails unless status reports `exists: true`, `access: "append_only"`, and `canAppend: true`.
+- Missing `Agent Wiki/index.md` is create-ready when status returns `exists: false`, `canCreate: true`, `canUpdate: false`, and `suggestedAction: "create"`.
 
 OSMD command envelopes keep the global CLI envelope and put the file metadata directly in `data`:
 
@@ -359,6 +365,9 @@ OSMD command envelopes keep the global CLI envelope and put the file metadata di
     "access": "read_write",
     "owner": "atlas",
     "exists": true,
+    "canCreate": false,
+    "canUpdate": true,
+    "canAppend": false,
     "parentRef": "projects/Wave Tools",
     "content": "..."
   },
@@ -372,19 +381,24 @@ On write preflight errors, `data` contains the status metadata and `error.sugges
 ```json
 {
   "ok": false,
-  "command": "osmd.agent.update",
+  "command": "osmd.wiki.update",
   "status": 404,
   "data": {
-    "path": "projects/Wave Tools/.agent/notes.md",
+    "path": "Agent Wiki/index.md",
+    "source": "agent_wiki",
+    "access": "read_write",
+    "owner": "atlas",
     "exists": false,
     "canCreate": true,
     "canUpdate": false,
     "canAppend": false,
-    "suggestedAction": "create"
+    "parentRef": null,
+    "suggestedAction": "create",
+    "errorCode": null
   },
   "error": {
     "code": "agent_file_not_found",
-    "message": "Agent markdown file does not exist: projects/Wave Tools/.agent/notes.md",
+    "message": "Agent markdown file does not exist: Agent Wiki/index.md",
     "suggestedAction": "create",
     "details": {}
   },