feat: add cursor pagination and time windows to query command

Replace the old 'last N results' approach with forward pagination:
- Add --after and --before for absolute ISO timestamp bounds
- Default limit reduced from 100 to 50 for manageable pages
- Output includes 'Next page: --after <timestamp>' when more results exist
- Results returned oldest-first for natural forward pagination

Update skill to guide agents toward broad queries with pagination
instead of aggressive namespace/match filtering.

Author: ericallam

docs/content/docs/cli/query.mdx

@@ -5,7 +5,7 @@ description: "Search historical crumbs"
 
 ## `agentcrumbs query`
 
-Query historical crumbs with time ranges and filters.
+Query historical crumbs with time windows and cursor-based pagination.
 
 ```bash
 agentcrumbs query --since 5m
@@ -15,38 +15,50 @@ agentcrumbs query --since 5m
 
 | Flag | Description |
 | --- | --- |
-| `--since <duration>` | Time range (e.g., `5m`, `1h`, `24h`, `7d`) |
+| `--since <duration>` | Relative time window (e.g., `5m`, `1h`, `24h`, `7d`) |
+| `--after <timestamp>` | Crumbs after this ISO timestamp (cursor for pagination) |
+| `--before <timestamp>` | Crumbs before this ISO timestamp |
+| `--limit <n>` | Results per page (default: 50) |
 | `--ns <pattern>` | Filter by namespace |
 | `--tag <tag>` | Filter by tag |
 | `--session <id>` | Filter by session ID |
 | `--match <text>` | Text search |
 | `--app <name>` | Scope to a specific app (default: auto-detect from package.json) |
 | `--all-apps` | Query crumbs from all apps |
 | `--json` | JSON output |
-| `--limit <n>` | Maximum number of results |
 
 Time units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days).
 
+### Pagination
+
+Results are returned oldest-first, capped at `--limit` (default 50). When there are more results, the output includes a `Next page:` line with an `--after` timestamp you can use to fetch the next page.
+
+```bash
+# First page
+agentcrumbs query --since 5m
+# Output: 50 of 128 crumbs. Next page: --after 2026-03-11T14:20:00.123Z
+
+# Next page
+agentcrumbs query --since 5m --after 2026-03-11T14:20:00.123Z
+```
+
 ### Examples
 
 ```bash
-# Last 5 minutes
+# Last 5 minutes (all namespaces)
 agentcrumbs query --since 5m
 
-# Last hour, filtered by namespace
-agentcrumbs query --since 1h --ns auth-service
+# Time window with absolute timestamps
+agentcrumbs query --after 2026-03-11T14:00:00Z --before 2026-03-11T14:05:00Z
 
-# Filter by tag
-agentcrumbs query --tag root-cause
+# Paginate through results
+agentcrumbs query --since 1h --limit 25
 
 # Filter by session
 agentcrumbs query --session a1b2c3
 
-# JSON output with limit
-agentcrumbs query --since 1h --json --limit 50
-
-# Text search
-agentcrumbs query --since 24h --match "connection refused"
+# Filter by tag
+agentcrumbs query --tag root-cause
 
 # Query a specific app
 agentcrumbs query --since 1h --app my-project

packages/agentcrumbs/skills/agentcrumbs/SKILL.md

@@ -82,7 +82,8 @@ agentcrumbs collect           # Start HTTP collector (required for query/tail)
 agentcrumbs tail              # Live tail (auto-scoped to current app)
 agentcrumbs tail --app foo    # Tail a specific app
 agentcrumbs tail --all-apps   # Tail all apps
-agentcrumbs query --since 5m  # Query history (--ns, --tag, --session, --json)
+agentcrumbs query --since 5m  # Query last 5 minutes (all namespaces, 50 per page)
+agentcrumbs query --since 5m --after <timestamp>  # Next page
 agentcrumbs clear             # Clear crumbs for current app
 agentcrumbs clear --all-apps  # Clear crumbs for all apps
 agentcrumbs strip             # Remove all crumb markers from source
@@ -92,6 +93,28 @@ agentcrumbs --help            # Full command reference
 
 Most commands accept `--app <name>` and `--all-apps`. Default is auto-detect from `package.json`.
 
+## Querying crumbs
+
+Start broad — query a time window across all namespaces, then paginate if there are too many results. Do NOT filter by namespace or match text unless you are looking for something very specific. The whole point of crumbs is seeing the full picture across services.
+
+```bash
+# Start here: get recent crumbs across all services
+agentcrumbs query --since 5m
+
+# Paginate forward (timestamp from "Next page:" in output)
+agentcrumbs query --since 5m --after 2026-03-11T14:20:00.123Z
+
+# Time window with absolute bounds
+agentcrumbs query --after 2026-03-11T14:00:00Z --before 2026-03-11T14:05:00Z
+
+# Smaller pages if context is tight
+agentcrumbs query --since 5m --limit 25
+
+# Only filter by namespace/match when you have a specific reason
+agentcrumbs query --since 5m --tag error
+agentcrumbs query --session a1b2c3
+```
+
 Run `agentcrumbs <command> --help` for detailed options on any command.
 
 ## Enable tracing

packages/agentcrumbs/src/cli/commands/query.ts

@@ -7,22 +7,44 @@ export async function query(args: string[]): Promise<void> {
   const ns = getFlag(args, "--ns");
   const tag = getFlag(args, "--tag");
   const since = getFlag(args, "--since");
+  const after = getFlag(args, "--after");
+  const before = getFlag(args, "--before");
   const session = getFlag(args, "--session");
   const match = getFlag(args, "--match");
   const json = hasFlag(args, "--json");
-  const limit = parseInt(getFlag(args, "--limit") ?? "100", 10);
+  const limit = parseInt(getFlag(args, "--limit") ?? "50", 10);
   const appCtx = parseAppFlags(args);
   const showApp = appCtx.allApps;
 
   const allCrumbs = readAllCrumbs(appCtx);
 
   let filtered = allCrumbs;
 
+  // Time window filters
   if (since) {
     const cutoff = parseSince(since);
     filtered = filtered.filter((c) => new Date(c.ts).getTime() >= cutoff);
   }
 
+  if (after) {
+    const afterMs = new Date(after).getTime();
+    if (isNaN(afterMs)) {
+      process.stderr.write(`Invalid --after timestamp: "${after}". Use ISO 8601 format.\n`);
+      process.exit(1);
+    }
+    filtered = filtered.filter((c) => new Date(c.ts).getTime() > afterMs);
+  }
+
+  if (before) {
+    const beforeMs = new Date(before).getTime();
+    if (isNaN(beforeMs)) {
+      process.stderr.write(`Invalid --before timestamp: "${before}". Use ISO 8601 format.\n`);
+      process.exit(1);
+    }
+    filtered = filtered.filter((c) => new Date(c.ts).getTime() < beforeMs);
+  }
+
+  // Content filters
   if (ns) {
     const pattern = new RegExp(`^${ns.replace(/\*/g, ".*")}$`);
     filtered = filtered.filter((c) => pattern.test(c.ns));
@@ -40,7 +62,10 @@ export async function query(args: string[]): Promise<void> {
     filtered = filtered.filter((c) => JSON.stringify(c).includes(match));
   }
 
-  const results = filtered.slice(-limit);
+  const total = filtered.length;
+
+  // Take first `limit` crumbs (oldest first) for forward pagination
+  const results = filtered.slice(0, limit);
 
   if (results.length === 0) {
     process.stderr.write("No crumbs found matching filters.\n");
@@ -55,7 +80,16 @@ export async function query(args: string[]): Promise<void> {
     }
   }
 
-  process.stderr.write(`\n${results.length} crumbs found.\n`);
+  // Pagination footer
+  const hasMore = total > results.length;
+  if (hasMore) {
+    const lastTs = results[results.length - 1]!.ts;
+    process.stderr.write(
+      `\n${results.length} of ${total} crumbs. Next page: --after ${lastTs}\n`
+    );
+  } else {
+    process.stderr.write(`\n${results.length} crumbs.\n`);
+  }
 }
 
 function parseSince(since: string): number {

packages/agentcrumbs/src/cli/index.ts

@@ -35,12 +35,14 @@ Tail options:
   --json               Output as JSON
 
 Query options:
-  --since <duration>   Time filter (e.g., 5m, 1h, 24h)
+  --since <duration>   Relative time window (e.g., 5m, 1h, 24h)
+  --after <timestamp>  Crumbs after this ISO timestamp (for pagination)
+  --before <timestamp> Crumbs before this ISO timestamp
+  --limit <n>          Max results per page (default: 50)
   --ns <pattern>       Filter by namespace
   --tag <tag>          Filter by tag
   --session <id>       Filter by session ID
   --match <text>       Filter by text content
-  --limit <n>          Max results (default: 100)
   --json               Output as JSON
 
 Collect options: