docs: update all docs and READMEs for app concept and cursor pagination

- Fix storage path to ~/.agentcrumbs/<app>/crumbs.jsonl everywhere
- Add app field to cross-language examples (curl, Python, Go, Rust)
- Update CLI examples with --app, --all-apps, --cursor flags
- Add AGENTCRUMBS_APP env var to README env var table
- Update collect.mdx to show per-app routing
- Update multi-service guide with per-app storage

Author: ericallam

README.md

@@ -7,7 +7,7 @@ Crumbs are development-only. They get stripped before merge and cost nothing whe
 ```
 Service A ──┐                                ┌── $ agentcrumbs tail
 Service B ──┤── fetch() ──> Collector :8374 ──┤── $ agentcrumbs query --since 5m
-Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/crumbs.jsonl
+Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/<app>/crumbs.jsonl
 ```
 
 ## Getting started
@@ -54,14 +54,16 @@ When something goes wrong, the agent starts the collector and queries the trail:
 ```bash
 agentcrumbs collect --quiet &
 AGENTCRUMBS=1 node app.js
-agentcrumbs query --since 5m --ns auth-service
+agentcrumbs query --since 5m
 ```
 
 ```
 auth-service  login attempt       +0ms  { tokenPrefix: "eyJhbGci" }
 auth-service  token decode ok     +3ms  { userId: "u_8f3k" }
 auth-service  permissions check   +8ms  { roles: [] }
 auth-service  rejected: no roles  +8ms  { status: 401 }
+
+4 crumbs.
 ```
 
 Now the agent knows: the token is valid, but the user has no roles. The fix is in role assignment, not token validation.
@@ -114,8 +116,11 @@ Everything is controlled by a single `AGENTCRUMBS` environment variable.
 | `auth-*,api-*` | Multiple patterns (comma or space separated) |
 | `* -internal-*` | Match all except excluded patterns |
 | `{"ns":"*","port":9999}` | JSON config with full control |
+| `{"app":"my-app","ns":"*"}` | Explicit app name |
+
+JSON config fields: `app` (app name, default auto-detect from package.json), `ns` (namespace filter, required), `port` (collector port, default 8374), `format` (`"pretty"` or `"json"`, default `"pretty"`).
 
-JSON config fields: `ns` (namespace filter, required), `port` (collector port, default 8374), `format` (`"pretty"` or `"json"`, default `"pretty"`).
+You can also set `AGENTCRUMBS_APP` to override the app name independently.
 
 ## CLI
 
@@ -127,24 +132,27 @@ agentcrumbs collect --quiet &        # Start in background
 agentcrumbs collect --port 9999      # Custom port
 
 # Live tail
-agentcrumbs tail                     # All namespaces
+agentcrumbs tail                     # All namespaces (scoped to current app)
 agentcrumbs tail --ns auth-service   # Filter by namespace
-agentcrumbs tail --tag perf          # Filter by tag
+agentcrumbs tail --app my-app        # Tail a specific app
+agentcrumbs tail --all-apps          # Tail all apps
 
-# Query
-agentcrumbs query --since 5m        # Last 5 minutes
-agentcrumbs query --ns auth-service --since 1h
-agentcrumbs query --tag root-cause
-agentcrumbs query --json --limit 50
+# Query (paginated, 50 per page)
+agentcrumbs query --since 5m         # Last 5 minutes
+agentcrumbs query --since 5m --cursor a1b2c3d4  # Next page
+agentcrumbs query --since 1h --limit 25          # Smaller pages
+agentcrumbs query --session a1b2c3   # Filter by session
+agentcrumbs query --tag root-cause   # Filter by tag
 
 # Strip
 agentcrumbs strip --dry-run          # Preview removals
 agentcrumbs strip                    # Remove all crumb code
 agentcrumbs strip --check            # CI gate (exits 1 if markers found)
 
 # Utilities
-agentcrumbs stats                    # Crumb counts, file size
-agentcrumbs clear                    # Delete stored crumbs
+agentcrumbs stats                    # Crumb counts (current app)
+agentcrumbs stats --all-apps         # Stats for all apps
+agentcrumbs clear                    # Clear crumbs (current app)
 ```
 
 Time units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days).
@@ -160,7 +168,7 @@ The collector is language-agnostic. Any language with HTTP support can send crum
 ```bash
 curl -X POST http://localhost:8374/crumb \
   -H "Content-Type: application/json" \
-  -d '{"ts":"2026-01-01T00:00:00Z","ns":"shell","msg":"hello","type":"crumb","dt":0,"pid":1}'
+  -d '{"app":"my-app","ts":"2026-01-01T00:00:00Z","ns":"shell","msg":"hello","type":"crumb","dt":0,"pid":1}'
 ```
 
 ## Runtime compatibility

docs/content/docs/cli/collect.mdx

@@ -11,7 +11,7 @@ The collector is an HTTP server that receives crumbs via `POST /crumb` and write
 agentcrumbs collect
 # agentcrumbs collector
 #   http:  http://localhost:8374/crumb
-#   store: ~/.agentcrumbs/crumbs.jsonl
+#   crumbs stored per-app in ~/.agentcrumbs/<app>/
 #   press ctrl+c to stop
 ```
 
@@ -50,8 +50,8 @@ agentcrumbs collect --quiet
 
 1. Listens on the specified port for `POST /crumb` requests
 2. Validates the JSON body matches the crumb schema
-3. Appends each crumb as a line to `crumbs.jsonl`
-4. The `tail` and `query` commands read from this file
+3. Routes each crumb to per-app storage at `~/.agentcrumbs/<app>/crumbs.jsonl`
+4. The `tail` and `query` commands read from these files
 
 ### Without the collector
 

docs/content/docs/guides/cross-language.mdx

@@ -13,6 +13,7 @@ Send a `POST` request to `http://localhost:8374/crumb` with a JSON body matching
 
 | Field | Type | Description |
 | --- | --- | --- |
+| `app` | `string` | App name (used for per-app storage routing) |
 | `ts` | `string` | ISO 8601 timestamp |
 | `ns` | `string` | Namespace |
 | `msg` | `string` | Message |
@@ -38,7 +39,7 @@ Send a `POST` request to `http://localhost:8374/crumb` with a JSON body matching
 ```bash
 curl -X POST http://localhost:8374/crumb \
   -H "Content-Type: application/json" \
-  -d '{"ts":"2026-01-01T00:00:00Z","ns":"shell","msg":"hello","type":"crumb","dt":0,"pid":1}'
+  -d '{"app":"my-app","ts":"2026-01-01T00:00:00Z","ns":"shell","msg":"hello","type":"crumb","dt":0,"pid":1}'
 ```
 
 ### Python
@@ -50,6 +51,7 @@ from datetime import datetime
 def crumb(ns, msg, data=None):
     try:
         requests.post("http://localhost:8374/crumb", json={
+            "app": "my-app",
             "ts": datetime.utcnow().isoformat() + "Z",
             "ns": ns,
             "msg": msg,
@@ -69,6 +71,7 @@ crumb("python-service", "processing started", {"items": 42})
 ```go
 func crumb(ns, msg string, data any) {
     body, _ := json.Marshal(map[string]any{
+        "app":  "my-app",
         "ts":   time.Now().UTC().Format(time.RFC3339Nano),
         "ns":   ns,
         "msg":  msg,
@@ -86,6 +89,7 @@ func crumb(ns, msg string, data any) {
 ```rust
 fn crumb(ns: &str, msg: &str) {
     let body = serde_json::json!({
+        "app": "my-app",
         "ts": chrono::Utc::now().to_rfc3339(),
         "ns": ns,
         "msg": msg,

docs/content/docs/guides/multi-service.mdx

@@ -10,13 +10,13 @@ agentcrumbs is designed for systems with multiple services running locally.
 ```
 Service A ──┐                                ┌── $ agentcrumbs tail
 Service B ──┤── fetch() ──> Collector :8374 ──┤── $ agentcrumbs query --since 5m
-Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/crumbs.jsonl
+Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/<app>/crumbs.jsonl
 ```
 
 1. Each service imports `agentcrumbs` and calls `trail()` to create namespaced trail functions
 2. When `AGENTCRUMBS` is set, crumbs are sent via HTTP to the collector
-3. The collector writes crumbs to a shared JSONL file
-4. The CLI reads from the JSONL file to provide tail, query, and replay
+3. The collector routes crumbs to per-app storage at `~/.agentcrumbs/<app>/crumbs.jsonl`
+4. The CLI reads from these files to provide tail, query, and replay (auto-scoped to current app)
 
 ## Setup
 

docs/content/docs/index.mdx

@@ -14,7 +14,7 @@ Crumbs are development-only. They get stripped before merge and cost nothing whe
 ```
 Service A ──┐                                ┌── $ agentcrumbs tail
 Service B ──┤── fetch() ──> Collector :8374 ──┤── $ agentcrumbs query --since 5m
-Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/crumbs.jsonl
+Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/<app>/crumbs.jsonl
 ```
 
 ## Why agents need this

packages/agentcrumbs/README.md

@@ -7,7 +7,7 @@ Crumbs are development-only. They get stripped before merge and cost nothing whe
 ```
 Service A ──┐                                ┌── $ agentcrumbs tail
 Service B ──┤── fetch() ──> Collector :8374 ──┤── $ agentcrumbs query --since 5m
-Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/crumbs.jsonl
+Service C ──┘  (fire & forget)               └── ~/.agentcrumbs/<app>/crumbs.jsonl
 ```
 
 ## Getting started
@@ -54,14 +54,16 @@ When something goes wrong, the agent starts the collector and queries the trail:
 ```bash
 agentcrumbs collect --quiet &
 AGENTCRUMBS=1 node app.js
-agentcrumbs query --since 5m --ns auth-service
+agentcrumbs query --since 5m
 ```
 
 ```
 auth-service  login attempt       +0ms  { tokenPrefix: "eyJhbGci" }
 auth-service  token decode ok     +3ms  { userId: "u_8f3k" }
 auth-service  permissions check   +8ms  { roles: [] }
 auth-service  rejected: no roles  +8ms  { status: 401 }
+
+4 crumbs.
 ```
 
 Now the agent knows: the token is valid, but the user has no roles. The fix is in role assignment, not token validation.
@@ -114,8 +116,11 @@ Everything is controlled by a single `AGENTCRUMBS` environment variable.
 | `auth-*,api-*` | Multiple patterns (comma or space separated) |
 | `* -internal-*` | Match all except excluded patterns |
 | `{"ns":"*","port":9999}` | JSON config with full control |
+| `{"app":"my-app","ns":"*"}` | Explicit app name |
+
+JSON config fields: `app` (app name, default auto-detect from package.json), `ns` (namespace filter, required), `port` (collector port, default 8374), `format` (`"pretty"` or `"json"`, default `"pretty"`).
 
-JSON config fields: `ns` (namespace filter, required), `port` (collector port, default 8374), `format` (`"pretty"` or `"json"`, default `"pretty"`).
+You can also set `AGENTCRUMBS_APP` to override the app name independently.
 
 ## CLI
 
@@ -127,24 +132,27 @@ agentcrumbs collect --quiet &        # Start in background
 agentcrumbs collect --port 9999      # Custom port
 
 # Live tail
-agentcrumbs tail                     # All namespaces
+agentcrumbs tail                     # All namespaces (scoped to current app)
 agentcrumbs tail --ns auth-service   # Filter by namespace
-agentcrumbs tail --tag perf          # Filter by tag
+agentcrumbs tail --app my-app        # Tail a specific app
+agentcrumbs tail --all-apps          # Tail all apps
 
-# Query
-agentcrumbs query --since 5m        # Last 5 minutes
-agentcrumbs query --ns auth-service --since 1h
-agentcrumbs query --tag root-cause
-agentcrumbs query --json --limit 50
+# Query (paginated, 50 per page)
+agentcrumbs query --since 5m         # Last 5 minutes
+agentcrumbs query --since 5m --cursor a1b2c3d4  # Next page
+agentcrumbs query --since 1h --limit 25          # Smaller pages
+agentcrumbs query --session a1b2c3   # Filter by session
+agentcrumbs query --tag root-cause   # Filter by tag
 
 # Strip
 agentcrumbs strip --dry-run          # Preview removals
 agentcrumbs strip                    # Remove all crumb code
 agentcrumbs strip --check            # CI gate (exits 1 if markers found)
 
 # Utilities
-agentcrumbs stats                    # Crumb counts, file size
-agentcrumbs clear                    # Delete stored crumbs
+agentcrumbs stats                    # Crumb counts (current app)
+agentcrumbs stats --all-apps         # Stats for all apps
+agentcrumbs clear                    # Clear crumbs (current app)
 ```
 
 Time units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days).
@@ -160,7 +168,7 @@ The collector is language-agnostic. Any language with HTTP support can send crum
 ```bash
 curl -X POST http://localhost:8374/crumb \
   -H "Content-Type: application/json" \
-  -d '{"ts":"2026-01-01T00:00:00Z","ns":"shell","msg":"hello","type":"crumb","dt":0,"pid":1}'
+  -d '{"app":"my-app","ts":"2026-01-01T00:00:00Z","ns":"shell","msg":"hello","type":"crumb","dt":0,"pid":1}'
 ```
 
 ## Runtime compatibility