docs: document Find Moments and moments collections (spec v0.7.23); v0.7.30

[kdr]

Why

#160 shipped the Find Moments API and the moments collection type without docs — reopening the gap #159 had just closed. The embedded docs ship inside the npm package (files: ["dist", "docs"]), so a consumer on 0.7.29 today has the client but no reference for it.

What

New docs/find-moments.md, covering both entry points:

• One video, one criterion — client.findMoments: create / list / get / delete, plus the waitForReady poller (attempt cap 60 rather than the SDK-wide 36, because discovery reads the whole video).
• A whole collection — collection_type: 'moments', whose criteria run over every current and future member.

The three semantics most likely to bite are called out explicitly, because each one is easy to get backwards:

1. limit / min_score / sort on getFindMoments are read-time shaping, not selection. Every accepted moment is persisted and total_moments always reports the full accepted count — narrowing a read never destroys results.
2. criterion_score / rank_score sorting on collection moments requires a single-criterion filter (400 otherwise). Scores are only comparable within one rubric.
3. Detaching a criterion, or removing a file, drops moments from collection enumeration — but the underlying runs persist as job history. Membership governs enumeration, not the existence of results.

Also documented: criterion snapshot + criterion_hash, the attach-is-free / per-file-runs-charge billing split with its backfill_status + files_* counters, the delete refund rule (in-flight refunded, completed not), findings as the non-temporal counterpart (absence / observation), and scope: 'moment' search carrying criterion_name.

Cross-linked from overview (namespace table), collections (type table), and search (scope table).

Version bump → 0.7.30

Docs only reach consumers via a publish, so this carries a patch bump. Tag v0.7.30 after merge to cut the release.

Verification

Every field, method, and enum checked against the built SDK, not prose:

client.findMoments methods: createFindMoments, listFindMoments, getFindMoments, deleteFindMoments, waitForReady
collections moment methods: listCollectionMoments, listCollectionMomentFindings,
                            createCollectionMomentCriterion, deleteCollectionMomentCriterion
NewFindMoments:             url, describe_job_id, criterion, signals_required, boundary_policy,
                            speaker_filter, min_duration_seconds, max_duration_seconds, cache_policy
MomentCriterion:            name, instructions, moment_schema, finding_schema, anchors, scoring
Moment:                     moment_id, start_time, end_time, anchors, title, reason, speakers,
                            criterion_score, rank_score, properties, evidence
MomentCriterionAttachment:  attachment_id, criterion_name, criterion_hash, criterion, options,
                            backfill_status, files_total, files_completed, files_failed, created_at

Defaults were read out of the v0.7.23 OpenAPI spec rather than assumed — I'd initially hedged boundary_policy and omitted a default entirely; the spec declares boundary_policy: sentence, cache_policy: reuse, and signals_required: ['speech'], and the doc now states all three.

npm test 107/107, npm run build clean, and every internal doc link resolves.

[cursor]

PR Summary

Low Risk
Documentation and version bump only; no runtime, API, or security code changes.

Overview
Documents the already-shipped Find Moments API and moments collection type so the npm package (docs/ is published) matches the client.

New docs/find-moments.md covers one-video runs (client.findMoments) and standing collection criteria, including criterion hashing, read-time shaping vs persistence, billing/refund rules, findings, scope: 'moment' search, and webhooks. Overview, collections, and search tables are cross-linked.

Package version is 0.7.29 → 0.7.30 so consumers get the docs on publish.

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