paperclip/.farhoodlabs/CLAUDE.md

Paperclip Fork — Project Context

This is a fork of paperclipai/paperclip. Fork repo: https://git.farh.net/farhoodlabs/paperclip

Branch Model

Branch	Purpose
master	Mirrors upstream/master exactly + .farhoodlabs/ overlay directory + assemble-local.yml action. Never commit application code here.
local	Default branch. Assembled automatically by assemble-local.yml on every master push. Contains: upstream + fork Dockerfile/workflows + all pending upstream PR cherry-picks. Builds git.farh.net/farhoodlabs/paperclip.
dev	Development branch based on upstream/master. Builds git.farh.net/farhoodlabs/paperclip-dev on every push.
PR branches	skill-pat-feature, skill-scan-refresh, feat/company-portability-complete — open PRs to upstream, never rebase onto master/local.

Never commit directly to local — it is fully regenerated by the assemble action and any direct commits will be overwritten.

Fork Overlay (.farhoodlabs/)

Files committed to master that get copied into position on local by the assemble action:

.farhoodlabs/
  CLAUDE.md                          → CLAUDE.md (repo root)
  Dockerfile                         → Dockerfile
  .github/workflows/build-prod.yml   → .github/workflows/build-prod.yml
  .github/workflows/build-dev.yml    → .github/workflows/build-dev.yml

The fork's Dockerfile production stage additions over upstream: kubectl, kubeseal, uv/uvx, forgejo-cli (fj, fj-ex, fgj), nano, vim.

To modify fork-specific files, edit them in .farhoodlabs/ on master and push — the assemble action will apply them to local automatically.

Pending Upstream PRs (included in local)

These are cherry-picked/squashed onto local by the assemble action. When upstream merges one, remove its entry from assemble-local.yml.

PR	Branch	Method	Notes
#3237	skill-pat-feature	cherry-pick	GitHub PAT support for private skill repos
#3351	skill-scan-refresh	cherry-pick (exclude: skill-pat-feature)	Rebased onto skill-pat-feature
#3987	feat/company-portability-complete	squash	Secrets export/import; squashed to bypass intra-PR merge commits

Common Tasks

Sync upstream into master

git fetch upstream
git push origin upstream/master:master --force-with-lease
# assemble-local.yml triggers automatically and rebuilds local

Add a new pending PR to local

Edit .github/workflows/assemble-local.yml on master:

• Simple PR (clean commits, no merge commits): add to PR_CHERRY_PICK
• Complex PR (has merge commits mixed in): add to PR_SQUASH
• If the branch was rebased onto another PR branch: use exclude:base-branch

Remove a PR after upstream merges it

Delete its entry from PR_CHERRY_PICK or PR_SQUASH in assemble-local.yml on master.

Submit a new PR to upstream

Branch from upstream/master (not from local or master):

git fetch upstream
git checkout -b feat/my-feature upstream/master

Modify the fork Dockerfile

Edit .farhoodlabs/Dockerfile on master. Only modify the production stage — keep base/deps/build stages identical to upstream so diffs are minimal and upstream changes apply cleanly.

Deployment

Paperclip runs in Kubernetes, not locally. Use kubectl to access it. The production image is git.farh.net/farhoodlabs/paperclip:latest.

Key Files

• .github/workflows/assemble-local.yml — assembles local branch; edit this to manage pending PRs
• .farhoodlabs/ — fork overlay; all fork-specific files live here on master
• server/package.json — has an adapter-utils workspace vs canary hack that needs fixing eventually