# AI Agent Instructions

Quick reference for AI agents installing OpenTimestamp hooks.

## ⚠️ Hard Requirement

**`ots` CLI must be installed.** No fallback available.

```bash
pipx install opentimestamps-client
```

The Node.js `@opentimestamps/ots` package is **not a valid alternative** - it only creates local proofs without calendar submission or Bitcoin attestation.

## Installation

```bash
# 1. Verify/install prerequisites
if ! command -v ots &> /dev/null; then
    pipx install opentimestamps-client
fi

# 2. Install hooks
./hooks/install.sh .

# 3. Commit proofs
git add .ots/ .gitignore
git commit -m "Add OpenTimestamp proofs for commit history"
```

## Manual Installation

```bash
cp hooks/post-commit .git/hooks/post-commit
cp hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/post-commit .git/hooks/pre-commit
```

**.gitignore:**
```
.ots/.attestation-cache
```

## Key Files

| File | Purpose | Version? |
|------|---------|----------|
| `hooks/post-commit` | Post-commit hook | Yes |
| `hooks/pre-commit` | Backfill hook | Yes |
| `hooks/install.sh` | Installer (checks ots) | Yes |
| `.ots/*.ots` | Individual proofs | Yes |
| `.ots/proof.ots` | Latest proof reference | Yes |
| `.ots/commit-chain.txt` | Commit chain | Yes |
| `.ots/.attestation-cache` | Local cache | No |

## Verification

```bash
# Check attestation status
ots info .ots/<commit-hash>.ots | grep -c "PendingAttestation"
# 0 = attested, >0 = pending

# Verify proof
ots verify .ots/<commit-hash>.ots

# Upgrade pending proofs
ots upgrade .ots/<commit-hash>.ots
```

## Important Notes

- **No Node.js fallback** - ots CLI is mandatory
- **Attestation time:** ~10 min (Bitcoin confirmation)
- **Cache validity:** 1 hour, re-checks pending after 10 min
- **Commit overhead:** ~10-15s after initial backfill
- **Proof size:** ~500-900 bytes each
- **Safe to commit:** Yes, `.ots/` directory should be versioned

## Why ots CLI is Required

| Feature | ots CLI | Node.js Package |
|---------|---------|-----------------|
| Calendar submission | ✓ | ✗ |
| Bitcoin attestation | ✓ | ✗ |
| Proof upgrade | ✓ | ✗ |
| Verification | ✓ | ✗ |
| Local proofs | ✓ | ✓ |

The Node.js package only creates self-attested local proofs with no third-party verification. For tamper-evident timestamps anchored to Bitcoin, ots CLI is the only complete implementation.