docs: clarify schema helper typing follow-ups

[bokelley]

Summary

• clarify the schema helper changeset and public JSDoc for exact known-key schema maps plus nullable dynamic lookups
• point future TS7056 fixes at the generator allowlist instead of hand-authored schema declarations
• drop a redundant update_rights type intersection and strengthen ProductSchema helper-return type assertions
• make schemas:ensure recognize prerelease schema cache directories like 3.1.0-beta.3 so local builds do not refetch unnecessarily

Validation

• npm run typecheck
• npm run build:lib
• npm run check:adopter-types

[aao-ipr-bot]

LGTM. Follow-ups noted below. Tight follow-up to #1981 — the prose addition pulls its weight, the redundant intersection drop is type-safe via the mapped portion, and the type-test grows the regression surface that #1981 was about.

Things I checked

• update_rights removal is safe. KnownToolRequestSchemas['update_rights'] at src/lib/utils/tool-request-schemas.ts:101 is typeof schemas.UpdateRightsRequestSchema (no withOptionalAccount wrapper), so ShapeOf<…> resolves to exactly the type the explicit intersection used to assert. creative_approval correctly stays — it's not in KnownToolRequestSchemas.
• Runtime literal at src/lib/schemas/index.ts:95 still spreads update_rights: schemas.UpdateRightsRequestSchema.shape. Type-correct (mapped portion of ToolInputShapes covers it) and the runtime key stays present.
• scripts/schemas-ensure.ts:33 regex now accepts 3.1.0-beta.3 directories. Matches the current schema cache pin without further script changes.
• Type-test additions at src/type-tests/zod-object-intersections.type-test.ts:29,33,38 exercise .shape.<key> after .pick() / .omit() / .extend() — the exact regression path #1981 fixed.
• Changeset amended (not replaced); Check for changeset CI job is green.

Follow-ups (non-blocking — file as issues)

• scripts/schemas-ensure.ts:33 — prerelease class [0-9A-Za-z.-]+ is a permissive superset of semver §9 (accepts 3.1.0-.. or trailing dots). Fine today since the only writer is sync-schemas echoing the upstream pin, but the strict form [0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)* matches the spec, and neither form accepts build metadata (+build.1). The comment promises pin updates land here without script changes — a future +-suffixed pin would silently miss the probe.

Minor nits (non-blocking)

1. Runtime spread parity. src/lib/schemas/index.ts:95 keeps update_rights: schemas.UpdateRightsRequestSchema.shape after the type-level intersection was dropped. A one-line comment noting "kept for parity with the freeze-time entries; mapped type covers the static type" would prevent a future cleanup from deleting line 95 and silently dropping the key at runtime.

Interesting choice of docs: for a commit that drops a type intersection and widens a regex — the changeset amendment is the right shape, the conventional-commit prefix is a touch generous.

Approving.