[G-ELM]

Summary

Adds four documentation deliverables aimed at integrators, contributors, and operators: an FAQ and troubleshooting guide, a guide to testing integrations locally, a wallet integration guide, and a changelog with a documented release process.

Type of Change

• Documentation update

Changes Made

Task 1 — FAQ and developer troubleshooting guide

• Add docs/getting-started/faq.md (15 entries): what Shade is not, supported tokens and networks, fees and the 48h fee time-lock, custody of funds, refunds, fiat pricing, who can pause and upgrade, admin transfer, merchant registration, snapshots, error lookup.
• Add docs/getting-started/troubleshooting.md (12 entries, each with symptom / cause / fix and exact error text): missing wasm32 target, rustc too old, SDK version mismatch, stale Cargo.lock, linker errors, test_snapshots/ in git, zero tests running, Error(Auth, InvalidAction), Error(Contract, #N), simulation vs. submission differences, archived entries / TTL, CLI identity and network setup. Includes a "Still stuck?" section linking the issue tracker and the errors reference.
• Link both pages from docs/getting-started/README.md.

Task 2 — Guide to testing integrations locally

• Add docs/guides/testing-integrations.md.
• In-process: importing the compiled shade and account WASMs with contractimport!, a reusable Fixture helper (SAC test token, hub init, account WASM hash, merchant registration, linked account contract, funded payer), a mock oracle for fiat invoices, try_* error assertions, and an event-assertion helper.
• Local network: stellar container start local, funding identities, deploying the stack, a TypeScript backend test using generated bindings and getEvents, and resetting state.
• Discusses extracting the helper into a testutils feature or shade-testutils crate as a follow-up issue.
• Link from docs/guides/README.md.

Task 3 — Wallet integration guide

• Add docs/guides/wallet-integration.md.
• Covers connecting Freighter, multi-wallet support via Stellar Wallets Kit, network selection and wrong-network risk, Soroban authorization entries and which address must authorize each Shade function, token prerequisites (trustlines for payer/merchant/platform, balance, XLM fee reserve) with a pre-flight check and user-facing messages, an end-to-end build → simulate → sign → submit pay_invoice flow, contract-error-to-message mapping, and a minimal Vite example app.
• Link from docs/guides/README.md, accepting-payments.md, and contract-bindings.md.

Task 4 — CHANGELOG and release process

• Add CHANGELOG.md (Keep a Changelog format, entries grouped by contract) with entries backfilled from merged PRs, February–July 2026.
• Add docs/operations/releases.md: versioning scheme (coordinated release tags plus per-contract SemVer, and how versions map to tags and WASM hashes), breaking-change criteria (interface signatures, event shapes, error codes, storage layout, behavior), and the release procedure (tagging, reproducible builds, recording hashes, release notes template, gh release create).
• Add an "Update CHANGELOG" section to .github/pull_request_template.md and a matching item to the CONTRIBUTING.md checklists.
• Link the runbook from docs/operations/README.md.

Test Evidence

Documentation-only change; no contract code was modified. Code samples were written against the existing test patterns and were not compiled or run in this change.

• make test passes locally (not applicable — no code changes)
• I have tested this manually (not run; see Additional Notes)
• No test_snapshots/ file is staged in this PR

Documentation Updates

• This PR adds/changes a docs/ page and satisfies the Documentation Style Guide's review checklist.
• New pages are linked from their section README.md.

Closes #508
Closes #511
Closes #512
Closes #513

[drips-wave]

@G-ELM 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