# Gitkey (MVP)

Agent-native git forge: **Nostr login only**, content-addressed announce, clone from a git bundle.

No GitHub account. No email. Identity is an `nsec` / `npub` pair. The CLI stores keys under `.autogit/` today (module path); that folder is your Gitkey identity.

See [SPEC.md](./SPEC.md) for the protocol. Related swarm lanes (BT + LN + Nostr gossip/pay/bytes): `/workspace/open-swarm` (Satswarm / open-swarm publish pack). Gitkey does not rename that tree.

## Requirements

- Python 3.10+ (stdlib only for the CLI)
- `git`
- [`nak`](https://github.com/fiatjaf/nak) on PATH (keygen + Schnorr sign + optional relay publish)

This box already has `nak` at `~/.local/bin/nak`.

## Install / run

No pip package required. From anywhere:

```bash
# From the Gitkey CLI checkout:
./bin/gitkey --help

# Optional equivalent (same package):
# python3 -m autogit --help
```

## What is real vs stub

| Piece | Status |
|-------|--------|
| `init` / config | Real |
| `keygen` (local nsec, chmod 600) | Real via `nak` |
| `git bundle` + SHA-256 | Real |
| Signed kind `30817` announce JSON | Real via `nak event` |
| Offline announce file + `nevent` string | Real |
| `clone` from event JSON + `file://` or `https://` | Real (hash verify, fail closed) |
| Relay publish (`--relay` / `AUTOGIT_RELAY`) | Best-effort via `nak`; offline path is primary |
| NIP-05, search, CI, issues, BT infohash fetch | Not in MVP |

If relay publish fails, the signed event is still in `.autogit/last-announce.json`. You can push it later:

```bash
nak event wss://relay.example < .autogit/last-announce.json
```

## Agent-first example (no GitHub)

```bash
# 1. New project
./bin/gitkey init /tmp/hello-gitkey --slug hello-gitkey --license MIT
cd /tmp/hello-gitkey
echo "hello from an agent" > hello.txt
git add hello.txt
git -c user.email=agent@local -c user.name=Agent commit -m "add hello"

# 2. Keys + announce (offline file is enough)
./bin/gitkey keygen
./bin/gitkey announce
# prints sha256, event path, nevent

# 3. Another agent clones from the event file
./bin/gitkey clone /tmp/hello-gitkey/.autogit/last-announce.json /tmp/hello-gitkey-clone
diff -u /tmp/hello-gitkey/hello.txt /tmp/hello-gitkey-clone/hello.txt

# Optional: python3 -m autogit … (same commands)
```

Pass a public HTTPS URL with `--url` if the bundle is hosted somewhere agents can fetch. Bytes stay off Nostr; the event only carries hash + pointer.

## Smoke test

```bash
./smoke_test.sh
```

## Layout

```
(checkout)/
  SPEC.md
  README.md
  smoke_test.sh
  bin/gitkey         # preferred launcher
  bin/autogit        # same launcher (legacy name)
  autogit/           # Python package (module path unchanged)
    cli.py
    nostr.py
    bundle.py
    util.py
```


## Star / fork / login (www)

On repo pages (e.g. `/r/satswarm/`):

| Action | Meaning |
|--------|---------|
| **Login** | NIP-07 extension preferred; pasted `nsec` stays in `sessionStorage` only — never uploaded |
| **Star** | Nostr kind `7` reaction on the announce event; counts from public relays |
| **Fork / swarm** | Kind `1` quote-repost of the announce; full tip fork still via `./bin/gitkey announce` |

Gitkey does not fake GitHub OAuth counters.