paperclip/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	Pure mirror of upstream/master. No fork-specific files in the tree. Sync via git push origin upstream/master:master --force-with-lease.
local	Default branch. Assembled automatically by assemble-local.yml (defined on dev) on every master push. Contains: upstream + fork Dockerfile/workflows + all pending upstream PR cherry-picks. Builds git.farh.net/farhoodlabs/paperclip.
dev	Development branch and canonical home of the .farhoodlabs/ overlay and the assemble-local.yml action. 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 .farhoodlabs/ on dev (the canonical source) 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 dev and push. The assemble action will apply them to local on the next master push (or trigger it manually via workflow_dispatch).

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 dev:

• 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 dev.

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 dev. 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 dev (canonical) and are also kept in sync on local
• server/package.json — has an adapter-utils workspace vs canary hack that needs fixing eventually