clawdie-ai/docs/FORGEJO-SETUP.md

# Forgejo SSH Setup for Agents

Primary git remote: `code.smilepowered.org` (Forgejo 10.0.3, SSH port 2222).

Each agent host gets its own machine user and SSH key. No shared credentials.

## On a new agent host

### 1. Generate a host-specific SSH key

```sh
ssh-keygen -t ed25519 -f ~/.ssh/forgejo-<username> -C "<username>"
```

Replace `<username>` with the machine user assigned to this host:
- debby → `hermes-debby`
- domedog → `claude-domedog`
- osa → `codex-osa`

### 2. Add Forgejo SSH config

```ssh-config
Host code.smilepowered.org
    HostName code.smilepowered.org
    User git
    Port 2222
    IdentityFile ~/.ssh/forgejo-<username>
    IdentitiesOnly yes
```

### 3. Have the operator register your public key

Send the output of `cat ~/.ssh/forgejo-<username>.pub` to the operator (Samo
or Hermes on debby). They will register it under your machine user on Forgejo.

### 4. Verify

```sh
ssh -T git@code.smilepowered.org
# Expected: "Hi there, <username>! You've successfully authenticated..."
```

### 5. Clone or add remote

```sh
# Fresh clone
git clone git@code.smilepowered.org:clawdie/<repo>.git

# Add remote to existing checkout
git remote add forgejo git@code.smilepowered.org:clawdie/<repo>.git
```

## Repos

| Repo | SSH URL |
|------|---------|
| clawdie-ai | `git@code.smilepowered.org:clawdie/clawdie-ai.git` |
| clawdie-iso | `git@code.smilepowered.org:clawdie/clawdie-iso.git` |
| colibri | `git@code.smilepowered.org:clawdie/colibri.git` |

## Permissions

| Host | User | Permissions |
|------|------|------------|
| debby | hermes-debby | write (all three) |
| domedog | claude-domedog | write (all three) |
| osa | codex-osa | write (all three) |
| smilepowered.org | opus-smilepowered | write (all three) |

## Agent readiness checklist

Agents update their own row after testing from the named host. Use ✅ only for
proof captured on that host; use ⏳ for pending work and N/A when intentionally
not applicable.

| Host | User | Key generated on host | Key registered on user | SSH auth verified | Repo read verified | Push verified | Last proof |
|------|------|-----------------------|------------------------|-------------------|--------------------|---------------|------------|
| debby | hermes-debby | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | pending Hermes self-check |
| domedog | claude-domedog | ⏳ | ⏳ | ⏳ | ⏳ | ⏳ | pending Claude self-check |
| osa | codex-osa | ✅ | ✅ | ✅ | ✅ all three repos | ✅ all three repos | 2026-05-29: `ssh -T` identified `codex-osa`; `git ls-remote` succeeded for all repos; scratch branch push/delete succeeded for `colibri`, `clawdie-ai`, `clawdie-iso` |
| smilepowered.org | opus-smilepowered | ✅ | ✅ | ✅ | ✅ all three repos | ✅ all three repos | 2026-05-29: `ssh -T` identified `opus-smilepowered`; cloned all three repos; scratch branch push/delete succeeded for `colibri`, `clawdie-ai`, `clawdie-iso` |

## Forgejo cutover checklist

| Item | Status | Notes |
|------|--------|-------|
| Organization created | ✅ | `clawdie` on `code.smilepowered.org` |
| Repos imported | ✅ | `clawdie-ai`, `clawdie-iso`, `colibri` |
| Clean ISO history published | ✅ | `clawdie-iso` main includes Colibri ISO staging (`ef28677`) |
| Machine users created | ✅ | `hermes-debby`, `claude-domedog`, `codex-osa` |
| Per-host SSH keys | ✅ | `hermes-debby`, `claude-domedog`, and `codex-osa` have per-host keys; no shared private keys |
| Bootstrap/admin tokens deleted | ⏳ | Admin token retained briefly for stabilization; delete within 1–2 days |
| Branch protection | ✅ | Direct pushes to `main` rejected on all three repos; `clawdie-iso/xfce-operator-usb` also protected while live |
| Vaultwarden secrets | ✅ | `vault.smilepowered.org` has `agent-secrets` collection for operator-managed secrets |
| Webhook validation | ⏳ | Planned: Forgejo push → OSA FreeBSD proof gate |

## Rules

- Never copy or share SSH private keys between hosts.
- Codeberg is the public mirror — do not push to it. Push to Forgejo.
- See `AGENTS.md#forgejo-primary-git-remote` for the full permissions table.