docs: rewrite roadmap to tell the project's story

··· 1 1 # roadmap 2 2 3 - `zat` is a grab bag of **AT Protocol building blocks** in Zig: parsers, validators, resolvers, and small protocol helpers. 3 + zat started as a small set of string primitives for AT Protocol - the types everyone reimplements (`Tid`, `Did`, `Handle`, `Nsid`, `Rkey`, `AtUri`). the scope grew based on real usage. 4 4 5 - This roadmap is intentionally short. If it doesn’t fit into one file, it probably belongs in issues. 5 + ## history 6 6 7 - ## now 7 + **initial scope** - string primitives with parsing and validation. the philosophy: primitives not frameworks, layered design, zig idioms, minimal scope. 8 8 9 - - use zat in real projects and let usage drive what's next 10 - - keep current APIs stable (0.x semver) 11 - - tighten docs/examples as real apps discover sharp edges 12 - - keep the "primitives, not framework" ethos 9 + **what grew from usage:** 10 + - DID resolution was originally "out of scope" - real projects needed it, so `DidResolver` and `DidDocument` got added 11 + - XRPC client and JSON helpers - same story 12 + - JWT verification for service auth 13 + - handle resolution via HTTP well-known 14 + - handle resolution via DNS-over-HTTP (community contribution) 15 + - sync types for firehose consumption (`CommitAction`, `EventKind`, `AccountStatus`) 13 16 14 - ## next 17 + this pattern - start minimal, expand based on real pain - continues. 15 18 16 - ### polish 19 + ## now 17 20 18 - - improve docs around common workflows: 19 - - ~~resolving handle → DID → PDS~~ done: `HandleResolver` (HTTP + DoH), `DidResolver`, `DidDocument` 20 - - ~~making XRPC calls + parsing JSON~~ done: `Xrpc`, `json` helpers 21 - - verifying JWTs from DID documents (`Jwt` exists, docs could be better) 22 - - add more integration tests that hit real-world edge cases (without becoming flaky) 21 + use zat in real projects. let usage drive what's next. 23 22 24 - ### primitives 23 + the primitives are reasonably complete. what's missing will show up when people build things. until then, no speculative features. 25 24 26 - - fill gaps that show up repeatedly in other atproto projects: 27 - - ~~CIDs and common multiformats plumbing~~ done: `multibase`, `multicodec` 28 - - ~~richer `AtUri` helpers~~ done: `AtUri` with parsing, formatting 29 - - ~~more ergonomic JSON navigation patterns~~ done: `json` module (still optional, no forced codegen) 30 - - sync types for firehose consumption (`CommitAction`, `EventKind`, `AccountStatus`) 25 + ## maybe later 31 26 32 - ## later (maybe) 27 + these stay out of scope unless real demand emerges: 33 28 34 - - lexicon codegen is still “probably a separate project” 35 - - higher-level clients/frameworks stay out of scope 29 + - lexicon codegen - probably a separate project 30 + - higher-level clients/frameworks - too opinionated 31 + - token refresh/session management - app-specific 32 + - feed generator scaffolding - each feed is unique 36 33 37 34 ## non-goals 38 35 39 - - token refresh/session frameworks 40 - - opinionated app scaffolding 41 - - “one true SDK” that tries to do everything 36 + zat is not trying to be: 42 37 38 + - a "one true SDK" that does everything 39 + - an opinionated app framework 40 + - a replacement for understanding the protocol