@rewind-ai/cli 0.6.2

package/docs/ATTRIBUTION.md

@@ -0,0 +1,179 @@
+# Attribution research — REWIND V1
+
+This document separates **TESTED**, **DOCUMENTED**, and **SPECULATIVE** findings.
+
+V1 goal: learn what macOS exposes about *who* changed a file **without** restricted Apple entitlements.
+
+---
+
+## Executive result
+
+| Capability | Result |
+|------------|--------|
+| Live filesystem observation (WHAT) | **YES** — chokidar / FSEvents |
+| Authoritative final diff | **YES** — V0 manifest diff |
+| Full-session exact rewind | **YES** — V0 restore |
+| Responsible process ID per write | **NO** (without Endpoint Security / privileged tools) |
+| Reliable AGENT vs USER attribution | **NO** |
+| Safe selective agent-only rewind | **NO — disabled** |
+
+**Reliable restoration: YES**  
+**Live observation: YES**  
+**Reliable agent attribution: NO**
+
+That outcome is intentional and architecturally decisive for V2.
+
+---
+
+## TESTED (on this Mac, no special entitlements)
+
+### Cursor process hierarchy (observed via `ps`)
+
+`npm run session:probe` observed a real Cursor tree on this machine, including approximately:
+
+- `Cursor.app` main process
+- `Cursor Helper (Renderer)` windows
+- `Cursor Helper (Plugin)` / extension-host processes
+- language servers (json/html/…) as plugin children
+- `Cursor Helper: terminal pty-host` → interactive `zsh` → user commands (`npm`, `node`, …)
+- `cursorsandbox` helper with network allowlist policy
+- crashpad / GPU / network utility helpers
+
+This confirms Cursor has a deep, multi-process tree — but **none of these PIDs are attached to FSEvents write notifications**. Seeing the tree does not attribute a file change.
+
+### FSEvents via chokidar
+
+- Node `chokidar` uses FSEvents on macOS.
+- Delivers create / change / unlink / addDir / unlinkDir style signals.
+- **Does not include the PID of the process that performed the I/O.**
+- Signals are coalesced/debounced; they are **not** the transaction source of truth.
+- Final SHA-256 manifest diff remains authoritative.
+
+### Process table (`ps`)
+
+- Can list PIDs, PPIDs, users, command lines when the environment allows process enumeration.
+- Can heuristically find processes whose args contain `Cursor` / `Cursor.app`.
+- Can print a **candidate** Cursor process tree (children of Cursor-named roots).
+- **Cannot** prove that a given filesystem event was caused by a node in that tree.
+- In some constrained agent/sandbox environments, `ps`/`pgrep` return empty — treat process listing as best-effort.
+
+### `lsof +D <sandbox>`
+
+- Sometimes lists processes with open handles under the sandbox.
+- Short writes (typical agent edits) often complete before `lsof` runs → **empty result**.
+- Open-handle presence is correlative evidence at best (LOW/MEDIUM), never proof of authorship for a past event.
+
+### `eslogger` (Endpoint Security CLI)
+
+- Binary exists at `/usr/bin/eslogger`.
+- Without root: fails with `ES_NEW_CLIENT_RESULT_ERR_NOT_PRIVILEGED`.
+- Also requires Full Disk Access for the hosting terminal when root is available.
+- **Not usable as a V1 dependency** for an ordinary unprivileged CLI.
+
+### `fs_usage`
+
+- Present at `/usr/bin/fs_usage`.
+- Typically requires root; unprivileged runs fail or yield nothing useful.
+- Not a V1 dependency.
+
+### Ambient noise
+
+- `.DS_Store` and similar basename patterns can be tagged **SYSTEM/AMBIENT** with **MEDIUM** confidence based on **filename evidence only**.
+- This is pattern classification, not process attribution.
+- Concurrent human file `notes-from-jack.txt` is **not** auto-labeled AGENT just because an agent session is open.
+
+### Concurrent human change
+
+- When a human creates a file during an agent session, V1 **does not** claim it belongs to the agent.
+- Without an explicit test harness marker, it is **UNKNOWN**.
+- With an explicit harness marker (demo only), it can be labeled USER/HIGH — that marker is **not** available for real Cursor sessions.
+
+### Same-file conflict (research test)
+
+If the agent writes file A, then the human edits A:
+
+- “Undo the agent” ≠ restore checkpoint version of A (that destroys human work).
+- V1 does not attempt magical merge.
+- Full-session rewind remains the only safe restore primitive.
+
+---
+
+## DOCUMENTED (Apple / public sources — not implemented in V1)
+
+### Endpoint Security framework
+
+- Provides notify/auth events for file create/write/rename/unlink and process exec/fork/exit.
+- Event messages include rich `es_process_t` (pid, ppid, audit tokens, signing id, executable path, responsible audit token).
+- This **would materially improve attribution** by binding I/O to a responsible process.
+
+**Requirements (distribution reality):**
+
+- Entitlement: `com.apple.developer.endpoint-security.client` (Apple approval).
+- Usually runs as root / system extension style deployment.
+- Full Disk Access / TCC considerations.
+- Consumer Mac App Store distribution of a full ES client is **highly constrained**; more realistic as a notarized Developer ID system extension with explicit user trust, or enterprise MDM.
+
+**V1 stance:** research only — see FUTURE.md. Not a dependency.
+
+### Legacy `/dev/fsevents`
+
+- Historical character device could expose PID with events.
+- Deprecated / restricted; Apple pushes Endpoint Security.
+- Not used by V1.
+
+---
+
+## SPECULATIVE (unproven — do not ship assumptions)
+
+- Inferring AGENT from “Cursor is focused” or “timing overlaps agent chat” → **false confidence**.
+- Inferring AGENT from file extensions or path prefixes → **false confidence**.
+- Assuming shell children of Cursor Helper own all subsequent writes → **false** (async tools, other apps, Spotlight, git hooks).
+- Using DTrace in production for consumers → SIP / privilege / fragility issues.
+
+---
+
+## Confidence model used by V1
+
+| Actor | When allowed |
+|-------|----------------|
+| SYSTEM | Known ambient basename/temp patterns (MEDIUM) |
+| USER | Only with explicit harness marker (HIGH) — not inferred in live Cursor tests |
+| AGENT | Only with explicit harness marker (HIGH) — **never** inferred from Cursor presence |
+| UNKNOWN | Default for all other final diff paths |
+
+Evidence kinds actually emitted:
+
+- `watcher_signal`
+- `watcher_correlation`
+- `ambient_filename_pattern`
+- `no_watcher_event`
+- `no_responsible_pid`
+- `cursor_present_uncorrelated`
+- `explicit_human_marker` / `explicit_self_write_marker` (tests/demo only)
+
+---
+
+## Conflict strategies for later versions (not solved in V1)
+
+1. **Operation-level patches** — store each write as a patch; rewind agent ops only.
+2. **Three-way merge** — checkpoint base + agent tip + human tip.
+3. **Per-write snapshots** — content-addressable version per close/write.
+4. **CRDT-like / OT** — for collaborative text; weak for binary/project-wide ops.
+5. **Application integrations** — editor buffer awareness (Cursor extension) beats OS guessing.
+6. **Transaction mediation** — agent performs mutations through a REWIND proxy that records intent + before/after.
+
+Most promising near-term for Universal AI Undo: **(6) mediation + (1)/(3) snapshots**, with ES as optional high-assurance observer — not the sole source of truth.
+
+---
+
+## Implications
+
+Universal AI Undo **cannot** be built on FSEvents alone.
+
+V2 should assume either:
+
+- **Mediated agent I/O** (agent SDK / tool proxy), and/or
+- **Privileged observation** (Endpoint Security), and/or
+- **Editor-integrated hooks** (know which tool call wrote which buffer)
+
+Filesystem watching remains necessary for ambient detection and verification — insufficient for authorship.

package/docs/COMMERCIAL.md

@@ -0,0 +1,51 @@
+# Commercial boundary
+
+## What the cloud may know
+
+- User identity (email / subject)
+- Installation/device id, hostname, platform
+- Subscription status / Stripe customer ids
+- Entitlement issue/refresh events
+- Release/update metadata
+
+## What MUST stay local
+
+- Project source files
+- Before/after file contents and CAS blobs
+- Transaction payloads beyond opaque ids (optional aggregate counts only if ever added)
+- Permission policy contents (local)
+
+## Offline / outage
+
+| Condition | New mediation | Undo existing |
+|-----------|---------------|---------------|
+| Valid cached entitlement | Allowed | Always |
+| Past `expiresAt`, within `graceUntil` | Allowed (grace) | Always |
+| Past grace (Personal) | Denied / free fallback | **Always** |
+| Stripe/API down | Use cache + grace | **Always** |
+| Invalid signature | Free fallback | **Always** |
+
+## Invariant
+
+**NEVER PAYWALL RECOVERY OF ALREADY-RECORDED USER WORK.**
+
+## REAL STRIPE SANDBOX PROOF
+
+Local file store (`~/.rewind/commercial/`) is enough for TEST MODE proof.
+
+| Piece | Behaviour |
+|-------|-----------|
+| Env | `.env` (gitignored) — `REWIND_STRIPE_SECRET_KEY`, `REWIND_STRIPE_PRICE_ID`, `REWIND_STRIPE_WEBHOOK_SECRET`, optional publishable key |
+| Checkout | Real Stripe Checkout Session when `sk_test_` + `price_` set; else SIMULATED DEVELOPMENT MODE |
+| Webhook | `POST http://127.0.0.1:7429/v1/commercial/stripe/webhook` (raw body + Stripe-Signature) |
+| Events | `checkout.session.completed`, `customer.subscription.created/updated/deleted`, `invoice.payment_failed` |
+| Entitlement | Ed25519 signed Personal after active/trialing webhook |
+
+```bash
+rewind api
+stripe listen --forward-to http://127.0.0.1:7429/v1/commercial/stripe/webhook
+rewind login && rewind subscribe
+# pay with TEST card → webhook → rewind status shows Personal
+```
+
+See [HUMAN-SETUP.md](./HUMAN-SETUP.md). Live `sk_live_` keys are refused unless `REWIND_ALLOW_LIVE_STRIPE=1`.

package/docs/CURSOR-ENFORCEMENT.md

@@ -0,0 +1,73 @@
+# Cursor enforcement research (V3 → V4)
+
+Sources: official Cursor Hooks docs, create-hook skill, third-party hooks references. Verified against documented behaviour (2026).
+
+## SUPPORTED BY CURSOR
+
+| Capability | Notes |
+|------------|-------|
+| `preToolUse` permission allow/deny | Can block Write, Delete, Shell, Task, MCP:`name`, etc. before execution |
+| `postToolUse` / `afterFileEdit` | Observe after mutation; cannot veto |
+| `beforeShellExecution` permission allow/deny/ask | Can block shell; `failClosed: true` recommended |
+| `beforeMCPExecution` | Gate MCP tools |
+| `sessionStart` / `sessionEnd` | Session binding / recovery |
+| Project hooks `.cursor/hooks.json` | Loaded for workspace; auto-reload on save |
+| `failClosed` | Failures / timeout / invalid JSON deny instead of allow |
+| Exit code 2 | Equivalent to deny |
+| Matchers | Regex on tool name / command |
+| `updated_input` on preToolUse | Rewrite tool call (unused in V4 Model A) |
+
+## V4 FINDINGS (this repo)
+
+| Item | Result |
+|------|--------|
+| Model A: pre capture + allow native + post capture | **Works** in tests with realistic hook JSON fixtures |
+| User must mention REWIND MCP | **No** — protect + normal Cursor tools |
+| Native Write ledgered | YES |
+| Native Delete ledgered | YES |
+| Native StrReplace ledgered | YES |
+| Shell `echo > file` | BLOCKED |
+| Shell `node`/`python` one-liner write | BLOCKED (opaque policy) |
+| Read-only shell (`ls`, `git status`, …) | ALLOWED |
+| failClosed on preToolUse / beforeShellExecution | Installed `true` |
+| Broken hook script | Non-zero exit → Cursor blocks when failClosed |
+| Human editor edit during protect | Succeeds; not claimed as Cursor action |
+| Session undo + human conflict | Conflict preserved; independent actions undone |
+| Live Cursor agent E2E | Manual — see docs/PROTECTED-SESSIONS.md |
+
+## Tool coverage table
+
+| Cursor operation | Hook observed | Protected? |
+|---|---|---|
+| create/overwrite file | Write + pre/postToolUse | YES (ledger) |
+| modify file | Write / StrReplace | YES (ledger) |
+| delete file | Delete | YES (ledger) |
+| shell `echo >` | beforeShellExecution | YES (blocked) |
+| `mv` / `rm` / `sed -i` | beforeShellExecution | YES (blocked) |
+| `node`/`python` write | beforeShellExecution | YES (blocked) |
+| `ls` / `cat` / `git status` | beforeShellExecution | YES (allowed) |
+| Human keyboard save | (no agent hook) | N/A — not attributed |
+| Tab inline edit | afterTabFileEdit (not installed) | NOT in V4 scope |
+
+## NOT SUPPORTED (today)
+
+| Desired | Reality |
+|---------|---------|
+| Disable all native write tools via one “MCP-only” toggle | No first-party product mode |
+| OS-level block of human editor save | Hooks do not apply |
+| Guaranteed Tab write mediation | after* cannot veto; Tab hooks not wired in V4 |
+| Kernel authorship | Hooks observe declared tool requests only |
+
+## PROMPT-ONLY (NOT ENFORCEMENT)
+
+Rules / MCP tool descriptions that say “use REWIND” are **not** required for V4 Model A and are **not** enforcement by themselves.
+
+## Practical V4 policy
+
+Installed by `rewind protect <project>` into **that project’s** `.cursor/hooks.json` (merged; unrelated hooks preserved).
+
+Scope: the protected project workspace. Not system-wide. Not the REWIND monorepo root (refused).
+
+## V3 note
+
+V3 still uses repo-level hooks to **deny** native writes into `sandbox-enforced-project` and force MCP. V4 is a different product surface: **allow + ledger** native tools inside a protected project.

package/docs/ENFORCEMENT.md

@@ -0,0 +1,134 @@
+# REWIND V3 — Enforcement / Threat Model
+
+## Verdict (honest)
+
+Mandatory mediation for **all** Cursor activity on a normal macOS user account is **not** achieved by a single OS control without privileged Endpoint Security or a separate agent identity.
+
+V3 **does** demonstrate practical **partial** enforcement boundaries:
+
+1. **fs-readonly + REWIND broker** (same UID): direct `echo >` / `rm` against `sandbox-enforced-project/` fails while mediated MCP writes succeed via brief unlock.
+2. **sandbox-exec wrapper** (Option A harness): a child process denied `file-write*` under the enforced tree cannot mutate it; the host REWIND broker (unsandboxed) can.
+3. **Cursor hooks** (`preToolUse` / `beforeShellExecution`): agent native Write/Delete/StrReplace and mutating shell targeting the enforced sandbox can be **denied** by Cursor before execution. This is real vendor tool-loop enforcement — **not** prompt compliance, and **not** OS enforcement.
+
+None of these alone is universal. Combined, they form a credible **wrapped-agent** proof for this disposable sandbox only.
+
+## THREAT MODEL
+
+### Trusted
+- REWIND broker / MCP server process (when intentionally run outside seatbelt)
+- Local CAS / action ledger under `.rewind/`
+- Enforcement state under `.rewind/enforcement/`
+
+### Untrusted
+- Agent reasoning / tool selection
+- Native editor write path (Agent Write tool, Tab write)
+- Shell spawned by the agent
+- Subprocesses of the agent
+- Any process that can `chmod` the tree if shell is not also gated
+
+### Assets
+- Filesystem state inside approved sandboxes
+- Action history / provenance
+- User work that must not be clobbered by undo
+
+### Goals
+- Force or detect mutation outside REWIND for the enforced sandbox
+- Preserve reversibility of mediated actions
+- Prevent *silent* bypass where possible; surface policy events when not
+
+### Non-goals
+- Malicious root user
+- Kernel compromise
+- Malware / Endpoint Security evasion
+- Arbitrary system-wide protection
+- Claiming Cursor cannot edit files outside the enforced sandbox
+
+## Tested boundary (this machine)
+
+| Mechanism | Result |
+|-----------|--------|
+| chmod a-w tree + broker unlock | **Works** for direct writes; same UID can still `chmod`+write if shell ungated |
+| sandbox-exec deny file-write* under enforced path | **Works** for wrapped children (macOS 26.6); host unrestricted |
+| Docker RO mount + host broker | **Not tested** — Docker daemon unavailable |
+| Separate macOS user | **Research only** — not created |
+| macFUSE overlay | **Unavailable** |
+| Cursor hooks deny Write/Shell | **Supported by Cursor docs**; project hooks installed; policy unit-tested |
+| Prompt / rules only | **Not enforcement** |
+
+## Architecture (best working combo)
+
+```
+Cursor Agent tools (Write/Shell)
+    │  denied by .cursor/hooks when targeting sandbox-enforced-project
+    ▼
+(blocked)
+
+Cursor Agent → REWIND MCP (stdio, host)
+    │  allowed
+    ▼
+REWIND broker
+    │  unlock → mutate → re-lock  (fs-readonly)
+    ▼
+sandbox-enforced-project/   (authoritative when mediated)
+
+Optional harness:
+Restricted child (sandbox-exec) ──deny write──► sandbox-enforced-project
+Host REWIND ────────────────────write OK─────► sandbox-enforced-project
+```
+
+## Authoritative vs untrusted state
+
+- **AUTHORITATIVE**: path last updated by a COMPLETED mediated REWIND action (ledger + trust record).
+- **UNTRUSTED**: unexplained external mutation detected; policy event `UNKNOWN_MUTATION`; **not** absorbed as valid MCP provenance.
+
+## Human access
+
+fs-readonly **does** restrict the human owner for that tree while locked (same UID). Cursor hooks do **not** restrict human keyboard edits in the editor.
+
+Product implication: eventual architecture needs a separate agent identity or session boundary so the human stays unrestricted while the agent is gated.
+
+## What V3 does NOT protect against
+
+- Human (or any unsandboxed same-UID process) `chmod -R u+w` then write, if shell hooks are disabled/bypassed
+- Cursor Tab / non-agent edit paths if hooks do not cover them
+- Launching Cursor itself without project hooks loaded
+- Compromised REWIND broker
+- Edits outside `sandbox-enforced-project/`
+
+## Recovery if lock stuck
+
+```bash
+chmod -R u+w "sandbox-enforced-project"
+# or
+npm run enforce:disable
+```
+
+## Endpoint Security (research only — not used)
+
+Apple Endpoint Security can observe/deny file ops with process attribution. Requires restricted entitlement / system extension / user approval. Deferred — not used in V3 or V4.
+
+## V4 note
+
+V4 does **not** claim stronger OS enforcement. It proves a **protected Cursor agent session** via hooks (Model A: intercept + ledger). See [PROTECTED-SESSIONS.md](PROTECTED-SESSIONS.md).
+
+
+## Decision matrix (tested)
+
+| Approach | Blocks native write | Allows MCP write | Human unaffected | Privileged? | Practical |
+|----------|---------------------|------------------|------------------|-------------|-----------|
+| prompt rules | NO | YES | YES | NO | NO (not enforcement) |
+| chmod fs-readonly + broker | YES (direct) | YES (unlock) | NO (same UID locked) | NO | YES for disposable sandbox |
+| sandbox-exec wrapper | YES (child only) | YES (host) | YES if human outside wrapper | NO | YES as harness; Cursor.app not auto-wrapped |
+| Cursor hooks | YES (agent tools) | YES | YES for keyboard edits | NO | YES within Cursor agent loop |
+| combined (V3 default) | YES (layered) | YES | PARTIAL | NO | YES for `sandbox-enforced-project` only |
+| Docker RO + host broker | untested | — | — | NO | Daemon unavailable here |
+| separate macOS user | research | — | ideally YES | MAYBE | Not prototyped |
+| Endpoint Security | research only | — | — | YES | V4 candidate |
+
+## V3 RESULT
+
+**Partial success** for a controlled disposable sandbox using combined non-privileged mechanisms.
+
+Universal mandatory mediation of all Cursor activity without stronger OS/vendor control: **NOT PROVEN**.
+
+Recommended V4 (do not build now): smallest credible path is either (1) first-party Cursor MCP-only write mode / stronger tool policy, or (2) Endpoint Security deny of non-broker writers to project trees, or (3) agent always launched under seatbelt with MCP broker outside.

package/docs/FUTURE.md

@@ -0,0 +1,91 @@
+# REWIND — Future research directions
+
+These are intentional non-goals for V0. Do not implement them in this proof.
+
+## Filesystem observation
+
+- Continuous watching of a target tree
+- Attribute changes, renames, and bulk operations as a stream
+- Correlation of bursts of activity into candidate transactions
+
+## FSEvents
+
+- macOS FSEvents as a lightweight change signal
+- Coalescing high-frequency events
+- Gaps vs. truth (missed events, latency, historical limits)
+
+## Endpoint Security
+
+- Privileged observation of process-backed file ops
+- Attributing actions to a specific agent process / tool chain
+- Entitlements, privacy, and user consent implications
+
+## Agent session identification
+
+- Binding filesystem deltas to an “AI session”
+- Tool-call boundaries as transaction markers
+- Handling concurrent agents and human edits interleaved
+- **V1 finding:** FSEvents alone cannot attribute authorship; prefer mediated tool I/O and/or Endpoint Security
+
+## Browser transactions
+
+- Tab/history/download/bookmark mutations
+- Profile isolation and extension surfaces
+- What is reversible vs. merely compensable
+
+## Email inverse operations
+
+- Unsend / tombstone / compensatory follow-up
+- Provider API limits; true inverse often impossible
+
+## Calendar inverse operations
+
+- Event create/update/delete inverses
+- External attendee side effects (invites already sent)
+
+## Reversibility classes
+
+- **REVERSIBLE** — exact prior state can be restored
+- **COMPENSABLE** — cannot undo, but can counter with a new action
+- **IRREVERSIBLE** — no safe inverse (payment settled, message delivered)
+
+V0 classifies sandbox filesystem ops as REVERSIBLE only.
+
+## Approval gates
+
+- Block or confirm before irreversible actions
+- Policy layers: path allowlists, network egress, spend limits
+
+## Action ledger
+
+- Append-only record of observed actions + evidence
+- Cryptographic chaining for tamper-evidence
+- Retention and privacy controls
+
+## Agent SDK / transaction API
+
+- `beginTransaction` / `commit` / `rewind`
+- Agent-declared intents vs. observed effects
+- Partial rewind and conflict resolution
+- **V2:** MCP-mediated filesystem tools + action ledger + conflict-aware action undo (local proof)
+
+## MCP bypass / V3 enforcement
+
+- **V3:** fs-readonly + broker, sandbox-exec harness, Cursor hooks — see docs/ENFORCEMENT.md
+- V3 RESULT: mandatory mediation without stronger OS/vendor control is **partially** proven for a wrapped/enforced sandbox only — not universal Cursor lockdown
+- Remaining: privileged Endpoint Security, separate agent identity, first-party MCP-only write mode
+
+## MCP bypass
+
+- Cursor can still edit files with native tools while REWIND MCP is connected
+- Future: tool allowlists, OS sandbox, or first-party agent integration to force mediation
+- V2 exposes the bypass; it does not close it
+
+## macOS menu bar UI
+
+- Ambient “last AI transaction” affordance
+- Inspect + rewind without a full app shell
+
+---
+
+Stop here for V0. Prove the filesystem primitive first.

package/docs/HUMAN-SETUP.md

@@ -0,0 +1,98 @@
+# Human setup checklist (Jack)
+
+Do these outside the repo. V6 runs in **test/local mode** without them.
+
+## 1. Stripe (TEST MODE first)
+
+1. Create Stripe account → enable Test mode  
+2. Create Product: **REWIND Personal**  
+3. Price: **£2.99 GBP / month** recurring  
+4. Copy `price_…` → `REWIND_STRIPE_PRICE_ID`  
+5. API keys → `REWIND_STRIPE_SECRET_KEY=sk_test_…`  
+6. `REWIND_STRIPE_PUBLISHABLE_KEY=pk_test_…`  
+7. Webhook secret for local proof → `REWIND_STRIPE_WEBHOOK_SECRET=whsec_…` (from Stripe CLI listen)  
+8. **Do not** put live `sk_live_` in env until launch checklist says so  
+
+Without keys: `rewind subscribe` uses **SIMULATED DEVELOPMENT MODE**.  
+With `sk_test_` + `price_`: **STRIPE TEST MODE** real Checkout (Personal only after webhook).
+
+Prefer **`~/.rewind/.env`** for global installs (not inside the npm package).  
+Project-cwd `.env` also works (gitignored). Copy from `.env.example`. Never commit secrets.
+
+## REAL STRIPE SANDBOX PROOF
+
+End-to-end local proof (no website, no live keys):
+
+```bash
+# 1. User-level env
+mkdir -p ~/.rewind
+# Create ~/.rewind/.env with sk_test_…, price_…, and whsec_… (after listen)
+
+npm run build && npm pack && npm install -g ./rewind-ai-cli-*.tgz
+
+# 2. Local API (default port 7429, loopback only)
+rewind api
+# Webhook: POST http://127.0.0.1:7429/v1/commercial/stripe/webhook
+# Success (public HTML, no token): http://127.0.0.1:7429/subscribed
+
+# 3. Stripe CLI (separate terminal) — TEST mode
+stripe listen --forward-to http://127.0.0.1:7429/v1/commercial/stripe/webhook
+# Copy the printed whsec_… into ~/.rewind/.env as REWIND_STRIPE_WEBHOOK_SECRET
+# Restart `rewind api` after updating env so the process loads the secret
+
+# 4. Subscribe
+rewind login --email you@example.com
+rewind subscribe
+# Expect: STRIPE TEST MODE + browser opens real Checkout
+# Pay with Stripe TEST card (e.g. 4242 4242 4242 4242)
+
+# 5. Confirm
+rewind status
+# Expect: Entitlement shows Personal / REWIND Personal
+```
+
+If `rewind subscribe` prints **SIMULATED DEVELOPMENT MODE**, TEST credentials were not loaded.
+
+## 2. Auth provider (OIDC)
+
+Recommended: **Auth0** or **Clerk** (OIDC Authorization Code + PKCE).
+
+Why: no password storage in REWIND; browser login; CLI-friendly.
+
+1. Create application (Native / SPA + loopback redirect `http://127.0.0.1:<port>/callback`)  
+2. Set:
+   - `REWIND_OIDC_ISSUER`
+   - `REWIND_OIDC_CLIENT_ID`
+   - (if confidential) `REWIND_OIDC_CLIENT_SECRET` on the commercial service only  
+
+Until set: `rewind login` uses **LocalDevAuthProvider** (email only, loopback).
+
+## 3. Entitlement signing keys
+
+1. Generate ed25519 keypair (or use `~/.rewind/keys` created on first run)  
+2. **Private key** → signing service / `REWIND_ENTITLEMENT_PRIVATE_KEY` (server only)  
+3. **Public key** → ship in app / `REWIND_ENTITLEMENT_PUBLIC_KEY`  
+4. Never commit private keys  
+
+## 4. Package registry
+
+1. npm org **@rewind-ai** + package **`@rewind-ai/cli`** (CLI binary remains `rewind`)  
+2. Optional: Homebrew tap repo  
+3. Optional: Apple Developer ID for notarised macOS app (later)
+
+## 5. Domain / hosting (commercial API)
+
+Only needed when leaving local commercial store:
+
+1. HTTPS host for account API + Stripe webhooks  
+2. Do **not** upload project files / before-after contents  
+
+Local sandbox proof uses loopback `rewind api` + Stripe CLI forward — no public host required.
+
+## 6. Website GET STARTED (document only — do not wire yet)
+
+```
+visitor → account/checkout → download/install → rewind login → rewind setup → first undo
+```
+
+Keep marketing site unchanged until test-mode product flow is proven end-to-end on a clean machine.

package/docs/IDENTITY-AUTHORITY.md

@@ -0,0 +1,35 @@
+# Identity & Authority (V5)
+
+## EXISTS — foundation only
+
+### Actor (who requested)
+
+```ts
+{ type, client, clientVersion, identity }
+```
+
+For MCP: client name/version from the MCP handshake when available  
+(`cursor-vscode@…`). If missing: `UNKNOWN_MCP_CLIENT` / actor type `unknown`.
+
+**Never invent a human identity.**
+
+### Authority (on whose behalf)
+
+```ts
+{
+  status: "UNKNOWN" | "UNSPECIFIED" | "DELEGATED",
+  principal, scope, constraints, expiresAt,
+  limits, delegationChain  // reserved, unused
+}
+```
+
+V5 mediated actions use `authority.status = "UNKNOWN"`.
+
+## PLANNED
+
+- Real delegated principals (user accounts)
+- Scope constraints (paths, adapters, spend)
+- Expiry and revocation
+- Delegation chains
+
+Do not read UNKNOWN authority as “trusted human approved.”