Keeping these docs in sync

How the Phone SDK docs stay current with the code — an automated drift detector that compares the live SDK surface on the helix3 branch against the documented snapshot and flags anything new, changed, or removed.

The Phone SDK reference is meant to be comprehensive, which only works if it can't silently fall behind the code. This repo ships a small pipeline that compares the live SDK surface against a committed snapshot of what the docs cover, and flags drift automatically.

How it works

Snapshot. content/docs/phone/_meta/sdk-surface.json records every namespace.method the docs account for. It's generated from the real lib/phone/sdk.ts:

node scripts/extract-phone-sdk-surface.mjs <path-to>/lib/phone/sdk.ts --json \
  > content/docs/phone/_meta/sdk-surface.json

The extractor reads the stable bridge method strings (bridgeRequest("media.pickFromAlbum", …)) plus a small allow-list of non-bridge methods — so any method an app can actually call is captured.

Detect. scripts/check-phone-sdk-sync.mjs extracts the live surface and diffs it against the snapshot, reporting three buckets:

➕ In the SDK, missing from docs → document it (and move it off Proposed).
➖ In docs, gone from the SDK → prune or mark removed.
🆕 New namespaces → likely a whole new doc section.

It exits non-zero on drift, so CI can act on it.

PHONE_SDK_PATH=<path-to>/lib/phone/sdk.ts node scripts/check-phone-sdk-sync.mjs
# ✅ In sync — 74 methods across 18 namespaces.

Act. The phone-sdk-sync workflow runs the checker when the monorepo signals a change, on a weekly safety-net schedule, and on demand. On drift it opens (or updates) a phone-sdk-drift issue listing exactly what changed.

Wiring the trigger on the `helix3` branch

The docs repo can't see the private monorepo, so the monorepo pushes a signal when the SDK changes. Add this workflow to the Helix monorepo on the helix3 branch — it fires only when lib/phone/sdk.ts (or the phone types) change, and sends the SDK file inline so no cross-repo token is needed:

.github/workflows/notify-docs-phone-sdk.yml (in the monorepo, on helix3)

name: Notify docs of Phone SDK change
on:
  push:
    branches: [helix3]
    paths:
      - "lib/phone/sdk.ts"
      - "lib/phone/types.ts"
jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Dispatch to helix3-docs
        env:
          GH_TOKEN: ${{ secrets.DOCS_DISPATCH_TOKEN }} # PAT with repo scope on helix3-docs
        run: |
          SDK_B64=$(base64 -w0 lib/phone/sdk.ts)
          gh api repos/hypersonic-laboratories/helix3-docs/dispatches \
            -f event_type=phone-sdk-updated \
            -F client_payload[sdkBase64]="$SDK_B64"

That's the whole loop: SDK changes on helix3 → docs repo checks drift → drift opens an issue → the reference and Proposed page are reconciled → snapshot regenerated.

Scheduled fallback

If you'd rather not add the monorepo trigger yet, set a PHONE_SDK_URL repo secret (a raw URL to lib/phone/sdk.ts on helix3, with a token if private) and the weekly scheduled run will catch drift on its own.

Scope & limits

This pipeline tracks the shape of the SDK (namespaces and methods) — the thing most likely to drift and the thing the reference must mirror. It intentionally doesn't diff parameter types or prose; those are reconciled by a human (or an agent) when an issue is opened. It pairs with the main SDK's auto-generated reference pipeline — same philosophy, applied to the phone.

Keeping these docs in sync

How it works

Wiring the trigger on the helix3 branch

Scope & limits

On this page

Wiring the trigger on the `helix3` branch