feat(examples): add AT Protocol example tools and GUIDE

Add four example tools demonstrating AT Protocol library usage:

- bsky_bot: Bluesky bot for posting, timeline, profiles, following
- feed_generator: Firehose client with filtering and feed skeleton
(evolved from firehose_demo with keyword filtering)
- identity_tool: Handle/DID resolution and identity verification
- repo_inspector: Repository exploration with auto PDS resolution

Key improvements:
- repo_inspector now auto-resolves PDS from DID document
- Added --pds option to skip auto-resolution
- Fixed URL encoding issue (? was incorrectly encoded as %3F)

Add GUIDE.md showing complete workflow: firehose -> identity -> repo

Remove deprecated firehose_demo in favor of feed_generator.

.beads/issues.jsonl

···
 {"id":"atproto-61","title":"Set up interoperability test suite","description":"Set up and run the AT Protocol interoperability tests from bluesky-social/atproto-interop-tests.","design":"## Test Structure\n\n```\ntest/\n├── interop/\n│   ├── syntax_test.ml      # Handle, DID, NSID, TID, etc.\n│   ├── crypto_test.ml      # Signatures, did:key\n│   ├── data_model_test.ml  # DAG-CBOR, CID\n│   ├── mst_test.ml         # Key heights, tree structure\n│   ├── lexicon_test.ml     # Schema and record validation\n│   └── firehose_test.ml    # Commit proofs\n├── fixtures/               # Cloned from atproto-interop-tests\n└── dune\n```\n\n## Test Approach\n\n1. Clone test vectors from GitHub\n2. Parse JSON fixtures using jsont\n3. Parse text fixtures line by line\n4. Run each test case\n5. Compare output to expected values\n\n## Example Test\n\n```ocaml\nlet load_json_fixtures path =\n  let json = Jsont.of_file path in\n  Jsont.decode (Jsont.list fixture_jsont) json\n\nlet%test \"handle_syntax_valid\" =\n  let fixtures = load_lines \"fixtures/syntax/handle_syntax_valid.txt\" in\n  List.for_all (fun line -\u003e\n    match Handle.of_string line with\n    | Ok _ -\u003e true\n    | Error _ -\u003e false\n  ) fixtures\n\nlet%test \"handle_syntax_invalid\" =\n  let fixtures = load_lines \"fixtures/syntax/handle_syntax_invalid.txt\" in\n  List.for_all (fun line -\u003e\n    match Handle.of_string line with\n    | Ok _ -\u003e false\n    | Error _ -\u003e true\n  ) fixtures\n\nlet%test \"crypto_signature_fixtures\" =\n  let fixtures = load_json_fixtures \"fixtures/crypto/signature-fixtures.json\" in\n  List.for_all (fun fixture -\u003e\n    let message = Base64.decode fixture.message_base64 in\n    let signature = Base64.decode fixture.signature_base64 in\n    let key = Did_key.of_string fixture.public_key_did in\n    let result = Crypto.verify key message signature in\n    result = fixture.valid_signature\n  ) fixtures\n```\n\n## Dependencies\n- alcotest or ounit2\n- jsont","acceptance_criteria":"- All syntax interop tests pass\n- All crypto interop tests pass\n- All data-model interop tests pass\n- All MST interop tests pass\n- All lexicon interop tests pass\n- All firehose interop tests pass","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-28T00:12:40.553908313+01:00","updated_at":"2025-12-28T13:25:34.614867702+01:00","closed_at":"2025-12-28T13:25:34.614867702+01:00","labels":["conformance","testing"],"dependencies":[{"issue_id":"atproto-61","depends_on_id":"atproto-1","type":"parent-child","created_at":"2025-12-28T00:12:56.180809368+01:00","created_by":"daemon"}]}
 {"id":"atproto-62","title":"Set up monorepo package structure","description":"Set up the monorepo structure for multiple opam packages within a single repository.","design":"## Repository Structure\n\n```\natproto/\n├── dune-project           # Root with all packages\n├── packages/\n│   ├── atproto-syntax/\n│   │   ├── lib/\n│   │   │   ├── dune\n│   │   │   └── *.ml\n│   │   ├── test/\n│   │   │   ├── dune\n│   │   │   └── *_test.ml\n│   │   └── atproto-syntax.opam\n│   ├── atproto-crypto/\n│   ├── atproto-multibase/\n│   ├── atproto-ipld/\n│   ├── atproto-mst/\n│   ├── atproto-repo/\n│   ├── atproto-identity/\n│   ├── atproto-xrpc/\n│   ├── atproto-sync/\n│   ├── atproto-lexicon/\n│   ├── atproto-lexicon-gen/\n│   ├── atproto-api/\n│   └── atproto-effects/\n├── examples/\n│   ├── simple_client/\n│   └── firehose_consumer/\n└── interop-tests/\n```\n\n## dune-project\n\n```lisp\n(lang dune 3.20)\n(name atproto)\n(generate_opam_files true)\n\n(package\n (name atproto-syntax)\n (synopsis \"AT Protocol identifier syntax parsing\")\n (depends\n  (ocaml (\u003e= 5.4))\n  re\n  ptime))\n\n(package\n (name atproto-crypto)\n ...)\n```\n\n## CI (.github/workflows/ci.yml)\n\n- OCaml 5.4 matrix\n- Build all packages\n- Run all tests\n- Run interop tests","acceptance_criteria":"- Multi-package dune-project structure\n- Separate opam files per package\n- CI pipeline for building and testing\n- Documentation generation setup","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-28T00:12:50.547102438+01:00","updated_at":"2025-12-28T11:57:18.856810633+01:00","closed_at":"2025-12-28T11:57:18.856810633+01:00","labels":["infrastructure","setup"],"dependencies":[{"issue_id":"atproto-62","depends_on_id":"atproto-1","type":"parent-child","created_at":"2025-12-28T00:12:57.015938611+01:00","created_by":"daemon"}]}
 {"id":"atproto-cir","title":"Implement DAG-JSON codec","description":"Create lib/ipld/dag_json.ml, encode Links as {\"/\": \"\u003ccid-string\u003e\"}, encode Bytes as {\"/\": {\"bytes\": \"\u003cbase64\u003e\"}}","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-28T15:47:30.578398468+01:00","updated_at":"2025-12-28T16:06:13.475583417+01:00","closed_at":"2025-12-28T16:06:13.475583417+01:00","labels":["compliance","ipld"]}
+{"id":"atproto-ex-bot","title":"Implement Bluesky Bot Example (bsky_bot)","description":"Bot that can login, post with rich text, reply to mentions, follow back. Uses atproto-api Agent, Richtext, atproto-xrpc Client. Eio for I/O, Climate for CLI.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T09:07:59.407148786+01:00","updated_at":"2025-12-29T09:16:27.789416628+01:00","closed_at":"2025-12-29T09:16:27.789416628+01:00","labels":["api","bot","cli","example"]}
+{"id":"atproto-ex-feed","title":"Implement Feed Generator Example (feed_generator)","description":"Custom feed algorithm with XRPC server serving app.bsky.feed.getFeedSkeleton. Subscribes to firehose, filters posts by keyword/language. Uses atproto-xrpc Server, atproto-sync Firehose.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T09:08:01.619973249+01:00","updated_at":"2025-12-29T09:18:53.434611454+01:00","closed_at":"2025-12-29T09:18:53.434611454+01:00","labels":["example","feed","firehose","server"]}
+{"id":"atproto-ex-identity","title":"Implement Handle/DID Lookup Tool (identity_tool)","description":"CLI tool using Climate to resolve handles to DIDs, DIDs to documents, verify bidirectional identity links. Uses atproto-identity, atproto-syntax. Eio for I/O.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T09:07:57.316042741+01:00","updated_at":"2025-12-29T09:12:20.634271257+01:00","closed_at":"2025-12-29T09:12:20.634271257+01:00","labels":["cli","example","identity"]}
+{"id":"atproto-ex-repo","title":"Implement Repository Inspector Example (repo_inspector)","description":"Tool to explore AT Protocol repositories: download CAR, parse MST structure, show records with CIDs, verify commit signatures. Uses atproto-repo, atproto-mst, atproto-ipld, atproto-crypto.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T09:08:03.622391028+01:00","updated_at":"2025-12-29T09:21:32.223029796+01:00","closed_at":"2025-12-29T09:21:32.223029796+01:00","labels":["cli","educational","example","repo"]}
 {"id":"atproto-fw8","title":"Add filter option to firehose demo","description":"Add --filter option to firehose demo to filter events by type (posts, likes, follows, reposts, profiles, blocks, lists, etc.). This makes it easier to monitor specific activity types.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-28T21:08:20.29215305+01:00","updated_at":"2025-12-28T21:13:31.957432542+01:00","closed_at":"2025-12-28T21:13:31.957432542+01:00","labels":["demo","enhancement","firehose"]}
 {"id":"atproto-h09","title":"Add package documentation","description":"Add documentation for each of the 11 AT Protocol packages including:\n- Module-level documentation with examples\n- README.md for the root project\n- CONTRIBUTING.md guide\n- API documentation generation with odoc","status":"closed","priority":2,"issue_type":"task","assignee":"claude","created_at":"2025-12-28T13:34:10.559554696+01:00","updated_at":"2025-12-28T13:50:20.509417248+01:00","closed_at":"2025-12-28T13:50:20.509417248+01:00","labels":["documentation"],"dependencies":[{"issue_id":"atproto-h09","depends_on_id":"atproto-1","type":"parent-child","created_at":"2025-12-28T13:34:16.081103184+01:00","created_by":"daemon"}]}
 {"id":"atproto-kc7","title":"Verify/enforce CBOR strictness","description":"Check that CBOR library produces shortest-form encoding, add explicit rejection of indefinite-length items during decode","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-12-28T15:47:28.665226526+01:00","updated_at":"2025-12-28T16:02:55.549763384+01:00","closed_at":"2025-12-28T16:02:55.549763384+01:00","labels":["compliance","ipld"]}

examples/GUIDE.md

···
+# AT Protocol Tools Guide
+
+This guide demonstrates how to use the example tools together to explore the AT Protocol ecosystem. We'll walk through a complete workflow: finding interesting posts in the firehose, investigating user identities, and inspecting their repositories.
+
+## Prerequisites
+
+Build all examples:
+
+```bash
+dune build examples/
+```
+
+Set up your credentials for `bsky_bot` (required for authenticated operations):
+
+```bash
+export BSKY_USER="yourhandle.bsky.social"
+export BSKY_PASS="xxxx-xxxx-xxxx-xxxx"  # App password from Settings > App Passwords
+```
+
+## Overview of Tools
+
+| Tool | Purpose |
+|------|---------|
+| `feed_generator` | Subscribe to the firehose and filter events |
+| `identity_tool` | Resolve handles/DIDs and verify identities |
+| `repo_inspector` | Download and explore user repositories |
+| `bsky_bot` | Interact with Bluesky (post, timeline, profiles) |
+
+---
+
+## Step 1: Find Interesting Posts with feed_generator
+
+Start by subscribing to the firehose and filtering for posts containing a keyword of interest. Let's look for posts about "ocaml":
+
+```bash
+`dune exec examples/feed_generator/feed_generator.exe -- \
+  --filter posts \
+  --keyword "ocaml" \
+  --limit 5 \
+  --content`
+```
+
+Example output:
+
+```
+Feed Generator
+==============
+
+Type filter: posts
+Keyword: "ocaml"
+
+Connecting to wss://bsky.network/xrpc/com.atproto.sync.subscribeRepos...
+Connected!
+
+#commit seq=12345678 repo=did:plc:abc123xyz456
+        +app.bsky.feed.post/3abc123 "Just discovered OCaml! The type system is amazing..."
+#commit seq=12345680 repo=did:plc:def789uvw012
+        +app.bsky.feed.post/3def456 "Working on my first OCaml project today..."
+
+--- Stats: 1523 events (5 matched) | seq=12345700 | 8.2s | 185.7 evt/s ---
+```
+
+**Key information extracted:**
+- `did:plc:abc123xyz456` - The DID of a user who posted about OCaml
+- `app.bsky.feed.post/3abc123` - The record key of their post
+
+### Generating a Feed Skeleton
+
+If you want to build a custom feed, use the `--skeleton` flag to output a feed skeleton:
+
+```bash
+dune exec examples/feed_generator/feed_generator.exe -- \
+  --filter posts \
+  --keyword "rust" \
+  --limit 20 \
+  --skeleton
+```
+
+This outputs a JSON structure you can serve via `app.bsky.feed.getFeedSkeleton`:
+
+```json
+{
+  "feed": [
+    {"post": "at://did:plc:xxx/app.bsky.feed.post/abc123"},
+    {"post": "at://did:plc:yyy/app.bsky.feed.post/def456"}
+  ]
+}
+```
+
+### Monitoring Multiple Event Types
+
+Watch for posts, likes, and follows simultaneously:
+
+```bash
+dune exec examples/feed_generator/feed_generator.exe -- \
+  --filter posts,likes,follows \
+  --limit 50
+```
+
+---
+
+## Step 2: Verify User Identity with identity_tool
+
+Now that we have a DID from the firehose, let's verify the identity and get more details about the user.
+
+### Verify Identity (Bidirectional)
+
+The default mode verifies that the DID and handle point to each other:
+
+```bash
+dune exec examples/identity_tool/identity_tool.exe -- did:plc:abc123xyz456
+```
+
+Example output:
+
+```
+PASSED
+DID:    did:plc:abc123xyz456
+Handle: alice.bsky.social
+Key:    zQ3shXjHeiBuRCKmM...
+PDS:    https://morel.us-east.host.bsky.network
+```
+
+This tells us:
+- The identity verification passed (handle and DID are correctly linked)
+- The user's handle is `alice.bsky.social`
+- Their signing key (for verifying commits)
+- Their PDS (Personal Data Server) URL
+
+### Resolve Handle to DID
+
+If you have a handle and need the DID:
+
+```bash
+dune exec examples/identity_tool/identity_tool.exe -- -H alice.bsky.social
+```
+
+Output:
+
+```
+Handle: alice.bsky.social
+DID:    did:plc:abc123xyz456
+```
+
+### Resolve DID to Full Document
+
+Get the complete DID document with all services and keys:
+
+```bash
+dune exec examples/identity_tool/identity_tool.exe -- -d did:plc:abc123xyz456
+```
+
+Output:
+
+```
+DID:     did:plc:abc123xyz456
+Handle:  at://alice.bsky.social
+Key:     zQ3shXjHeiBuRCKmM... (Multikey)
+Service: AtprotoPersonalDataServer -> https://morel.us-east.host.bsky.network
+```
+
+---
+
+## Step 3: Inspect User Repository with repo_inspector
+
+With the verified DID, we can download and inspect the user's entire repository. The tool automatically resolves the user's PDS from their DID document.
+
+### Repository Summary
+
+Get an overview of the repository:
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- did:plc:abc123xyz456
+```
+
+Example output:
+
+```
+Repository Inspector
+====================
+
+Resolving PDS for did:plc:abc123xyz456...
+PDS: https://morel.us-east.host.bsky.network
+
+Fetching https://morel.us-east.host.bsky.network/xrpc/com.atproto.sync.getRepo?did=did:plc:abc123xyz456...
+
+CAR Header
+----------
+Version: 1
+Roots:   1
+  - bafyreib...
+Blocks:  1234
+
+Commit
+------
+DID:     did:plc:abc123xyz456
+Version: 3
+Rev:     3la7j2xyz...
+Data:    bafyreic...
+
+Collections
+-----------
+  app.bsky.feed.post: 456
+  app.bsky.feed.like: 789
+  app.bsky.graph.follow: 123
+  app.bsky.actor.profile: 1
+
+Total records: 1369
+```
+
+### List Collections
+
+See all collections with record counts:
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- \
+  did:plc:abc123xyz456 --collections
+```
+
+### Browse Records
+
+View individual records:
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- \
+  did:plc:abc123xyz456 --records --limit 10
+```
+
+Output:
+
+```
+Records
+-------
+app.bsky.feed.post/3abc123
+  CID: bafyreig...
+  Text: Just discovered OCaml! The type system is amazing...
+
+app.bsky.feed.post/3def456
+  CID: bafyreih...
+  Text: Working on my second OCaml project...
+
+... and 454 more
+```
+
+### Filter by Collection
+
+View only posts:
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- \
+  did:plc:abc123xyz456 --records --collection app.bsky.feed.post --limit 20
+```
+
+View only follows:
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- \
+  did:plc:abc123xyz456 --records --collection app.bsky.graph.follow --limit 20
+```
+
+### Verify Commit Signature
+
+Check the repository commit signature:
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- \
+  did:plc:abc123xyz456 --verify
+```
+
+### Skip PDS Resolution
+
+If you already know the PDS URL (from identity_tool or a previous run), you can skip the resolution step:
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- \
+  did:plc:abc123xyz456 --pds https://morel.us-east.host.bsky.network
+```
+
+---
+
+## Step 4: Get User Profile with bsky_bot
+
+For a more user-friendly view, use `bsky_bot` to get the profile (requires authentication):
+
+```bash
+dune exec examples/bsky_bot/bsky_bot.exe -- \
+  --user "$BSKY_USER" \
+  --password "$BSKY_PASS" \
+  --profile alice.bsky.social
+```
+
+Output:
+
+```
+Logged in as yourhandle.bsky.social
+Handle:    @alice.bsky.social
+DID:       did:plc:abc123xyz456
+Name:      Alice
+Bio:       OCaml enthusiast and functional programming advocate
+Followers: 1234
+Following: 567
+Posts:     456
+```
+
+### View Your Timeline
+
+See recent posts from people you follow:
+
+```bash
+dune exec examples/bsky_bot/bsky_bot.exe -- \
+  --user "$BSKY_USER" \
+  --password "$BSKY_PASS" \
+  --timeline --limit 10
+```
+
+### Follow a User
+
+Follow someone using their DID (obtained from identity_tool or feed_generator):
+
+```bash
+dune exec examples/bsky_bot/bsky_bot.exe -- \
+  --user "$BSKY_USER" \
+  --password "$BSKY_PASS" \
+  --follow did:plc:abc123xyz456
+```
+
+---
+
+## Complete Workflow Example
+
+Here's a complete example workflow to find OCaml enthusiasts and explore their content:
+
+```bash
+#!/bin/bash
+
+# 1. Find users posting about OCaml
+echo "=== Finding OCaml posts ==="
+dune exec examples/feed_generator/feed_generator.exe -- \
+  --filter posts --keyword "ocaml" --limit 3 --json 2>/dev/null | \
+  head -3
+
+# Let's say we found: did:plc:z72i7hdynmk6r22z27h6tvur
+
+DID="did:plc:z72i7hdynmk6r22z27h6tvur"
+
+# 2. Verify the identity
+echo -e "\n=== Verifying identity ==="
+dune exec examples/identity_tool/identity_tool.exe -- "$DID"
+
+# 3. Get their handle from the verification and look up their profile
+HANDLE="jay.bsky.social"  # Extracted from step 2
+
+echo -e "\n=== Getting profile ==="
+dune exec examples/bsky_bot/bsky_bot.exe -- \
+  --user "$BSKY_USER" --password "$BSKY_PASS" \
+  --profile "$HANDLE"
+
+# 4. Inspect their repository
+echo -e "\n=== Repository overview ==="
+dune exec examples/repo_inspector/repo_inspector.exe -- "$DID"
+
+# 5. See their recent posts
+echo -e "\n=== Recent posts ==="
+dune exec examples/repo_inspector/repo_inspector.exe -- \
+  "$DID" --records --collection app.bsky.feed.post --limit 5
+```
+
+---
+
+## Advanced Usage
+
+### JSON Output for Scripting
+
+The feed_generator supports JSON output for integration with other tools:
+
+```bash
+dune exec examples/feed_generator/feed_generator.exe -- \
+  --filter posts --keyword "atproto" --limit 5 --json --content
+```
+
+You can pipe this to `jq` for further processing:
+
+```bash
+dune exec examples/feed_generator/feed_generator.exe -- \
+  --filter posts --limit 10 --json 2>/dev/null | \
+  jq -r '.repo' | sort | uniq
+```
+
+### Resume from Cursor
+
+If you need to resume from a specific point in the firehose:
+
+```bash
+dune exec examples/feed_generator/feed_generator.exe -- \
+  --cursor 1234567890 --limit 100
+```
+
+### Monitoring Identity Changes
+
+Watch for handle changes and identity updates:
+
+```bash
+dune exec examples/feed_generator/feed_generator.exe -- \
+  --filter identities,handles --limit 20
+```
+
+### Watching Account Events
+
+Monitor account activations and deactivations:
+
+```bash
+dune exec examples/feed_generator/feed_generator.exe -- \
+  --filter accounts --limit 10
+```
+
+---
+
+## Architecture Overview
+
+```
+                           +-------------------+
+                           |   Bluesky Relay   |
+                           |  bsky.network     |
+                           +-------------------+
+                                    |
+                                    | WebSocket (firehose)
+                                    v
+                           +-------------------+
+                           | feed_generator    |
+                           | (filter events)   |
+                           +-------------------+
+                                    |
+                                    | DID extracted
+                                    v
++-------------------+      +-------------------+      +-------------------+
+|  identity_tool    |<---->|   PLC Directory   |      |   User's PDS      |
+| (resolve/verify)  |      |   DID Documents   |      |                   |
++-------------------+      +-------------------+      +-------------------+
+         |                                                     ^
+         | DID verified                                        |
+         v                                                     |
++-------------------+                                          |
+|  repo_inspector   |------------------------------------------+
+| (download & parse)|         com.atproto.sync.getRepo
++-------------------+
+
++-------------------+
+|    bsky_bot       |-------> Authenticated XRPC calls
+| (social actions)  |         (post, timeline, profile, follow)
++-------------------+
+```
+
+## Troubleshooting
+
+### Connection Errors
+
+If the firehose connection fails:
+- Check your internet connection
+- The relay at `bsky.network` may be temporarily unavailable
+- Try again after a few seconds
+
+### Identity Resolution Failures
+
+If identity verification fails:
+- The handle may have changed recently (DNS propagation delay)
+- The DID document may be temporarily unavailable
+- Try resolving the handle and DID separately to diagnose
+
+### Large Repositories
+
+For users with many records:
+- Use `--limit` to restrict the number of records shown
+- Use `--collection` to filter to specific record types
+- Repository download may take several seconds for active users
+
+---
+
+## Next Steps
+
+- Build a custom feed generator using `feed_generator` as a template
+- Create a bot that responds to mentions using `bsky_bot`
+- Build analytics tools using `repo_inspector` to analyze user behavior
+- Implement identity verification in your applications using `identity_tool`
+
+See the individual README files in each example directory for more details:
+- [bsky_bot/README.md](bsky_bot/README.md)
+- [feed_generator/README.md](feed_generator/README.md)
+- [identity_tool/README.md](identity_tool/README.md)
+- [repo_inspector/README.md](repo_inspector/README.md)

examples/bsky_bot/README.md

···
+# bsky_bot
+
+Bluesky bot for posting, viewing timelines, fetching profiles, and following users via AT Protocol.
+
+## Usage
+
+```
+bsky_bot --user <HANDLE> --password <APP_PASSWORD> [COMMAND]
+```
+
+Authentication is required for all operations. Use an App Password from your Bluesky account settings.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--pds <URL>` | PDS URL (default: https://bsky.social) |
+| `-u, --user <STRING>` | Handle or email for login |
+| `-p, --password <STRING>` | App password |
+| `--post <TEXT>` | Create a post with the given text |
+| `-t, --timeline` | Show timeline |
+| `--limit <INT>` | Number of timeline posts (default: 10) |
+| `--profile <ACTOR>` | Get profile for handle or DID |
+| `--follow <DID>` | Follow a user by DID |
+| `-h, --help` | Show help message |
+
+## Examples
+
+Post a message:
+
+```bash
+dune exec examples/bsky_bot/bsky_bot.exe -- \
+  --user myhandle.bsky.social \
+  --password xxxx-xxxx-xxxx-xxxx \
+  --post "Hello from OCaml!"
+```
+
+View your timeline:
+
+```bash
+dune exec examples/bsky_bot/bsky_bot.exe -- \
+  --user myhandle.bsky.social \
+  --password xxxx-xxxx-xxxx-xxxx \
+  --timeline --limit 5
+```
+
+Get a user's profile:
+
+```bash
+dune exec examples/bsky_bot/bsky_bot.exe -- \
+  --user myhandle.bsky.social \
+  --password xxxx-xxxx-xxxx-xxxx \
+  --profile jay.bsky.social
+```
+
+Follow a user:
+
+```bash
+dune exec examples/bsky_bot/bsky_bot.exe -- \
+  --user myhandle.bsky.social \
+  --password xxxx-xxxx-xxxx-xxxx \
+  --follow did:plc:z72i7hdynmk6r22z27h6tvur
+```
+
+## Output
+
+Timeline output:
+
+```
+Logged in as myhandle.bsky.social
[e-mail]: Just shipped a new feature...
[e-mail]: Check out this thread about...
+```
+
+Profile output:
+
+```
+Handle:    @jay.bsky.social
+DID:       did:plc:z72i7hdynmk6r22z27h6tvur
+Name:      Jay
+Bio:       Building things
+Followers: 12345
+Following: 678
+Posts:     901
+```
+
+## Notes
+
+- Posts automatically detect and link mentions (@handle.domain) and URLs
+- The `--post` option supports text up to 300 graphemes (Bluesky limit)
+- Use App Passwords from Settings > App Passwords, not your main password

examples/bsky_bot/bsky_bot.ml

···
+(** Bluesky Bot - Post, reply, follow operations via AT Protocol. Usage:
+    bsky_bot [--post|--timeline|--profile|--follow] [options] *)
+
+module Agent = Atproto_api.Agent
+module Richtext = Atproto_api.Richtext
+module Client = Atproto_xrpc.Client
+
+(** {1 HTTP Client with cohttp-eio} *)
+
+let http_request ~sw ~client (req : Client.request) : Client.response =
+  let headers = Cohttp.Header.of_list req.headers in
+  let body =
+    match req.body with
+    | Some b -> Cohttp_eio.Body.of_string b
+    | None -> Cohttp_eio.Body.of_string ""
+  in
+  let meth = match req.meth with `GET -> `GET | `POST -> `POST in
+  try
+    let resp, resp_body =
+      Cohttp_eio.Client.call ~sw client meth req.uri ~headers ~body
+    in
+    let status = Cohttp.Response.status resp |> Cohttp.Code.code_of_status in
+    let headers = Cohttp.Response.headers resp |> Cohttp.Header.to_list in
+    let body =
+      Eio.Buf_read.(of_flow ~max_size:(10 * 1024 * 1024) resp_body |> take_all)
+    in
+    { Client.status; headers; body }
+  with e -> { Client.status = 0; headers = []; body = Printexc.to_string e }
+
+(** {1 Effect Handler} *)
+
+let run_with_eio ~sw ~client f =
+  Effect.Deep.try_with f ()
+    {
+      effc =
+        (fun (type a) (eff : a Effect.t) ->
+          match eff with
+          | Client.Http_request req ->
+              Some
+                (fun (k : (a, _) Effect.Deep.continuation) ->
+                  Effect.Deep.continue k (http_request ~sw ~client req))
+          | _ -> None);
+    }
+
+(** {1 Commands} *)
+
+let login ~sw ~client ~pds ~identifier ~password =
+  run_with_eio ~sw ~client (fun () ->
+      let agent = Agent.create_from_url ~url:pds in
+      match Agent.login agent ~identifier ~password with
+      | Error e ->
+          Printf.printf "Login failed: %s\n" (Agent.error_to_string e);
+          None
+      | Ok agent ->
+          Printf.printf "Logged in as %s\n"
+            (Option.value ~default:"?" (Agent.handle agent));
+          Some agent)
+
+let post ~sw ~client agent text =
+  run_with_eio ~sw ~client (fun () ->
+      let rt = Richtext.detect_facets text in
+      match Agent.create_post_richtext agent ~richtext:rt () with
+      | Error e ->
+          Printf.printf "Post failed: %s\n" (Agent.error_to_string e);
+          1
+      | Ok r ->
+          Printf.printf "Posted: %s\n" r.uri;
+          0)
+
+let timeline ~sw ~client agent limit =
+  run_with_eio ~sw ~client (fun () ->
+      match Agent.get_timeline agent ~limit () with
+      | Error e ->
+          Printf.printf "Timeline failed: %s\n" (Agent.error_to_string e);
+          1
+      | Ok feed ->
+          List.iter
+            (fun (p : Agent.feed_item) ->
+              Printf.printf "@%s: %s\n" p.author_handle
+                (String.sub p.text 0 (min 80 (String.length p.text))))
+            feed.items;
+          0)
+
+let profile ~sw ~client agent actor =
+  run_with_eio ~sw ~client (fun () ->
+      match Agent.get_profile agent ~actor with
+      | Error e ->
+          Printf.printf "Profile failed: %s\n" (Agent.error_to_string e);
+          1
+      | Ok p ->
+          Printf.printf "Handle:    @%s\nDID:       %s\n" p.handle p.did;
+          Option.iter (Printf.printf "Name:      %s\n") p.display_name;
+          Option.iter (Printf.printf "Bio:       %s\n") p.description;
+          Printf.printf "Followers: %d\nFollowing: %d\nPosts:     %d\n"
+            p.followers_count p.follows_count p.posts_count;
+          0)
+
+let follow ~sw ~client agent did =
+  run_with_eio ~sw ~client (fun () ->
+      match Agent.follow agent ~did with
+      | Error e ->
+          Printf.printf "Follow failed: %s\n" (Agent.error_to_string e);
+          1
+      | Ok r ->
+          Printf.printf "Followed: %s\n" r.uri;
+          0)
+
+(** {1 CLI} *)
+
+type cmd =
+  | Post of string
+  | Timeline of int
+  | Profile of string
+  | Follow of string
+  | None
+
+let cli =
+  let open Climate.Arg_parser in
+  let+ pds = named_opt [ "pds" ] string ~doc:"PDS URL (default: bsky.social)"
+  and+ identifier = named_opt [ "u"; "user" ] string ~doc:"Handle or email"
+  and+ password = named_opt [ "p"; "password" ] string ~doc:"App password"
+  and+ post_text = named_opt [ "post" ] string ~doc:"Post text"
+  and+ do_timeline = flag [ "timeline"; "t" ] ~doc:"Show timeline"
+  and+ timeline_limit =
+    named_opt [ "limit" ] int ~doc:"Timeline limit (default: 10)"
+  and+ profile_actor = named_opt [ "profile" ] string ~doc:"Get profile"
+  and+ follow_did = named_opt [ "follow" ] string ~doc:"Follow DID" in
+  let pds = Option.value pds ~default:"https://bsky.social" in
+  let limit = Option.value timeline_limit ~default:10 in
+  let cmd =
+    match (post_text, do_timeline, profile_actor, follow_did) with
+    | Some t, _, _, _ -> Post t
+    | _, true, _, _ -> Timeline limit
+    | _, _, Some a, _ -> Profile a
+    | _, _, _, Some d -> Follow d
+    | _ -> None
+  in
+  (pds, identifier, password, cmd)
+
+let () =
+  Mirage_crypto_rng_unix.use_default ();
+  Eio_main.run @@ fun env ->
+  Eio.Switch.run @@ fun sw ->
+  let https_config =
+    match
+      Tls.Config.client ~authenticator:(fun ?ip:_ ~host:_ _ -> Ok None) ()
+    with
+    | Ok c -> c
+    | Error (`Msg m) -> failwith m
+  in
+  let https uri socket =
+    let tls_host =
+      match Uri.host uri with
+      | Some h -> (
+          match Domain_name.of_string h with
+          | Error _ -> Option.None
+          | Ok dn -> Domain_name.host dn |> Result.to_option)
+      | Option.None -> Option.None
+    in
+    Tls_eio.client_of_flow https_config ?host:tls_host socket
+  in
+  let client = Cohttp_eio.Client.make ~https:(Some https) env#net in
+  let pds, identifier, password, cmd =
+    Climate.Command.run ~program_name:(Climate.Program_name.Literal "bsky_bot")
+      (Climate.Command.singleton ~doc:"Bluesky bot - post, timeline, follow" cli)
+  in
+  match cmd with
+  | None ->
+      Printf.printf
+        "Usage: bsky_bot --user USER --password PASS [--post \
+         TEXT|--timeline|--profile ACTOR|--follow DID]\n";
+      exit 0
+  | _ -> (
+      match (identifier, password) with
+      | Some id, Some pw -> (
+          match login ~sw ~client ~pds ~identifier:id ~password:pw with
+          | None -> exit 1
+          | Some agent ->
+              exit
+                (match cmd with
+                | Post t -> post ~sw ~client agent t
+                | Timeline n -> timeline ~sw ~client agent n
+                | Profile a -> profile ~sw ~client agent a
+                | Follow d -> follow ~sw ~client agent d
+                | None -> 0))
+      | _ ->
+          Printf.printf "Error: --user and --password required\n";
+          exit 1)

examples/bsky_bot/dune

···
+(executable
+ (name bsky_bot)
+ (public_name bsky_bot)
+ (package atproto)
+ (libraries
+  atproto-api
+  atproto-xrpc
+  atproto-effects
+  climate
+  eio_main
+  cohttp-eio
+  tls-eio
+  mirage-crypto-rng.unix
+  uri))

examples/feed_generator/README.md

···
+# Feed Generator
+
+AT Protocol firehose client with filtering and feed skeleton generation.
+
+This example demonstrates how to:
+- Subscribe to the Bluesky network firehose using `atproto-sync`
+- Filter events by type (posts, likes, follows, etc.)
+- Filter posts by keyword content
+- Parse and decode CAR files and DAG-CBOR records
+- Generate feed skeleton output for custom feed generators
+
+## Building
+
+```bash
+dune build examples/feed_generator/feed_generator.exe
+```
+
+## Usage
+
+```bash
+dune exec examples/feed_generator/feed_generator.exe -- [OPTIONS]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--cursor <INT64>` | Resume from a specific sequence number |
+| `--limit <INT>` | Stop after N matched events |
+| `--filter <TYPES>` | Filter by event type (comma-separated) |
+| `-k, --keyword <STRING>` | Filter posts containing keyword (case-insensitive) |
+| `--json` | Output events as JSON |
+| `--content` | Include decoded record content in output |
+| `-s, --skeleton` | Output feed skeleton at end (for custom feeds) |
+
+### Event Types
+
+Available filter types:
+- `posts` - app.bsky.feed.post records
+- `likes` - app.bsky.feed.like records
+- `follows` - app.bsky.graph.follow records
+- `reposts` - app.bsky.feed.repost records
+- `blocks` - app.bsky.graph.block records
+- `lists` - app.bsky.graph.list records
+- `profiles` - app.bsky.actor.profile records
+- `feeds` - app.bsky.feed.generator records
+- `commits` - all commit events
+- `identities` - identity change events
+- `accounts` - account status events
+- `handles` - handle change events
+- `tombstones` - account deletion events
+
+## Examples
+
+### Watch all posts
+
+```bash
+feed_generator --filter posts
+```
+
+### Filter posts by keyword
+
+```bash
+feed_generator --filter posts --keyword "ocaml" --limit 10
+```
+
+### Generate a feed skeleton
+
+Collect posts matching a keyword and output a feed skeleton suitable for serving via `app.bsky.feed.getFeedSkeleton`:
+
+```bash
+feed_generator --filter posts --keyword "rust" --limit 50 --skeleton
+```
+
+Output includes:
+```json
+{
+  "feed": [
+    {"post": "at://did:plc:xxx/app.bsky.feed.post/abc123"},
+    {"post": "at://did:plc:yyy/app.bsky.feed.post/def456"}
+  ]
+}
+```
+
+### JSON output with full record content
+
+```bash
+feed_generator --filter posts --json --content --limit 5
+```
+
+### Watch multiple event types
+
+```bash
+feed_generator --filter posts,likes,follows --limit 100
+```
+
+### Resume from a cursor
+
+```bash
+feed_generator --cursor 1234567890 --limit 50
+```
+
+### Watch all activity with decoded content
+
+```bash
+feed_generator --content
+```
+
+## Architecture
+
+The tool uses several AT Protocol libraries:
+
+- **atproto-sync**: Firehose subscription and event parsing
+- **atproto-ipld**: CAR file parsing, DAG-CBOR decoding, CID handling
+
+Key components:
+1. **WebSocket client**: TLS-enabled WebSocket connection to the relay
+2. **Event handler**: Processes commit, identity, account, and other events
+3. **Type filter**: Matches operations against Lexicon record types
+4. **Keyword filter**: Case-insensitive text search in post records
+5. **Feed skeleton**: Collects AT URIs for matched posts
+
+## Building a Custom Feed
+
+To build a complete custom feed generator:
+
+1. Use this tool to prototype your filtering logic
+2. Run with `--skeleton` to verify the output format
+3. Implement a persistent service that:
+   - Subscribes to the firehose continuously
+   - Stores matched post URIs in a database
+   - Serves the feed via XRPC endpoint `app.bsky.feed.getFeedSkeleton`
+   - Publishes a feed generator record to your repository
+
+See the [AT Protocol Feed Generator documentation](https://docs.bsky.app/docs/starter-templates/custom-feeds) for more details.

examples/feed_generator/dune

···
+(executable
+ (name feed_generator)
+ (public_name feed_generator)
+ (package atproto)
+ (libraries
+  atproto-sync
+  atproto-ipld
+  climate
+  uri
+  eio
+  eio_main
+  tls-eio
+  ca-certs-nss
+  mirage-crypto-rng.unix
+  base64
+  cstruct))
+

examples/firehose_demo/dune

···
-(executable
- (name firehose_demo)
- (public_name firehose_demo)
- (package atproto)
- (libraries
-  atproto-sync
-  atproto-ipld
-  climate
-  uri
-  eio
-  eio_main
-  tls-eio
-  ca-certs-nss
-  mirage-crypto-rng.unix
-  base64
-  cstruct))
-
-(executable
- (name firehose_demo_lwt)
- (public_name firehose_demo_lwt)
- (package atproto)
- (libraries
-  atproto-sync
-  atproto-ipld
-  climate
-  uri
-  lwt
-  lwt.unix
-  websocket-lwt-unix
-  conduit-lwt-unix
-  tls-lwt
-  mirage-crypto-rng.unix))

examples/firehose_demo/firehose_demo.ml examples/feed_generator/feed_generator.ml

···
-(** Firehose Demo - AT Protocol real-time events. Use --help for options. *)
+(** Feed Generator - AT Protocol firehose client with filtering.
+
+    Subscribe to the Bluesky firehose, filter events by type or keyword, and
+    optionally output a feed skeleton for custom feed generation.
+
+    Use --help for options. *)
 
 module Firehose = Atproto_sync.Firehose
 module Car = Atproto_ipld.Car
···
       | Firehose.Tombstone _ -> List.mem Tombstones filters
       | Firehose.Info _ | Firehose.StreamError _ -> true)
 
+(** {1 Keyword Filtering} *)
+
+let contains_keyword keyword text =
+  let kw = String.lowercase_ascii keyword in
+  let txt = String.lowercase_ascii text in
+  let kw_len = String.length kw in
+  let txt_len = String.length txt in
+  if kw_len > txt_len then false
+  else
+    let rec search i =
+      if i > txt_len - kw_len then false
+      else if String.sub txt i kw_len = kw then true
+      else search (i + 1)
+    in
+    search 0
+
+let text_matches_keyword keyword blocks (op : Firehose.operation) =
+  match find_block blocks op with
+  | Some cbor -> (
+      match get_text cbor with
+      | Some text -> contains_keyword keyword text
+      | None -> false)
+  | None -> false
+
+let event_matches_keyword keyword event =
+  match keyword with
+  | None -> true
+  | Some kw -> (
+      match event with
+      | Firehose.Commit evt ->
+          let blocks = extract_blocks evt.blocks in
+          List.exists
+            (fun op ->
+              op.Firehose.action = `Create
+              && prefix_match "app.bsky.feed.post" op.path
+              && text_matches_keyword kw blocks op)
+            evt.ops
+      | _ -> false)
+
+(** {1 Feed Skeleton} *)
+
+let max_feed_size = 1000
+let feed_posts : string Queue.t = Queue.create ()
+
+let add_to_feed uri =
+  Queue.add uri feed_posts;
+  if Queue.length feed_posts > max_feed_size then ignore (Queue.pop feed_posts)
+
+let collect_post_uris (evt : Firehose.commit_event) keyword =
+  let blocks = extract_blocks evt.blocks in
+  List.iter
+    (fun (op : Firehose.operation) ->
+      if
+        op.action = `Create
+        && prefix_match "app.bsky.feed.post" op.path
+        &&
+        match keyword with
+        | None -> true
+        | Some kw -> text_matches_keyword kw blocks op
+      then
+        let rkey =
+          match String.rindex_opt op.path '/' with
+          | Some i -> String.sub op.path (i + 1) (String.length op.path - i - 1)
+          | None -> op.path
+        in
+        let uri =
+          Printf.sprintf "at://%s/app.bsky.feed.post/%s" evt.repo rkey
+        in
+        add_to_feed uri)
+    evt.ops
+
+let print_feed_skeleton () =
+  let items = Queue.fold (fun acc x -> x :: acc) [] feed_posts |> List.rev in
+  if items = [] then ()
+  else begin
+    Printf.printf "\n--- Feed Skeleton (app.bsky.feed.getFeedSkeleton) ---\n";
+    Printf.printf "{\n  \"feed\": [\n";
+    List.iteri
+      (fun i uri ->
+        Printf.printf "    {\"post\": \"%s\"}" uri;
+        if i < List.length items - 1 then Printf.printf ",";
+        Printf.printf "\n")
+      items;
+    Printf.printf "  ]\n}\n"
+  end
+
+(** {1 WebSocket Client} *)
+
 module Ws = struct
   type conn = {
     socket : Tls_eio.t;
···
           | _ -> None);
     }
 
+(** {1 Configuration} *)
+
 type config = {
   cursor : int64 option;
   limit : int option;
   filters : filter list;
+  keyword : string option;
   json : bool;
   rich : bool;
+  skeleton : bool;
 }
 
 let parse_filters s =
···
 let config_parser =
   let open Climate.Arg_parser in
   let+ cursor = named_opt [ "cursor" ] int64_conv ~doc:"Resume from sequence"
-  and+ limit = named_opt [ "limit" ] int ~doc:"Stop after N events"
+  and+ limit = named_opt [ "limit" ] int ~doc:"Stop after N matched events"
   and+ filter_str =
     named_opt [ "filter" ] string
-      ~doc:"Filter (posts,likes,follows,reposts,etc.)"
+      ~doc:"Filter by type (posts,likes,follows,reposts,etc.)"
+  and+ keyword =
+    named_opt [ "keyword"; "k" ] string ~doc:"Filter posts by keyword"
   and+ json = flag [ "json" ] ~doc:"JSON output"
-  and+ rich = flag [ "content" ] ~doc:"Show record content" in
+  and+ rich = flag [ "content" ] ~doc:"Show record content"
+  and+ skeleton = flag [ "skeleton"; "s" ] ~doc:"Output feed skeleton at end" in
   {
     cursor;
     limit;
     filters = Option.fold ~none:[] ~some:parse_filters filter_str;
+    keyword;
     json;
     rich;
+    skeleton;
   }
 
 let cli =
-  Climate.Command.singleton ~doc:"AT Protocol firehose demo" config_parser
+  Climate.Command.singleton
+    ~doc:"AT Protocol firehose client and feed generator" config_parser
+
+(** {1 Stats} *)
 
 type stats = {
   mutable total : int;
···
 let stats = { total = 0; matched = 0; last_seq = 0L; start = 0. }
 let interrupted = ref false
 
+(** {1 Main} *)
+
 let run ~net ~sw config =
   let uri =
     Uri.of_string "wss://bsky.network/xrpc/com.atproto.sync.subscribeRepos"
···
     (match Firehose.event_seq event with
     | Some s -> stats.last_seq <- s
     | None -> ());
-    if event_matches config.filters event then begin
+    (* Collect posts for skeleton if enabled *)
+    (if config.skeleton then
+       match event with
+       | Firehose.Commit evt -> collect_post_uris evt config.keyword
+       | _ -> ());
+    (* Check filters *)
+    let type_match = event_matches config.filters event in
+    let keyword_match = event_matches_keyword config.keyword event in
+    if type_match && keyword_match then begin
       print_endline (fmt event);
       stats.matched <- stats.matched + 1;
       match config.limit with
···
 let () =
   let config =
     Climate.Command.run
-      ~program_name:(Climate.Program_name.Literal "firehose_demo") cli
+      ~program_name:(Climate.Program_name.Literal "feed_generator") cli
   in
   if not config.json then begin
-    Printf.printf "AT Protocol Firehose Demo\n=========================\n\n%!";
+    Printf.printf "Feed Generator\n==============\n\n%!";
     if config.filters <> [] then
-      Printf.printf "Filtering: %s\n\n%!"
-        (String.concat ", " (List.map filter_to_string config.filters))
+      Printf.printf "Type filter: %s\n%!"
+        (String.concat ", " (List.map filter_to_string config.filters));
+    (match config.keyword with
+    | Some kw -> Printf.printf "Keyword: \"%s\"\n%!" kw
+    | None -> ());
+    Printf.printf "\n%!"
   end;
   Sys.set_signal Sys.sigint (Sys.Signal_handle (fun _ -> interrupted := true));
   stats.start <- Unix.gettimeofday ();
···
    with
   | Failure m -> Printf.eprintf "Error: %s\n%!" m
   | e -> Printf.eprintf "Error: %s\n%!" (Printexc.to_string e));
-  if not config.json then print_stats stats
+  if not config.json then print_stats stats;
+  if config.skeleton then print_feed_skeleton ()

examples/firehose_demo/firehose_demo_lwt.ml

···
-(** Firehose Demo (Lwt version) - AT Protocol real-time events. Uses
-    websocket-lwt-unix for WebSocket handling. Use --help for options. *)
-
-open Lwt.Infix
-module Firehose = Atproto_sync.Firehose
-module Car = Atproto_ipld.Car
-module Dag_cbor = Atproto_ipld.Dag_cbor
-module Dag_json = Atproto_ipld.Dag_json
-module Cid = Atproto_ipld.Cid
-
-(* Global interrupt handling via Lwt *)
-let interrupt_wakener : (unit, exn) result Lwt.u option ref = ref None
-let interrupted = ref false
-
-let trigger_interrupt () =
-  interrupted := true;
-  match !interrupt_wakener with
-  | Some w ->
-      Lwt.wakeup_later w (Error Exit);
-      interrupt_wakener := None
-  | None -> ()
-
-let truncate n s =
-  if String.length s <= n then s else String.sub s 0 (n - 3) ^ "..."
-
-let single_line s =
-  String.map (fun c -> if c = '\n' || c = '\r' then ' ' else c) s
-
-let opt_or d = Option.value ~default:d
-
-let extract_blocks blocks_data =
-  if String.length blocks_data = 0 then []
-  else
-    match Car.read blocks_data with
-    | Error _ -> []
-    | Ok (_, blocks) ->
-        List.filter_map
-          (fun (b : Car.block) ->
-            match Dag_cbor.decode b.data with
-            | Ok cbor -> Some (Cid.to_string b.cid, cbor)
-            | _ -> None)
-          blocks
-
-let find_block blocks (op : Firehose.operation) =
-  match op.cid with
-  | Some cid -> List.assoc_opt (Cid.to_string cid) blocks
-  | None -> None
-
-let get_text cbor =
-  match cbor with
-  | Dag_cbor.Map pairs -> Firehose.get_string "text" pairs
-  | _ -> None
-
-let format_op blocks (op : Firehose.operation) =
-  let action =
-    match op.action with `Create -> "+" | `Update -> "~" | `Delete -> "-"
-  in
-  let content =
-    match find_block blocks op with
-    | Some cbor -> (
-        match get_text cbor with
-        | Some t -> " \"" ^ truncate 70 (single_line t) ^ "\""
-        | None -> "")
-    | None -> ""
-  in
-  Printf.sprintf "%s%s%s" action op.path content
-
-let format_event ?(rich = false) = function
-  | Firehose.Commit evt ->
-      let blocks = if rich then extract_blocks evt.blocks else [] in
-      let ops =
-        String.concat
-          (if rich then "\n        " else " ")
-          (List.map (format_op blocks) evt.ops)
-      in
-      Printf.sprintf "#commit seq=%Ld repo=%s%s%s" evt.seq evt.repo
-        (if rich then "\n        " else " ")
-        ops
-  | Firehose.Identity e ->
-      Printf.sprintf "#identity seq=%Ld did=%s handle=%s" e.seq e.did
-        (opt_or "-" e.handle)
-  | Firehose.Account e ->
-      Printf.sprintf "#account seq=%Ld did=%s active=%b" e.seq e.did e.active
-  | Firehose.Handle e ->
-      Printf.sprintf "#handle seq=%Ld did=%s handle=%s" e.seq e.did e.handle
-  | Firehose.Tombstone e ->
-      Printf.sprintf "#tombstone seq=%Ld did=%s" e.seq e.did
-  | Firehose.Info m -> Printf.sprintf "#info name=%s" m.name
-  | Firehose.StreamError err -> Printf.sprintf "#error %s" err
-
-let json_of_op_with_record blocks (op : Firehose.operation) =
-  let base_json = Firehose.operation_to_json op in
-  match find_block blocks op with
-  | Some cbor ->
-      let record_json = Yojson.Safe.from_string (Dag_json.encode_string cbor) in
-      Firehose.add_record_to_op_json base_json record_json
-  | None -> base_json
-
-let json_of_event ?(rich = false) event =
-  let json =
-    match event with
-    | Firehose.Commit evt when rich -> (
-        let blocks = extract_blocks evt.blocks in
-        let ops = `List (List.map (json_of_op_with_record blocks) evt.ops) in
-        let base = Firehose.commit_event_to_json evt in
-        match base with
-        | `Assoc fields ->
-            `Assoc
-              (List.map
-                 (fun (k, v) -> if k = "ops" then (k, ops) else (k, v))
-                 fields)
-        | _ -> base)
-    | _ -> Firehose.event_to_json event
-  in
-  Yojson.Safe.to_string json
-
-type filter =
-  | Posts
-  | Likes
-  | Follows
-  | Reposts
-  | Blocks
-  | Lists
-  | Profiles
-  | Feeds
-  | Commits
-  | Identities
-  | Accounts
-  | Handles
-  | Tombstones
-
-let filters =
-  [
-    ("posts", Posts);
-    ("likes", Likes);
-    ("follows", Follows);
-    ("reposts", Reposts);
-    ("blocks", Blocks);
-    ("lists", Lists);
-    ("profiles", Profiles);
-    ("feeds", Feeds);
-    ("commits", Commits);
-    ("identities", Identities);
-    ("accounts", Accounts);
-    ("handles", Handles);
-    ("tombstones", Tombstones);
-  ]
-
-let filter_of_string s = List.assoc_opt s filters
-let filter_to_string f = fst (List.find (fun (_, v) -> v = f) filters)
-
-let prefix_match prefix path =
-  String.length path >= String.length prefix
-  && String.sub path 0 (String.length prefix) = prefix
-
-let op_matches filter (op : Firehose.operation) =
-  match filter with
-  | Posts -> prefix_match "app.bsky.feed.post" op.path
-  | Likes -> prefix_match "app.bsky.feed.like" op.path
-  | Follows -> prefix_match "app.bsky.graph.follow" op.path
-  | Reposts -> prefix_match "app.bsky.feed.repost" op.path
-  | Blocks -> prefix_match "app.bsky.graph.block" op.path
-  | Lists -> prefix_match "app.bsky.graph.list" op.path
-  | Profiles -> prefix_match "app.bsky.actor.profile" op.path
-  | Feeds -> prefix_match "app.bsky.feed.generator" op.path
-  | Commits -> true
-  | _ -> false
-
-let event_matches filters event =
-  match filters with
-  | [] -> true
-  | _ -> (
-      match event with
-      | Firehose.Commit evt ->
-          List.exists
-            (fun f -> f = Commits || List.exists (op_matches f) evt.ops)
-            filters
-      | Firehose.Identity _ -> List.mem Identities filters
-      | Firehose.Account _ -> List.mem Accounts filters
-      | Firehose.Handle _ -> List.mem Handles filters
-      | Firehose.Tombstone _ -> List.mem Tombstones filters
-      | Firehose.Info _ | Firehose.StreamError _ -> true)
-
-(** WebSocket client using websocket-lwt-unix *)
-module Ws = struct
-  type conn = Websocket_lwt_unix.conn
-
-  let connect uri : (conn, string) result Lwt.t =
-    let host = Uri.host uri |> Option.value ~default:"localhost" in
-    let scheme = Uri.scheme uri |> Option.value ~default:"wss" in
-    let port =
-      Uri.port uri |> Option.value ~default:(if scheme = "wss" then 443 else 80)
-    in
-    let resource = Uri.path_and_query uri in
-    (* Resolve hostname to IP *)
-    Lwt.catch
-      (fun () ->
-        Lwt_unix.getaddrinfo host (string_of_int port)
-          [ Unix.AI_SOCKTYPE Unix.SOCK_STREAM ]
-        >>= function
-        | [] -> Lwt.return (Error ("DNS failed: " ^ host))
-        | ai :: _ ->
-            let ip =
-              match ai.Unix.ai_addr with
-              | Unix.ADDR_INET (addr, _) -> Ipaddr_unix.of_inet_addr addr
-              | _ -> failwith "Unexpected address type"
-            in
-            let endp = `TLS_native (`Hostname host, `IP ip, `Port port) in
-            Websocket_lwt_unix.connect endp (Uri.with_path uri resource)
-            >|= fun conn -> Ok conn)
-      (fun exn -> Lwt.return (Error (Printexc.to_string exn)))
-
-  (* Buffer for accumulating fragmented messages *)
-  let frag_buf = Buffer.create 65536
-  let frag_opcode = ref Websocket.Frame.Opcode.Continuation
-
-  let recv_impl conn : (string, string) result Lwt.t =
-    let open Websocket in
-    let rec read_binary () =
-      Lwt.catch
-        (fun () ->
-          Websocket_lwt_unix.read conn >>= fun frame ->
-          match frame.Frame.opcode with
-          | Frame.Opcode.Binary ->
-              if frame.Frame.final then
-                (* Complete message in single frame *)
-                Lwt.return (Ok frame.Frame.content)
-              else begin
-                (* Start of fragmented binary message *)
-                Buffer.clear frag_buf;
-                Buffer.add_string frag_buf frame.Frame.content;
-                frag_opcode := Frame.Opcode.Binary;
-                read_binary ()
-              end
-          | Frame.Opcode.Continuation ->
-              (* Continuation of fragmented message *)
-              Buffer.add_string frag_buf frame.Frame.content;
-              if frame.Frame.final then begin
-                (* Fragmented message complete *)
-                let data = Buffer.contents frag_buf in
-                Buffer.clear frag_buf;
-                if !frag_opcode = Frame.Opcode.Binary then Lwt.return (Ok data)
-                else
-                  (* Was a text message, skip it *)
-                  read_binary ()
-              end
-              else read_binary ()
-          | Frame.Opcode.Text ->
-              if frame.Frame.final then
-                (* Skip complete text frames *)
-                read_binary ()
-              else begin
-                (* Start of fragmented text message - track but skip *)
-                Buffer.clear frag_buf;
-                Buffer.add_string frag_buf frame.Frame.content;
-                frag_opcode := Frame.Opcode.Text;
-                read_binary ()
-              end
-          | Frame.Opcode.Close -> Lwt.return (Error "Connection closed")
-          | Frame.Opcode.Ping ->
-              (* Respond to ping with pong *)
-              let pong =
-                Frame.create ~opcode:Frame.Opcode.Pong
-                  ~content:frame.Frame.content ()
-              in
-              Websocket_lwt_unix.write conn pong >>= fun () -> read_binary ()
-          | Frame.Opcode.Pong -> read_binary ()
-          | _ -> read_binary ())
-        (fun exn -> Lwt.return (Error (Printexc.to_string exn)))
-    in
-    read_binary ()
-
-  (** Interruptible recv - races against interrupt signal *)
-  let recv conn : (string, string) result Lwt.t =
-    (* Create a waiter that can be woken by Ctrl+C *)
-    let interrupt_waiter, wakener = Lwt.wait () in
-    interrupt_wakener := Some wakener;
-    (* Race between recv and interrupt *)
-    Lwt.pick
-      [
-        recv_impl conn;
-        ( interrupt_waiter >>= function
-          | Ok () -> Lwt.return (Error "Interrupted")
-          | Error _ -> Lwt.return (Error "Interrupted") );
-      ]
-    >>= fun result ->
-    (* Clear the wakener if we won the race *)
-    interrupt_wakener := None;
-    Lwt.return result
-
-  let close conn =
-    Lwt.catch
-      (fun () ->
-        let close_frame = Websocket.Frame.close 1000 in
-        Websocket_lwt_unix.write conn close_frame >>= fun () ->
-        Websocket_lwt_unix.close_transport conn)
-      (fun _ -> Lwt.return_unit)
-end
-
-(** Effect handler that uses Lwt for WebSocket operations *)
-let with_websocket_lwt f =
-  let open Effect.Deep in
-  (* We need to track Lwt state across effect invocations *)
-  let ws_conn : Ws.conn option ref = ref None in
-  try_with f ()
-    {
-      effc =
-        (fun (type a) (eff : a Effect.t) ->
-          match eff with
-          | Firehose.Ws_connect uri ->
-              Some
-                (fun (k : (a, _) continuation) ->
-                  let result = Lwt_main.run (Ws.connect uri) in
-                  (match result with
-                  | Ok conn -> ws_conn := Some conn
-                  | Error _ -> ());
-                  continue k (Result.map Obj.magic result))
-          | Firehose.Ws_recv _ws ->
-              Some
-                (fun k ->
-                  match !ws_conn with
-                  | None -> continue k (Error "Not connected")
-                  | Some conn ->
-                      let result = Lwt_main.run (Ws.recv conn) in
-                      continue k result)
-          | Firehose.Ws_close _ws ->
-              Some
-                (fun k ->
-                  (match !ws_conn with
-                  | None -> ()
-                  | Some conn ->
-                      Lwt_main.run (Ws.close conn);
-                      ws_conn := None);
-                  continue k ())
-          | _ -> None);
-    }
-
-type config = {
-  cursor : int64 option;
-  limit : int option;
-  filters : filter list;
-  json : bool;
-  rich : bool;
-}
-
-let parse_filters s =
-  String.split_on_char ',' s
-  |> List.filter_map (fun p -> filter_of_string (String.trim p))
-
-let int64_conv =
-  let open Climate.Arg_parser in
-  make_conv
-    ~parse:(fun s ->
-      match Int64.of_string_opt s with
-      | Some n -> Ok n
-      | None -> Error (`Msg "invalid integer"))
-    ~print:(fun fmt n -> Format.fprintf fmt "%Ld" n)
-    ()
-
-let config_parser =
-  let open Climate.Arg_parser in
-  let+ cursor = named_opt [ "cursor" ] int64_conv ~doc:"Resume from sequence"
-  and+ limit = named_opt [ "limit" ] int ~doc:"Stop after N events"
-  and+ filter_str =
-    named_opt [ "filter" ] string
-      ~doc:"Filter (posts,likes,follows,reposts,etc.)"
-  and+ json = flag [ "json" ] ~doc:"JSON output"
-  and+ rich = flag [ "content" ] ~doc:"Show record content" in
-  {
-    cursor;
-    limit;
-    filters = Option.fold ~none:[] ~some:parse_filters filter_str;
-    json;
-    rich;
-  }
-
-let cli =
-  Climate.Command.singleton ~doc:"AT Protocol firehose demo (Lwt)" config_parser
-
-type stats = {
-  mutable total : int;
-  mutable matched : int;
-  mutable last_seq : int64;
-  mutable start : float;
-}
-
-let print_stats s =
-  let elapsed = Unix.gettimeofday () -. s.start in
-  let rate = if elapsed > 0. then float_of_int s.total /. elapsed else 0. in
-  Printf.printf
-    "\n--- Stats: %d events (%d matched) | seq=%Ld | %.1fs | %.1f evt/s ---\n%!"
-    s.total s.matched s.last_seq elapsed rate
-
-let stats = { total = 0; matched = 0; last_seq = 0L; start = 0. }
-let json_mode = ref false
-
-let run config =
-  let uri =
-    Uri.of_string "wss://bsky.network/xrpc/com.atproto.sync.subscribeRepos"
-  in
-  let cfg = Firehose.config ~uri ?cursor:config.cursor () in
-  if not config.json then
-    Printf.printf "Connecting to %s...\n%!"
-      (Uri.to_string (Firehose.build_uri cfg));
-  let fmt =
-    if config.json then json_of_event ~rich:config.rich
-    else format_event ~rich:config.rich
-  in
-  let handler event =
-    stats.total <- stats.total + 1;
-    (match Firehose.event_seq event with
-    | Some s -> stats.last_seq <- s
-    | None -> ());
-    if event_matches config.filters event then begin
-      print_endline (fmt event);
-      stats.matched <- stats.matched + 1;
-      match config.limit with
-      | Some max when stats.matched >= max -> false
-      | _ -> true (* Always continue - interrupt handled via WebSocket error *)
-    end
-    else true (* Always continue processing *)
-  in
-  with_websocket_lwt (fun () ->
-      if not config.json then Printf.printf "Connected!\n\n%!";
-      match Firehose.subscribe cfg ~handler with
-      | Ok () ->
-          if not config.json then
-            Printf.printf "Subscribe completed normally\n%!"
-      | Error e ->
-          if not config.json then
-            Printf.printf "Subscribe ended: %s\n%!" (Firehose.error_to_string e))
-
-let () =
-  let config =
-    Climate.Command.run
-      ~program_name:(Climate.Program_name.Literal "firehose_demo_lwt") cli
-  in
-  json_mode := config.json;
-  if not config.json then begin
-    Printf.printf
-      "AT Protocol Firehose Demo (Lwt)\n===============================\n\n%!";
-    if config.filters <> [] then
-      Printf.printf "Filtering: %s\n\n%!"
-        (String.concat ", " (List.map filter_to_string config.filters));
-    Printf.printf "Press Ctrl+C to stop and show stats.\n\n%!"
-  end;
-  (* Use Lwt_unix signal handling for proper integration with Lwt *)
-  let _ = Lwt_unix.on_signal Sys.sigint (fun _ -> trigger_interrupt ()) in
-  stats.start <- Unix.gettimeofday ();
-  Mirage_crypto_rng_unix.use_default ();
-  (try run config with _ -> ());
-  if not config.json then print_stats stats

examples/identity_tool/README.md

···
+# identity_tool
+
+AT Protocol identity lookup and verification tool. Resolves handles to DIDs, DIDs to documents, and verifies bidirectional identity bindings.
+
+## Usage
+
+```
+identity_tool [OPTIONS] <IDENTIFIER>
+```
+
+Where `<IDENTIFIER>` is a handle (e.g., `jay.bsky.social`) or a DID (e.g., `did:plc:z72i7hdynmk6r22z27h6tvur`).
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-H, --resolve-handle` | Resolve handle to DID |
+| `-d, --resolve-did` | Resolve DID to document |
+| `-v, --verify` | Verify bidirectional identity (default) |
+| `-h, --help` | Show help message |
+
+## Examples
+
+Verify identity (default mode):
+
+```bash
+dune exec examples/identity_tool/identity_tool.exe -- jay.bsky.social
+```
+
+Resolve a handle to its DID:
+
+```bash
+dune exec examples/identity_tool/identity_tool.exe -- -H jay.bsky.social
+```
+
+Resolve a DID to its document:
+
+```bash
+dune exec examples/identity_tool/identity_tool.exe -- -d did:plc:z72i7hdynmk6r22z27h6tvur
+```
+
+## Output
+
+Handle resolution shows the DID:
+
+```
+Handle: jay.bsky.social
+DID:    did:plc:z72i7hdynmk6r22z27h6tvur
+```
+
+DID resolution shows the full document:
+
+```
+DID:     did:plc:z72i7hdynmk6r22z27h6tvur
+Handle:  at://jay.bsky.social
+Key:     zQ3shXjHeiBuRCKmM... (multikey)
+Service: AtprotoPersonalDataServer -> https://morel.us-east.host.bsky.network
+```
+
+Verification confirms bidirectional binding:
+
+```
+PASSED
+DID:    did:plc:z72i7hdynmk6r22z27h6tvur
+Handle: jay.bsky.social
+Key:    zQ3shXjHeiBuRCKmM...
+PDS:    https://morel.us-east.host.bsky.network
+```

examples/identity_tool/dune

···
+(executable
+ (name identity_tool)
+ (public_name identity_tool)
+ (package atproto)
+ (libraries
+  atproto-identity
+  atproto-syntax
+  climate
+  eio_main
+  cohttp-eio
+  tls-eio
+  mirage-crypto-rng.unix
+  uri))

examples/identity_tool/identity_tool.ml

···
+(** Identity Tool - Resolve handles/DIDs and verify AT Protocol identities.
+    Usage: identity_tool [--resolve-handle|--resolve-did|--verify] <identifier>
+*)
+
+open Atproto_syntax
+open Atproto_identity
+
+(** {1 HTTP Client with cohttp-eio} *)
+
+let http_get ~sw ~client uri =
+  try
+    let resp, resp_body = Cohttp_eio.Client.call ~sw client `GET uri in
+    let status = Cohttp.Response.status resp |> Cohttp.Code.code_of_status in
+    let body =
+      Eio.Buf_read.(of_flow ~max_size:(10 * 1024 * 1024) resp_body |> take_all)
+    in
+    Did_resolver.{ status; body }
+  with e -> Did_resolver.{ status = 0; body = Printexc.to_string e }
+
+(** {1 Effect Handler} *)
+
+let run_with_eio ~sw ~client f =
+  Effect.Deep.try_with f ()
+    {
+      effc =
+        (fun (type a) (eff : a Effect.t) ->
+          match eff with
+          | Did_resolver.Http_get uri ->
+              Some
+                (fun (k : (a, _) Effect.Deep.continuation) ->
+                  Effect.Deep.continue k (http_get ~sw ~client uri))
+          | Handle_resolver.Http_get uri ->
+              Some
+                (fun k ->
+                  let r = http_get ~sw ~client uri in
+                  Effect.Deep.continue k
+                    Handle_resolver.{ status = r.status; body = r.body })
+          | Handle_resolver.Dns_txt _ ->
+              Some
+                (fun k -> Effect.Deep.continue k Handle_resolver.Dns_not_found)
+          | _ -> None);
+    }
+
+(** {1 Commands} *)
+
+let resolve_handle ~sw ~client h =
+  match Handle.of_string h with
+  | Error _ ->
+      Printf.printf "Error: Invalid handle\n";
+      1
+  | Ok handle ->
+      run_with_eio ~sw ~client (fun () ->
+          match Handle_resolver.resolve handle with
+          | Error e ->
+              Printf.printf "Error: %s\n" (Handle_resolver.error_to_string e);
+              1
+          | Ok did ->
+              Printf.printf "Handle: %s\nDID:    %s\n" (Handle.to_string handle)
+                (Did.to_string did);
+              0)
+
+let resolve_did ~sw ~client d =
+  match Did.of_string d with
+  | Error _ ->
+      Printf.printf "Error: Invalid DID\n";
+      1
+  | Ok did ->
+      run_with_eio ~sw ~client (fun () ->
+          match Did_resolver.resolve_did did with
+          | Error e ->
+              Printf.printf "Error: %s\n" (Did_resolver.error_to_string e);
+              1
+          | Ok doc ->
+              Printf.printf "DID:     %s\n" doc.id;
+              List.iter
+                (fun a -> Printf.printf "Handle:  %s\n" a)
+                doc.also_known_as;
+              List.iter
+                (fun (v : Did_resolver.verification_method) ->
+                  Printf.printf "Key:     %s (%s)\n"
+                    (Option.value ~default:"-" v.public_key_multibase)
+                    v.type_)
+                doc.verification_method;
+              List.iter
+                (fun (s : Did_resolver.service) ->
+                  Printf.printf "Service: %s -> %s\n" s.type_ s.service_endpoint)
+                doc.service;
+              0)
+
+let verify ~sw ~client id =
+  let is_did = String.length id > 4 && String.sub id 0 4 = "did:" in
+  run_with_eio ~sw ~client (fun () ->
+      let result =
+        if is_did then
+          match Did.of_string id with
+          | Error _ -> Error "Invalid DID"
+          | Ok d ->
+              Identity.verify_did d |> Result.map_error Identity.error_to_string
+        else
+          match Handle.of_string id with
+          | Error _ -> Error "Invalid handle"
+          | Ok h ->
+              Identity.verify_handle h
+              |> Result.map_error Identity.error_to_string
+      in
+      match result with
+      | Error e ->
+          Printf.printf "FAILED: %s\n" e;
+          1
+      | Ok v ->
+          Printf.printf "PASSED\nDID:    %s\nHandle: %s\n" (Did.to_string v.did)
+            (Handle.to_string v.handle);
+          Option.iter (Printf.printf "Key:    %s\n") v.signing_key;
+          Option.iter
+            (fun u -> Printf.printf "PDS:    %s\n" (Uri.to_string u))
+            v.pds_endpoint;
+          0)
+
+(** {1 CLI} *)
+
+type mode = Resolve_handle | Resolve_did | Verify
+
+let cli =
+  let open Climate.Arg_parser in
+  let+ id =
+    pos_req 0 string ~value_name:"IDENTIFIER" ~doc:"Handle or DID to look up"
+  and+ rh = flag [ "H"; "resolve-handle" ] ~doc:"Resolve handle to DID"
+  and+ rd = flag [ "d"; "resolve-did" ] ~doc:"Resolve DID to document"
+  and+ _vf = flag [ "v"; "verify" ] ~doc:"Verify bidirectional identity" in
+  let mode =
+    if rh then Resolve_handle else if rd then Resolve_did else Verify
+  in
+  (mode, id)
+
+let () =
+  Mirage_crypto_rng_unix.use_default ();
+  Eio_main.run @@ fun env ->
+  Eio.Switch.run @@ fun sw ->
+  let https_config =
+    match
+      Tls.Config.client ~authenticator:(fun ?ip:_ ~host:_ _ -> Ok None) ()
+    with
+    | Ok c -> c
+    | Error (`Msg m) -> failwith m
+  in
+  let https uri socket =
+    let tls_host =
+      match Uri.host uri with
+      | Some h -> (
+          match Domain_name.of_string h with
+          | Error _ -> None
+          | Ok dn -> Domain_name.host dn |> Result.to_option)
+      | None -> None
+    in
+    Tls_eio.client_of_flow https_config ?host:tls_host socket
+  in
+  let client = Cohttp_eio.Client.make ~https:(Some https) env#net in
+  let mode, id =
+    Climate.Command.run
+      ~program_name:(Climate.Program_name.Literal "identity_tool")
+      (Climate.Command.singleton ~doc:"AT Protocol identity lookup tool" cli)
+  in
+  exit
+    (match mode with
+    | Resolve_handle -> resolve_handle ~sw ~client id
+    | Resolve_did -> resolve_did ~sw ~client id
+    | Verify -> verify ~sw ~client id)

examples/repo_inspector/README.md

···
+# repo_inspector
+
+AT Protocol repository inspector for exploring repository contents, collections, and records.
+
+## Usage
+
+```
+repo_inspector [OPTIONS] <DID>
+```
+
+Downloads and parses the repository for the given DID. The tool automatically resolves the user's PDS (Personal Data Server) from their DID document.
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--pds <URL>` | PDS URL (auto-resolved from DID document if not specified) |
+| `-c, --collections` | List all collections with record counts |
+| `-r, --records` | Show individual records |
+| `--collection <STRING>` | Filter records by collection prefix |
+| `-n, --limit <INT>` | Limit number of records shown (default: 20) |
+| `-v, --verify` | Show commit signature information |
+| `-h, --help` | Show help message |
+
+## Examples
+
+Show repository summary:
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- did:plc:z72i7hdynmk6r22z27h6tvur
+```
+
+List collections:
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- \
+  did:plc:z72i7hdynmk6r22z27h6tvur --collections
+```
+
+Show records:
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- \
+  did:plc:z72i7hdynmk6r22z27h6tvur --records --limit 10
+```
+
+Show only posts:
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- \
+  did:plc:z72i7hdynmk6r22z27h6tvur --records --collection app.bsky.feed.post
+```
+
+Verify commit signature:
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- \
+  did:plc:z72i7hdynmk6r22z27h6tvur --verify
+```
+
+Use a specific PDS (skip auto-resolution):
+
+```bash
+dune exec examples/repo_inspector/repo_inspector.exe -- \
+  did:plc:z72i7hdynmk6r22z27h6tvur --pds https://puffball.us-east.host.bsky.network
+```
+
+## Output
+
+Summary output:
+
+```
+Repository Inspector
+====================
+
+Resolving PDS for did:plc:z72i7hdynmk6r22z27h6tvur...
+PDS: https://puffball.us-east.host.bsky.network
+
+Fetching https://puffball.us-east.host.bsky.network/xrpc/com.atproto.sync.getRepo?did=...
+
+CAR Header
+----------
+Version: 1
+Roots:   1
+  - bafyreib...
+Blocks:  1234
+
+Commit
+------
+DID:     did:plc:z72i7hdynmk6r22z27h6tvur
+Version: 3
+Rev:     3abc123def456
+Data:    bafyreic...
+
+Collections
+-----------
+  app.bsky.feed.post: 456
+  app.bsky.feed.like: 789
+  app.bsky.graph.follow: 123
+  app.bsky.actor.profile: 1
+
+Total records: 1369
+```
+
+Records output:
+
+```
+Records
+-------
+app.bsky.feed.post/3abc123
+  CID: bafyreig...
+  Text: Hello world, this is my first post...
+
+app.bsky.feed.post/3def456
+  CID: bafyreih...
+  Text: Another post here...
+
+... and 454 more
+```
+
+Verify output:
+
+```
+Commit Verification
+-------------------
+DID:       did:plc:z72i7hdynmk6r22z27h6tvur
+Signature: MEUCIQDa7H8c9X...
+Status:    Signature present but key resolution not implemented
+           (would need to resolve DID document to verify)
+```
+
+## Notes
+
+- Automatically resolves the user's PDS from their DID document via PLC directory
+- Use `--pds` to skip auto-resolution and specify a PDS directly
+- Large repositories may take time to download
+- Record text preview is truncated to 60 characters
+- The `--collection` filter matches the start of the collection path

examples/repo_inspector/dune

···
+(executable
+ (name repo_inspector)
+ (public_name repo_inspector)
+ (package atproto)
+ (libraries
+  atproto-repo
+  atproto-mst
+  atproto-ipld
+  atproto-identity
+  atproto-syntax
+  atproto-crypto
+  climate
+  eio_main
+  cohttp-eio
+  tls-eio
+  ca-certs-nss
+  base64
+  mirage-crypto-rng.unix
+  uri))

examples/repo_inspector/repo_inspector.ml

···
+(** Repository Inspector - Explore AT Protocol repositories.
+
+    This example demonstrates: 1. Downloading a repository as CAR file 2.
+    Parsing the MST structure 3. Displaying records with CIDs 4. Verifying
+    commit signatures
+
+    Usage: repo_inspector <DID> [--pds URL] [--collections|--records|--verify]
+*)
+
+module Car = Atproto_ipld.Car
+module Dag_cbor = Atproto_ipld.Dag_cbor
+module Dag_json = Atproto_ipld.Dag_json
+module Cid = Atproto_ipld.Cid
+module Repo = Atproto_repo.Repo
+module Commit = Atproto_repo.Commit
+module Blockstore = Atproto_mst.Memory_blockstore
+module Mst = Atproto_mst.Make (Blockstore)
+module Did = Atproto_syntax.Did
+module Did_resolver = Atproto_identity.Did_resolver
+
+(** {1 HTTP Client with cohttp-eio} *)
+
+let http_get ~sw ~client uri =
+  try
+    let resp, resp_body = Cohttp_eio.Client.call ~sw client `GET uri in
+    let status = Cohttp.Response.status resp |> Cohttp.Code.code_of_status in
+    let body =
+      Eio.Buf_read.(of_flow ~max_size:(100 * 1024 * 1024) resp_body |> take_all)
+    in
+    (status, body)
+  with e -> (0, Printexc.to_string e)
+
+(** {1 DID Resolution Effect Handler} *)
+
+let run_with_resolver ~sw ~client f =
+  Effect.Deep.try_with f ()
+    {
+      effc =
+        (fun (type a) (eff : a Effect.t) ->
+          match eff with
+          | Did_resolver.Http_get uri ->
+              Some
+                (fun (k : (a, _) Effect.Deep.continuation) ->
+                  let status, body = http_get ~sw ~client uri in
+                  Effect.Deep.continue k Did_resolver.{ status; body })
+          | _ -> None);
+    }
+
+(** {1 PDS Resolution} *)
+
+let resolve_pds ~sw ~client did_str =
+  match Did.of_string did_str with
+  | Error _ -> Error "Invalid DID format"
+  | Ok did ->
+      run_with_resolver ~sw ~client (fun () ->
+          match Did_resolver.resolve_did did with
+          | Error e -> Error (Did_resolver.error_to_string e)
+          | Ok doc -> (
+              (* Find AtprotoPersonalDataServer service *)
+              match
+                List.find_opt
+                  (fun (s : Did_resolver.service) ->
+                    s.type_ = "AtprotoPersonalDataServer")
+                  doc.service
+              with
+              | Some s -> Ok s.service_endpoint
+              | None -> Error "No PDS service found in DID document"))
+
+(** {1 Repository Fetching} *)
+
+let fetch_repo ~sw ~client ~pds_url did =
+  let uri =
+    Uri.of_string (pds_url ^ "/xrpc/com.atproto.sync.getRepo")
+    |> Fun.flip Uri.add_query_param ("did", [ did ])
+  in
+  Printf.printf "Fetching %s...\n%!" (Uri.to_string uri);
+  let status, body = http_get ~sw ~client uri in
+  if status = 200 then Ok body
+  else
+    Error
+      (Printf.sprintf "HTTP %d: %s" status
+         (String.sub body 0 (min 200 (String.length body))))
+
+(** {1 Repository Analysis} *)
+
+let truncate n s =
+  if String.length s <= n then s else String.sub s 0 (n - 3) ^ "..."
+
+let single_line s =
+  String.map (fun c -> if c = '\n' || c = '\r' then ' ' else c) s
+
+let get_text cbor =
+  match cbor with
+  | Dag_cbor.Map pairs -> (
+      match List.assoc_opt "text" pairs with
+      | Some (Dag_cbor.String s) -> Some s
+      | _ -> None)
+  | _ -> None
+
+let analyze_repo car_data =
+  match Car.read car_data with
+  | Error e ->
+      Printf.printf "Failed to parse CAR: %s\n" (Car.error_to_string e);
+      None
+  | Ok (header, blocks) -> (
+      Printf.printf "\nCAR Header\n----------\n";
+      Printf.printf "Version: %d\n" header.version;
+      Printf.printf "Roots:   %d\n" (List.length header.roots);
+      List.iter
+        (fun r -> Printf.printf "  - %s\n" (Cid.to_string r))
+        header.roots;
+      Printf.printf "Blocks:  %d\n\n" (List.length blocks);
+      (* Build blockstore *)
+      let store = Blockstore.create () in
+      List.iter
+        (fun (b : Car.block) -> Blockstore.put store b.cid b.data)
+        blocks;
+      (* Find commit *)
+      let commit_cid = List.hd header.roots in
+      let commit_data = Blockstore.get store commit_cid in
+      match commit_data with
+      | None ->
+          Printf.printf "Commit block not found\n";
+          None
+      | Some data -> (
+          match Commit.of_dag_cbor data with
+          | Error _ ->
+              Printf.printf "Failed to parse commit\n";
+              None
+          | Ok commit -> Some (store, commit)))
+
+let show_commit (commit : Commit.t) =
+  Printf.printf "Commit\n------\n";
+  Printf.printf "DID:     %s\n" commit.did;
+  Printf.printf "Version: %d\n" commit.version;
+  Printf.printf "Rev:     %s\n" commit.rev;
+  Printf.printf "Data:    %s\n" (Cid.to_string commit.data);
+  (match commit.prev with
+  | Some p -> Printf.printf "Prev:    %s\n" (Cid.to_string p)
+  | None -> ());
+  Printf.printf "\n"
+
+let show_collections store (commit : Commit.t) =
+  Printf.printf "Collections\n-----------\n";
+  let entries = Mst.to_list store commit.data in
+  let collections = Hashtbl.create 16 in
+  List.iter
+    (fun (key, _) ->
+      match String.index_opt key '/' with
+      | Some i ->
+          let coll = String.sub key 0 i in
+          let count =
+            match Hashtbl.find_opt collections coll with
+            | Some n -> n + 1
+            | None -> 1
+          in
+          Hashtbl.replace collections coll count
+      | None -> ())
+    entries;
+  Hashtbl.iter
+    (fun coll count -> Printf.printf "  %s: %d\n" coll count)
+    collections;
+  Printf.printf "\nTotal records: %d\n" (List.length entries)
+
+let show_records ?(limit = 20) ?(collection = None) store (commit : Commit.t) =
+  Printf.printf "Records%s\n-------\n"
+    (match collection with Some c -> " (" ^ c ^ ")" | None -> "");
+  let entries = Mst.to_list store commit.data in
+  let filtered =
+    match collection with
+    | None -> entries
+    | Some prefix ->
+        List.filter
+          (fun (key, _) ->
+            String.length key > String.length prefix
+            && String.sub key 0 (String.length prefix) = prefix)
+          entries
+  in
+  let shown = ref 0 in
+  List.iter
+    (fun (key, cid) ->
+      if !shown < limit then begin
+        Printf.printf "%s\n  CID: %s\n" key (Cid.to_string cid);
+        (* Try to get and show content preview *)
+        (match Blockstore.get store cid with
+        | Some data -> (
+            match Dag_cbor.decode data with
+            | Ok cbor -> (
+                match get_text cbor with
+                | Some t ->
+                    Printf.printf "  Text: %s\n" (truncate 60 (single_line t))
+                | None -> ())
+            | Error _ -> ())
+        | None -> ());
+        incr shown
+      end)
+    filtered;
+  if List.length filtered > limit then
+    Printf.printf "\n... and %d more\n" (List.length filtered - limit)
+
+let verify_commit _store (commit : Commit.t) =
+  Printf.printf "Commit Verification\n-------------------\n";
+  Printf.printf "DID:       %s\n" commit.did;
+  let sig_b64 =
+    if String.length commit.sig_ > 0 then
+      truncate 40 (Base64.encode_exn commit.sig_)
+    else "(none)"
+  in
+  Printf.printf "Signature: %s\n" sig_b64;
+  (* Get signing key from DID - would need identity resolution *)
+  Printf.printf
+    "Status:    Signature present but key resolution not implemented\n";
+  Printf.printf "           (would need to resolve DID document to verify)\n"
+
+(** {1 CLI} *)
+
+type mode = Summary | Collections | Records of string option | Verify
+
+let cli =
+  let open Climate.Arg_parser in
+  let+ did = pos_req 0 string ~value_name:"DID" ~doc:"Repository DID to inspect"
+  and+ pds =
+    named_opt [ "pds" ] string ~doc:"PDS URL (auto-resolved if not specified)"
+  and+ collections = flag [ "c"; "collections" ] ~doc:"List collections"
+  and+ records = flag [ "r"; "records" ] ~doc:"Show records"
+  and+ collection =
+    named_opt [ "collection" ] string ~doc:"Filter by collection"
+  and+ verify = flag [ "v"; "verify" ] ~doc:"Verify commit signature"
+  and+ limit = named_opt [ "n"; "limit" ] int ~doc:"Limit records shown" in
+  let mode =
+    if collections then Collections
+    else if records then Records collection
+    else if verify then Verify
+    else Summary
+  in
+  (did, pds, mode, Option.value limit ~default:20)
+
+let () =
+  Mirage_crypto_rng_unix.use_default ();
+  Eio_main.run @@ fun env ->
+  Eio.Switch.run @@ fun sw ->
+  let auth =
+    match Ca_certs_nss.authenticator () with
+    | Ok a -> a
+    | Error (`Msg m) -> failwith m
+  in
+  let https_config =
+    match Tls.Config.client ~authenticator:auth () with
+    | Ok c -> c
+    | Error (`Msg m) -> failwith m
+  in
+  let https uri socket =
+    let tls_host =
+      match Uri.host uri with
+      | Some h -> (
+          match Domain_name.of_string h with
+          | Error _ -> None
+          | Ok dn -> Domain_name.host dn |> Result.to_option)
+      | None -> None
+    in
+    Tls_eio.client_of_flow https_config ?host:tls_host socket
+  in
+  let client = Cohttp_eio.Client.make ~https:(Some https) env#net in
+  let did, pds_opt, mode, limit =
+    Climate.Command.run
+      ~program_name:(Climate.Program_name.Literal "repo_inspector")
+      (Climate.Command.singleton ~doc:"AT Protocol repository inspector" cli)
+  in
+  Printf.printf "Repository Inspector\n====================\n\n";
+  (* Resolve PDS if not provided *)
+  let pds_url =
+    match pds_opt with
+    | Some url -> url
+    | None -> (
+        Printf.printf "Resolving PDS for %s...\n%!" did;
+        match resolve_pds ~sw ~client did with
+        | Ok url ->
+            Printf.printf "PDS: %s\n\n%!" url;
+            url
+        | Error e ->
+            Printf.printf "Error resolving PDS: %s\n" e;
+            exit 1)
+  in
+  match fetch_repo ~sw ~client ~pds_url did with
+  | Error e ->
+      Printf.printf "Error: %s\n" e;
+      exit 1
+  | Ok car_data -> (
+      match analyze_repo car_data with
+      | None -> exit 1
+      | Some (store, commit) -> (
+          show_commit commit;
+          match mode with
+          | Summary -> show_collections store commit
+          | Collections -> show_collections store commit
+          | Records coll -> show_records ~limit ~collection:coll store commit
+          | Verify -> verify_commit store commit))