@ted-galago/wave-cli 0.1.14 → 0.1.16

package/README.md

@@ -119,6 +119,17 @@ wave markdown-tree root --tree-view
 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 read "projects/Wave Tools"
+wave osmd children "projects/Wave Tools"
+wave osmd status "projects/Wave Tools/.agent/notes.md" --parent-ref "projects/Wave Tools"
+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 wiki read index.md
+wave osmd wiki create index.md --content "# Agent Wiki"
+wave osmd wiki update "Agent Wiki/index.md" --file ./agent-wiki-index.md
 wave find "Ted"
 wave open "Ted Martinez"
 wave ls --path "directory/Members/Ted Martinez"
@@ -286,6 +297,96 @@ Backend error codes are surfaced explicitly from GraphQL `errors[].extensions.co
 - `INVALID_SCOPE`
 - `UNSUPPORTED_BRANCH`
 
+## 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.
+
+Commands:
+
+- `wave osmd tree [--depth <n>] [--tree-view]`
+- `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 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 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)`
+
+GraphQL mapping:
+
+- `osmd status` / `osmd agent status` / `osmd wiki status` -> `agentMarkdownStatus`
+- `osmd read` / `osmd agent read` / `osmd wiki read` -> `agentMarkdownFile`
+- `osmd children` / `osmd wiki children` -> `agentMarkdownChildren`
+- `osmd agent init` -> `initAgentMarkdown`
+- `osmd agent create` / `osmd wiki create` -> `createAgentMarkdownFile`
+- `osmd agent update` / `osmd wiki update` -> `updateAgentMarkdownFile`
+
+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`).
+- `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`.
+- Reads never create files.
+- Create/update 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.
+
+OSMD command envelopes keep the global CLI envelope and put the file metadata directly in `data`:
+
+```json
+{
+  "ok": true,
+  "command": "osmd.agent.read",
+  "status": 200,
+  "data": {
+    "path": "projects/Wave Tools/.agent/notes.md",
+    "source": "agent_overlay",
+    "access": "read_write",
+    "owner": "atlas",
+    "exists": true,
+    "parentRef": "projects/Wave Tools",
+    "content": "..."
+  },
+  "error": null,
+  "meta": { "requestId": "req_123" }
+}
+```
+
+On write preflight errors, `data` contains the status metadata and `error.suggestedAction` mirrors backend guidance:
+
+```json
+{
+  "ok": false,
+  "command": "osmd.agent.update",
+  "status": 404,
+  "data": {
+    "path": "projects/Wave Tools/.agent/notes.md",
+    "exists": false,
+    "canCreate": true,
+    "canUpdate": false,
+    "canAppend": false,
+    "suggestedAction": "create"
+  },
+  "error": {
+    "code": "agent_file_not_found",
+    "message": "Agent markdown file does not exist: projects/Wave Tools/.agent/notes.md",
+    "suggestedAction": "create",
+    "details": {}
+  },
+  "meta": { "requestId": "req_124" }
+}
+```
+
 ## Navigation Shell
 
 Primary agent-facing discovery/navigation commands:
@@ -306,6 +407,7 @@ 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`.
 
 Ambiguity contract: