docs: add 6 usage examples

examples/01-basic-workflow.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# Example: Basic grit workflow — single agent
+#
+# Demonstrates: init → claim → work → done
+
+set -euo pipefail
+
+PROJECT_DIR=$(mktemp -d)
+echo "=== Creating sample project in $PROJECT_DIR ==="
+
+# Create a sample git repo with some code
+cd "$PROJECT_DIR"
+git init -q
+mkdir -p src
+
+cat > src/math.ts << 'EOF'
+export function add(a: number, b: number): number {
+  return a + b;
+}
+
+export function subtract(a: number, b: number): number {
+  return a - b;
+}
+
+export function multiply(a: number, b: number): number {
+  return a * b;
+}
+
+export function divide(a: number, b: number): number {
+  if (b === 0) throw new Error("division by zero");
+  return a / b;
+}
+EOF
+
+git add -A && git commit -q -m "initial commit"
+
+# 1. Initialize grit
+echo ""
+echo "=== Step 1: grit init ==="
+grit init
+
+# 2. See what symbols are available
+echo ""
+echo "=== Step 2: grit symbols ==="
+grit symbols
+
+# 3. Agent claims functions to work on
+echo ""
+echo "=== Step 3: Agent claims 'add' and 'subtract' ==="
+grit claim -a agent-1 -i "add input validation" \
+  "src/math.ts::add" \
+  "src/math.ts::subtract"
+
+# 4. Check lock status
+echo ""
+echo "=== Step 4: grit status ==="
+grit status
+
+# 5. Agent works in its isolated worktree
+echo ""
+echo "=== Step 5: Agent edits files in worktree ==="
+WORKTREE="$PROJECT_DIR/.grit/worktrees/agent-1"
+cat > "$WORKTREE/src/math.ts" << 'EOF'
+export function add(a: number, b: number): number {
+  if (typeof a !== "number" || typeof b !== "number") throw new Error("invalid input");
+  return a + b;
+}
+
+export function subtract(a: number, b: number): number {
+  if (typeof a !== "number" || typeof b !== "number") throw new Error("invalid input");
+  return a - b;
+}
+
+export function multiply(a: number, b: number): number {
+  return a * b;
+}
+
+export function divide(a: number, b: number): number {
+  if (b === 0) throw new Error("division by zero");
+  return a / b;
+}
+EOF
+
+# 6. Done: auto-commit, rebase, merge, release locks
+echo ""
+echo "=== Step 6: grit done ==="
+grit done -a agent-1
+
+# 7. Verify clean state
+echo ""
+echo "=== Step 7: Final status (should be empty) ==="
+grit status
+
+echo ""
+echo "=== Done! Changes merged back to main branch ==="
+git log --oneline -5
+
+# Cleanup
+rm -rf "$PROJECT_DIR"

examples/02-parallel-agents.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Example: Parallel agents — 3 agents working on the same file simultaneously
+#
+# Demonstrates: multiple claims on different functions in the SAME file,
+# parallel worktrees, sequential done (merge serialization)
+
+set -euo pipefail
+
+PROJECT_DIR=$(mktemp -d)
+echo "=== Creating sample project in $PROJECT_DIR ==="
+
+cd "$PROJECT_DIR"
+git init -q
+mkdir -p src
+
+cat > src/auth.ts << 'EOF'
+export function validateToken(token: string): boolean {
+  return token.length > 0;
+}
+
+export function refreshToken(token: string): string {
+  return token + "-refreshed";
+}
+
+export function revokeToken(token: string): void {
+  console.log("revoked:", token);
+}
+
+export function generateToken(user: string): string {
+  return btoa(user + ":" + Date.now());
+}
+
+export function parseToken(token: string): { user: string; exp: number } {
+  const decoded = atob(token);
+  const [user, exp] = decoded.split(":");
+  return { user, exp: parseInt(exp) };
+}
+EOF
+
+git add -A && git commit -q -m "initial commit"
+
+# Initialize
+grit init
+echo ""
+echo "=== Symbols indexed ==="
+grit symbols
+
+# 3 agents claim different functions in the SAME file
+echo ""
+echo "=== Agent 1: claims validateToken + parseToken ==="
+grit claim -a agent-1 -i "add JWT validation" \
+  "src/auth.ts::validateToken" \
+  "src/auth.ts::parseToken"
+
+echo ""
+echo "=== Agent 2: claims refreshToken ==="
+grit claim -a agent-2 -i "add expiry check" \
+  "src/auth.ts::refreshToken"
+
+echo ""
+echo "=== Agent 3: claims generateToken ==="
+grit claim -a agent-3 -i "use crypto.randomUUID" \
+  "src/auth.ts::generateToken"
+
+echo ""
+echo "=== Status: 3 agents, same file, no conflicts ==="
+grit status
+
+# Agent 2 tries to claim a symbol already held by Agent 1
+echo ""
+echo "=== Agent 2 tries to claim parseToken (held by Agent 1) ==="
+grit claim -a agent-2 -i "also want parseToken" \
+  "src/auth.ts::parseToken" 2>&1 || echo "  → Blocked as expected!"
+
+# Each agent edits in their own worktree
+echo ""
+echo "=== Agents work in parallel worktrees ==="
+ls -la .grit/worktrees/
+
+# Agent 1 finishes
+echo ""
+echo "=== Agent 1: done ==="
+grit done -a agent-1
+
+# Agent 2 finishes
+echo ""
+echo "=== Agent 2: done ==="
+grit done -a agent-2
+
+# Agent 3 finishes
+echo ""
+echo "=== Agent 3: done ==="
+grit done -a agent-3
+
+echo ""
+echo "=== Final status: all locks released ==="
+grit status
+
+echo ""
+echo "=== Git log: each agent's merge is a separate commit ==="
+git log --oneline -10
+
+rm -rf "$PROJECT_DIR"

examples/03-session-pr.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Example: Session workflow — feature branch + GitHub PR
+#
+# Demonstrates: session start → agents work → session pr → session end
+# NOTE: This example requires a GitHub remote to create PRs.
+#       Run it in a real repo with `gh` CLI configured.
+
+set -euo pipefail
+
+echo "=== Session Workflow ==="
+echo "This example shows the full session lifecycle."
+echo "Run it in a real git repo with a GitHub remote."
+echo ""
+
+# 1. Start a session (creates branch grit/<name>)
+echo "$ grit session start auth-refactor"
+echo "  → Creates branch grit/auth-refactor"
+echo "  → Records base branch for PR"
+echo ""
+
+# 2. Agents claim and work
+echo "$ grit claim -a agent-1 -i 'add JWT' src/auth.ts::validateToken"
+echo "$ grit claim -a agent-2 -i 'add OAuth' src/auth.ts::oauthLogin"
+echo "  → Each agent gets an isolated worktree"
+echo ""
+
+# 3. Check session status
+echo "$ grit session status"
+echo "  → Shows: branch, base, active agents, locked symbols"
+echo ""
+
+# 4. Agents finish
+echo "$ grit done -a agent-1"
+echo "$ grit done -a agent-2"
+echo "  → Each merge is serialized (no conflicts)"
+echo ""
+
+# 5. Create PR
+echo "$ grit session pr --title 'Auth refactor: JWT + OAuth'"
+echo "  → Pushes branch to origin"
+echo "  → Creates GitHub PR with session summary"
+echo ""
+
+# 6. End session
+echo "$ grit session end"
+echo "  → Cleans up expired locks"
+echo "  → Switches back to base branch"
+echo ""
+
+echo "=== Full command sequence ==="
+cat << 'CMD'
+grit init
+grit session start auth-refactor
+
+grit claim -a agent-1 -i "add JWT validation" src/auth.ts::validateToken
+grit claim -a agent-2 -i "add OAuth flow"     src/auth.ts::oauthLogin
+
+# ... agents edit in .grit/worktrees/agent-{1,2}/ ...
+
+grit done -a agent-1
+grit done -a agent-2
+
+grit session pr --title "Auth refactor: JWT + OAuth"
+grit session end
+CMD

examples/04-s3-backend.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Example: S3-compatible backend — distributed lock coordination
+#
+# Demonstrates: configuring grit to use S3/R2/MinIO for locks,
+# enabling multi-machine agent coordination.
+
+set -euo pipefail
+
+echo "=== S3 Backend Configuration ==="
+echo ""
+echo "By default, grit uses SQLite (local). For distributed teams"
+echo "or cloud-based agents, switch to an S3-compatible backend."
+echo ""
+
+echo "--- AWS S3 ---"
+cat << 'CMD'
+export AWS_ACCESS_KEY_ID=...
+export AWS_SECRET_ACCESS_KEY=...
+
+grit init
+grit config set-s3 --bucket my-grit-locks --region us-east-1
+grit config show
+CMD
+
+echo ""
+echo "--- Cloudflare R2 ---"
+cat << 'CMD'
+export AWS_ACCESS_KEY_ID=...        # R2 API token
+export AWS_SECRET_ACCESS_KEY=...
+
+grit init
+grit config set-s3 \
+  --bucket grit-locks \
+  --endpoint https://<account-id>.r2.cloudflarestorage.com \
+  --region auto
+CMD
+
+echo ""
+echo "--- MinIO (self-hosted) ---"
+cat << 'CMD'
+export AWS_ACCESS_KEY_ID=minioadmin
+export AWS_SECRET_ACCESS_KEY=minioadmin
+
+grit init
+grit config set-s3 \
+  --bucket grit-locks \
+  --endpoint http://localhost:9000 \
+  --region us-east-1
+CMD
+
+echo ""
+echo "--- Google Cloud Storage (S3-compatible) ---"
+cat << 'CMD'
+export AWS_ACCESS_KEY_ID=...        # HMAC key
+export AWS_SECRET_ACCESS_KEY=...
+
+grit init
+grit config set-s3 \
+  --bucket grit-locks \
+  --endpoint https://storage.googleapis.com \
+  --region auto
+CMD
+
+echo ""
+echo "--- Switch back to local ---"
+cat << 'CMD'
+grit config set-local
+grit config show
+CMD
+
+echo ""
+echo "=== How S3 locking works ==="
+echo "Each lock is an S3 object:"
+echo "  Key:  .grit/locks/{url_encoded_symbol_id}"
+echo "  Body: JSON LockEntry (agent, intent, TTL, timestamp)"
+echo ""
+echo "Atomic acquisition via conditional PUT (If-None-Match: *)"
+echo "  → Only one agent can create the lock object"
+echo "  → Race conditions handled with retry logic"