Publish TypeScript SDK documentation

[bigboateng]

Summary

• generate one TypeDoc site for both public TypeScript Flow packages, including five Product Delivery guides and an API reflection model
• document public authoring, authority, delegation, target, entry, and diagnostics semantics in the TypeScript source
• validate documentation in the required Flow SDK job and deploy main through an independent GitHub Pages workflow
• enforce direct public-export, parsed-trigger, main-ref, and deployment-time documentation contracts
• structurally validate executable workflow jobs, permissions, conditions, runs, and action uses
• keep explain immutability snapshots scoped to repository files and stable Git semantics, including symbolic HEAD and index, instead of transient Git internals

Verification

• npm run docs:check
• python3 -m unittest discover -s .github/tests -p 'test_*.py' (51 tests; one expected failure)
• python3 .github/scripts/run_go_tests.py (369 tests)
• five focused explain and snapshot-boundary tests repeated 25 times on the current tree
• GOWORK=off go vet ./... and GOWORK=off go build ./...
• release-note validation and preflight
• an injected broken guide link made docs:check exit 3
• desktop render: /tmp/boatstack-typescript-docs-home-current.png
• 390 x 844 API render: /tmp/boatstack-typescript-docs-mobile-current.png
• both rendered surfaces had zero browser console warnings or errors

Boundary conformance

Boundary: documentation source to required CI, Pages artifact, and deployment request.

Control law: a public SDK change must pass TypeScript and documentation validation; documentation publication cannot invoke or mutate the runtime release workflow.

Evidence: repository-contract tests bind the required CI command, both package inputs, main-only Pages trigger, official Pages action identities, minimum deployment permissions, and release independence. Rejection leaves runtime release state unchanged.

Residual risk: GitHub Pages is not enabled for this repository yet. After merge, a maintainer must select GitHub Actions as the Pages publishing source before the first deployment can complete.

Self-documenting API findings

• the predicate representation supports any and not, but no public ergonomic helpers expose them
• facet and evidence accept less descriptive metadata than their public definition types
• callers must pass the same lifecycle to trustedOperators and trustedTransitions; that pairing is currently implicit
• entry diagnostics use an inline public shape rather than a named interface

Release note: release-notes/2026-08-15-typescript-sdk-documentation.md

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[github-actions]

Codex automated review

Verdict: patch is incorrect
Confidence: 0.96

The documentation implementation is otherwise consistent with the unchanged SDK behavior, but both newly added contract verifiers accept concrete invalid inputs. Model-level verification is not recommended because this diff does not change runtime control semantics.

[github-actions]

Codex automated review

Verdict: patch is incorrect
Confidence: 0.97

The patch introduces two publication-admission bypasses and weakens both new and existing regression oracles. Runtime control semantics are otherwise unchanged, so model-level verification is not recommended before merge.

[github-actions]

Codex automated review

Verdict: patch is incorrect
Confidence: 0.94

The documentation build itself is consistent, but two newly changed regression oracles are unsound: one misses durable Git mutations and the other treats comments as active workflow configuration. Model-level verification is not recommended before merge; targeted negative tests are sufficient.

[github-actions]

Codex automated review

Verdict: patch is incorrect
Confidence: 0.98

The documentation changes appear consistent, but the modified regression oracle no longer enforces its stated no-mutation contract. Model-level verification is not recommended because executable control behavior was not changed.