# Paperclip fork — farhoodlabs

This is a thin fork of [paperclipai/paperclip](https://github.com/paperclipai/paperclip).
Fork repo: https://git.farh.net/farhoodlabs/paperclip

## Branch model

| Branch | Purpose |
|---|---|
| `master` | Pure mirror of `upstream/master`. No fork files. Sync via `git push origin upstream/master:master --force-with-lease`. |
| `dev` | `master` + one fork commit (Dockerfile prod stage + 2 build workflows). Builds `git.farh.net/farhoodlabs/paperclip-dev:*` on push. |
| `local` | **Deployed branch.** Same content as `dev`. Builds `git.farh.net/farhoodlabs/paperclip:*` on push. |

The fork tree differs from upstream by exactly **3 files**:

```
Dockerfile                                 (production stage adds kubectl, kubeseal, uv, forgejo CLIs, tea, mmx-cli, nano, vim)
.github/workflows/build-prod.yml           (pushes to git.farh.net/farhoodlabs/paperclip)
.github/workflows/build-dev.yml            (pushes to git.farh.net/farhoodlabs/paperclip-dev)
```

The base/deps/build stages of the Dockerfile match upstream verbatim so upstream changes apply cleanly.

## Sync upstream

```bash
git fetch upstream
git push origin upstream/master:master --force-with-lease
git checkout dev && git merge master && git push origin dev
git checkout local && git merge dev && git push origin local
```

Conflicts should only ever appear on `Dockerfile` itself (if upstream changes the production stage). Resolution rule: keep upstream's deps/base/build stages exactly; preserve the fork's `RUN` block in the production stage.

## Deployment

Production runs in Kubernetes (`paperclip` namespace, single replica). Image: `git.farh.net/farhoodlabs/paperclip:<tag>`. Flux does not watch moving tags — rolling a fix means either pushing a semver-tagged release or `kubectl rollout restart deploy/paperclip -n paperclip`.

## Don't

- **Don't add fork code changes.** This fork is intentionally minimal after the 2026-05-31 reset (event-loop starvation bug from accumulated drift). If a feature is missing relative to a prior fork iteration (Gitea-hosted skills, PAT support for private skill repos, secret export/import, k8s sandbox-provider plugin, agentId threading), surface the regression — don't pull it back from `git log` without explicit go-ahead.
- **Don't commit to `local` without going through `dev` first** (and through `master` for upstream syncs). The promotion order is enforced.
- **Don't recreate `.farhoodlabs/` overlay or `assemble-local.yml`.** That model was retired.