docs: add full local integration guide, checks, and handoff (#186)

[0xsteins]

Closes #186

Summary

Adds a single documented path for a new contributor to bring up contracts → indexer → web locally, plus automated checks (CI +
local) that catch schema, mapping, and manifest-sync regressions before review.

What's included

1. docs/local-full-stack.md — top-level integration guide

• Prerequisites: Bun, Docker, Stellar CLI, Rust/Soroban target, local/testnet keys.
• Step-by-step: build contracts → deploy/bootstrap → sync manifests → start indexer services → run local smoke → start web app →
  verify GraphQL → verify UI.
• Expected URLs/ports table for web, SubQuery GraphQL, Postgres, Horizon/RPC, Docker services.
• local vs testnet vs (future) mainnet separation.
• Troubleshooting:
  • Missing .deployed/<network>.env
  • Wrong network passphrase
  • Stale market token IDs
  • SubQuery DB not ready
  • Indexer behind latest ledger
  • Missing local token balances / approvals
  • Web "no data" with healthy GraphQL
• Definition-of-done checklist for the complete local integration.

2. Offline fixture deployment files

• apps/s03-indexer/tests/fixtures/contracts-repo/ mirrors the real contracts-repo layout (.deployed/*.env,
  .stellar/contract-ids/local.json) so manifest sync and validation can run without a live Stellar deploy.

3. Local check scripts

• scripts/check-integration.sh — runs indexer codegen / build / mapping unit tests, manifest sync against fixtures, manifest
  validation, web typecheck + build.
• scripts/validate-manifest.sh — checks generated manifests contain every required network field, core contract, and token (no jq
  dependency).
• Wired up as bun run check:integration at the repo root.

4. CI workflow

• .github/workflows/integration-checks.yml — two parallel jobs:
  • Indexer: codegen, build, mapping unit tests, manifest sync against fixtures, manifest validation.
  • Web: typecheck, build.
• README and indexer README link the new guide so the doc is discoverable from the existing landing pages.

Test plan

• bun install from a clean clone
• bun run check:integration (mirrors the new CI matrix locally)
• bun run --cwd apps/s03-indexer codegen
• bun run --cwd apps/s03-indexer build
• bun run --cwd apps/s03-indexer test
• SO4_CONTRACTS_REPO=apps/s03-indexer/tests/fixtures/contracts-repo bun run --cwd apps/s03-indexer sync:contracts:local
• bash scripts/validate-manifest.sh apps/s03-indexer/config/contracts.local.json
• bun run --cwd apps/web typecheck
• bun run --cwd apps/web build
• Confirm the new Integration Checks workflow runs green on this PR

Notes

• All commits authored by 0xsteins.
• No code paths in apps/web or apps/s03-indexer/src changed — this PR is docs + fixtures + tooling + CI only.

[vercel]

@0xsteins is attempting to deploy a commit to the Ijai's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@0xsteins Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits