[codex] ship a production SDK, confirmation-safe runtime, and maintainable docs

[bayyubenjamin]

Scope

This follow-up turns StacksOne into a reusable protocol integration package while preserving the existing routes, screens, configured contract identifiers, transaction function names, and core user flows.

Production SDK

• implement StacksOneClient with injectable network, read-only caller, fetch implementation, and decoders
• add profile, leaderboard, token balance, mission status, badge ownership, badge eligibility, wallet connection, and generic read APIs
• add canonical contract, mission, and badge registries
• expose stable package entrypoints and npm subpath exports
• add deterministic public API tests with injected mocks

Runtime integrity

• make the frontend consume the same registry exposed to package users
• safely restore pending wallet sessions
• separate wallet request, transaction submission, and confirmed on-chain state
• keep mission, badge, and ChainTap writes pending until reads confirm state
• make Supabase optional
• remove fabricated profile badge fallback data
• display only holdings from the configured badge contract
• handle partial profile API failures without discarding available state

Contract engineering

• register tested contracts in Clarinet.toml
• add the external SIP-010 trait requirement used by token-one
• migrate reputation tests to the current Clarinet SDK/Vitest environment
• isolate contract tests from root frontend PostCSS configuration
• retain contract diagnostics as CI artifacts

Package and release quality

• align package specifications with the committed lockfile
• add export maps, Node engine requirements, test/check scripts, and package dry-run verification
• limit npm publication contents to the public SDK surface and project metadata

Documentation overhaul

• replace the repetitive 1,000-line README with a focused project landing page
• preserve the original product flow while making transaction confirmation explicit
• add CI, npm, network, and license badges
• document repository structure, quick start, quality commands, SDK usage, configured contracts, principles, and roadmap
• add .env.example for optional Supabase configuration
• add focused SDK quick-start and API-reference documents
• add a development workflow, current system architecture, documentation index, synchronized contract registry, and updated security policy
• remove the temporary documentation draft

Compatibility

• no route was removed or renamed
• no configured deployed contract identifier was changed
• existing transaction function names and arguments remain unchanged
• UI structure and product capabilities remain intact

Validation

GitHub Actions run 5488 completed successfully:

• locked root dependency installation
• SDK core and client behavior tests
• Vite production build
• npm package dry-run and published-file verification
• locked smart-contract dependency installation
• Clarinet/Vitest contract suites

Review note

The current v10 mission write interface remains unchanged for compatibility. Moving reward resolution fully into contract-controlled state requires a separately reviewed and deployed contract version.