Auto-generate Stellar contract reference from source

[truthixify]

Labels: Stellar Wave, stellar, tooling, docs, drips, help-wanted
Tier: L (1–2 weeks)
Type: tooling

Context

docs/contracts/stellar.mdx is hand-maintained and drifts (see #02). The contracts source has all the type info we need. We should be generating the reference page automatically, the way Solana's Anchor IDL is consumed.

Scope

Build a script scripts/generate-stellar-reference.ts that:

1. Reads either:
   • The generated TypeScript bindings (from contracts/08), OR
   • The Soroban contract WASM directly via stellar contract inspect
2. For each contract, emits an MDX section with:
   • Title (contract name + testnet/mainnet addresses)
   • Function table: name, params (with types), return type, "requires auth" flag
   • Event signatures
   • Storage keys (where relevant)
3. Writes the combined output to docs/contracts/stellar.mdx between marker comments (<!-- AUTO-GEN:STELLAR:START --> ... <!-- AUTO-GEN:STELLAR:END -->), preserving any hand-written prose around the markers.
4. Runs in CI on every contracts-or-docs PR; fails if the generated section is out of date.

Sketch

pnpm docs:generate:stellar
# generates the section in-place

git diff --exit-code docs/contracts/stellar.mdx
# CI fails if there's drift

Acceptance criteria

• Script runs locally against the current testnet deployments.
• CI job catches drift.
• At least one hand-written paragraph survives a regeneration cycle (proves the markers work).
• Documented in docs/CONTRIBUTING.md: "when you change a Stellar contract, run this script before opening the PR."

Why this matters

This is the only way to keep the docs accurate forever, not just this week. Once the system exists, drift becomes structurally impossible.

Dependencies

Easier if contracts/08 (TypeScript bindings) lands first, but can be done with stellar contract inspect parsing directly. Argue the choice in the PR.