docs(readme): restore the #49 enrichment on top of main's grounded facts

[yakimoto]

User description

User description

Restores this branch's README enrichment on top of main's grounded facts — and drops the parts of it that were no longer true.

This PR had been CONFLICTING since #50 landed. Both branches regenerated the same two files from d807aac, so every line conflicted. Resolved by regeneration, not by hand-merge — a hand-resolved generated file is a file no generator would ever produce.

The conflict was hiding a grounding regression

Reading the two sides rather than just the conflict markers: main is not merely newer here, it is more honest. PR #50 (the currency rewrite) replaced a uniform lib status with measured ones. This branch predates that and would have reverted it.

	this branch (63c67fc)	main (e3864a7)
capability statuses	33 × lib	6 lib · 10 planned · 2 ga
purpose	"34 API modules"	"42 API module subpaths … most are SDK-side TypeScript surface only"

So merging the old side in any form would have republished, on a public repo, runnable code examples for capabilities with no fleet backend.

What was dropped, and why

Seven product examples, each for a capability main marks planned or does not declare at all:

Chapters · Phone · Podcast · Collab · Analytics (Pulse) · VOD (Vault) · Studio AI

These rendered as working await wave.podcast… / await wave.phone… snippets. A reader would have pasted them and got nothing. planned means the client surface exists and the backend does not.

What was kept — and verified before keeping it

Six product examples, for the capabilities main marks lib: Streams (Pipeline), Clips, Captions, Voice, Transcription, Editor. Every method they call was checked to exist in src/ on main before the example was carried over:

waitForLive 3 · waitForReady 11 · waitForSynthesis 1 · waitForRender 1 · listVoices 1
createProject 2 · addTrack 2 · addElement 2 · getText 2 · synthesize 7 · translate 6

Twelve generic sections — Configuration, individual API imports, error handling, events, four troubleshooting entries, requirements, related packages. These assert no capability, so there is nothing to be stale about. Every npm link in Related packages was resolved (@wave-av/adk, mcp-server, cli, create-app, workflow-sdk all 200; wave-av/api-spec is public).

Three defects fixed on the way through

1. The API tables were mislabeled and incomplete. They were titled "All 34 APIs", listed 33 rows, and omitted 5 accessors — client, drm, notifications, perception, realtime. Measured against src/index.ts on main: there are 38 public readonly accessors (37 product modules + client) and 43 export subpaths.

Retitled without the wrong count, given a Status column populated from the SSOT, and the four missing product modules added as an API modules — Platform table with descriptions quoted from each module's own header comment. client is the transport, not a product API, so it stays out.

lib 6 · planned 10 · sdk-surface 21   = 37 product modules

A legend section defines each label, so sdk-surface cannot be misread as shipping.

2. wave.voice was described as "Text-to-speech, voice cloning" while main's own capability entry says voice-clone methods "exist as SDK client surface but are not backed by the wave-voice product yet." The table now says so.

3. Requirements claimed "TypeScript 5.0+ (recommended 5.5+ for best subpath support)" with nothing behind either number. Replaced with what is checkable: engines.node is >=18.0.0; TS 4.7+ is what moduleResolution: node16 actually needs; this package builds on TypeScript 5.9.

Receipts

main's grounded facts are preserved verbatim — not merged, not reconciled:

keys where candidate differs from main: NONE
keys added: ['sections']

The README is rendered by the engine, never hand-edited — RepoFacts.parse → generateReadme from wave-context:

SCHEMA: valid (24 sections)
NEEDLES: 29/29 SSOT needles present in committed README
BYTE-IDENTICAL: committed README === engine render of committed SSOT (no hand edit)

The byte-identity check is the one that matters: it proves nobody touched the generated file after generation, which is exactly the failure mode a conflicted generated file invites.

Two engine findings this surfaced — neither is a blocker for this PR

generate --check cannot verify a feature branch. discoverFactsSources resolves each repo's .wave/repo.json from its default ref via git show — correct branch-truth discipline for a fleet scan, but it means an uncommitted or non-default-branch candidate is invisible to the CLI, which silently renders main's facts instead. I hit this first as a mystifying 101-line render. Verified here with a small branch-aware harness instead. Worth a --ref flag.

www.npmjs.com is not in the content-policy publish allowlist. The engine's own links.npm field emits an npmjs.com URL and its stage-⑥ scanner then flags it, so main already trips this 3× today. This PR's Related packages table takes it from 3 → 15 findings — all one pre-existing class, every URL verified live. Filed separately against wave-context; not caused by this change.

Verification caveat

CI has run on none of this. Actions are refusing every job org-wide on an account-level billing lock (plan=free, locked=yes, re-confirmed today), so every number above is local measurement. Do not read a green-looking mergeStateStatus as CI approval — during this outage GitHub creates no Actions check-run at all, so there is no red to see.

This is public-facing copy on a public repo, so it wants a human read before it merges regardless of what CI eventually says.

---

Note

Low Risk
Documentation and SSOT metadata only; no runtime SDK or API behavior changes. Main risk is inaccurate public copy if statuses or examples drift from the codebase.

Overview
Adds a new sections array to .wave/repo.json (with JSON pretty-printing of existing metadata) so the README generator can emit a much larger public doc surface while keeping main’s grounded capability facts unchanged.

The generated README.md now includes grouped API module tables (Core, Enterprise, Content & commerce, Specialized, Platform) with Access, Status (lib / planned / sdk-surface), and descriptions—including previously missing platform modules (drm, notifications, perception, realtime) and a legend for what each status means. wave.voice is described as TTS via synthesize() with clone APIs called out as SDK-only.

Six product code examples are limited to capabilities marked lib (pipeline, clips, captions, voice, transcribe, editor); examples for planned or unproven modules are omitted so readers are not shown runnable snippets against non-shipping backends. Additional generic sections cover configuration, subpath imports, errors, events, troubleshooting, requirements (Node 18+, TS 4.7+ / build on 5.9), and related npm packages.

^{Reviewed by Cursor Bugbot for commit 4efba2e. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

CodeAnt-AI Description

Expand the SDK README with grounded capability details and practical usage examples

What Changed

• Documents API modules across streaming, enterprise, content, specialized, and platform areas, including whether each is live, planned, or only an SDK surface
• Adds working examples for streams, clips, captions, text-to-speech, transcription, and video editing
• Adds configuration, individual imports, error handling, event monitoring, troubleshooting, requirements, and related package guidance
• Updates the source facts so generated documentation preserves accurate backend availability and package claims

Impact

✅ Clearer distinction between live and unavailable capabilities
✅ Faster SDK onboarding with ready-to-use examples
✅ Fewer failed production calls to planned modules

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

Summary by Sourcery

Restore the README enrichment on top of main's grounded capability facts while ensuring public documentation reflects verified SDK and backend support.

New Features:

• Expand the generated README with grounded API module reference tables, status definitions, verified product examples, usage guidance, troubleshooting, requirements, and related packages.

Bug Fixes:

• Correct inaccurate API counts and descriptions, document previously omitted platform modules, and remove examples for capabilities without confirmed production backends.
• Align README requirements and voice capability wording with the SDK's actual supported behavior.

Enhancements:

• Preserve main's grounded capability metadata while adding README sections through the repository facts and generation pipeline.

Documentation:

• Restore and substantially enrich the public README with status-aware API documentation and examples limited to verified library-backed capabilities.

Chores:

• Update repository metadata to provide the source content for the expanded generated README.

---

PR Type

Documentation

---

Description

• Reconciles SDK docs with grounded SSOT, updating capability statuses

• Adds gateway capabilities (wave-dispatch, gateway-agent-payments) with generic client access

• Fixes voice module claims to reflect TTS-only implementation

• Regenerates README with structured API tables and product examples

---

Diagram Walkthrough

flowchart LR
  A[".wave/repo.json"] --> B["Capability status updates"]
  A --> C["New GA gateway capabilities"]
  A --> D["Module count fix"]
  E["README.md"] --> F["Structured API tables"]
  E --> G["Product example code snippets"]

Loading

File Walkthrough

Relevant files

Documentation

repo.json SDK capability status reconciliation and documentation updates .wave/repo.json Updates 14 capabilities from 'lib' to 'planned' status Adds 2 new 'ga' status capabilities (wave-dispatch, gateway-agent-payments) Fixes module count claim to 42 subpath exports Adds grounding claims for generic client access and voice TTS +631/-32 README.md Regenerated README with structured documentation and examples README.md Adds 5 structured API module tables with status columns Includes 6 product example code snippets (pipeline, clips, captions, voice, transcription, editor) Adds troubleshooting sections for type resolution and ESM/CJS Updates configuration and error handling examples Includes related packages and requirements sections +280/-0

---

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_012353ed-1884-4749-92cb-bcf17471bc44)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6f845e1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Warning

Review limit reached

Next included review available in 23 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available. Your 97 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: 28d7ae49-851f-4bf2-a451-d2c01aa3fab8

📥 Commits

Reviewing files that changed from the base of the PR and between 0e59286 and 4efba2e.

📒 Files selected for processing (2)

• .wave/repo.json
• README.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ce/facts-enrich

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch ce/facts-enrich

---

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_bf3e77d0-7515-40ba-b7e5-c59fcab5cc26)

[yakimoto]

Follow-up note, recorded so the dropped content is recoverable rather than lost.

Seven product examples were dropped from this PR because their capability is planned (no fleet backend) or undeclared in the SSOT:

Chapters · Phone · Podcast · Collab · Analytics (Pulse) · VOD (Vault) · Studio AI

They are not deleted — they remain at 63c67fc, this branch's pre-merge commit, and can be lifted back individually:

git show 63c67fc:.wave/repo.json | python3 -c "import sys,json;print(json.dumps(json.load(sys.stdin)['sections'],indent=2))"

The condition for restoring any one of them is the same condition that made it wrong to ship now: its capability moving from planned to lib/ga in .wave/repo.json. When a backend lands, restore that example in the same PR that flips the status — the two facts should never disagree, which is the whole point of the currency rewrite in #50.

Worth noting the engine cannot yet catch this class on its own: nothing today cross-checks a narrative sections entry against the status of the capability it demonstrates. A section titled "Product example — Podcast" showing working code while podcast is planned is exactly the drift the SSOT exists to prevent, and it passes every current check. That is a real gap in E-WATCH — filed as an ordering note on wave-av/wave-context#61 rather than blocking this PR.

[codeant-ai]

🤖 CodeAnt AI — Review Status

Status	Commit	Started (UTC)	Finished (UTC)
✅ Reviewed your PR	4efba2e	Sep 06, 2026 · 20:06	20:08

[codeant-ai]

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_8a86abe1-e3ca-474d-9b36-423f750caaaf)

[codeant-ai]

CodeAnt Nitpicks

5 code suggestions

1. The new ga capabilities have no corresponding sections, so section-based generated documentation hides two shipped gateway capabilities.

Incomplete implementation · .wave/repo.json:106-114

---

2. The claim records version 2.1.0-next.0, but package.json and the current changelog identify 2.1.3, making generated release metadata incorrect.

Api mismatch · .wave/repo.json:128-133

---

3. The claim says there are 42 importable module subpaths, while package.json declares 45, so consumers and validation tools receive an incorrect SDK surface count.

Api mismatch · .wave/repo.json:137-142

---

4. The module tables omit exported APIs such as mail, meter, pricing, inference, and sandbox, so this section is an incomplete SDK inventory.

Incomplete implementation · README.md:40-45

---

5. The status definition explains lib, planned, and sdk-surface but not the newly added ga status, leaving shipped capabilities undefined to readers.

Api mismatch · README.md:104

[macroscopeapp]

Approvability

Verdict: Would Approve

Macroscope's review found this PR approvable — This PR only adds README content and corresponding documentation metadata, without changing SDK source, package exports, CI, or production behavior. Its blast radius is limited to published documentation and documentation/discovery rendering.

Not approved because:

• Credit balance exhausted. Approvability relies on correctness review in order to determine eligibility

^{Review your spending limits in Billing settings. You can add or adjust custom eligibility rules. Learn more.}