# AI Agent Instructions

Quick reference for AI agents installing OpenTimestamp hooks.

## When to Use

Use this skill when the user wants to:
- Add tamper-evident timestamps to git commits
- Create cryptographic proof of commit history
- Anchor commits to Bitcoin blockchain via OpenTimestamp

## Installation (Auto-Detect)

```bash
# 1. Install prerequisites (ots CLI recommended)
pipx install opentimestamps-client

# 2. Install hooks (auto-detects available tools)
./hooks/install.sh .

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

## Installation Modes

The installer auto-detects and installs matching hooks:

| Detected | Hooks Installed | Attestation |
|----------|----------------|-------------|
| `ots` CLI | `post-commit-ots`, `pre-commit-ots` | Full Bitcoin |
| `@opentimestamps/ots` (node) | `post-commit-node`, `pre-commit-node` | Local only |

**Recommendation:** Always prefer ots CLI for production use.

## Manual Installation

### ots CLI Mode
```bash
cp hooks/post-commit-ots .git/hooks/
cp hooks/pre-commit-ots .git/hooks/
chmod +x .git/hooks/*
```

### Node.js Mode
```bash
cp hooks/post-commit-node .git/hooks/
cp hooks/pre-commit-node .git/hooks/
chmod +x .git/hooks/*
npm install @opentimestamps/ots  # If not already installed
```

## Key Files

| File | Purpose | Version? |
|------|---------|----------|
| `hooks/post-commit-ots` | Post-commit hook (ots CLI) | Yes |
| `hooks/pre-commit-ots` | Backfill hook (ots CLI) | Yes |
| `hooks/post-commit-node` | Post-commit hook (Node.js) | Yes |
| `hooks/pre-commit-node` | Backfill hook (Node.js) | Yes |
| `hooks/install.sh` | Auto-detect installer | 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 |
| `node_modules/` | Node dependencies (if used) | No |

## Verification

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

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

## Notes

- Proofs take ~10 min to become Bitcoin-attested
- Cache avoids redundant calendar calls (1-hour validity)
- Pre-commit backfill adds ~10-15s to commit time
- Node.js version creates local proofs only (no calendar submission)
- Safe to commit `.ots/` directory (binary proofs are ~500-900B each)