docs: restructure README and command help by persona

Separate developer vs agent vs ad-hoc touchpoints with clear tables
showing what the user does and what Rekal does in response. Update
push and sync Long help to explain data ownership and compaction.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Frank Guo

README.md

@@ -130,50 +130,70 @@ flowchart LR
     style query fill:#faf5ff,stroke:#a855f7,color:#333
 ```
 
-The flow: commit, capture, push, sync, recall.
+The flow: commit → capture → push → sync → recall.
 
-1. **Commit.** You commit code as usual. The post-commit hook runs `rekal checkpoint`, which snapshots your active AI session into `data.db`. Append-only — nothing is ever modified or deleted.
+### Developer touchpoints
 
-2. **Push.** `rekal push` encodes your data into a compact wire format (zstd compression, string interning) and writes it to your personal orphan branch `rekal/<your-email>`. Your git history stays clean — rekal data lives on a separate branch.
+| You do | Rekal does |
+|--------|------------|
+| `rekal init` (once per repo) | Creates `.rekal/`, installs git hooks, writes agent skill file |
+| `git commit` | Hook runs `rekal checkpoint` — snapshots your active AI session into `data.db` (append-only) |
+| `git push` | Hook runs `rekal push` — encodes only your unexported data into compact wire format (zstd + string interning) and pushes to your orphan branch `rekal/<email>` |
+| `rekal sync` (manual, when you want team context) | Fetches teammates' orphan branches, imports their sessions into your local DB and rebuilds the search index |
+| `rekal clean` (if needed) | Removes `.rekal/` and hooks from the repo |
 
-3. **Sync.** `rekal sync` pulls your teammates' orphan branches and imports their session data into your local index.
+Day-to-day: commit and push as normal. Everything else is automatic.
 
-4. **Recall.** `rekal "query"` runs a three-signal hybrid search (BM25 full-text, LSA embeddings, Nomic deep semantic embeddings) and returns scored results. The agent picks what matters.
+### Agent touchpoints
 
-### Two databases
+| Agent does | Rekal does |
+|------------|------------|
+| `rekal "auth middleware"` | Runs hybrid search (BM25 + LSA + Nomic), returns scored JSON with `snippet_turn_index` pointing to the best-matching turn |
+| `rekal query --session <id> --offset N --limit 5` | Returns a small window of turns around the relevant part of the conversation, with `has_more` for pagination |
+| `rekal query --session <id> --role human` | Returns only human turns — cheapest way to understand session intent |
+| `rekal query --session <id> --full` | Returns everything: turns, tool calls, files touched — only when the agent needs full detail |
+| `rekal --file src/billing/ "discount"` | Scoped search filtered by file path |
+| `rekal sync` (optional, at session start) | Pulls team context before the agent starts working |
 
-Rekal keeps two local DuckDB databases. The split is deliberate.
+The agent controls how much context it loads. Search first, drill down progressively, full sessions only when needed.
 
-- **data.db** — The shared truth. Append-only. Contains sessions, turns, tool calls, checkpoints, files touched. This is what gets encoded and pushed through git. `rekal query` reads from here.
+```bash
+# Agent touches src/billing/ — first, recall prior context
+rekal --file src/billing/ "discount logic"
 
-- **index.db** — Local intelligence. Full-text indexes, vector embeddings, file co-occurrence graphs. Never synced. Rebuilt anytime with `rekal index`. This is what powers `rekal "query"` search.
+# Agent finds a relevant session, drills into the matching turn
+rekal query --session 01JNQX... --offset 10 --limit 5
 
-Thin on the wire, rich on the machine.
+# Agent loads full detail only if needed
+rekal query --session 01JNQX... --full
+```
 
-### Orphan branches
+### Ad-hoc usage
 
-Rekal data lives on git orphan branches named `rekal/<email>`. These branches have no common ancestor with your code branches — they do not appear in your project history, do not affect merges, and do not clutter your working tree. Standard git push and fetch move the data.
+```bash
+# Raw SQL for edge cases
+rekal query "SELECT id, user_email, branch FROM sessions ORDER BY captured_at DESC LIMIT 5"
 
-## Using Rekal with your agent
+# Rebuild the search index after manual DB changes
+rekal index
 
-Rekal is agent-first. The agent is the primary consumer.
+# View recent checkpoints
+rekal log
+```
 
-When you run `rekal init`, it installs a Claude Code skill that teaches the agent how to use Rekal. The agent learns to search for prior context before modifying files, load sessions progressively to stay within token budgets, and use the structured output to make informed decisions.
+### Two databases
 
-The agent workflow:
+Rekal keeps two local DuckDB databases. The split is deliberate.
 
-```bash
-# Agent touches src/billing/ — first, recall prior context
-rekal --file src/billing/ "discount logic"
+- **data.db** — The shared truth. Append-only. Contains sessions, turns, tool calls, checkpoints, files touched. This is what gets encoded and pushed through git. `rekal query` reads from here.
 
-# Agent finds a relevant session, drills in
-rekal query --session 01JNQX... --limit 5
+- **index.db** — Local intelligence. Full-text indexes, vector embeddings, file co-occurrence graphs. Never synced. Rebuilt anytime with `rekal index`. This is what powers `rekal "query"` search.
 
-# Agent loads more detail if needed
-rekal query --session 01JNQX... --full
-```
+Thin on the wire, rich on the machine.
 
-The agent controls how much context it loads. Lightweight search first, full sessions only when needed.
+### Orphan branches
+
+Rekal data lives on git orphan branches named `rekal/<email>`. These branches have no common ancestor with your code branches — they do not appear in your project history, do not affect merges, and do not clutter your working tree. Standard git push and fetch move the data.
 
 ## Commands reference
 

cmd/rekal/cli/push.go

@@ -17,14 +17,19 @@ func newPushCmd() *cobra.Command {
 		Short: "Push Rekal data to the remote branch",
 		Long: `Export new checkpoints to the wire format and push to the remote orphan branch.
 
-Unexported checkpoints in data.db are encoded into the compact binary wire
-format (rekal.body + dict.bin) and committed to the local orphan branch
-(rekal/<email>). The branch is then pushed to origin.
+Only YOUR unexported checkpoints are pushed — team data imported via 'rekal sync'
+is never re-exported. Each user pushes to their own branch (rekal/<email>).
+
+Checkpoints contain sessions (conversation turns, tool calls) and file change
+metadata anchored to git commits. They are encoded into a compact binary wire
+format (rekal.body + dict.bin) using zstd compression and string interning —
+a 2-10 MB session compresses to ~300 bytes on the wire.
 
 Use --force to overwrite the remote branch when it has diverged from local
 (e.g. after a rebuild or conflict).
 
-Normally runs automatically via the pre-push hook installed by 'rekal init'.`,
+Normally runs automatically via the pre-push git hook installed by 'rekal init'.
+You do not need to run this manually.`,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			cmd.SilenceUsage = true
 

cmd/rekal/cli/sync.go

@@ -17,12 +17,23 @@ func newSyncCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "sync",
 		Short: "Sync team context from remote rekal branches",
-		Long: `Fetch rekal branches from the remote and merge into the local search index.
+		Long: `Fetch team session data from remote rekal branches and import into the local database.
+
+This is a manual, deliberate operation — it is NOT automated via git hooks.
+Run it when you want to pull your team's session history before starting work.
+
+Imported data includes conversation turns, tool calls, and file change metadata
+from your teammates' AI coding sessions. Imported checkpoints are marked as
+exported so they are never re-pushed to your own branch.
 
 By default, fetches all rekal/* branches (whole team). Use --self to fetch
 only your own rekal branch — useful when syncing across your own machines
-(e.g. pulling context from your work laptop to your home machine) without
-fetching the whole team's data.`,
+(e.g. pulling context from your work laptop to your home machine).
+
+Typical usage:
+  Developer:  Run 'rekal sync' at the start of the day
+  Agent:      Run 'rekal sync' at the start of a session if team context matters
+  Ad-hoc:     Run 'rekal sync --self' to pull your own data from another machine`,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			cmd.SilenceUsage = true