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

[yakimoto]

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.

[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

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 4 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3d63dd79-bb94-4a8a-a750-397071ce0930

📥 Commits

Reviewing files that changed from the base of the PR and between e3864a7 and 6f845e1.

📒 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.