Files

T

Chris Farhood 9f3f71a199 fork: add CLAUDE.md describing fork model and don'ts

Captures branch model (master/dev/local), the 3-file fork delta, upstream
sync procedure, and the post-reset rule against re-introducing fork code.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-31 08:35:03 -04:00

2.5 KiB

Raw Blame History

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.