paperclip/CLAUDE.md

Paperclip fork — farhoodlabs

This is a thin fork of 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

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.