⚡ FLASHY DOCUMENTATION — The Complete Reference for a Consent-Gated Economy

Everything you need to understand, build, and deploy the Flashy ecosystem. From core concepts to production patterns.

Comprehensive guides and references for Ledger, Rails, Magician, and FlashyID. Learn how the four systems integrate to build append-only settlement, consent-gated transfers, trust routing, and delegated identity. Every guide's samples name the exports the packages actually have, measured against a named commit.

New to Flashy? Read in this order:

1. ⚡ System Architecture (10 min) — How all four systems fit together
2. 📊 Ledger Basics (5 min) — Append-only settlement
3. ✅ Rails Consent (5 min) — The approval gate
4. 🧭 Magician Trust (5 min) — Trust graphs and routing
5. 🔐 FlashyID Assertions (5 min) — Verified assertions and delegation chains

Then run the working examples:

npm install && npm run examples:ledger
npm run examples:rails
npm run examples:magician
npm run examples:flashyid
npm run examples:combined

Every link below points at a page that exists; npm test fails otherwise.

• overview.md — How all four systems work together; data flow diagrams

• ledger-101.md — post + a store: assets, opaque identity, Minor, transfers, the hash chain, idempotent replay
• rails-consent.md — RailsService: draft → consent → execute; grants, attenuation, revocation
• magician-routing.md — trust/1 graphs, findPaths and the veil, the consent machine, sealed introduction/1 records
• flashyid-oauth.md — verifyAssertion / authorize, the grant kernel, the enforcement gate, rail tokens (the SDK is not an OAuth client; the guide says where login lives)
• combined-workflow.md — End-to-end example: Alice pays Dave in Flashy Gold through a consented, sealed trust chain
• setup-local.md — Building the four packages from sibling checkouts (they are not on the public registry)
• mesh-integration.md — Consuming the estate's four standards
• intentmesh-roadmaps.md, rites-witnessed-observances.md, aao-governance-conformance.md — the intent/1, ritual/1 and AAO formats
• oss-excellence-standard.md — The bar every estate repository is measured against

Each page is measured against a named commit of its package's source and says so at the top. Where a guide and an API page disagree, the API page was measured.

• ledger-api.md — @flashylabs/ledger: post, the store port, entries, errors
• rails-api.md — @flashylabs/rails: RailsService, draft → execute, grants, error codes
• magician-api.md — @magician-network/core: trust/1, the router, consent, introduction/1
• flashyid-api.md — @flashyid/sdk: verify, authorize, the grant kernel, rail tokens

• patterns.md — Deployment patterns for each system and the full stack

• OPERATIONAL-PRINCIPLES.md · INTEGRATOR-PROGRAM.md · STATUS.md (generated by npm run status)

Named here so the plan is visible, and linked from nowhere until each one exists. No dates: a page is added when someone writes it from the source.

• Architecture: ledger-design.md, rails-consent.md, magician-routing.md, flashyid-identity.md, integration-patterns.md
• Troubleshooting: faq.md, debugging.md, errors.md, performance.md
• Deployment: runbook.md, security.md, monitoring.md, production-patterns.md

All four systems work together — FlashyID signs the assertion and the consent, Magician routes through trust, Rails gates the transfer, Ledger records it immutably.

All concepts are taught through runnable examples in flashy-examples:

npm run examples:ledger           # Ledger basics
npm run examples:rails            # Rails consent
npm run examples:magician         # Magician routing
npm run examples:flashyid         # FlashyID OAuth
npm run examples:combined         # Combined workflow
npm test                          # All tests

True in every Flashy repository:

• Amounts are Minor (branded integer), never raw numbers. Convert at the edge with the ledger's fromDecimal() / toDecimal(), or Rails' toMinor() / toGold() for Flashy Gold
• Consent is explicit; never auto-approve. Every Rails execute requires a consent bound to that exact draft
• Grants narrow, never widen. Attenuation is the only allowed delegation operation
• Sealed means sealed. Outcomes use portable sha256; replayed digests are refused
• Identity is opaque. No hardcoded names; holders are unforgeable identifiers
• No unverified claims. Every number is measured, not assumed

.
├── README.md                 # You are here
├── CLAUDE.md                 # Repository rules
├── docs/
│   ├── architecture/         # System design
│   ├── guides/               # Tutorials and how-tos
│   ├── api/                  # API reference, measured against source
│   ├── deployment/           # Production setup
│   └── STATUS.md             # Generated: what the sibling checkouts declare
├── tools/
│   ├── check-links.mjs       # Every relative link resolves to a file
│   ├── check-samples.mjs     # Every ```js / ```mjs fence parses (node --check)
│   └── status.mjs            # Writes docs/STATUS.md
└── .github/workflows/        # doc-checks.yml runs both checkers; secret-scan.yml

Worked examples live in the separate flashy-examples repository.

Documentation improvements welcome. Before opening a pull request:

• npm test passes: every relative link resolves and every JavaScript sample parses
• TypeScript samples are checked by hand — nothing here type-checks them
• Every claim about a package names the commit it was read from
• No unverified audience claims or hardcoded figures

See CONTRIBUTING.md for details.

Apache-2.0. Holder: Flashy Labs.

Quick Links:

• Ledger Repo
• Rails Repo
• Magician Repo
• FlashyID Repo
• Examples Repo