readme updates, new codegen binaries, llms.txt

README.md

···
 
 It is also designed around zero-copy/borrowed deserialization: types like [`Post<'_>`](https://tangled.org/@nonbinary.computer/jacquard/blob/main/crates/jacquard-api/src/app_bsky/feed/post.rs) can borrow data (via the [`CowStr<'_>`](https://docs.rs/jacquard/latest/jacquard/cowstr/enum.CowStr.html) type and a host of other types built on top of it) directly from the response buffer instead of allocating owned copies. Owned versions are themselves mostly inlined or reference-counted pointers and are therefore still quite efficient. The `IntoStatic` trait (which is derivable) makes it easy to get an owned version and avoid worrying about lifetimes.
 
+## Features
+
+- Validated, spec-compliant, easy to work with, and performant baseline types
+- Designed such that you can just work with generated API bindings easily
+- Straightforward OAuth
+- Server-side convenience features
+- Lexicon Data value type for working with unknown atproto data (dag-cbor or json)
+- An order of magnitude less boilerplate than some existing crates
+- Batteries-included, but easily replaceable batteries.
+   - Easy to extend with custom lexicons using code generation or handwritten api types
+   - Stateless options (or options where you handle the state) for rolling your own
+   - All the building blocks of the convenient abstractions are available
+   - Use as much or as little from the crates as you need
+
 ## 0.8.0 Release Highlights:
 
 **`jacquard-repo` crate**
···
  - CAR file write order compatible with streaming mode from the [sync iteration proposal](https://github.com/bluesky-social/proposals/blob/main/0006-sync-iteration/README.md#streaming-car-processing)
  - Big rewrite of all the errors in the crate, improvements to context and overall structure
  - Made handle parsing a bit more permissive for a common case ('handle.invalid' when someone has a messed up handle), added a method to confirm syntactic validity (the correct way to confirm validity is resolve_handle() from the  IdentityResolver trait, then fetching and comparing to the DID document).
-
-> [!WARNING]
-> A lot of the streaming code is still pretty experimental. The examples work, though.\
-The modules are also less well-documented, and don't have code examples. There are also a lot of utility functions for conveniently working with the streams and transforming them which are lacking. Use [`n0-future`](https://docs.rs/n0-future/latest/n0_future/index.html) to work with them, that is what Jacquard uses internally as much as possible.\
->I would also note the same for the repository crate until I've had more third parties test it.
-
-### Changelog
-
-[CHANGELOG.md](./CHANGELOG.md)
-
-## Goals and Features
-
-- Validated, spec-compliant, easy to work with, and performant baseline types
-- Batteries-included, but easily replaceable batteries.
-   - Easy to extend with custom lexicons using code generation or handwritten api types
-   - Straightforward OAuth
-   - Stateless options (or options where you handle the state) for rolling your own
-   - All the building blocks of the convenient abstractions are available
-   - Server-side convenience features
-- Lexicon Data value type for working with unknown atproto data (dag-cbor or json)
-- An order of magnitude less boilerplate than some existing crates
-- Use as much or as little from the crates as you need
 
 ## Example
 
···
 ```
 
 If you have `just` installed, you can run the [examples](https://tangled.org/@nonbinary.computer/jacquard/tree/main/examples) using `just example {example-name} {ARGS}` or `just examples` to see what's available.
+
+> [!WARNING]
+> A lot of the streaming code is still pretty experimental. The examples work, though.\
+The modules are also less well-documented, and don't have code examples. There are also a lot of utility functions for conveniently working with the streams and transforming them which are lacking. Use [`n0-future`](https://docs.rs/n0-future/latest/n0_future/index.html) to work with them, that is what Jacquard uses internally as much as possible.\
+>I would also note the same for the repository crate until I've had more third parties test it.
+
+### Changelog
+
+[CHANGELOG.md](./CHANGELOG.md)
+
+<!--### Testimonials
+
+- ["the most straightforward interface to atproto I've encountered so far."](https://bsky.app/profile/offline.mountainherder.xyz/post/3m3xwewzs3k2v) - @offline.mountainherder.xyz
+
+- "It has saved me a lot of time already! Well worth a few beers and or microcontrollers" - [@baileytownsend.dev](https://bsky.app/profile/baileytownsend.dev)-->
+
+### Projects using Jacquard
+
+- [skywatch-phash-rs](https://tangled.org/@skywatch.blue/skywatch-phash-rs)
+- [PDS MOOver](https://pdsmoover.com/) - [tangled repository](https://tangled.org/@baileytownsend.dev/pds-moover)
 
 ## Component crates
 

binaries/SHA256SUMS

···
-1cca585492c14f4fbf2b913bb00023523a95aa0736696b5328e72c090fc7d356  jacquard-codegen_aarch64-unknown-linux-gnu.tar.xz
-a55847e84237c5775ab17f2079ce263efc3670d2ad15fb5b660dde40051ef8d6  jacquard-codegen_x86_64-unknown-linux-gnu.tar.xz
-e232a64747a107286311de80e4d868ad51c1515f9bc45a13cd71f4494a0e0fd4  lex-fetch_aarch64-unknown-linux-gnu.tar.xz
-f52f5e5cc78ef95747e26ba3583f36ad2d05ba040382593b9d4d85544b1d2789  lex-fetch_x86_64-unknown-linux-gnu.tar.xz
-cc9c53669e2d5532589d83bca168182eab049675ac5f0e59612add18e9e587b2  jacquard-codegen_x86_64-pc-windows-gnu.zip
-de3b47c2f0c76543d96cebf4bac6d5468a06cac79a5997473fdbfc92a559c2c3  lex-fetch_x86_64-pc-windows-gnu.zip
[phone]d68a813f9d270ea478b03f30e573222760486969106bec14c9283  jacquard-codegen_aarch64-unknown-linux-gnu.tar.xz
+74692d2ab91869681a32a9d25fb6d48b9461ff490d5fc289536f739f8f277cd9  jacquard-codegen_x86_64-unknown-linux-gnu.tar.xz
+948c675059875880468cda4c35ea2bad1bf9e8a0310d47e32e62f60b925a6cdd  lex-fetch_aarch64-unknown-linux-gnu.tar.xz
+451e5361280f059c269827c0272431e604d3473507897239753171e249837323  lex-fetch_x86_64-unknown-linux-gnu.tar.xz
+5d5adab46222e0f1fd5f541213991c14b7b1ece4b22cd62b5ab5e1e0d6c65eca  jacquard-codegen_x86_64-pc-windows-gnu.zip
[phone]ffea860151fcec913422cf4fa102d4961e85319d50a07a98705bcf  lex-fetch_x86_64-pc-windows-gnu.zip

crates/jacquard/src/lib.rs

···
 //! It is also designed around zero-copy/borrowed deserialization: types like [`Post<'_>`](https://docs.rs/jacquard-api/latest/jacquard_api/app_bsky/feed/post/struct.Post.html) can borrow data (via the [`CowStr<'_>`](https://docs.rs/jacquard/latest/jacquard/cowstr/enum.CowStr.html) type and a host of other types built on top of it) directly from the response buffer instead of allocating owned copies. Owned versions are themselves mostly inlined or reference-counted pointers and are therefore still quite efficient. The `IntoStatic` trait (which is derivable) makes it easy to get an owned version and avoid worrying about lifetimes.
 //!
 //!
-//! ## Goals and Features
+//! ## Features
 //!
 //! - Validated, spec-compliant, easy to work with, and performant baseline types
+//! - Designed such that you can just work with generated API bindings easily
+//! - Straightforward OAuth
+//! - Server-side convenience features
+//! - Lexicon Data value type for working with unknown atproto data (dag-cbor or json)
+//! - An order of magnitude less boilerplate than some existing crates
 //! - Batteries-included, but easily replaceable batteries.
 //!    - Easy to extend with custom lexicons using code generation or handwritten api types
-//!    - Straightforward OAuth
 //!    - Stateless options (or options where you handle the state) for rolling your own
 //!    - All the building blocks of the convenient abstractions are available
-//!    - Server-side convenience features
-//! - Lexicon Data value type for working with unknown atproto data (dag-cbor or json)
-//! - An order of magnitude less boilerplate than some existing crates
-//! - Use as much or as little from the crates as you need
-//!
+//!    - Use as much or as little from the crates as you need
 //!
 //!
 //!

llms.txt

···
+# Jacquard: AT Protocol Library for Rust
+
+> Simple and powerful AT Protocol (Bluesky) client library emphasizing spec compliance, zero-copy deserialization, and minimal boilerplate.
+
+## Core Philosophy
+
+**Zero-copy by default, owned when needed.** All API types support borrowed deserialization via lifetimes, with `IntoStatic` trait for conversion to `'static` when needed. This avoids the performance penalty of `DeserializeOwned` while giving you control over ownership.
+
+**Validated types everywhere.** DIDs, handles, AT-URIs, NSIDs, TIDs, CIDs—all have strongly-typed, validated wrappers. Invalid inputs fail at construction time, not deep in your application logic.
+
+**Batteries included, but replaceable.** High-level `Agent` for convenience, or use stateless `XrpcCall` builder for full control. Mix and match as needed.
+
+---
+
+## Critical Patterns to Internalize
+
+### String Type Constructors
+
+ALL validated string types (Did, Handle, AtUri, Nsid, etc.) follow this pattern:
+
+```rust
+// ✅ PREFERRED: Zero-allocation for borrowed strings
+let did = Did::new("did:plc:abc123")?;  // Borrows from input
+
+// ✅ BEST: Zero-allocation for static strings
+let nsid = Nsid::new_static("com.atproto.repo.getRecord")?;
+
+// ✅ When you need ownership
+let owned = Did::new_owned("did:plc:abc123")?;
+
+// ❌ AVOID: FromStr always allocates
+let did: Did = "did:plc:abc123".parse()?;  // Always allocates!
+
+// ❌ NEVER: Roundtripping through String
+let s = did.as_str().to_string();
+let did2 = Did::new(&s)?;  // Pointless allocation
+```
+
+**Rule**: Use `new()` for borrowed, `new_static()` for `'static` strings, `new_owned()` when you have ownership. Avoid `FromStr::parse()` unless you don't care about allocations.
+
+### Response Parsing: Borrow vs Own
+
+XRPC responses wrap a `Bytes` buffer. You choose when to parse and whether to own the data:
+
+```rust
+let response = agent.send(request).await?;
+
+// Option 1: Borrow from response buffer (zero-copy)
+let output: GetPostOutput<'_> = response.parse()?;
+// ⚠️  `output` borrows from `response`, both must stay in scope
+
+// Option 2: Convert to owned (allocates, but can outlive response)
+let output: GetPostOutput<'static> = response.into_output()?;
+drop(response);  // OK, output is now fully owned
+
+// ❌ WRONG: Can't drop response while holding borrowed parse
+let output = response.parse()?;
+drop(response);  // ERROR: output borrows from response
+```
+
+**Rule**: Use `.parse()` when processing immediately in the same scope. Use `.into_output()` when returning from functions or storing long-term.
+
+### Lifetime Pattern: GATs Not HRTBs
+
+Jacquard uses **Generic Associated Types** on `XrpcResp` to avoid Higher-Rank Trait Bounds:
+
+```rust
+// ✅ Jacquard's approach (GAT)
+trait XrpcResp {
+    type Output<'de>: Deserialize<'de> + IntoStatic;
+    type Err<'de>: Error + Deserialize<'de> + IntoStatic;
+}
+
+// ❌ Alternative that forces DeserializeOwned semantics
+trait BadXrpcResp<'de> {
+    type Output: Deserialize<'de>;
+}
+// Would require: where R: for<'any> BadXrpcResp<'any>
+// This forces owned deserialization!
+```
+
+**Why this matters**: Async methods return `Response<R>` that owns the buffer. Caller controls lifetime by choosing `.parse()` (borrow) or `.into_output()` (owned). No HRTB needed, zero-copy works in async contexts.
+
+**When implementing custom types**: Use method-level lifetime generics (`<'de>`), not trait-level lifetimes.
+
+### CRITICAL: Never Use `for<'de> Deserialize<'de>` Bounds
+
+**The bound `T: for<'de> Deserialize<'de>` is EQUIVALENT to `T: DeserializeOwned`** and will break all Jacquard types.
+
+```rust
+// ❌ CATASTROPHIC - No Jacquard type can satisfy this
+fn bad<T>(data: &[u8]) -> Result<T>
+where
+    T: for<'de> Deserialize<'de>  // Forces owned deserialization!
+{
+    serde_json::from_slice(data)  // Can't borrow from data
+}
+
+// ✅ CORRECT - Use method-level lifetime
+fn good<'de, T>(data: &'de [u8]) -> Result<T>
+where
+    T: Deserialize<'de>  // Can borrow from data
+{
+    serde_json::from_slice(data)
+}
+```
+
+**Why this breaks**: `CowStr<'a>` and all Jacquard types need to borrow from the input buffer. The HRTB `for<'de>` means "must work with ANY lifetime", which forces the deserializer to allocate owned copies instead of borrowing.
+
+**What to do instead**: Always use method-level lifetime parameters (`<'de>`) and pass the lifetime through to the `Deserialize` bound. Jacquard's entire design (GATs, Response wrapper, IntoStatic) exists to make this pattern work in async contexts.
+
+---
+
+## Crate-by-Crate Guide
+
+### jacquard (Main Crate)
+
+**Primary entry point**: `Agent<A: AgentSession>`
+
+```rust
+use jacquard::client::{Agent, CredentialSession, MemorySessionStore};
+use jacquard::identity::PublicResolver;
+
+// App password auth
+let (session, _info) = CredentialSession::authenticated(
+    "alice.bsky.social".into(),
+    "app-password".into(),
+    None,  // session_id
+).await?;
+let agent = Agent::from(session);
+
+// Make typed XRPC calls
+use jacquard::api::app_bsky::feed::get_timeline::GetTimeline;
+let response = agent.send(&GetTimeline::new().limit(50).build()).await?;
+let timeline = response.into_output()?;
+```
+
+**Auto-refresh**: Both `CredentialSession` and `OAuthSession` automatically refresh tokens on 401/expired errors. One retry per request.
+
+**Typed record operations** (via `AgentSessionExt` trait):
+
+```rust
+use jacquard::api::app_bsky::feed::post::Post;
+
+// Create
+let post = Post::builder()
+    .text("Hello ATProto!")
+    .created_at(Datetime::now())
+    .build();
+agent.create_record(post, None).await?;
+
+// Get (type-safe!)
+let uri = Post::uri("at://did:plc:abc/app.bsky.feed.post/123")?;
+let response = agent.get_record::<Post>(&uri).await?;
+let post_output = response.parse()?;
+
+// Update with fetch-modify-put pattern
+agent.update_record::<Profile>(&uri, |profile| {
+    profile.display_name = Some("New Name".into());
+}).await?;
+```
+
+**Key traits**:
+- `AgentSession`: Common interface for both auth types
+- `XrpcClient`: Stateful XRPC (has base URI, auth tokens)
+- `HttpClient`: Low-level HTTP abstraction
+
+**Common mistake**: Not converting to owned when returning from functions. If your function returns `Post<'_>`, caller can't use it after function returns. Return `Post<'static>` and call `.into_static()` on the value.
+
+### jacquard-common (Foundation)
+
+**Core types**: `Did`, `Handle`, `AtUri`, `Nsid`, `Tid`, `Cid`, `CowStr`, `Data`, `RawData`
+
+**String type traits** (ALL validated types implement these):
+- `new(&str)` - Validates, borrows (zero alloc)
+- `new_static(&'static str)` - Validates, zero alloc
+- `new_owned(impl Into<String>)` - Validates, takes ownership
+- `raw(&str)` - Panics on invalid (use when you KNOW it's valid)
+- `unchecked(&str)` - Unsafe, no validation
+- `as_str(&self) -> &str` - Get string reference
+- `Display`, `FromStr`, `Serialize`, `Deserialize`, `IntoStatic`
+
+**CowStr internals**: Uses `SmolStr` for owned variant (inline storage ≤23 bytes), so most AT Protocol strings (handles, DIDs) don't heap allocate when owned, or are O(1) copy (due to the allocated variant using Arc<str>).
+
+**XRPC layer**:
+
+```rust
+// Stateless XRPC (with any HttpClient)
+use jacquard::common::xrpc::XrpcExt;
+let http = reqwest::Client::new();
+let response = http
+    .xrpc(Url::parse("https://bsky.social")?)
+    .auth(AuthorizationToken::Bearer(token))
+    .proxy(did)
+    .send(&request)
+    .await?;
+
+// Stateful XRPC (implement XrpcClient trait)
+let response = agent.send(request).await?;
+```
+
+**Data vs RawData**:
+- `Data<'a>`: Validated, type-inferred atproto values (strings parsed to Did/Handle/etc.)
+- `RawData<'a>`: Minimal validation, suitable for pass-through/relay use cases
+
+```rust
+// Convert typed → untyped → typed
+let post = Post::builder().text("test").build();
+let data: Data = to_data(&post)?;
+let post2: Post = from_data(&data)?;
+
+// NEVER use serde_json::Value
+// ❌ let value: serde_json::Value = ...;
+// ✅ let data: Data = ...;
+```
+
+**Streaming** (feature: `streaming`):
+- `ByteStream` / `ByteSink`: Platform-agnostic (works on WASM via `n0-future`)
+- `HttpClientExt::send_http_streaming()`: Stream response
+- `HttpClientExt::send_http_bidirectional()`: Stream both request and response
+
+**WebSocket** (feature: `websocket`):
+- `WebSocketClient` trait, `WebSocketConnection`
+- Native + WASM: tokio-tungstenite-wasm
+
+**Collection trait** (for record types):
+
+```rust
+pub trait Collection {
+    const NSID: &'static str;
+    type Record: XrpcResp;  // Marker type for get_record()
+}
+
+// Enables typed record retrieval:
+let response: Response<Post::Record> = agent.get_record(did, rkey).await?;
+```
+
+**Critical error**: Using types that don't implement `IntoStatic` in response positions. All generated API types do, but custom types need `#[derive(jacquard_derive::IntoStatic)]`.
+
+### jacquard-api (Generated Bindings)
+
+**764 lexicon schemas** across 52+ namespaces.
+
+**Feature organization**:
+- `minimal`: Core atproto only
+- `bluesky`: Bluesky app + chat + ozone
+- `other`: Curated third-party lexicons
+- `lexicon_community`: Community extensions
+- `ufos`: Experimental/niche
+
+**Generated patterns**:
+- All types have `'a` lifetime for zero-copy deserialization
+- All implement `IntoStatic`, `Serialize`, `Deserialize`, `Clone`, `PartialEq`, `Eq`
+- Builders (`bon::Builder`) on types with 2+ fields (some required)
+- Open unions have `Unknown(Data<'a>)` variant via `#[open_union]` macro
+- Objects have `extra_data: BTreeMap<SmolStr, Data<'a>>` via `#[lexicon]` macro
+
+**Union collision detection**: When multiple namespaces define similar types, foreign refs get prefixed:
+```rust
+// If both app.bsky.embed.images and sh.custom.embed.images exist:
+pub enum SomeUnion<'a> {
+    BskyImages(Box<app_bsky::embed::images::View<'a>>),
+    CustomImages(Box<sh_custom::embed::images::View<'a>>),
+}
+```
+
+**For each collection (record type)**, generated code includes:
+1. Main record struct (e.g., `Post<'a>`)
+2. `GetRecordOutput` wrapper (`PostGetRecordOutput<'a>` with uri, cid, value)
+3. Marker struct (`PostRecord`) implementing `XrpcResp`
+4. `Collection` trait impl
+5. Helper: `Post::uri()` for constructing typed URIs
+
+**For each XRPC endpoint**:
+1. Request struct with builder
+2. Output struct
+3. Error enum (open union, includes `Unknown` variant)
+4. Response marker implementing `XrpcResp`
+5. Request marker implementing `XrpcRequest`
+6. Endpoint marker implementing `XrpcEndpoint` (server-side)
+
+**Common mistakes**:
+- Not handling `Unknown` variant in union matches (non-exhaustive!)
+- Forgetting that when not using the builder pattern, or Default construction, you must supply `extra_data: BTreeMap::new()` in the constructor, in addition to explicitly named fields.
+- Calling `.into_static()` in tight loops (it clones all borrowed data)
+
+### jacquard-derive (Macros)
+
+**`#[lexicon]`**: Adds `extra_data` field to capture unknown fields during deserialization.
+
+```rust
+#[lexicon]
+#[derive(Serialize, Deserialize)]
+struct MyType<'a> {
+    known_field: CowStr<'a>,
+    // Macro adds: pub extra_data: BTreeMap<SmolStr, Data<'a>>
+}
+```
+
+With `bon::Builder`: Automatically adds `#[builder(default)]` to `extra_data`.
+
+**`#[open_union]`**: Adds `Unknown(Data<'a>)` variant to enums.
+
+```rust
+#[open_union]
+#[serde(tag = "$type")]
+enum MyUnion<'a> {
+    KnownVariant(Foo<'a>),
+    // Macro adds: #[serde(untagged)] Unknown(Data<'a>)
+}
+```
+
+**`#[derive(IntoStatic)]`**: Generates owned conversion.
+
+```rust
+#[derive(IntoStatic)]
+struct Post<'a> {
+    text: CowStr<'a>,
+    likes: u32,
+}
+
+// Generates:
+impl IntoStatic for Post<'_> {
+    type Output = Post<'static>;
+    fn into_static(self) -> Post<'static> {
+        Post {
+            text: self.text.into_static(),  // Converts to owned
+            likes: self.likes.into_static(),  // Passthrough (Copy)
+        }
+    }
+}
+```
+
+**`#[derive(XrpcRequest)]`**: Generates XRPC boilerplate for custom endpoints.
+
+```rust
+#[derive(Serialize, Deserialize, XrpcRequest)]
+#[xrpc(
+    nsid = "com.example.getThing",
+    method = Query,
+    output = GetThingOutput,
+    error = GetThingError,  // Optional, defaults to GenericError
+    server  // Optional, generates XrpcEndpoint marker
+)]
+struct GetThing<'a> {
+    #[serde(borrow)]
+    pub id: CowStr<'a>,
+}
+```
+
+**Critical**: All custom types with lifetimes MUST derive `IntoStatic` or manually implement it. Otherwise, you can't use them with `.into_output()`.
+
+### jacquard-oauth (OAuth/DPoP)
+
+**OAuth flow**:
+
+```rust
+use jacquard::oauth::client::OAuthClient;
+use jacquard::client::FileAuthStore;
+
+let oauth = OAuthClient::with_default_config(
+    FileAuthStore::new("./auth.json")
+);
+
+// Loopback flow (feature: loopback)
+let session = oauth.login_with_local_server(
+    "alice.bsky.social",
+    Default::default(),
+    LoopbackConfig::default(),
+).await?;
+
+let agent = Agent::from(session);
+```
+
+**DPoP proofs**: Automatically generated for every request. Include:
+- `jti`: Unique token ID (random)
+- `htm`: HTTP method
+- `htu`: Target URI
+- `iat`: Issued at timestamp
+- `nonce`: Server-provided (cached and retried on `use_dpop_nonce` error)
+- `ath`: SHA-256 hash of access token (when present)
+
+**Nonce handling**: Automatic retry on `use_dpop_nonce` errors (400 for auth server, 401 for PDS). Max one retry per request.
+
+**Nonce storage**:
+- `dpop_authserver_nonce`: For token endpoint
+- `dpop_host_nonce`: For PDS XRPC requests
+
+**Token refresh**: Automatic on `invalid_token` errors. Uses `SessionRegistry` with per-DID+session_id locks to prevent concurrent refresh races.
+
+**private_key_jwt**: For non-loopback clients. Automatically used if server supports it.
+
+**Issuer verification**: ALWAYS verify issuer has authority over the DID before trusting tokens. This is a **critical security check**.
+
+```rust
+// In callback flow, after exchanging code:
+let token_response = exchange_code(...).await?;
+// ⚠️  MUST verify before using token
+let pds = resolver.verify_issuer(&server_metadata, &token_response.sub).await?;
+```
+
+**Common mistakes**:
+- Skipping issuer verification (security vulnerability!)
+- Not updating session after refresh (next request uses expired token)
+- Reusing DPoP proofs across requests (each request needs a fresh proof with new jti/iat)
+- Mixing auth server and host nonces (they're tracked separately)
+- Forgetting `ath` claim when including access token in PDS requests
+
+### jacquard-identity (Identity Resolution)
+
+**Resolution chains** (configurable fallback order):
+
+**Handle → DID**:
+1. DNS TXT `_atproto.<handle>` (feature: `dns`, skipped on WASM)
+2. HTTPS `https://<handle>/.well-known/atproto-did`
+3. PDS XRPC `com.atproto.identity.resolveHandle`
+4. Public API fallback `https://public.api.bsky.app` (if enabled)
+5. Slingshot mini-doc (if configured)
+
+**DID → Document**:
+1. `did:web`: HTTPS `.well-known/did.json`
+2. `did:plc`: PLC directory or Slingshot
+3. PDS XRPC `com.atproto.identity.resolveDid`
+
+```rust
+use jacquard::identity::{JacquardResolver, PublicResolver};
+
+let resolver = PublicResolver::default();  // DNS + public fallbacks enabled
+
+// Handle → DID
+let did: Did<'static> = resolver.resolve_handle(&handle).await?;
+
+// DID → Document
+let response = resolver.resolve_did_doc(&did).await?;
+let doc = response.parse_validated()?;  // Validates doc.id matches requested DID
+
+// Combined: Get PDS endpoint
+let pds_url = resolver.pds_for_did(&did).await?;
+```
+
+**DidDocResponse pattern** (same as XRPC responses):
+
+```rust
+let response = resolver.resolve_did_doc(&did).await?;
+
+// Borrow from buffer
+let doc: DidDocument<'_> = response.parse()?;
+
+// Validate doc ID
+let doc = response.parse_validated()?;  // Error if doc.id != requested DID
+
+// Convert to owned
+let doc: DidDocument<'static> = response.into_owned()?;
+```
+
+**Mini-doc fallback**: If full DID document parsing fails, automatically tries parsing as `MiniDoc` (Slingshot's minimal format) and synthesizes a minimal `DidDocument`. This is transparent to caller.
+
+**OAuthResolver trait**: Auto-implemented for `JacquardResolver`. Adds OAuth metadata resolution:
+
+```rust
+// High-level: accepts handle, DID, or HTTPS URL
+let (server_metadata, doc_opt) = resolver.resolve_oauth("alice.bsky.social").await?;
+
+// From identity (handle or DID)
+let (server_metadata, doc) = resolver.resolve_from_identity("alice.bsky.social").await?;
+
+// From service URL (PDS or entryway)
+let server_metadata = resolver.resolve_from_service(&pds_url).await?;
+
+// Verify issuer authority over DID
+let pds = resolver.verify_issuer(&server_metadata, &sub_did).await?;
+```
+
+**Common mistakes**:
+- Not validating doc ID (use `.parse_validated()`, not just `.parse()`)
+- Assuming DNS resolution works on WASM (it doesn't)
+- Comparing issuer URLs with string equality (use `issuer_equivalent()` for trailing slash tolerance)
+- Trusting DID documents without checking `alsoKnownAs` for handle aliases
+- Not caching resolver (it's `Clone`, cheap to share)
+
+### jacquard-axum (Server-Side)
+
+**ExtractXrpc**: Type-safe XRPC request extraction.
+
+```rust
+use jacquard_axum::{ExtractXrpc, IntoRouter};
+use jacquard::api::com_atproto::identity::resolve_handle::ResolveHandleRequest;
+
+async fn handle_resolve(
+    ExtractXrpc(req): ExtractXrpc<ResolveHandleRequest>
+) -> Json<ResolveHandleOutput<'static>> {
+    let did = resolve_handle_logic(&req.handle).await;
+    Json(ResolveHandleOutput { did, extra_data: Default::default() })
+}
+
+// Automatic routing
+let app = Router::new()
+    .merge(ResolveHandleRequest::into_router(handle_resolve));
+```
+
+**Query vs Procedure**:
+- Query (GET): Extracts from query string via `serde_html_form`
+- Procedure (POST): Calls `Request::decode_body()` (default: JSON, override for CBOR)
+
+**Zero-copy → owned conversion**: Extractor borrows during deserialization, then converts to `'static` via `IntoStatic`. This is why all request types must implement `IntoStatic`.
+
+**Custom encodings**:
+
+```rust
+impl XrpcRequest for MyRequest<'_> {
+    fn decode_body<'de>(body: &'de [u8]) -> Result<Box<Self>> {
+        let req = serde_ipld_dagcbor::from_slice(body)?;
+        Ok(Box::new(req))
+    }
+}
+```
+
+**Service auth** (feature: `service-auth`):
+
+```rust
+use jacquard_axum::service_auth::{ServiceAuthConfig, ExtractServiceAuth};
+
+let config = ServiceAuthConfig::new(
+    Did::new_static("did:web:feedgen.example.com")?,
+    resolver,
+);
+
+async fn handler(
+    ExtractServiceAuth(auth): ExtractServiceAuth,
+) -> String {
+    format!("Authenticated as {}", auth.did())
+}
+
+let app = Router::new()
+    .route("/xrpc/app.bsky.feed.getFeedSkeleton", get(handler))
+    .with_state(config);
+```
+
+**Method binding (`lxm` claim)**: Default enabled. Binds JWTs to specific XRPC methods to prevent token reuse across endpoints.
+
+**JTI replay protection**: NOT built-in. You must implement:
+
+```rust
+if let Some(jti) = auth.jti() {
+    if state.seen_jtis.contains(jti) {
+        return Err(StatusCode::UNAUTHORIZED);
+    }
+    state.seen_jtis.insert(jti.to_string(), auth.exp);
+}
+```
+
+**Common mistakes**:
+- Forgetting `IntoStatic` derive on custom request types
+- Using wrong trait (use `XrpcEndpoint` marker, not `XrpcRequest`)
+- Not implementing JTI tracking (allows replay attacks)
+- Disabling method binding without understanding security implications
+
+### jacquard-repo (Repository Primitives)
+
+**MST (Merkle Search Tree)**: Immutable, persistent data structure.
+
+```rust
+use jacquard_repo::mst::Mst;
+use jacquard_repo::storage::MemoryBlockStore;
+
+let storage = MemoryBlockStore::new();
+let mst = Mst::new(storage.clone());
+
+// ⚠️  IMMUTABLE: Always reassign
+let mst = mst.add("app.bsky.feed.post/abc", record_cid).await?;
+let mst = mst.add("app.bsky.feed.post/xyz", record_cid2).await?;
+
+// Persist and get root CID
+let root_cid = mst.persist().await?;
+```
+
+**Key validation**: `[a-zA-Z0-9._:~-]+` with exactly one `/` separator. Max 256 bytes. Format: `collection/rkey`.
+
+**Diff operations**:
+
+```rust
+let diff = old_mst.diff(&new_mst).await?;
+diff.validate_limits()?;  // Enforce 200 op limit (protocol)
+
+// Convert to different formats
+let verified_ops = diff.to_verified_ops();  // For batch()
+let repo_ops = diff.to_repo_ops();  // For firehose
+```
+
+**Commits**:
+
+```rust
+use jacquard_repo::commit::Commit;
+
+// Create and sign
+let commit = Commit::new_unsigned(did, data_cid, rev, prev_cid)
+    .sign(&signing_key)?;
+
+// Verify
+commit.verify(&public_key)?;
+```
+
+**Supported signature algorithms**: Ed25519, ECDSA P-256, ECDSA secp256k1.
+
+**Firehose validation**:
+
+```rust
+// Sync v1.0 (requires prev MST state)
+let new_root = commit.validate_v1_0(prev_mst_root, prev_storage, pubkey).await?;
+
+// Sync v1.1 (inductive, requires prev_data field + op prev CIDs)
+let new_root = commit.validate_v1_1(pubkey).await?;
+```
+
+**v1.1 inductive validation**: Inverts operations on claimed result, verifies inverted result matches `prev_data`. Requires:
+- `prev_data` field in commit
+- All operations have `prev` CIDs for updates/deletes
+- All required MST blocks in CAR
+
+**CAR I/O**:
+
+```rust
+// Read
+let parsed = parse_car_bytes(&bytes)?;
+let root_cid = parsed.root;
+let blocks = parsed.blocks;  // BTreeMap<CID, Bytes>
+
+// Write
+let bytes = write_car_bytes(root_cid, blocks)?;
+```
+
+**BlockStore trait**: Pluggable storage backend.
+
+```rust
+#[trait_variant::make(Send)]  // Conditionally Send on non-WASM
+pub trait BlockStore: Clone {
+    async fn get(&self, cid: &CID) -> Result<Option<Bytes>>;
+    async fn put(&self, data: &[u8]) -> Result<CID>;
+    async fn apply_commit(&self, commit: CommitData) -> Result<()>;  // Atomic
+}
+```
+
+**Implementations**:
+- `MemoryBlockStore`: In-memory (testing)
+- `FileBlockStore`: File-based (persistent)
+- `LayeredBlockStore`: Read-through cache (e.g., temp over persistent for firehose)
+
+**Repository API** (high-level):
+
+```rust
+use jacquard_repo::repo::Repository;
+
+let repo = Repository::create(storage, did, signing_key, None).await?;
+
+// Single operations (don't auto-commit)
+repo.create_record(collection, rkey, cid).await?;
+let old_cid = repo.update_record(collection, rkey, new_cid).await?;
+let deleted_cid = repo.delete_record(collection, rkey).await?;
+
+// Batch commit
+let ops = vec![
+    RecordWriteOp::Create { collection, rkey, record },
+    RecordWriteOp::Update { collection, rkey, record, prev },
+];
+let (repo_ops, commit_data) = repo.create_commit(&ops, &did, prev, &key).await?;
+repo.apply_commit(commit_data).await?;
+```
+
+**Common mistakes**:
+- Forgetting immutability (not reassigning MST operations)
+- Not calling `validate_limits()` before creating commits (protocol violation)
+- Using v1.1 validation without `prev_data` field (will fail)
+- Missing `prev` CIDs on update/delete operations for v1.1
+- Not implementing `Clone` cheaply on custom `BlockStore` (use `Arc` internally)
+- Ignoring CID mismatch errors (indicates data corruption)
+
+### jacquard-lexicon (Code Generation)
+
+**ONLY use `just` commands** for code generation:
+
+```bash
+just lex-gen      # Fetch + generate
+just lex-fetch    # Fetch only
+just codegen      # Generate from existing lexicons
+```
+
+**Union collision detection**: When multiple namespaces have similar type names in a union, foreign refs get prefixed with second NSID segment:
+
+```
+app.bsky.embed.images → BskyImages
+sh.custom.embed.images → CustomImages
+```
+
+**Builder heuristics**:
+- Has builder: 1+ required fields, not all bare `CowStr`
+- Has `Default`: 0 required fields OR all required are bare `CowStr`
+
+**Empty objects**: Generate as empty structs with `#[lexicon]` attribute (adds `extra_data`), not as `Data<'a>`.
+
+**Local refs**: `#fragment` normalized to `{current_nsid}#fragment` during generation.
+
+**Feature generation**: Tracks cross-namespace dependencies:
+
+```toml
+net_anisota = ["app_bsky"]  # Uses Bluesky embeds
+```
+
+**Token types**: Unit structs with `Display` impl:
+
+```rust
+pub struct ClickthroughAuthor;
+impl Display for ClickthroughAuthor {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "clickthroughAuthor")
+    }
+}
+```
+
+**Common mistakes**: Running codegen commands manually without `just` (wrong flags, paths).
+
+---
+
+## Anti-Patterns to Avoid
+
+### ❌ Roundtripping through String
+
+```rust
+// ❌ BAD
+let did_str = did.as_str().to_string();
+let did2 = Did::new(&did_str)?;
+
+// ✅ GOOD
+let did2 = did.clone();
+// or
+let did2 = did.into_static();  // If you need 'static
+```
+
+### ❌ Using serde_json::Value
+
+```rust
+// ❌ NEVER
+let value: serde_json::Value = serde_json::from_slice(bytes)?;
+let post: Post = serde_json::from_value(value)?;
+
+// ✅ ALWAYS
+let data: Data = serde_json::from_slice(bytes)?;
+let post: Post = from_data(&data)?;
+```
+
+### ❌ Using FromStr for validated types
+
+```rust
+// ❌ SLOW (always allocates)
+let did: Did = "did:plc:abc".parse()?;
+
+// ✅ FAST (zero allocation)
+let did = Did::new("did:plc:abc")?;
+```
+
+### ❌ Not deriving IntoStatic on custom types
+
+```rust
+// ❌ WILL NOT COMPILE with XRPC responses
+struct MyOutput<'a> {
+    field: CowStr<'a>,
+}
+
+// ✅ REQUIRED
+#[derive(jacquard_derive::IntoStatic)]
+struct MyOutput<'a> {
+    field: CowStr<'a>,
+}
+```
+
+### ❌ Dropping response while holding borrowed parse
+
+```rust
+// ❌ WILL NOT COMPILE
+let output = {
+    let response = agent.send(request).await?;
+    response.parse()?  // Borrows from response!
+};
+
+// ✅ Keep response alive OR convert to owned
+let response = agent.send(request).await?;
+let output = response.parse()?;
+// OR
+let output = agent.send(request).await?.into_output()?;
+```
+
+### ❌ Calling .into_static() in tight loops
+
+```rust
+// ❌ WASTEFUL (clones all borrowed data every iteration)
+for post in timeline.feed {
+    let owned = post.into_static();
+    process(owned);
+}
+
+// ✅ EFFICIENT (borrow when possible)
+for post in &timeline.feed {
+    process(post);
+}
+
+// Only convert to static if storing long-term:
+let stored: Vec<Post<'static>> = timeline.feed.into_iter()
+    .map(|p| p.into_static())
+    .collect();
+```
+
+### ❌ Non-exhaustive union matches
+
+```rust
+// ❌ WILL NOT COMPILE (missing Unknown variant)
+match embed {
+    PostEmbed::Images(img) => { /* ... */ }
+    PostEmbed::Video(vid) => { /* ... */ }
+}
+
+// ✅ HANDLE ALL VARIANTS
+match embed {
+    PostEmbed::Images(img) => { /* ... */ }
+    PostEmbed::Video(vid) => { /* ... */ }
+    _ => { /* Unknown or other variants */ }
+}
+```
+
+### ❌ Forgetting MST immutability
+
+```rust
+// ❌ WRONG (loses result)
+mst.add(key, cid).await?;
+
+// ✅ CORRECT (reassign)
+let mst = mst.add(key, cid).await?;
+```
+
+### ❌ Skipping issuer verification in OAuth
+
+```rust
+// ❌ SECURITY VULNERABILITY
+let token_response = exchange_code(...).await?;
+// Immediately trusting token_response.sub without verification!
+
+// ✅ ALWAYS VERIFY
+let token_response = exchange_code(...).await?;
+let pds = resolver.verify_issuer(&server_metadata, &token_response.sub).await?;
+// Now safe to use token_response
+```
+
+### ❌ Using `for<'de> Deserialize<'de>` bounds (CATASTROPHIC)
+
+**This is the SINGLE MOST COMMON mistake LLMs make with Jacquard.** The HRTB `for<'de>` forces owned deserialization and breaks ALL Jacquard types.
+
+```rust
+// ❌ CATASTROPHIC - Breaks all Jacquard types
+fn deserialize_anything<T>(data: &[u8]) -> Result<T>
+where
+    T: for<'de> Deserialize<'de>  // Equivalent to DeserializeOwned!
+{
+    serde_json::from_slice(data)
+}
+
+// Attempting to use:
+let post: Post = deserialize_anything(&bytes)?;  // ERROR: Post<'_> doesn't satisfy bound
+
+// ❌ Also breaks in generic contexts
+struct MyContainer<T>
+where
+    T: for<'de> Deserialize<'de>  // No Jacquard type can be stored here!
+{
+    value: T,
+}
+
+// ❌ Even if you think you need it for async
+async fn fetch<T>(url: &str) -> Result<T>
+where
+    T: for<'de> Deserialize<'de>  // Still wrong! Use Response<R> pattern instead
+{
+    let bytes = http_get(url).await?;
+    serde_json::from_slice(&bytes)  // Can't borrow, bytes about to be dropped
+}
+```
+
+```rust
+// ✅ CORRECT - Method-level lifetime
+fn deserialize_anything<'de, T>(data: &'de [u8]) -> Result<T>
+where
+    T: Deserialize<'de>
+{
+    serde_json::from_slice(data)
+}
+
+// ✅ CORRECT - With IntoStatic for async
+fn deserialize_owned<'de, T>(data: &'de [u8]) -> Result<T::Output>
+where
+    T: Deserialize<'de> + IntoStatic,
+    T::Output: 'static,
+{
+    let borrowed: T = serde_json::from_slice(data)?;
+    Ok(borrowed.into_static())
+}
+
+// ✅ CORRECT - Use Jacquard's Response pattern for async
+async fn fetch<R: XrpcRequest>(url: &str) -> Result<Response<R::Response>> {
+    let bytes = http_get(url).await?;
+    Ok(Response::new(bytes))  // Caller chooses .parse() or .into_output()
+}
+```
+
+**Why `for<'de>` breaks**: It means "T must deserialize from ANY lifetime", which is impossible if T contains borrowed data. The deserializer can't satisfy "any lifetime" including lifetimes shorter than the input buffer, so it forces owned allocation.
+
+**Rule**: If you see `for<'de> Deserialize<'de>` anywhere in your code with Jacquard types, it's wrong. Use method-level `<'de>` parameters and propagate lifetimes explicitly.
+
+---
+
+## WASM Compatibility
+
+Core crates support `wasm32-unknown-unknown` target:
+- jacquard-common
+- jacquard-api
+- jacquard-identity (no DNS resolution)
+- jacquard-oauth
+
+**Pattern**: `#[cfg_attr(not(target_arch = "wasm32"), trait_variant::make(Send))]`
+
+**What's different on WASM**:
+- No `Send` bounds on traits
+- DNS resolution skipped in handle→DID chain
+- Tokio-specific features disabled
+
+**Test WASM compilation**:
+
+```bash
+just check-wasm
+# or
+cargo build --target wasm32-unknown-unknown -p jacquard-common --no-default-features
+```
+
+---
+
+## Quick Reference
+
+### String Type Constructors
+
+| Method | Allocates? | Use When |
+|--------|-----------|----------|
+| `new(&str)` | No | Borrowed string |
+| `new_static(&'static str)` | No | Static string literal |
+| `new_owned(String)` | Reuses | Already have owned String |
+| `FromStr::parse()` | Yes | Don't care about performance |
+
+### Response Parsing
+
+| Method | Lifetime | Allocates? |
+|--------|----------|-----------|
+| `.parse()` | `<'_>` | No (zero-copy) |
+| `.into_output()` | `'static` | Yes (converts to owned) |
+
+### XRPC Traits
+
+| Trait | Side | Purpose |
+|-------|------|---------|
+| `XrpcRequest` | Client + Server | Request with NSID, method, encode/decode |
+| `XrpcResp` | Client + Server | Response marker with GAT Output/Err |
+| `XrpcEndpoint` | Server | Routing marker with PATH, METHOD |
+| `XrpcClient` | Client | Stateful XRPC with base_uri, send() |
+| `XrpcExt` | Client | Stateless XRPC builder on any HttpClient |
+
+### Session Types
+
+| Type | Auth Method | Auto-Refresh | Storage |
+|------|------------|--------------|---------|
+| `CredentialSession` | Bearer (app password) | Via refreshSession | SessionStore |
+| `OAuthSession` | DPoP (OAuth) | Via token endpoint | ClientAuthStore |
+
+### BlockStore Implementations
+
+| Type | Persistent? | Use Case |
+|------|------------|----------|
+| `MemoryBlockStore` | No | Testing |
+| `FileBlockStore` | Yes | Production |
+| `LayeredBlockStore` | Depends | Read-through cache |
+
+---
+
+## Common Operations
+
+### Making an XRPC call
+
+```rust
+use jacquard::api::app_bsky::feed::get_author_feed::GetAuthorFeed;
+
+let request = GetAuthorFeed::new()
+    .actor("alice.bsky.social".into())
+    .limit(50)
+    .build();
+
+let response = agent.send(request).await?;
+let output = response.into_output()?;
+
+for post in output.feed {
+    println!("{}: {}", post.post.author.handle, post.post.uri);
+}
+```
+
+### Creating a record
+
+```rust
+use jacquard::api::app_bsky::feed::post::Post;
+use jacquard::common::types::string::Datetime;
+
+let post = Post::builder()
+    .text("Hello ATProto from Jacquard!")
+    .created_at(Datetime::now())
+    .build();
+
+agent.create_record(post, None).await?;
+```
+
+### Resolving identity
+
+```rust
+use jacquard::identity::PublicResolver;
+
+let resolver = PublicResolver::default();
+
+// Handle → DID
+let did = resolver.resolve_handle(&handle).await?;
+
+// DID → PDS endpoint
+let pds = resolver.pds_for_did(&did).await?;
+
+// Combined
+let (did, pds) = resolver.pds_for_handle(&handle).await?;
+```
+
+### OAuth login
+
+```rust
+use jacquard::oauth::client::OAuthClient;
+use jacquard::client::FileAuthStore;
+
+let oauth = OAuthClient::with_default_config(
+    FileAuthStore::new("./auth.json")
+);
+
+let session = oauth.login_with_local_server(
+    "alice.bsky.social",
+    Default::default(),
+    Default::default(),
+).await?;
+
+let agent = Agent::from(session);
+```
+
+### Server-side XRPC handler
+
+```rust
+use jacquard_axum::{ExtractXrpc, IntoRouter};
+use axum::{Router, Json};
+
+async fn handler(
+    ExtractXrpc(req): ExtractXrpc<MyRequest>
+) -> Json<MyOutput<'static>> {
+    // Process request
+    Json(output)
+}
+
+let app = Router::new()
+    .merge(MyRequest::into_router(handler));
+```
+
+### MST operations
+
+```rust
+use jacquard_repo::mst::Mst;
+use jacquard_repo::storage::MemoryBlockStore;
+
+let storage = MemoryBlockStore::new();
+let mst = Mst::new(storage.clone());
+
+let mst = mst.add("app.bsky.feed.post/abc123", record_cid).await?;
+let mst = mst.add("app.bsky.feed.post/xyz789", record_cid2).await?;
+
+let root_cid = mst.persist().await?;
+```
+
+---
+
+## Documentation Links
+
+- [docs.rs/jacquard](https://docs.rs/jacquard/latest/jacquard/)
+- [docs.rs/jacquard-common](https://docs.rs/jacquard-common/latest/jacquard_common/)
+- [docs.rs/jacquard-api](https://docs.rs/jacquard-api/latest/jacquard_api/)
+- [docs.rs/jacquard-oauth](https://docs.rs/jacquard-oauth/latest/jacquard_oauth/)
+- [docs.rs/jacquard-identity](https://docs.rs/jacquard-identity/latest/jacquard_identity/)
+- [docs.rs/jacquard-repo](https://docs.rs/jacquard-repo/latest/jacquard_repo/)
+- [docs.rs/jacquard-axum](https://docs.rs/jacquard-axum/latest/jacquard_axum/)
+- [Repository](https://tangled.org/@nonbinary.computer/jacquard)
+
+---
+
+## Philosophy Summary
+
+Jacquard is designed for **correctness**, **performance**, and **ergonomics** in that order. It favors:
+
+1. **Validation at construction time** - Invalid inputs fail fast, not deep in your code
+2. **Zero-copy by default** - Borrow from buffers, convert to owned only when needed
+3. **Explicit lifetime control** - You choose when to allocate via `.into_static()` or `.into_output()`
+4. **Type safety without boilerplate** - Generated bindings just work, with strong typing
+5. **Batteries included, but replaceable** - High-level `Agent` for convenience, low-level primitives for control
+
+**When in doubt**: Read the documentation, use the validated types, respect the lifetimes, and trust the zero-copy patterns. Jacquard is designed to guide you toward correct, performant code.