docs: validate and correct documentation vs codebase

- Fixed GASP acronym hallucination and Network domain summary
- Synced README.md + docs/packages/index.md (avoided exact counts per feedback)
- Updated BRC-100 spec with ReviewActionResult notes and cross-refs to match Wallet.interfaces.ts
- Updated dates, added HUMAN_QUESTION.md with review items
Why: Ensure all statements/examples accurate to rebuild developer trust; err on side of removing unverified claims

Author: sirdeggen

HUMAN_QUESTION.md

@@ -0,0 +1,43 @@
+# Questions for Human Review on ts-stack Documentation
+
+## Package Organization and Counts
+- The top-level README.md claims 35 packages + conformance across 7 domains, with a detailed map. docs/packages/index.md claims 27 production-ready. Which count and structure should be canonical? Should we consolidate into one source of truth?
+Consolidate into one source of truth. 27 seems right, because we condensed overlay topics into one package.
+
+- Some packages like wallet-toolbox-examples, wallet-infra, btms-backend are marked private or legacy. Should they be excluded from main "production-ready" lists?
+No, just avoid using exact numbers because they're bound to change over time.
+
+- Templates and did-client moved from sdk/ to helpers/. Should README.md be updated to reflect current locations?
+Yes please.
+
+## GASP Acronym
+- Confirmed from code: "Graph Aware Sync Protocol". The "Generic Append-only Structured Proofs" in docs/packages/index.md is a hallucination. I've planned to fix it. Any preferred full description or link to spec?
+Correct. The spec is somewhere in this repo under ./specs
+
+## Network Domain
+- The teranode-listener is for P2P event subscription (blocks, subtrees, etc.), not general broadcast or node queries (explicitly "When NOT to use"). Should the domain summary in docs/packages/index.md and docs/index.md be revised to "P2P Real-time Event Listener for Teranode" ?
+Yes please.
+
+## Documentation Site vs Embedded Docs
+- There are docs/*.md, package-specific docs/ in packages/*/, CLAUDE.md, BASELINE.md, specs/*.md, and top-level README. What is the intended primary documentation for developers? Should we de-duplicate content or use one as source?
+the tol level ./docs are the intended primary documentation for developers. The lower level ./docs go into detail for particular packages (they were written prior to this monorepo) and serve as good source material and should even be included within the main docs if developers want to dig deep into the details.
+
+## Code Examples and Links
+- Many links point to ./packages/helpers/wallet-helper.md but the file might be in docs/packages/helpers/wallet-helper.md. Are relative links correct for the docs site?
+They seem to work fine as they are: https://bsv-blockchain.github.io/ts-stack/packages/helpers/wallet-helper/ is working.
+
+- In teranode-listener.md, API reference and GitHub links point to old ts-p2p repo and ts-p2p TypeDoc. What should they point to now (ts-stack monorepo, new docs site)?
+This repo, but we need to update the spec anyway so leave it broken for now.
+
+## BRC-100 and Specs
+- The specs/brc-100-wallet.md seems to document the interface. Is it generated or hand-written? Does it accurately match packages/sdk/src/wallet/Wallet.interfaces.ts and the JSON schema?
+I want you to verify whether it does or not. It was generated by another model.
+
+## Infrastructure and Conformance
+- Infrastructure docs reference deployed endpoints. Are the names and statuses in docs/infrastructure/*.md still accurate? (e.g. store-us-1.bsvb.tech)
+Yes that's a good reference URL.
+
+- Conformance vectors coverage claims - do they match current META.json and vectors/ ?
+We should check.
+
+Please review and provide guidance on these. I will update docs to remove any unverified claims in the meantime.

README.md

@@ -6,18 +6,18 @@ BSV TypeScript monorepo — all production TypeScript packages for the BSV block
 
 ## Domains
 
-| Domain | Path | Packages |
-|--------|------|----------|
-| **SDK** | `packages/sdk/` | 3 |
-| **Wallet** | `packages/wallet/` | 9 |
-| **Network** | `packages/network/` | 1 |
-| **Overlays** | `packages/overlays/` | 9 |
-| **Messaging** | `packages/messaging/` | 6 |
-| **Middleware** | `packages/middleware/` | 3 |
-| **Helpers** | `packages/helpers/` | 4 |
-| **Conformance** | `conformance/` | 1 runner |
-
-**35 packages** + conformance runner across 7 domains.
+| Domain | Path | Description |
+|--------|------|-------------|
+| **SDK** | `packages/sdk/` | Core crypto, scripts, tx, BRC-100 |
+| **Wallet** | `packages/wallet/` | BRC-100 implementation components |
+| **Network** | `packages/network/` | P2P real-time event listener for Teranode |
+| **Overlays** | `packages/overlays/` | Topic indexing, validation, GASP sync |
+| **Messaging** | `packages/messaging/` | Message Box, Authsocket, Paymail |
+| **Middleware** | `packages/middleware/` | Auth & HTTP 402 for Express |
+| **Helpers** | `packages/helpers/` | `@bsv/simple`, wallet-helper, utilities |
+| **Conformance** | `conformance/` | Vectors for interoperability |
+
+See `docs/packages/index.md` for details (primary developer documentation).
 
 ---
 
@@ -26,9 +26,7 @@ BSV TypeScript monorepo — all production TypeScript packages for the BSV block
 ### SDK — `packages/sdk/`
 | Package | npm |
 |---------|-----|
-| [ts-sdk](packages/sdk/ts-sdk) | [@bsv/sdk](https://www.npmjs.com/package/@bsv/sdk) |
-| [ts-templates](packages/sdk/ts-templates) | [@bsv/templates](https://www.npmjs.com/package/@bsv/templates) |
-| [did-client](packages/sdk/did-client) | [@bsv/did-client](https://www.npmjs.com/package/@bsv/did-client) |
+| [sdk](packages/sdk) | [@bsv/sdk](https://www.npmjs.com/package/@bsv/sdk) |
 
 ### Wallet — `packages/wallet/`
 | Package | npm |
@@ -82,6 +80,8 @@ BSV TypeScript monorepo — all production TypeScript packages for the BSV block
 |---------|-----|
 | [simple](packages/helpers/simple) | [@bsv/simple](https://www.npmjs.com/package/@bsv/simple) |
 | [bsv-wallet-helper](packages/helpers/bsv-wallet-helper) | [@bsv/wallet-helper](https://www.npmjs.com/package/@bsv/wallet-helper) |
+| [ts-templates](packages/helpers/ts-templates) | [@bsv/templates](https://www.npmjs.com/package/@bsv/templates) |
+| [did-client](packages/helpers/did-client) | [@bsv/did-client](https://www.npmjs.com/package/@bsv/did-client) |
 | [amountinator](packages/helpers/amountinator) | [@bsv/amountinator](https://www.npmjs.com/package/@bsv/amountinator) |
 | [fund-wallet](packages/helpers/fund-wallet) | `@bsv/fund-wallet` |
 

docs/architecture/layers.md

@@ -3,8 +3,8 @@ id: architecture-layers
 title: Stack Layers
 kind: meta
 version: "n/a"
-last_updated: "2026-04-30"
-last_verified: "2026-04-30"
+last_updated: "2026-05-01"
+last_verified: "2026-05-01"
 review_cadence_days: 30
 status: stable
 tags: ["architecture", "layers"]

docs/index.md

@@ -3,8 +3,8 @@ id: home
 title: ts-stack
 kind: meta
 version: "n/a"
-last_updated: "2026-04-30"
-last_verified: "2026-04-30"
+last_updated: "2026-05-01"
+last_verified: "2026-05-01"
 review_cadence_days: 7
 status: stable
 tags: []

docs/packages/index.md

@@ -3,16 +3,16 @@ id: packages-index
 title: Packages
 kind: meta
 version: "n/a"
-last_updated: "2026-04-30"
-last_verified: "2026-04-30"
+last_updated: "2026-05-01"
+last_verified: "2026-05-01"
 review_cadence_days: 30
 status: stable
 tags: ["packages"]
 ---
 
 # Packages
 
-ts-stack contains 27 production-ready packages organized into 7 domains. Each domain serves a specific part of the stack — from core crypto to business logic.
+ts-stack contains packages organized into 7 domains. Each domain serves a specific part of the stack — from core crypto to business logic. See the top-level README.md for the current package map.
 
 ## Seven Domains
 
@@ -29,13 +29,13 @@ ts-stack contains 27 production-ready packages organized into 7 domains. Each do
 - [@bsv/wallet-toolbox](./wallet/wallet-toolbox.md) — BRC-100 wallet client library
 - [@bsv/btms](./wallet/btms.md) — Basic Token Management System for token issuance, transfer, receiving, burning, and ownership proofs
 - [@bsv/btms-permission-module](./wallet/btms-permission-module.md) — Token permission checking
-- [@bsv/wallet-relay](./wallet/wallet-relay.md) — Broadcast and query wrapper for wallet synchronization
+- [@bsv/wallet-relay](./wallet/wallet-relay.md) — Mobile-to-desktop wallet pairing via QR codes + encrypted WebSocket relay
 
 ### Network
 
-**Broadcast transactions and query BSV nodes through a typed client.**
+**P2P Real-time Event Listener for Teranode**
 
-- [@bsv/teranode-listener](./network/teranode-listener.md) — Connect to Teranode and listen for transactions
+- [@bsv/teranode-listener](./network/teranode-listener.md) — Subscribe to Teranode P2P topics (blocks, subtrees, mining) with callbacks (see specs/sync for related)
 
 ### Overlays
 
@@ -45,7 +45,7 @@ ts-stack contains 27 production-ready packages organized into 7 domains. Each do
 - [@bsv/overlay-express](./overlays/overlay-express.md) — HTTP server for the Overlay spec
 - [@bsv/overlay-topics](./overlays/overlay-topics.md) — Topic managers (UHRP, BTMS, custom)
 - [@bsv/overlay-discovery-services](./overlays/overlay-discovery-services.md) — Discover overlays by service type
-- [@bsv/gasp](./overlays/gasp.md) — GASP (Generic Append-only Structured Proofs) sync protocol
+- [@bsv/gasp](./overlays/gasp.md) — Graph Aware Sync Protocol (GASP) for incremental ancestry/descendancy graph sync
 - [@bsv/btms-backend](./overlays/btms-backend.md) — Backend for running a token overlay
 
 ### Messaging

docs/specs/brc-100-wallet.md

@@ -3,8 +3,8 @@ id: spec-brc-100-wallet
 title: BRC-100 Wallet Interface
 kind: spec
 version: "1.0.0"
-last_updated: "2026-04-30"
-last_verified: "2026-04-30"
+last_updated: "2026-05-01"
+last_verified: "2026-05-01"
 status: stable
 tags: ["spec", "wallet", "brc-100"]
 ---
@@ -15,11 +15,11 @@ BRC-100 is the standard application-to-wallet interface used by BSV Desktop, BSV
 
 The authoritative sources for this page are:
 
-- `packages/sdk/src/wallet/Wallet.interfaces.ts`
-- `specs/sdk/brc-100-wallet.json`
+- `packages/sdk/src/wallet/Wallet.interfaces.ts` (TypeScript definitions)
+- `specs/sdk/brc-100-wallet.json` (wire-format schema)
 - [BRC-100 in the BRC repository](https://github.com/bitcoin-sv/BRCs/blob/master/wallet/0100.md)
 
-The TypeScript interface passes `originator?: OriginatorDomainNameStringUnder250Bytes` as an optional second method parameter. Wire formats may carry the originator inside the request envelope.
+This MD is a human-readable summary. Implement against the TS interfaces and JSON schema. The TypeScript interface passes `originator?: OriginatorDomainNameStringUnder250Bytes` as an optional second method parameter (wire formats carry it in the request envelope). See `ReviewActionResult` for delayed-broadcast responses.
 
 ## Data Conventions
 
@@ -96,6 +96,7 @@ Returns:
 | `noSendChange` | `OutpointString[]` | When `noSend` produces change for later chained actions. |
 | `sendWithResults` | `SendWithResult[]` | When sending a batch created with `sendWith`. |
 | `signableTransaction` | `{ tx: AtomicBEEF, reference: Base64String }` | When the action needs a follow-up `signAction`. |
+| (ReviewActionResult fields) | `object` | When `acceptDelayedBroadcast: false`; see `ReviewActionResult` (status, competingTxs, etc.) in `Wallet.interfaces.ts`. |
 
 Minimal shape:
 
@@ -238,7 +239,7 @@ Optional args:
 |-------|------|---------|
 | `tags` | `OutputTagStringUnder300Bytes[]` | - |
 | `tagQueryMode` | `'all' | 'any'` | `'any'` |
-| `include` | `'locking scripts' | 'entire transactions'` | - |
+| `include` | `'locking scripts' | 'entire transactions'` | - | Legacy `includeEntireTransactions: boolean` also supported for compatibility; prefer `include` enum. |
 | `includeCustomInstructions` | `boolean` | `false` |
 | `includeTags` | `boolean` | `false` |
 | `includeLabels` | `boolean` | `false` |