@ted-galago/wave-cli 0.1.5 → 0.1.7

package/README.md

@@ -35,6 +35,27 @@ printf '%s' '{"token":"token-value","baseUrl":"https://api.example.com","organiz
   | 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):
@@ -82,8 +103,8 @@ wave foundation annual-objectives create --data-json '{"annual_objective":{"stra
 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"}'
-wave knowledge create --data-json '{"title":"Runbook","content":"..."}'
+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 notes create-member --target-member-id 67 --name "1:1 Note" --body "Strong progress"
 wave notes create-manager --actor-member-id 67 --target-member-id 68 --name "Manager Note" --body "Coaching plan"
 wave notes create-team --actor-member-id 67 --team-id 9 --name "Team Note" --body "Team context"
@@ -94,6 +115,15 @@ wave notes list --contentable-type Member --contentable-id 67 --member-id 67 --p
 wave notes show --id 1001
 wave notes update --id 1001 --name "Updated Note" --body "Updated body" --status published
 wave notes 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 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
@@ -116,6 +146,7 @@ These child resources enforce parent IDs at CLI validation time:
 - `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`
@@ -126,6 +157,139 @@ These child resources enforce parent IDs at CLI validation time:
 
 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.
+
+`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`
+
+## 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.
+
+Ambiguity contract:
+
+- no silent bad guesses
+- returns `error.code = "ambiguous_match"` with ranked candidates in `error.details.candidates`
+
 ## Notes Contract
 
 The `notes` command uses exact GraphQL operation names: