Paperclip Fork — Project Context

This is a fork of paperclipai/paperclip. Fork repo: https://github.com/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 `ghcr.io/farhoodlabs/paperclip`.
`dev`	Development branch based on upstream/master. Builds `ghcr.io/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 ghcr.io/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

3.7 KiB Raw Blame History