dblurt developer guide

This directory contains the canonical human-written developer documentation for @beblurt/dblurt.

Every guide should answer one precise developer question. AI-specific routing and repository-agent instructions live outside this directory.

Documentation ownership

Location	Role	Maintained by	Rule
README.md	Landing page and first-contact experience	humans	route readers to the right source
guide/	Human developer guides	humans	canonical explanations and task guides
examples/	Executable evidence	humans + validation	reusable read-only/product examples first
ai/	Thin AI context/rules	humans	link to guide/ and examples/; do not duplicate them
docs/	Generated API reference site	TypeDoc	regenerated by make docs; do not edit by hand

Start here

Developer question	Guide
How do I make my first Blurt RPC call?	Getting started
What do Blurt, blocks, operations, authorities and Nexus mean?	Blockchain model
Which dblurt API surface should I use?	API guide
Where are runnable examples?	Examples and ../examples/README.md
Can I use dblurt in my runtime?	Runtime compatibility
How do I use dblurt in a browser?	Browser usage
How does RPC failover work?	RPC failover
How do I publish a transaction safely?	Broadcasting
What is Nexus Layer 2?	Nexus Layer 2
How do keys, crypto and memos work?	Crypto, keys and memos
How should I reason about security boundaries?	Security guide
How should I use TypeScript?	TypeScript
What are common answers?	FAQ
How should AI assistants use the docs?	../ai/README.md
How should maintainers validate docs/builds?	Maintainer workflows

Concepts

• Blockchain model — canonical domain vocabulary for humans and AI assistants.
• API guide — public surfaces and Layer 1 / Layer 2 routing.
• Nexus Layer 2 — indexed/social data model and boundaries.
• Runtime compatibility — supported environments and validation status.

Learning path

Follow this path when learning dblurt for the first time:

1. Getting started — install and run a first read-only RPC call.
2. Blockchain model — learn the domain vocabulary.
3. API guide — choose the right helper surface.
4. Examples — run reusable examples from examples/.
5. Nexus Layer 2 — understand indexed/social views.
6. Broadcasting — only after read-only flows are clear.

This path links existing guides instead of duplicating their content.

How-to guides

• Getting started
• Browser usage
• RPC failover
• Broadcasting
• TypeScript

Reference and maintainer guides

• Examples
• Crypto, keys and memos
• Security guide
• FAQ
• Maintainer workflows

Generated API reference

Run:

make docs
Copy

Then open:

docs/index.html
Copy

TypeDoc imports the Markdown files in this directory through projectDocuments, so the generated site can expose both API reference pages and long-form guides while keeping docs/ fully generated.