Skip to content

HUMAN_QUESTION.md

Latest commit

 

History

History
43 lines (31 loc) · 3.21 KB

HUMAN_QUESTION.md

File metadata and controls

43 lines (31 loc) · 3.21 KB
Raw

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.