@ted-galago/wave-cli 0.1.4 → 0.1.6

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,9 +103,36 @@ 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"
+wave notes create-project --actor-member-id 67 --project-id 80 --name "Project Note" --body "Project context"
+wave notes create-customer --actor-member-id 67 --customer-id 30 --name "Customer Note" --body "Customer context"
+wave notes create-contact --actor-member-id 67 --contact-id 31 --name "Contact Note" --body "Contact context"
+wave notes list --contentable-type Member --contentable-id 67 --member-id 67 --page 1 --per 20
+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
+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`.
@@ -98,10 +146,186 @@ 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`
+- `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.
+
+`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`.
+
+`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`.
+- 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.
+
+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:
+
+- `CreateContent`
+- `UpdateContent`
+- `DestroyContent`
+- `ContentShow`
+- `ContentsIndex`
+
+Placement rules enforced by command shape:
+
+- `notes create-member`
+  - `contentable_type: "Member"`
+  - `contentable_id: TARGET_MEMBER_ID`
+  - `member_id: TARGET_MEMBER_ID`
+  - `focus_member_id: null`
+  - `focus_team_id: null`
+- `notes create-manager`
+  - `contentable_type: "Member"`
+  - `contentable_id: ACTOR_MEMBER_ID`
+  - `member_id: ACTOR_MEMBER_ID`
+  - `focus_member_id: TARGET_MEMBER_ID`
+- `notes create-team`
+  - `contentable_type: "Team"`
+  - `contentable_id: TEAM_ID`
+  - `member_id: ACTOR_MEMBER_ID`
+  - `focus_team_id: TEAM_ID`
+- `notes create-project`
+  - `contentable_type: "Project"`
+  - `contentable_id: PROJECT_ID`
+  - `member_id: ACTOR_MEMBER_ID`
+- `notes create-customer`
+  - `contentable_type: "Customer"`
+  - `contentable_id: CUSTOMER_ID`
+  - `member_id: ACTOR_MEMBER_ID`
+- `notes create-contact`
+  - `contentable_type: "Contact"`
+  - `contentable_id: CONTACT_ID`
+  - `member_id: ACTOR_MEMBER_ID`
+
 ## JSON Envelope
 
 Success: