docs: FAQ sections, searchable finance README titles, and llms.txt

CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this repository are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [2026-07-11] - Discoverability and FAQ pass
+
+### Added
+
+- FAQ sections, written as the questions people actually ask, in the root README and every finance example's `anchor/` README.
+- `llms.txt` at the repository root: a summary and link manifest for LLM crawlers and answer engines.
+- `docs/example-readme-template.md`, the example-README template that `CONTRIBUTING.md` referenced but which did not exist. It documents the H1 convention and the definition-first opener.
+
+### Changed
+
+- Every finance example README now titles itself `# Solana <Example> (<Framework>)` (e.g. `# Solana Escrow (Anchor)`) and opens with a self-contained definition that names Solana, so each example page stands alone in search results.
+- The root README states its toolchain currency explicitly (Anchor 1.1, LiteSVM, July 2026) with a pointer to this changelog.
+- `CONTRIBUTING.md` style rules now include the README H1 naming convention and the no-em-dash rule.
+
 ## [2026-07-10] - Failed fundraisers can be retired
 
 ### Added

CONTRIBUTING.md

@@ -58,7 +58,8 @@ Also update [CHANGELOG.md](./CHANGELOG.md) when you ship user-visible changes.
 
 Write American English in prose (e.g. "behavior", "initialize", "favor"). Code identifiers stay as-is.
 
-- One H1 per markdown file.
+- One H1 per markdown file. Example READMEs title it `# Solana <Example> (<Framework>)`, e.g. `# Solana Escrow (Anchor)`.
+- No em-dashes in prose. Use a colon, comma, or a new sentence.
 - Fenced code blocks include a language tag (` ```rust `, ` ```typescript `, ` ```bash `, ` ```toml `).
 - Link canonical Solana terms to the [terminology page](https://solana.com/docs/references/terminology) on first mention in READMEs.
 

README.md

@@ -4,7 +4,7 @@
 
 _Solana program examples ('smart contracts') in Anchor, Quasar, Pinocchio, native Rust, and sBPF assembly. Focused on financial software ('DeFi'), plus the basics, tokens, Token Extensions, state compression, and more._
 
-Working, tested, up-to-date examples of common Solana programs (what other chains call smart contracts), maintained by [Quicknode](https://www.quicknode.com/chains/solana). Every example builds and passes CI on a current toolchain — **Anchor 1.1**, the current multi-file program layout (one file per instruction handler, account type, etc), and [LiteSVM](https://github.com/LiteSVM/litesvm) tests rather than the older `solana-test-validator` / web3.js stack.
+Working, tested, up-to-date examples of common Solana programs (what other chains call smart contracts), maintained by [Quicknode](https://www.quicknode.com/chains/solana). Current as of July 2026 (see [CHANGELOG.md](./CHANGELOG.md)): every example builds and passes CI on **Anchor 1.1**, the current multi-file program layout (one file per instruction handler, account type, etc), and [LiteSVM](https://github.com/LiteSVM/litesvm) tests rather than the older `solana-test-validator` / web3.js stack.
 
 [![Anchor](../../actions/workflows/anchor.yml/badge.svg)](../../actions/workflows/anchor.yml) [![Quasar](../../actions/workflows/quasar.yml/badge.svg)](../../actions/workflows/quasar.yml) [![Pinocchio](../../actions/workflows/pinocchio.yml/badge.svg)](../../actions/workflows/pinocchio.yml) [![Native](../../actions/workflows/native.yml/badge.svg)](../../actions/workflows/native.yml) [![ASM](../../actions/workflows/solana-asm.yml/badge.svg)](../../actions/workflows/solana-asm.yml)
 
@@ -59,7 +59,7 @@ An exchange with no order book: swaps fill instantly against a shared liquidity
 
 ### Prop AMM
 
-A **proprietary AMM**: a market-making firm funds a venue with its own capital and quotes both sides of it, selling the base token at the oracle price plus a spread and buying it back at the oracle price minus the spread. No pricing curve, no liquidity providers, no pool shares — the operator is the only capital in the market, can re-quote or pull its quotes at will, and earns the spread instead of a fee. Because the price comes from an oracle rather than the pool's balances, trades have no price impact and nothing to sandwich. This is the design behind venues like Lifinity, SolFi, and HumidiFi, which fill most Solana swap volume through Jupiter routing.
+A **proprietary AMM**: a market-making firm funds a venue with its own capital and quotes both sides of it, selling the base token at the oracle price plus a spread and buying it back at the oracle price minus the spread. No pricing curve, no liquidity providers, no pool shares: the operator is the only capital in the market, can re-quote or pull its quotes at will, and earns the spread instead of a fee. Because the price comes from an oracle rather than the pool's balances, trades have no price impact and nothing to sandwich. This is the design behind venues like Lifinity, SolFi, and HumidiFi, which fill most Solana swap volume through Jupiter routing.
 
 [⚓ Anchor](./finance/prop-amm/anchor) [💫 Quasar](./finance/prop-amm/quasar)
 
@@ -77,7 +77,7 @@ Parimutuel (pooled) prediction market - an admin opens an event with multiple ou
 
 ### Perpetual Futures
 
-A perpetual futures exchange — a venue for making leveraged bets on an asset's price without ever owning the asset. Traders post collateral and open a **long** (betting the price rises) or **short** (betting it falls) sized up to several times their collateral; their profit or loss tracks the price move and is paid in the collateral token. Rather than matching buyers to sellers, every trade is against a shared **liquidity pool** that other users fund and that is the counterparty to all of it — the pool pays winners and keeps losers' collateral, and its providers earn the trading and funding fees in return. The price comes from an oracle, positions accrue a funding fee over time, and anyone can **liquidate** a position whose collateral can no longer cover its loss. This is the design behind venues like Jupiter Perpetuals and GMX.
+A perpetual futures exchange: a venue for making leveraged bets on an asset's price without ever owning the asset. Traders post collateral and open a **long** (betting the price rises) or **short** (betting it falls) sized up to several times their collateral; their profit or loss tracks the price move and is paid in the collateral token. Rather than matching buyers to sellers, every trade is against a shared **liquidity pool** that other users fund and that is the counterparty to all of it: the pool pays winners and keeps losers' collateral, and its providers earn the trading and funding fees in return. The price comes from an oracle, positions accrue a funding fee over time, and anyone can **liquidate** a position whose collateral can no longer cover its loss. This is the design behind venues like Jupiter Perpetuals and GMX.
 
 [⚓ Anchor](./finance/perpetual-futures/anchor) [💫 Quasar](./finance/perpetual-futures/quasar)
 
@@ -385,6 +385,32 @@ Generate an IDL from a native Rust program with [Shank](https://github.com/metap
 
 [🦀 Native](./tools/shank-and-codama/native)
 
+## FAQ
+
+### Is a Solana program the same as a smart contract?
+
+Yes. "Program" is Solana's term for what other chains call a smart contract: code deployed onchain that holds state in accounts and executes instructions. Everything in this repository is a Solana program.
+
+### How do I build an escrow on Solana?
+
+Start with the [escrow example](./finance/escrow/anchor/), the best first finance program to learn: one state PDA, one vault, and three instruction handlers that swap two tokens atomically. There is also a [30-minute video walkthrough](https://www.youtube.com/watch?v=B5eBWWQfQuM) building it from scratch.
+
+### How do I test a Solana program without running a validator?
+
+Use [LiteSVM](https://www.anchor-lang.com/docs/testing/litesvm): Rust integration tests that run the program in-process, orders of magnitude faster than `solana-test-validator`. Every example in this repository tests this way, and `anchor init` scaffolds it by default since Anchor 1.0.
+
+### What is the difference between Anchor, Quasar, Pinocchio, and native Rust?
+
+[Anchor](https://www.anchor-lang.com/) is the most popular Solana framework, generating account validation and serialization from declarative constraints. [Quasar](https://quasar-lang.com/docs) offers Anchor-like ergonomics with zero-copy, `no_std` performance and smaller binaries. [Pinocchio](https://github.com/anza-xyz/pinocchio) is a zero-allocation library for hand-rolled programs, and native Rust uses Solana's crates directly with no framework. Most examples here ship several variants of the same program so you can compare.
+
+### What is the best way to learn Solana finance programming?
+
+Work through the [finance examples](#financial-software-defi) in order of complexity: [escrow](./finance/escrow/anchor/), then [token swap AMM](./finance/token-swap/anchor/), [order book](./finance/order-book/anchor/), [lending](./finance/lending/anchor/), and [perpetual futures](./finance/perpetual-futures/anchor/). Each README explains the financial mechanics in plain terms before the code.
+
+### Are these examples production-ready?
+
+They are teaching examples: every one builds and passes CI, and the finance programs additionally carry [Kani](https://github.com/model-checking/kani) formal-verification proofs of their money math. None are audited or deployed to mainnet, so treat them as reference implementations to learn from, not code to deploy as-is.
+
 ## Acknowledgements
 
 Big thanks to Joe Caulfield and Solana Foundation for originally creating this repository.

docs/example-readme-template.md

@@ -0,0 +1,48 @@
+# Example README template
+
+Copy this structure for every example's framework directory (`anchor/`, `quasar/`, `native/`, etc.). Replace the placeholder text; delete sections that genuinely do not apply.
+
+## Conventions
+
+- **H1 format**: `# Solana <Example> (<Framework>)`, for example `# Solana Escrow (Anchor)`. One H1 per file. Each example directory is its own indexable page, so the H1 names the example the way someone would search for it.
+- **Definition-first opener**: the first sentence must say what the program is, in a way that stands alone when quoted out of context, and include the word "Solana". Good: "A Solana escrow is a program that holds a maker's tokens in a vault until a taker delivers the requested tokens." Bad: "This directory contains the Anchor version."
+- **No em-dashes** in prose. Use a colon, comma, or a new sentence.
+- Write American English. Fenced code blocks include a language tag. Link canonical Solana terms to the [terminology page](https://solana.com/docs/references/terminology) on first mention.
+- Name the actual instruction handlers (`make_offer`, `take_offer`) in lifecycle prose so readers can connect the narrative to the code. Confirm each identifier exists in the source before naming it.
+
+## Template
+
+```markdown
+# Solana <Example> (<Framework>)
+
+<One-paragraph definition-first opener: what the program is, what real-world
+mechanism it mirrors, and which production Solana protocols use the design.>
+
+<Links to the other framework variants of the same example.>
+
+## Major concepts
+
+<Key accounts and PDAs with their seeds, the state structures, and the
+program logic. For finance examples, explain the financial mechanics in
+plain terms before the code.>
+
+## Lifecycle
+
+<Who calls which instruction handler, in order, and what each one does.>
+
+## Setup
+
+<Prerequisites and build command, e.g. `anchor build`.>
+
+## Testing
+
+<How to run the tests (e.g. `cargo test` against LiteSVM) and what the
+suite covers.>
+
+## FAQ
+
+<Finance examples only, and only in the anchor/ variant to avoid duplicate
+content: three or four questions phrased the way someone would ask them
+("How does an escrow work on Solana?"), each answered in two to four
+self-contained sentences that name the relevant instruction handlers.>
+```

finance/betting-market/anchor/README.md

@@ -1,6 +1,6 @@
-# Betting Market
+# Solana Betting Market (Anchor)
 
-A parimutuel (pooled) betting market. An admin opens an **event**, adds the possible
+A parimutuel (pooled) betting market on Solana. An admin opens an **event**, adds the possible
 **outcomes**, and bettors stake a token on the outcome they think will win. Every stake across
 every outcome goes into one pool. When the admin settles the event to the winning outcome, the
 losing stakes - minus a protocol fee - are split among the winners in proportion to their stake.
@@ -116,3 +116,17 @@ anchor test
 ```
 
 (`Anchor.toml` sets `test = "cargo test"`, so `cargo test` works too.)
+
+## FAQ
+
+### How does a prediction market work on Solana?
+
+This example uses the parimutuel (pooled) model: an admin opens an event with `create_event` and `add_outcome`, and bettors stake tokens on an outcome with `place_bet`. Every stake goes into one pool; after `settle_event` names the winning outcome, winners call `claim_winnings` to split the losing stakes, minus a protocol fee, in proportion to their own stake.
+
+### How are the odds set?
+
+By the crowd, not a bookmaker: each winner's payout scales with their share of the winning pool, so the implied odds shift as stakes arrive. This is the model used by Solana prediction-market platforms such as Hedgehog Markets and by racetrack tote boards.
+
+### What happens if an event is cancelled?
+
+The admin calls `cancel_event` and every bettor reclaims their full stake with `claim_refund`. After a settled event, losers reclaim their bet account's rent with `close_losing_bet`.

finance/betting-market/quasar/README.md

@@ -1,6 +1,6 @@
-# Betting Market, Quasar port
+# Solana Betting Market (Quasar)
 
-A parimutuel betting market. An admin opens events (markets), adds the possible
+A parimutuel betting market on Solana, written with Quasar. An admin opens events (markets), adds the possible
 outcomes, and later settles or cancels each one. Bettors stake a fixed token on
 the outcome they think will happen; when the event is settled, the winners split
 the losing side's stakes in proportion to their own, after a protocol fee. This
@@ -107,7 +107,7 @@ cargo test            # QuasarSVM integration tests (they load the compiled .so)
 [QuasarSVM](https://github.com/blueshift-gg/quasar-svm), an in-process SVM. The
 suite in `src/tests.rs` drives the full lifecycle (open a market, add outcomes,
 place opposing bets, settle, claim the winnings, close the losing bet) and the
-cancel-and-refund path, asserting on-chain state, token balances, and fee
+cancel-and-refund path, asserting onchain state, token balances, and fee
 accounting at each step, plus an admin-authorization rejection.
 
 ## Extending

finance/escrow/anchor/README.md

@@ -1,4 +1,4 @@
-# Anchor Escrow
+# Solana Escrow (Anchor)
 
 This Solana [program](https://solana.com/docs/terminology#program) is an **escrow** - it lets a **maker** swap a specific amount of one token for a desired amount of another token with a **taker**, atomically and without either party having to trust the other.
 
@@ -41,6 +41,24 @@ cargo test
 
 (`anchor test` runs the same command, per `Anchor.toml`.) The tests cover the make/take flow, the make/cancel flow, rejection of a non-maker cancel, token balances on every leg, and the rent refunds (the maker's lamports recover the offer and vault rent after both take and cancel).
 
+## FAQ
+
+### How does an escrow work on Solana?
+
+A Solana escrow is a program that holds a maker's tokens in a program-controlled vault until a taker delivers the tokens the maker asked for, then releases both sides in one atomic transaction. This example implements the whole lifecycle in three instruction handlers: `make_offer`, `take_offer`, and `cancel_offer`.
+
+### Is this a good first Solana finance program to learn?
+
+Yes. Escrow is the smallest complete finance program: one state PDA, one vault, three instruction handlers, and the atomic swap idea that underlies every onchain exchange. Start here before the [AMM](../../token-swap/anchor/), [order book](../../order-book/anchor/), and [lending](../../lending/anchor/) examples.
+
+### How do I run and test this escrow example?
+
+Build with `anchor build`, then run `cargo test`. The tests are Rust integration tests against [LiteSVM](https://www.anchor-lang.com/docs/testing/litesvm), so no local validator is needed.
+
+### How is this escrow program verified?
+
+Two ways: LiteSVM integration tests covering the make, take, and cancel flows, and [Kani](https://github.com/model-checking/kani) proofs in [`../kani-proofs/`](../kani-proofs/) that check the money-math invariants over all possible inputs, not just test cases.
+
 ## Credit
 
 Based on [Dean Little's Anchor Escrow](https://github.com/deanmlittle/anchor-escrow-2024), restructured for teaching.

finance/escrow/native/README.md

@@ -1,4 +1,4 @@
-# Escrow (Native)
+# Solana Escrow (Native)
 
 This Solana program is an **escrow** written directly against `solana-program`, with no framework. It lets a **maker** swap a specific amount of one token for a desired amount of another token with a **taker**, atomically and without either party having to trust the other.
 

finance/escrow/quasar/README.md

@@ -1,6 +1,6 @@
-# Escrow (Quasar)
+# Solana Escrow (Quasar)
 
-Atomic token swap escrow between maker and taker.
+An atomic token swap escrow on Solana, written with Quasar: the program holds a maker's tokens in a vault until a taker delivers the tokens the maker asked for, then releases both sides in one transaction.
 
 See also: the [repository catalog](../../../README.md).
 

finance/lending/anchor/README.md

@@ -1,6 +1,6 @@
-# Lending
+# Solana Lending (Anchor)
 
-A Kamino/Solend-style borrow/lend program: suppliers earn interest on deposits,
+A Kamino/Solend-style borrow/lend program on Solana: suppliers earn interest on deposits,
 borrowers post collateral and draw other assets against it, and liquidators keep
 the market solvent. It demonstrates the techniques the most-used Solana lending
 protocols share: share-token deposit accounting, a utilization-based interest
@@ -173,3 +173,21 @@ anchor test    # or: cargo test     - runs the LiteSVM integration tests
 non-happy-path branches: interest accrual, borrowing at the LTV limit, stale
 reserve/price rejection, liquidation of an unhealthy obligation after a price
 move, the share-inflation guard, and rounding edges.
+
+## FAQ
+
+### How does a lending protocol work on Solana?
+
+Suppliers deposit a token with `deposit_reserve_liquidity` and receive share tokens that grow in value as borrowers pay interest. Borrowers post those shares as collateral (`deposit_obligation_collateral`) and draw a different token with `borrow_obligation_liquidity`, up to a loan-to-value limit. When a position's collateral no longer covers its debt, anyone can call `liquidate_obligation` to repay part of the debt in exchange for discounted collateral.
+
+### How does interest accrue without looping over every account?
+
+Through a cumulative interest index: `refresh_reserve` advances a per-reserve index along a utilization-based rate curve, and each obligation stores the index value from its last interaction. The gap between the two is the interest owed, so no per-account accrual loop is needed. This is the same technique the most-used Solana lending protocols share.
+
+### How are prices fed into the protocol?
+
+The admin `set_price` instruction handler stands in for an oracle feed in this example. `refresh_obligation` re-values collateral and debt at those prices before any borrow, withdraw, or liquidation is allowed, and stale reserves or prices are rejected.
+
+### How is this lending program tested and verified?
+
+`anchor build` then `cargo test` runs LiteSVM integration tests covering interest accrual, borrowing at the LTV limit, liquidation after a price move, and the share-inflation guard. The money math also has [Kani](https://github.com/model-checking/kani) proofs in [`../kani-proofs/`](../kani-proofs/).

finance/lending/quasar/README.md

@@ -1,4 +1,4 @@
-# Lending (Quasar)
+# Solana Lending (Quasar)
 
 A Kamino/Solend-style borrow/lend program written with [Quasar](https://quasar-lang.com),
 a zero-copy, `no_std` Solana framework. It is the Quasar counterpart to the Anchor