Quickstart

This walks the whole loop once: initialize a repository, record an Arc while you work, seal it, verify it, and (optionally) share it. Everything before share runs with no account and no network.

1. Initialize the repository

$ cd your-repo
$ patcharc init
✓ Initialised PatchArc in /Users/you/src/your-repo
  config:   /Users/you/src/your-repo/.patcharc/config.yaml
  key:      /Users/you/src/your-repo/.patcharc/keys/arc-signing.ed25519 (mode 0600)
  database: /Users/you/src/your-repo/.patcharc/session.db

init creates .patcharc/ with a config file, a fresh Ed25519 signing key, a SQLite session store, and two id files, and it appends the key and database paths to your .gitignore. Run it again with --force to rotate the key; capsules signed with the old key still verify because the public key travels inside each capsule.

2. Start an Arc

$ patcharc start --detach "Rework session storage"
✓ Arc arc_8f2c1d4a9b started on main @ a1b2c3d
  goal: Rework session storage
  record: git events, manual decisions, tests, and notes
  observer: detached (PID file: .patcharc/observer.pid)
  next:  patcharc stop  (or  patcharc stop --share)

Use --detach. It forks a background observer that polls Git every 1.5 seconds and records each new commit and the files it touched. Without --detach the observer runs in the foreground for 1.5 seconds and exits, which only captures commits made in that window.

The goal is optional (it defaults to Untitled Arc) but it becomes the first section of your review, so write the sentence you would put at the top of a pull request.

3. Work, and say what you decided

Make commits as usual, with any tool: your editor, an AI coding agent, a script. The observer records them. When you make a call worth remembering, record it in one line:

$ patcharc note "WAL mode avoids the lock storm under concurrent writers"
✓ note recorded
$ patcharc decision "Keep SQLite; Postgres is not justified at this size"
✓ decision recorded
$ patcharc risk "Migration on existing databases has not been tested"
✓ risk recorded
$ patcharc checkpoint "before the schema change"
✓ Checkpoint #1 recorded

Check progress at any time:

$ patcharc status
Arc arc_8f2c1d4a9b (active)
  goal:        Rework session storage
  branch:      main
  head before: a1b2c3d
  commits:     4
  files:       9

4. Stop and seal

$ patcharc stop
✓ Arc sealed: /Users/you/src/your-repo/.patcharc/capsules/arc_8f2c1d4a9b.parc
  inspect:  patcharc inspect /Users/you/src/your-repo/.patcharc/capsules/arc_8f2c1d4a9b.parc
  verify:   patcharc verify  /Users/you/src/your-repo/.patcharc/capsules/arc_8f2c1d4a9b.parc

stop ends the observer, computes the six-section review from what was recorded, and writes a .parc capsule: a ZIP with a canonical-JSON manifest, an Ed25519 signature, the public key, the review, per-commit metadata and patches, and the scope index. See What is in a capsule.

5. Verify it

$ patcharc verify .patcharc/capsules/arc_8f2c1d4a9b.parc
✓ arc_8f2c1d4a9b is valid (9 files, 48213 bytes, signed by 3f9a1c7e2b5d…)

verify re-checks the signature, every file's SHA-256 and size, path safety, and the compression ratio. It exits 1 on any failure, so you can use it as a gate. patcharc inspect prints the same checks as a table.

6. Share (optional)

$ patcharc login
To authenticate, visit: https://patcharc.dev/device?code=KQ7P-MX2A-91ZC
and enter code:         KQ7P-MX2A-91ZC
Waiting for approval…
✓ Logged in to PatchArc Cloud
  account:     acc_…
  user:        usr_…
  credentials: ~/.patcharc/credentials.json (0600)

$ patcharc share --visibility public
✓ Uploaded arc_8f2c1d4a9b.parc (48213 bytes, sha256 9f1c2e…)
  capsule: cap_… (verifying)
  ArcLink: https://patcharc.dev/a/X9kQ2mN4vR7s

The cloud re-verifies the signature and every hash before it publishes the link. --visibility defaults to public; read Sharing and ArcLinks before you share anything sensitive, and note that the redaction engine is not applied automatically in 0.2.0 (Redaction).

Where things live

Next: Recording an Arc for the details of what is captured.