@wave-ai-os/wave-cli 0.1.57

package/README.md

@@ -0,0 +1,928 @@
+# @wave/cli
+
+Machine-first CLI used by a Node LangGraph agent to execute semantic Wave operations against the Rails API.
+
+See also:
+
+- `./.env.example`
+- `./docs/ENVIRONMENT_CONTRACT_CHECKLIST.md`
+
+## Principles
+
+- `stdout` emits exactly one JSON envelope for machine commands by default.
+- `stderr` is for debug/diagnostic logs only.
+- Help output is human-readable and exits `0`; it does not emit a JSON error envelope.
+- `--readable` enables human formatting where a command supports it; `--json` forces the stable machine envelope where both flags are present.
+- No prompts, colors, or implicit interactive UX in this phase.
+- JWT forwarding is centralized.
+
+## Install
+
+```bash
+npm install @wave/cli
+```
+
+Or run locally from source:
+
+```bash
+npm run --silent dev -- tasks list --project-id 123 --organization-id 42 --base-url https://api.example.com --token token
+```
+
+Direct source smoke checks can use the same Node entrypoint as the dev script:
+
+```bash
+node --disable-warning=DEP0205 --import tsx src/index.ts capabilities tools --json
+```
+
+Secure stdin auth/context examples:
+
+```bash
+printf '%s' "token-value" | wave --token-stdin --base-url https://api.example.com --organization-id 42 tasks list --page 1 --per 10
+
+printf '%s' '{"token":"token-value","baseUrl":"https://api.example.com","organizationId":"42","agentName":"atlas"}' \
+  | wave --auth-json-stdin tasks list --page 1 --per 10
+```
+
+## Benchmark Wave vs Obsidian CLI
+
+Run the side-by-side benchmark harness:
+
+```bash
+npm run benchmark:cli
+```
+
+Useful options:
+
+```bash
+npm run benchmark:cli -- --runs 20 --warmup 3 --query "meeting notes"
+npm run benchmark:cli -- --obsidian-bin /Applications/Obsidian.app/Contents/MacOS/obsidian-cli
+npm run benchmark:cli -- --json-out /tmp/cli-benchmark.json
+```
+
+Notes:
+
+- Wave scenarios expect JSON envelopes for domain operations.
+- Obsidian scenarios require the CLI to be registered and the Obsidian app available.
+
+## Runtime Contract
+
+Required (from flags, stdin, or env):
+
+- `WAVE_API_TOKEN`
+- `WAVE_API_BASE_URL`
+- `WAVE_ORGANIZATION_ID`
+
+Optional env:
+
+- `WAVE_AGENT_NAME`
+- `WAVE_AGENT_RUN_ID`
+- `WAVE_REQUEST_ID`
+- `WAVE_CONFIG_PATH`
+- `WAVE_TIMEOUT_MS`
+- `WAVE_DEBUG`
+- `WAVE_OPENAPI_PATH` (local contract file, e.g. `openapi/wave-cli.yaml`)
+- `WAVE_OPENAPI_URL` (hosted contract file)
+- `WAVE_OPENAPI_VERSION` (pinned spec version/hash)
+
+Deterministic precedence:
+
+- explicit flags (`--token` / `--jwt`, `--base-url`, `--organization-id`, and tracing/runtime flags)
+- stdin context (`--token-stdin` or `--auth-json-stdin`)
+- env vars (`WAVE_*`)
+- config file (`--config`, `WAVE_CONFIG_PATH`, or `~/.wave/config.json` when present)
+- failure with structured JSON error
+
+Config files are JSON objects using the same keys accepted by `--auth-json-stdin`, for example:
+
+```json
+{
+  "token": "token-value",
+  "baseUrl": "https://api.example.com",
+  "organizationId": "42",
+  "agentName": "atlas"
+}
+```
+
+Entity targeting follows the same explicit-first rule: command flags and positional args, then stdin JSON where supported, then environment/config context for organization and runtime. If a target remains unresolved, the CLI returns a structured JSON error with `suggestedAction`, `suggestedCommands`, or both where the command can provide actionable guidance.
+
+## Discoverability and Diagnostics
+
+Wave exposes native discovery commands without undocumented spec/docs flags:
+
+```bash
+wave help
+wave capabilities list
+wave capabilities list --readable
+wave capabilities tools
+wave capabilities tools mail
+wave broadcast open
+wave broadcast schema
+wave broadcast examples
+wave support counts
+wave support tickets --status open
+wave support knowledge-articles --collection-id 123
+wave recognition list --page 1 --per 20
+wave recognition top-value --period-start 2026-01-01
+wave whiteboards list --page 1 --per 20
+wave whiteboards show --slug product-planning
+wave time-tracking entries --member-id 67 --start-date 2026-01-01 --end-date 2026-01-31
+wave time-tracking report --start-date 2026-01-01 --end-date 2026-01-31
+wave planner events --starts-at 2026-01-01T00:00:00Z --ends-at 2026-01-07T00:00:00Z
+wave planner public-booking-link --slug intro-call --starts-at 2026-01-01T00:00:00Z --ends-at 2026-01-07T00:00:00Z --timezone America/Phoenix
+wave api ls
+wave graphql fields
+wave osmd schema
+wave osmd examples
+wave markdown-tree schema
+wave doctor
+wave doctor --readable
+```
+
+Namespace taxonomy:
+
+- Primary: `osmd`, `broadcast`, `support`, `recognition`, `whiteboards`, `time-tracking`, `planner`, `tasks`, `projects`, `rocks`, `meetings`, `members`, `teams`, `issues`, `foundation`
+- Advanced: generated CRUD resources, `markdown-tree`, content/meta/resource-specific command groups
+- Aliases / shortcuts: `find`, `open`, `ls`, `cat`, `tree`, `phantom` help alias
+
+`wave capabilities tools` exposes the shared recent-tool support registry for Broadcast, Support, Recognition, Whiteboards, Time Tracking, Planner, and Mail. Backend keys come from WAVE-02 evidence and route/deep-link templates come from WAVE-03 evidence. WAVE-05 enables only the read-only Broadcast commands `list`, `workspace`, `community`, and `open` for safe counts, metrics, provider/service status, and channel status metadata. WAVE-06 enables only read-only Support counts, inbox/ticket metadata, labels, settings, knowledge metadata, and route commands. WAVE-07 enables only read-only Recognition commands for list/show metadata, top value, point balance, and route metadata. WAVE-08 enables only read-only Whiteboards commands for list/show metadata and route metadata. WAVE-09 enables only read-only Time Tracking commands for timesheet, timer, entry, project, report, and route metadata. WAVE-10 enables only read-only Planner safe state, event, booking-link, preference, public booking-link, and route metadata. Mail remains registry-only, and Broadcast/Support/Recognition/Whiteboards/Time Tracking/Planner write, reply, send, publish, delete, destroy, media, scene, export, import, start, stop, cancel, upsert, payroll, billing, event write, preference update, booking-link write, and booking-reservation surfaces are not enabled.
+
+`wave doctor` is read-only. It checks auth token resolution, organization ID resolution, base URL resolution, GraphQL reachability, API JSON response health, optional OpenAPI contract configuration, and CLI runtime integrity.
+
+## Commands
+
+Examples:
+
+```bash
+wave tasks list --project-id 123
+wave tasks create --project-id 123 --title "Fix auth bug"
+wave tasks update --id 99 --status in_progress
+wave tasks destroy --id 99
+wave projects list
+wave projects show --id 123
+wave rocks update-status --id 55 --status on_track
+wave meetings show --id 77
+wave members show --id 44
+wave members meta-profile --member-id 44 --json
+wave skills list --json
+wave skills show --id 123 --json
+wave meetings notes --id 77 --content "Decisions captured"
+wave issues create --issue-group-id 321 --name "Auth issue" --issue-type short_term
+wave foundation strategic-plans show
+wave foundation strategic-objectives update --data-json '{"strategic_objective":{"summary":"Updated"}}'
+wave foundation annual-objectives create --data-json '{"annual_objective":{"strategic_objective_id":"7","name":"Annual Goal"}}'
+wave foundation quarterly-objectives create --data-json '{"quarterly_objective":{"strategic_objective_id":"7","annual_objective_id":"8","name":"Quarterly Goal"}}'
+wave lists create --data-json '{"name":"Weekly List"}'
+wave list-items create --data-json '{"list_id":"123","summary":"Follow up"}'
+wave todos create --data-json '{"todo_group_id":"55","name":"Send update","status":"open"}'
+wave knowledge create --data-json '{"content":{"name":"Runbook","content_type":"process","status":"draft","member_id":"67"}}'
+wave content create-member --target-member-id 67 --name "1:1 Note" --body "Strong progress"
+wave content create-manager --actor-member-id 67 --target-member-id 68 --name "Manager Note" --body "Coaching plan"
+wave content create-team --actor-member-id 67 --team-id 9 --name "Team Note" --body "Team context"
+wave content create-project --actor-member-id 67 --project-id 80 --name "Project Note" --body "Project context"
+wave content create-customer --actor-member-id 67 --customer-id 30 --name "Customer Note" --body "Customer context"
+wave content create-contact --actor-member-id 67 --contact-id 31 --name "Contact Note" --body "Contact context"
+wave content list --contentable-type Member --contentable-id 67 --member-id 67 --page 1 --per 20
+wave content show --id 1001
+wave content update --id 1001 --name "Updated Note" --body "Updated body" --status published
+wave content destroy --id 1001
+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 markdown-tree schema
+wave osmd tree
+wave osmd search "Wave Tools" --scope combined --limit 10
+wave osmd lint --scope combined
+wave osmd lint --scope combined --json
+wave osmd ingest text "Customer interview notes" --source-type pasted_text --slug customer-interviews --parent-ref "projects/Wave Tools" --summary "Customer interview source summary" --run-lint
+wave osmd ingest file ./source.md --source-type uploaded_markdown --slug source-document --parent-ref "projects/Wave Tools" --summary "Source document summary"
+wave osmd ingest url "https://example.com/source" --source-type url --slug example-source --parent-ref "projects/Wave Tools" --summary "Example source summary"
+wave osmd ingest transcript --file ./meeting-transcript.md --source-type meeting_transcript --slug team-meeting-transcript --parent-ref "projects/Wave Tools" --summary "Meeting transcript summary"
+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 agent update "projects/Wave Tools" customer-interviews.md --content "# Customer Interviews"
+wave osmd agent children "projects/Wave Tools"
+wave osmd wiki read index.md
+wave osmd wiki read log.md
+wave osmd wiki index-upsert ".agent/customer-interviews.md" --parent-ref "projects/Wave Tools" --summary "Customer interview source summary"
+wave osmd wiki append-log --content "Observed durable event"
+wave osmd examples
+wave osmd schema
+wave capabilities list
+wave api ls
+wave graphql fields
+wave doctor
+wave find "Ted"
+wave open "Ted Martinez"
+wave ls --path "directory/Members/Ted Martinez"
+wave cat --path "directory/Members/Ted Martinez/Member Profile"
+wave tree --path "knowledge/Processes" --depth 2
+wave pulse update --id 12 --data-json '{"status":"on_track"}'
+wave subtasks list --task-id 123 --page 1 --per 20
+wave milestones list --rock-id 234 --page 1 --per 20
+wave subitems list --list-item-id 345 --page 1 --per 20
+wave subtodos list --todo-id 456 --page 1 --per 20
+wave subissues list --issue-id 567 --page 1 --per 20
+wave talking-points list --meeting-id 678 --page 1 --per 20
+wave subtasks create --data-json '{"subtask":{"task_id":"123","member_id":"67","name":"Subtask name","description":"Subtask description"}}'
+wave subissues destroy --id 999
+```
+
+All commands require organization context via `--organization-id` or `WAVE_ORGANIZATION_ID`.
+You can also provide `organizationId` via `--auth-json-stdin`.
+
+## Parent-Child Create Rules
+
+These child resources enforce parent IDs at CLI validation time:
+
+- `list-items.create` requires `list_id`
+- `issues.create` requires `issue_group_id`
+- `todos.create` requires `todo_group_id`
+- `rocks.create` requires `rock_collection_id`
+- `kpis.create` requires `smart_kpi_view_id`
+- `scorecards.create` requires `measurable_group_id`
+- `subtasks.create` requires `task_id`
+- `milestones.create` requires `rock_id`
+- `subitems.create` requires `list_item_id`
+- `subtodos.create` requires `todo_id`
+- `subissues.create` requires `issue_id`
+- `talking-points.create` requires `meeting_id`
+
+If a required parent field is missing, CLI returns JSON error with exit code `2`.
+
+`kpis.create` contract notes:
+
+- `smart_kpi.name` must be one of the backend enum values.
+- If payload uses free-text `smart_kpi.name` with `measurable_group_id`, CLI routes to `create_measurable` (`scorecards.create`) instead of `create_smart_kpi`.
+
+`meetings.create` contract notes:
+
+- `meeting.type` is required and must be `TeamMeeting` or `OneOnOneMeeting`.
+- Required fields: `member_id`, `date`, `start_time`.
+- `meeting.repeats` defaults to `never` if omitted.
+- For `TeamMeeting`, `teams_ids` is required.
+
+`organizations.update` contract notes:
+
+- `organization.workspace_name` is normalized to `organization.organization_detail_attributes.workspace_name`.
+
+`organizations.meta-profile.update` contract notes:
+
+- Payload must be shaped as `organization_meta_profile.profile.<section>.<field>`.
+- Legacy shorthand `organization_meta_profile.title` is normalized to `profile.company_identity.one_sentence_summary`.
+
+`organizations.key-metric-meta-profile.update` contract notes:
+
+- Payload must be shaped as `key_metric_meta_profile.profile.<section>.<field>`.
+- Legacy shorthand `key_metric_meta_profile.annual_revenue` is normalized to `profile.financial.revenue`.
+
+`knowledge.create` contract notes:
+
+- `content.content_type` must be one of `company`, `policy`, `process`.
+- `content.status` must be `draft` or `published`.
+- `content.member_id` is required.
+- `content.type` is not required for create.
+
+`knowledge.list` filter notes:
+
+- `--assigned true` uses backend "assigned for current authenticated member" logic.
+- `--assigned true` defaults to incomplete items only.
+- CLI `knowledge list` does not currently expose an `include_completed` toggle.
+- `--member-id` filters `contents.member_id` (owner/author), not assignment target.
+- `--focus-member-id` filters `contents.focus_member_id` (focus scope), not assignment target.
+- For manager/admin users, `--assigned true` may include creator-visible items with assignments, not only direct assignee matches.
+
+Examples:
+
+```bash
+# Assigned to current authenticated member (incomplete only by default)
+wave knowledge list --assigned true --page 1 --per 50
+
+# Owner filter (not assignment target filter)
+wave knowledge list --member-id 67 --page 1 --per 50
+
+# Focus scope filter (not assignment target filter)
+wave knowledge list --focus-member-id 67 --page 1 --per 50
+```
+
+`news.create` contract notes:
+
+- Requires `headline.member_id`, `headline.status`, and `headline.headline_type`.
+- `headline.status` must be `active` or `completed`.
+- `headline.headline_type` must be `team` or `org_wide`.
+
+`questions.create/update` contract notes:
+
+- Use `question.name` (legacy `summary` is normalized to `name`).
+- `questions.create` requires `question.member_id` and `question.name`.
+- `question.status`, when provided, must be `asked` or `answered`.
+- `questions.list` supports only `asked` and `answered` filters (plus `page` / `per`).
+- `questions.list` does not expose `--query-json`; unsupported filters are rejected at CLI parse time.
+
+`pulse.create` contract notes:
+
+- Requires `health_update.health_updatable_id`, `health_update.health_updatable_type`, `health_update.member_id`, and `health_update.status`.
+- Legacy `updatable_id`/`updatable_type` are normalized to `health_updatable_id`/`health_updatable_type`.
+- `health_update.status` must be `on_track`, `at_risk`, or `off_track`.
+
+`surveys.create/update` contract notes:
+
+- Use `survey.name` and `survey.recipient_type` (`title` is normalized to `name`).
+- `survey.recipient_type` must be `member`, `team`, or `org_wide`.
+- Survey results are written via `surveys.update` using nested `survey.survey_results_attributes`.
+- There is no standalone `createSurveyResult` / `updateSurveyResult` CLI command.
+- Valid `survey.name` values:
+  - `employee_net_promoter_score`
+  - `continuous_performance_review`
+  - `core_value_alignment`
+  - `engagement`
+  - `wellness_and_mental_health`
+  - `workspace_culture`
+  - `peer_review`
+  - `manager_review`
+  - `onboarding`
+
+`feedbacks.create/update` contract notes:
+
+- Use `feedback.name` (`title` is normalized to `name`).
+- `feedbacks.create` requires `feedback.name`, `feedback.quarter`, `feedback.year`.
+- `feedback.quarter` must be `q1`, `q2`, `q3`, or `q4`.
+
+`accountability.create/update` contract notes:
+
+- Use `responsibility.name` (`summary` is normalized to `name`).
+- `accountability.create` requires `responsibility.name` and `responsibility.member_id`.
+
+## Markdown Tree Traversal
+
+Thin GraphQL adapter over backend markdown-tree services.
+CLI does not re-implement traversal/scope rules.
+
+Commands:
+
+- `wave markdown-tree root [--tree-view]`
+- `wave markdown-tree resolve --tool-key <k> --node-key <k> [--parent-id <id>] [--record-id <id>] [--member-id <id>] [--team-id <id>] [--content-type <t>] [--tree-view]`
+- `wave markdown-tree children --tool-key <k> --node-key <k> [--parent-id <id>] [--record-id <id>] [--member-id <id>] [--team-id <id>] [--content-type <t>] [--tree-view]`
+- `wave markdown-tree subtree --tool-key <k> --node-key <k> --depth <n> [--parent-id <id>] [--record-id <id>] [--member-id <id>] [--team-id <id>] [--content-type <t>] [--tree-view]`
+
+GraphQL mapping:
+
+- `root` -> `markdownTreeRoot`
+- `resolve` -> `markdownTreeNode`
+- `children` -> `markdownTreeChildren`
+- `subtree` -> `markdownTreeSubtree`
+
+Backend error codes are surfaced explicitly from GraphQL `errors[].extensions.code`:
+
+- `UNAUTHORIZED`
+- `NOT_FOUND`
+- `INVALID_SCOPE`
+- `UNSUPPORTED_BRANCH`
+
+## OSMD Agent Markdown
+
+The `osmd` command group is the machine interface for canonical OSMD, `.agent` pages, and Agent Wiki index/log files. Canonical OSMD files are read-only. New synthesized pages are written under an OSMD parent node's `.agent/` folder; Agent Wiki is limited to `index.md`, append-only `log.md`, and legacy read/status visibility for older content folders.
+
+Commands:
+
+- `wave osmd tree [--depth <n>] [--tree-view]`
+- `wave osmd schema [--json | --readable]`
+- `wave osmd examples [--json | --readable]`
+- `wave osmd search "<query>" [--scope os-only|agent-overlay-only|agent-wiki-only|combined] [--limit <n>]`
+- `wave osmd lint [--scope combined|agent-overlay-only|agent-wiki-only] [--json] [--fix=false]`
+- `wave osmd memory-quality [--scope agent-overlay-only] [--json | --readable]`
+- `wave osmd ingest text [text] [--content <text> | --file <path> | stdin] --slug <slug> --parent-ref <canonicalPath> --summary <summary> [--source-type <type>] [--title <title>] [--run-lint] [--dry-run] [--readable]`
+- `wave osmd ingest file <path> --slug <slug> --parent-ref <canonicalPath> --summary <summary> [--source-type <type>] [--title <title>] [--run-lint] [--dry-run] [--readable]`
+- `wave osmd ingest url <url> --slug <slug> --parent-ref <canonicalPath> --summary <summary> [--source-type <type>] [--title <title>] [--run-lint] [--dry-run] [--readable]`
+- `wave osmd ingest transcript [text] [--content <text> | --file <path> | stdin] --slug <slug> --parent-ref <canonicalPath> --summary <summary> [--source-type <type>] [--title <title>] [--run-lint] [--dry-run] [--readable]`
+- `wave osmd phantom run [--dry-run] [--readable]`
+- `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> <file>`
+- `wave osmd agent init <parent-ref>`
+- `wave osmd agent read <parent-ref> <file>`
+- `wave osmd agent create <parent-ref> <file> (--content <markdown> | --file <path> | stdin)`
+- `wave osmd agent update <parent-ref> <file> (--content <markdown> | --file <path> | stdin)`
+- `wave osmd agent children <parent-ref>`
+- `wave osmd wiki status <path>`
+- `wave osmd wiki read <path>`
+- `wave osmd wiki index-upsert <.agent-file> --summary <summary> --parent-ref <canonicalPath>`
+- `wave osmd wiki append-log [log.md] (--content <markdown> | --file <path> | stdin)`
+- `wave phantom inventory --json`
+- `wave phantom observations --json`
+- `wave phantom observations --run-id <run-id> --json`
+- `wave phantom observations --source-table <source-table> --json`
+- `wave phantom observations --source-record-id <source-record-id> --json`
+- `wave phantom observations --source-event-id <source-event-id> --json`
+- `wave phantom observations --test-run-id <test-run-id> --json`
+- `wave phantom observation <id> --json`
+- `wave phantom candidates --json`
+- `wave phantom candidates --run-id <run-id> --json`
+- `wave phantom candidates --observation-id <observation-id> --json`
+- `wave phantom candidates --candidate-type <candidate-type> --json`
+- `wave phantom candidates --test-run-id <test-run-id> --json`
+- `wave phantom candidate <id> --json`
+- `wave phantom evidences --json`
+- `wave phantom evidences --candidate-id <candidate-id> --json`
+- `wave phantom evidences --observation-id <observation-id> --json`
+- `wave phantom evidences --test-run-id <test-run-id> --json`
+- `wave phantom evidence <id> --json`
+- `wave phantom validations --json`
+- `wave phantom validations --run-id <run-id> --json`
+- `wave phantom validations --candidate-id <candidate-id> --json`
+- `wave phantom validations --status <status> --json`
+- `wave phantom validations --validation-type <validation-type> --json`
+- `wave phantom validations --test-run-id <test-run-id> --json`
+- `wave phantom validation <id> --json`
+- `wave phantom apply-operations --json`
+- `wave phantom apply-operations --run-id <run-id> --json`
+- `wave phantom apply-operations --candidate-id <candidate-id> --json`
+- `wave phantom apply-operations --status <status> --json`
+- `wave phantom apply-operations --operation-type <operation-type> --json`
+- `wave phantom apply-operations --test-run-id <test-run-id> --json`
+- `wave phantom apply-operation <id> --json`
+- `wave phantom report <run-id|latest> --json`
+
+GraphQL mapping:
+
+- `osmd status` / `osmd agent status` / `osmd wiki status` -> `agentMarkdownStatus`
+- `osmd search` -> `osMdSearch`
+- `osmd lint` -> `osMdWikiLint`
+- `osmd memory-quality` -> `osMdMemoryQuality`
+- `osmd ingest text` / `osmd ingest file` / `osmd ingest url` / `osmd ingest transcript` -> `registerRawSource`, then `ingestRawSource`
+- `osmd ingest ... --dry-run` -> `rawSourceIngestionPlan`
+- `osmd phantom run --dry-run` -> `runPhantomOsmdMaintenance(dryRun: true)`
+- `osmd phantom run` -> `runPhantomOsmdMaintenance(dryRun: false)`
+- `phantom inventory --json` -> `phantomLedgerInventory`
+- `phantom observations --json` -> `phantomObservations`
+- `phantom observations --run-id <run-id> --json` -> `phantomObservations(phantomRunId: <run-id>)`
+- `phantom observations --source-table <source-table> --json` -> `phantomObservations(sourceTable: <source-table>)`
+- `phantom observations --source-record-id <source-record-id> --json` -> `phantomObservations(sourceRecordId: <source-record-id>)`
+- `phantom observations --source-event-id <source-event-id> --json` -> `phantomObservations(sourceEventId: <source-event-id>)`
+- `phantom observations --test-run-id <test-run-id> --json` -> `phantomObservations(testRunId: <test-run-id>)`
+- `phantom observation <id> --json` -> `phantomObservation(id: <id>)`
+- `phantom candidates --json` -> `phantomCandidates`
+- `phantom candidates --run-id <run-id> --json` -> `phantomCandidates(phantomRunId: <run-id>)`
+- `phantom candidates --observation-id <observation-id> --json` -> `phantomCandidates(phantomObservationId: <observation-id>)`
+- `phantom candidates --candidate-type <candidate-type> --json` -> `phantomCandidates(candidateType: <candidate-type>)`
+- `phantom candidates --test-run-id <test-run-id> --json` -> `phantomCandidates(testRunId: <test-run-id>)`
+- `phantom candidate <id> --json` -> `phantomCandidate(id: <id>)`
+- `phantom evidences --json` -> `phantomCandidateEvidences`
+- `phantom evidences --candidate-id <candidate-id> --json` -> `phantomCandidateEvidences(phantomCandidateId: <candidate-id>)`
+- `phantom evidences --observation-id <observation-id> --json` -> `phantomCandidateEvidences(phantomObservationId: <observation-id>)`
+- `phantom evidences --test-run-id <test-run-id> --json` -> `phantomCandidateEvidences(testRunId: <test-run-id>)`
+- `phantom evidence <id> --json` -> `phantomCandidateEvidence(id: <id>)`
+- `phantom validations --json` -> `phantomValidations`
+- `phantom validations --run-id <run-id> --json` -> `phantomValidations(phantomRunId: <run-id>)`
+- `phantom validations --candidate-id <candidate-id> --json` -> `phantomValidations(phantomCandidateId: <candidate-id>)`
+- `phantom validations --status <status> --json` -> `phantomValidations(status: <status>)`
+- `phantom validations --validation-type <validation-type> --json` -> `phantomValidations(validationType: <validation-type>)`
+- `phantom validations --test-run-id <test-run-id> --json` -> `phantomValidations(testRunId: <test-run-id>)`
+- `phantom validation <id> --json` -> `phantomValidation(id: <id>)`
+- `phantom apply-operations --json` -> `phantomApplyOperations`
+- `phantom apply-operations --run-id <run-id> --json` -> `phantomApplyOperations(phantomRunId: <run-id>)`
+- `phantom apply-operations --candidate-id <candidate-id> --json` -> `phantomApplyOperations(phantomCandidateId: <candidate-id>)`
+- `phantom apply-operations --status <status> --json` -> `phantomApplyOperations(status: <status>)`
+- `phantom apply-operations --operation-type <operation-type> --json` -> `phantomApplyOperations(operationType: <operation-type>)`
+- `phantom apply-operations --test-run-id <test-run-id> --json` -> `phantomApplyOperations(testRunId: <test-run-id>)`
+- `phantom apply-operation <id> --json` -> `phantomApplyOperation(id: <id>)`
+- `phantom report <run-id> --json` -> `phantomRun`, then `phantomReports(phantomRunId: <run-id>)`
+- `phantom report latest --json` -> `phantomRuns`, then `phantomReports(phantomRunId: <latest API-listed run id>)`
+- `members meta-profile --member-id <member-id> --json` -> `memberMetaProfile(organizationId: <organization-id>, memberId: <member-id>)`
+- `skills list --json` -> `skills(organizationId: <organization-id>)`
+- `skills list --scope <scope> --query <query> --limit <limit> --json` -> `skills(organizationId: <organization-id>, scope: <scope>, query: <query>, limit: <limit>)`
+- `skills show --id <skill-id> --json` -> `skills(organizationId: <organization-id>)`, then selects the API-returned skill id locally for read-only proof.
+- `osmd read` / `osmd agent read` / `osmd wiki read` -> `agentMarkdownFile`
+- `osmd children` / `osmd agent children` -> `agentMarkdownChildren`
+- `osmd agent init` -> `initAgentMarkdown`
+- `osmd agent create` -> `createAgentMarkdownFile`
+- `osmd agent update` -> `updateAgentMarkdownFile`
+- `osmd wiki create` / `osmd wiki update` -> local `unsupported_contract`
+- `osmd wiki index-upsert` -> `upsertAgentWikiIndexEntry`
+- `osmd wiki append-log` -> `recordAgentMarkdownLog`
+
+Path and permission rules:
+
+- Canonical OSMD reads use backend `path` values from tree/status/file responses.
+- The OSMD display root is the organization name returned by `wave osmd tree`, formatted by the backend as `${OrgName}.MD`. Callers must use the returned `runtimeLabel`/`path` and must not hardcode a fixed root label.
+- UI display folders such as `Org.MD`, `Members.MD`, `Teams.MD`, `Tools.MD`, and `Agent Wiki.MD` are presentation labels, not storage paths. Callers should resolve them from `wave osmd tree` metadata and then pass backend `path` values to `osmd status`/`osmd read`.
+- `Members.MD` maps to the canonical directory branch identified by `toolKey: "directory"` and `nodeKey: "members"`; member records beneath it expose backend paths such as `directory/<member name>`.
+- `Teams.MD` maps to `toolKey: "directory"` and `nodeKey: "teams"`; team records beneath it expose backend paths such as `directory/<team name>`.
+- `Org.MD` maps to the canonical organization branch identified by `toolKey: "org"` and `nodeKey: "root"`; the root backend path is `org`.
+- `Tools.MD` is a UI grouping over the remaining canonical tool roots returned by `osmd tree` such as `projects`, `knowledge`, `issues`, and other backend `toolKey` roots. Use each returned node's `path`.
+- `Agent Wiki.MD` maps to the Agent Wiki root path `Agent Wiki`; new writes are limited to `index-upsert` and append-only `log.md`.
+- Canonical OSMD writes are blocked before mutation when status reports `source: "canonical_osmd"` or `access: "read_only"`.
+- `.agent` write commands require a canonical `parent-ref`; the CLI passes it as backend metadata and does not invent backend storage rules.
+- `.agent` files support `notes.md`, `summary.md`, and `<lowercase-kebab-slug>.md`.
+- `osmd agent init <parent-ref>` is idempotent for default `.agent` files.
+- Agent Wiki index paths may be `index.md` or `Agent Wiki/index.md`; the CLI normalizes these to `Agent Wiki/index.md`.
+- Legacy Agent Wiki content folder paths may still be used for `read`/`status` visibility when needed: `concepts/<slug>.md`, `playbooks/<slug>.md`, `decisions/<slug>.md`, `org-summaries/<slug>.md`, `sources/<slug>.md`, or the same forms prefixed with `Agent Wiki/`.
+- New writes to Agent Wiki content folders are rejected locally with `unsupported_contract`.
+- Agent Wiki log paths may be `log.md` or `Agent Wiki/log.md`; the CLI normalizes these to `Agent Wiki/log.md`.
+- Agent Wiki `index-upsert` upserts one backend-managed `Agent Wiki/index.md` entry for a `.agent` target using backend metadata and permissions.
+- `index-upsert` targets must be `.agent/notes.md`, `.agent/summary.md`, or `.agent/<lowercase-kebab-slug>.md` with `--parent-ref <canonicalPath>`.
+- Full parent paths such as `directory/Wave Tools Team/.agent/notes.md` are intentionally unsupported for `index-upsert`; pass `.agent/notes.md` and `--parent-ref "directory/Wave Tools Team"` instead.
+- `index-upsert` is not a broad write command and cannot target `Agent Wiki/index.md`, `Agent Wiki/log.md`, or Agent Wiki content folders.
+- 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`, `wikiRole`, `formatVersion`, `createdAt`, `updatedAt`, `ingestedAt`, `lastSeenAt`, `canonicalParentUpdatedAt`, `suggestedAction`, and `errorCode`.
+- Atlas owns report filename date choices and log-entry date content. The CLI does not generate, normalize, or decide report/log dates.
+- OSMD status/read/children responses pass backend timestamp metadata through as strings when provided: `createdAt`, `updatedAt`, `ingestedAt`, `lastSeenAt`, and `canonicalParentUpdatedAt`. Missing timestamp fields are emitted as `null`.
+- The CLI does not generate or normalize OSMD timestamp values. Atlas should treat timestamp strings as backend-owned metadata.
+- `osmd lint` remains backend pass-through for lint payloads and does not add OSMD file timestamp fields.
+- When Atlas needs organization timezone context for report naming, use `wave organizations show` and inspect `data.organization.organizationDetail.timezone` when the backend provides it.
+- `osmd search` scopes map to backend `source` values: `os-only` -> `canonical_osmd`, `agent-overlay-only` -> `agent_overlay`, `agent-wiki-only` -> `agent_wiki`, and `combined` -> backend merged search.
+- `osmd search` returns backend candidates with `path`, `source`, `access`, `owner`, `wikiRole`, `formatVersion`, `parentRef`, `exists`, `agentChildrenAllowed`, `title`, `label`, `snippet`, `rank`, `matchReason`, `toolKey`, `nodeKey`, and `nodeKind` where the backend provides them.
+- `osmd lint` is read-only and delegates all lint rules to backend `osMdWikiLint`; the CLI does not implement, infer, or auto-fix lint rules.
+- `osmd lint` scopes map to backend values: `combined` -> `combined`, `agent-overlay-only` -> `agent_overlay`, and `agent-wiki-only` -> `agent_wiki`.
+- `osmd lint --fix=true` is unsupported and rejected before GraphQL. Lint never calls create, update, init, append-log, or index-upsert mutations.
+- `osmd lint` defaults to readable text showing status, counts, and issue details for human review.
+- `osmd lint --json` returns the stable global JSON envelope. The backend lint payload is passed through in `data` with `status`, `summary.totalIssues`, `summary.errors`, `summary.warnings`, `summary.suggestions`, and `issues`.
+- `osmd memory-quality` is read-only and delegates Semantic Memory Quality Evaluation to backend `osMdMemoryQuality`.
+- `osmd memory-quality --json` returns the stable global JSON envelope and passes backend structured scores, weakest overlays, and issues through in `data`.
+- `osmd memory-quality --readable` renders status, evaluated/pass/warn/fail counts, weakest overlays, issue code, dimension, evidence snippet, suggested action, and `canAutoFix: false`. It does not expose fix, delete, path-target, or canonical write flags.
+- `osmd ingest` commands are Source Ingestion Phase 1 pass-throughs. The CLI registers a raw source with backend `registerRawSource`, then calls backend `ingestRawSource` with the returned `rawSourceId`.
+- `osmd ingest` requires `--slug <lowercase-kebab-slug>`, `--parent-ref <canonicalPath>`, and `--summary <summary>` so backend ingestion targets `.agent/<slug>.md` under the resolved parent node with an explicit summary.
+- Supported raw source types are `pasted_text`, `uploaded_markdown`, `uploaded_text`, `uploaded_json`, `uploaded_csv`, `meeting_transcript`, and `url`.
+- `registerRawSource` receives flat variables: `organization_id`, `source_type`, `title`, `content`, `file_name`, `url`, and `metadata`.
+- `ingestRawSource` receives flat variables: `organization_id`, `raw_source_id`, `slug`, `parent_ref`, `summary`, `overlay_updates`, and `run_lint`.
+- `rawSourceIngestionPlan` receives flat planning variables: `organization_id`, `slug`, `parent_ref`, `source_type`, `title`, `file_name`, `url`, `overlay_updates`, and `run_lint`; it is used for `--dry-run` and does not call `registerRawSource` or `ingestRawSource`.
+- `osmd ingest` JSON output is the default machine interface and includes `rawSourceId`, `sourceSummaryPath`, `createdFiles`, `updatedFiles`, `skippedUpdates`, and optional `lintResult`.
+- `osmd ingest --run-lint` is passed to backend `ingestRawSource`; the CLI does not call `osmd lint`, does not auto-fix, and does not run lint before ingestion.
+- `osmd ingest --dry-run` calls backend `rawSourceIngestionPlan` and returns the backend plan through the same output schema.
+- `osmd ingest --update-overlays` is rejected locally with `unsupported_contract`; CLI Phase 1 does not pass a blind overlay boolean.
+- `osmd ingest file` reads local file content and sends the filename as source metadata. The CLI does not mutate raw sources, upload raw-source storage objects, infer source storage paths, or implement summarization rules.
+- `osmd phantom run` is organization-scoped, manual-only, and fixed to the backend OSMD/agent semantic memory scope. The CLI does not schedule cron jobs.
+- `osmd phantom run --dry-run` calls backend `runPhantomOsmdMaintenance` with `dryRun: true` and does not write files directly.
+- `osmd phantom run` passes backend result fields through, including run id, run status, inventory count fields, optional `countSemantics`, lint summary, report path, updated files, skipped nodes, and notification metadata when provided.
+- Phantom runs use a 120 second default HTTP timeout because the backend maintenance pass can outlive the CLI's normal 10 second default. Operators can still override this with `--timeout-ms <milliseconds>` or `WAVE_TIMEOUT_MS`.
+- Top-level `phantom` commands are read-only operator/debug surfaces over the API-owned inert Phantom Evidence Ledger.
+- `phantom inventory --json` returns backend ledger counts in the standard JSON envelope.
+- `phantom observations --json` returns API-owned Phantom observations with ids, run ids, observation/source metadata, content hash, payload, schema version, test run id, idempotency key, and timestamps.
+- `phantom observations --run-id <run-id> --json`, `--source-table <source-table>`, `--source-record-id <source-record-id>`, `--source-event-id <source-event-id>`, and `--test-run-id <test-run-id>` pass API read filters directly to `phantomObservations`.
+- `phantom observation <id> --json` reads a single API-owned Phantom observation by id.
+- `phantom candidates --json` returns API-owned Phantom candidates with candidate ids, run ids, observation ids, target metadata, approval state metadata, payload, schema version, test run id, idempotency key, and timestamps.
+- `phantom candidates --run-id <run-id> --json`, `--observation-id <observation-id>`, `--candidate-type <candidate-type>`, and `--test-run-id <test-run-id>` pass API read filters directly to `phantomCandidates`.
+- `phantom candidate <id> --json` reads a single API-owned Phantom candidate by id.
+- `phantom evidences --json` returns API-owned Phantom candidate evidences with evidence ids, candidate ids, observation ids, source metadata, content hash, payload, schema version, test run id, idempotency key, and timestamps.
+- `phantom evidences --candidate-id <candidate-id> --json`, `--observation-id <observation-id>`, and `--test-run-id <test-run-id>` pass API read filters directly to `phantomCandidateEvidences`.
+- `phantom evidence <id> --json` reads a single API-owned Phantom candidate evidence by id.
+- `phantom validations --json` returns API-owned Phantom validations with validation ids, run ids, candidate ids, validation type, dry-run flag, payloads, schema version, test run id, idempotency key, and timestamps.
+- `phantom validations --run-id <run-id> --json`, `--candidate-id <candidate-id>`, `--status <status>`, `--validation-type <validation-type>`, and `--test-run-id <test-run-id>` pass API read filters directly to `phantomValidations`.
+- `phantom validation <id> --json` reads a single API-owned Phantom validation by id.
+- `phantom apply-operations --json` returns API-owned Phantom dry-run apply operation ledger records with operation ids, run ids, candidate ids, operation type, target metadata, payloads, schema version, test run id, idempotency key, and timestamps.
+- `phantom apply-operations --run-id <run-id> --json`, `--candidate-id <candidate-id>`, `--status <status>`, `--operation-type <operation-type>`, and `--test-run-id <test-run-id>` pass API read filters directly to `phantomApplyOperations`.
+- `phantom apply-operation <id> --json` reads a single API-owned Phantom apply operation ledger record by id.
+- `phantom report <run-id> --json` returns the API-read Phantom run and reports for that run id.
+- `phantom report latest --json` resolves `latest` only through API-listed `phantomRuns`; the CLI does not inspect local state or infer a latest run.
+- Top-level `phantom` commands do not run Phantom, create ledger records, ingest observations, trigger extraction, create validations, create approvals, create apply operations, approve candidates, apply candidates, write memory/profile files, schedule work, or generate prompts.
+- `members meta-profile --member-id <member-id> --json` is a read-only before/after proof surface over the API-owned `memberMetaProfile` query. It does not create, update, approve, or apply member profile changes.
+- `skills list/show --json` are read-only before/after proof surfaces over the API-owned `skills` query. They do not create, update, destroy, archive, approve, or apply Skill records.
+- 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 and does not initialize files implicitly.
+- 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. Require `data.exists === true`, `data.access === "append_only"`, and `data.canAppend === true`.
+3. `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; Agent Wiki index/log initialization is backend-owned.
+
+Atlas maintenance examples:
+
+Routine catalog maintenance should use backend-managed `index-upsert`, not manual `Agent Wiki/index.md` rewrites. Atlas should:
+
+1. Create or update a `.agent` page with an explicit parent ref.
+2. Run `wave osmd wiki index-upsert` with the relative `.agent/<file>.md` target and the backend-returned parent ref.
+3. Append a parseable `Agent Wiki/log.md` entry.
+
+Entity note maintenance:
+
+```bash
+wave osmd agent update "directory/Wave Tools Team" notes.md --content "## Working notes\n\n- New durable entity note."
+wave osmd wiki index-upsert .agent/notes.md \
+  --parent-ref "directory/Wave Tools Team" \
+  --summary "Durable working notes for the Wave Tools Team"
+wave osmd wiki append-log --content "```yaml
+event: entity_note_updated
+parentRef: directory/Wave Tools Team
+targetPath: directory/Wave Tools Team/.agent/notes.md
+summary: Added durable working notes for the Wave Tools Team.
+```"
+```
+
+Synthesized page maintenance:
+
+```bash
+wave osmd agent status "projects/Wave Tools" customer-interviews.md
+wave osmd agent create "projects/Wave Tools" customer-interviews.md --content "# Customer Interviews\n\nSynthesized source summary."
+wave osmd wiki index-upsert .agent/customer-interviews.md \
+  --parent-ref "projects/Wave Tools" \
+  --summary "Summary of customer interview source material"
+wave osmd wiki append-log --content "```yaml
+event: agent_page_updated
+parentRef: projects/Wave Tools
+targetPath: projects/Wave Tools/.agent/customer-interviews.md
+summary: Created the customer interview synthesized page.
+```"
+```
+
+Direct `Agent Wiki/index.md` create/update and content folder writes are not part of the current CLI write contract.
+
+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: Recorded Agent Wiki maintenance event.' '```' | wave osmd wiki append-log
+````
+
+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,
+    "canCreate": false,
+    "canUpdate": true,
+    "canAppend": false,
+    "wikiRole": "notes",
+    "formatVersion": "agent_markdown_v1",
+    "createdAt": "2026-05-07T18:10:11.123-07:00",
+    "updatedAt": "2026-05-07T18:20:21.456-07:00",
+    "ingestedAt": "2026-05-07T18:11:00.000-07:00",
+    "lastSeenAt": "2026-05-07T18:30:31.789-07:00",
+    "canonicalParentUpdatedAt": "2026-05-07T17:59:59.999-07:00",
+    "parentRef": "projects/Wave Tools",
+    "suggestedAction": "update",
+    "errorCode": null,
+    "content": "..."
+  },
+  "error": null,
+  "meta": { "requestId": "req_123" }
+}
+```
+
+Merged OSMD search keeps the same envelope and returns backend-ranked candidates:
+
+```json
+{
+  "ok": true,
+  "command": "osmd.search",
+  "status": 200,
+  "data": {
+    "query": "Wave Tools",
+    "scope": "combined",
+    "count": 3,
+    "candidates": [
+      {
+        "path": "directory/Wave Tools Team/.agent/notes.md",
+        "source": "agent_overlay",
+        "access": "read_write",
+        "owner": "atlas",
+        "wikiRole": "notes",
+        "formatVersion": "agent_markdown_v1",
+        "parentRef": "directory/Wave Tools Team",
+        "exists": true,
+        "agentChildrenAllowed": false,
+        "title": "notes.md",
+        "label": "notes.md",
+        "snippet": "...",
+        "rank": 1,
+        "matchReason": "content",
+        "toolKey": "agent_overlay",
+        "nodeKey": "notes",
+        "nodeKind": "agent_overlay_file"
+      }
+    ]
+  },
+  "error": null,
+  "meta": { "requestId": "req_125" }
+}
+```
+
+OSMD lint keeps the same envelope and returns the backend-owned lint result. Human readers should use `data.status` and `data.summary` for the high-level status/counts, then inspect `data.issues` for backend-provided issue details:
+
+```json
+{
+  "ok": true,
+  "command": "osmd.lint",
+  "status": 200,
+  "data": {
+    "status": "warn",
+    "summary": {
+      "totalIssues": 2,
+      "errors": 0,
+      "warnings": 1,
+      "suggestions": 1
+    },
+    "issues": [
+      {
+        "code": "missing_index_entry",
+        "severity": "warning",
+        "path": "Agent Wiki/concepts/customer-health.md",
+        "source": "agent_wiki",
+        "parentRef": null,
+        "message": "Controlled Agent Wiki page is missing from Agent Wiki/index.md.",
+        "suggestedAction": "upsert_index_entry",
+        "canAutoFix": false
+      }
+    ]
+  },
+  "error": null,
+  "meta": { "requestId": "req_126" }
+}
+```
+
+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/customer-interviews.md",
+    "source": "agent_overlay",
+    "access": "read_write",
+    "owner": "atlas",
+    "exists": false,
+    "canCreate": true,
+    "canUpdate": false,
+    "canAppend": false,
+    "wikiRole": "index",
+    "formatVersion": "agent_markdown_v1",
+    "createdAt": null,
+    "updatedAt": null,
+    "ingestedAt": null,
+    "lastSeenAt": null,
+    "canonicalParentUpdatedAt": null,
+    "parentRef": "projects/Wave Tools",
+    "suggestedAction": "create",
+    "errorCode": null
+  },
+  "error": {
+    "code": "agent_file_not_found",
+    "message": "Agent markdown file does not exist: projects/Wave Tools/.agent/customer-interviews.md",
+    "suggestedAction": "create",
+    "details": {}
+  },
+  "meta": { "requestId": "req_124" }
+}
+```
+
+## Navigation Shell
+
+Primary agent-facing discovery/navigation commands:
+
+- `wave find "<query>" [--under <path>] [--limit <n>]`
+- `wave open "<name>" [--under <path>] [--tree-view]`
+- `wave ls [query] --path <path>` or `wave ls [query] --tool-key ... --node-key ...`
+- `wave cat --path <path>` or `wave cat --tool-key ... --node-key ...`
+- `wave tree --depth <n> --path <path>` or `wave tree --depth <n> --tool-key ... --node-key ...`
+
+These wrap backend-owned markdown-tree primitives:
+
+- `find` -> `markdownTreeFind`
+- `open` -> `markdownTreeFind` + `markdownTreeNode`
+- `ls` -> `markdownTreeChildren`
+- `cat` -> `markdownTreeNode`
+- `tree` -> `markdownTreeSubtree`
+
+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`.
+Use `wave osmd search "<query>" --scope combined` when Atlas needs merged canonical OSMD, `.agent`, and Agent Wiki search. Use narrower scopes for targeted memory lookup:
+
+- `--scope os-only` searches canonical OSMD only.
+- `--scope agent-overlay-only` searches entity-specific `.agent` files.
+- `--scope agent-wiki-only` searches backend Agent Wiki files, including `index.md`, legacy indexed pages when present, and append-only `log.md`.
+- `--scope combined` searches the backend merged OSMD surface.
+
+Ambiguity contract:
+
+- no silent bad guesses
+- returns `error.code = "ambiguous_match"` with ranked candidates in `error.details.candidates`
+
+## Content Command Contract
+
+The `content` command uses exact GraphQL operation names:
+
+- `CreateContent`
+- `UpdateContent`
+- `DestroyContent`
+- `ContentShow`
+- `ContentsIndex`
+
+Placement rules enforced by command shape:
+
+- `content create-member`
+  - `contentable_type: "Member"`
+  - `contentable_id: TARGET_MEMBER_ID`
+  - `member_id: TARGET_MEMBER_ID`
+  - `focus_member_id: null`
+  - `focus_team_id: null`
+- `content create-manager`
+  - `contentable_type: "Member"`
+  - `contentable_id: ACTOR_MEMBER_ID`
+  - `member_id: ACTOR_MEMBER_ID`
+  - `focus_member_id: TARGET_MEMBER_ID`
+- `content create-team`
+  - `contentable_type: "Team"`
+  - `contentable_id: TEAM_ID`
+  - `member_id: ACTOR_MEMBER_ID`
+  - `focus_team_id: TEAM_ID`
+- `content create-project`
+  - `contentable_type: "Project"`
+  - `contentable_id: PROJECT_ID`
+  - `member_id: ACTOR_MEMBER_ID`
+- `content create-customer`
+  - `contentable_type: "Customer"`
+  - `contentable_id: CUSTOMER_ID`
+  - `member_id: ACTOR_MEMBER_ID`
+- `content create-contact`
+  - `contentable_type: "Contact"`
+  - `contentable_id: CONTACT_ID`
+  - `member_id: ACTOR_MEMBER_ID`
+
+## JSON Envelope
+
+Success:
+
+```json
+{
+  "ok": true,
+  "command": "tasks.list",
+  "status": 200,
+  "data": {},
+  "error": null,
+  "meta": {
+    "requestId": "req_123"
+  }
+}
+```
+
+Failure:
+
+```json
+{
+  "ok": false,
+  "command": "tasks.create",
+  "status": 403,
+  "data": null,
+  "error": {
+    "code": "forbidden",
+    "message": "Forbidden",
+    "details": {}
+  },
+  "meta": {
+    "requestId": "req_124"
+  }
+}
+```
+
+## Exit Codes
+
+- `0`: success
+- `1`: generic uncaught error
+- `2`: invalid args/config
+- `3`: missing or invalid auth
+- `4`: forbidden
+- `5`: not found
+- `6`: validation failure
+- `7`: network or upstream error