elysosss · Aug 10, 2026 · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026
diff --git a/.github/workflows/commitperclip-review.yml b/.github/workflows/commitperclip-review.yml
@@ -15,6 +15,11 @@ permissions:
 
 jobs:
   review:
+    # Upstream's review bot, and only upstream can run it. Dependency Review needs
+    # Advanced Security, which a private fork does not have, and the token step needs
+    # `COMMITPERCLIP_KEY` — upstream's GitHub App, not a secret a fork can hold. On the
+    # fork this job could only ever fail, so it is scoped to the repository that owns it.
+    if: github.repository == 'paperclipai/paperclip'
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:

diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
@@ -27,10 +27,17 @@ jobs:
       - name: Block manual lockfile edits
         if: >-
           github.head_ref != 'chore/refresh-lockfile' &&
+          !startsWith(github.head_ref, 'sync/upstream-') &&
           github.event.pull_request.user.login != 'dependabot[bot]'
         run: |
           # Diff the PR branch against its merge base so recent base-branch commits
           # do not masquerade as changes made by the PR itself.
+          #
+          # `sync/upstream-*` is exempt: those PRs merge upstream/master into the
+          # fork's integration branch, so upstream's own lockfile arrives with the
+          # merge. Blocking it would make an upstream sync unmergeable. The property
+          # that matters — the committed lockfile agrees with the manifests — is
+          # still enforced downstream by `pnpm install --frozen-lockfile`.
           changed="$(git diff --name-only "${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}")"
           if printf '%s\n' "$changed" | grep -qx 'pnpm-lock.yaml'; then
             echo "Do not commit pnpm-lock.yaml in pull requests. CI owns lockfile updates."
@@ -151,26 +158,31 @@ jobs:
         include:
           # The server suite is pinned to maxWorkers=1 (server/vitest.config.ts),
           # so it can only be parallelized across runners. Shard it to keep this
-          # lane off the PR critical path. Four shards because the suite has
-          # grown to ~880s of serial vitest wall time (run 30723165356,
-          # 2026-08-01): at three shards the worst shard ran 313s and was the
-          # slowest check in the whole PR run; four brings each shard to ~220s.
+          # lane off the PR critical path. Five shards because the suite has
+          # grown to ~946s of serial vitest wall time (run 30930345729,
+          # 2026-08-04): at four shards the worst shard ran 311s and was the
+          # slowest check in the whole PR run; five brings each shard to ~196s
+          # of suite time (~240s job), level with the other ~250-300s lanes.
           - group: general-server
-            group_label: server (1/4)
+            group_label: server (1/5)
             shard_index: 0
-            shard_count: 4
+            shard_count: 5
           - group: general-server
-            group_label: server (2/4)
+            group_label: server (2/5)
             shard_index: 1
-            shard_count: 4
+            shard_count: 5
           - group: general-server
-            group_label: server (3/4)
+            group_label: server (3/5)
             shard_index: 2
-            shard_count: 4
+            shard_count: 5
           - group: general-server
-            group_label: server (4/4)
+            group_label: server (4/5)
             shard_index: 3
-            shard_count: 4
+            shard_count: 5
+          - group: general-server
+            group_label: server (5/5)
+            shard_index: 4
+            shard_count: 5
           - group: general-workspaces-a
             group_label: workspaces-a
           - group: general-workspaces-b
@@ -272,18 +284,25 @@ jobs:
       fail-fast: false
       matrix:
         include:
+          # A successful PR run on 2026-08-04 (30876682788) spent 256s in
+          # serialized shard 2/4, making its 305s job the run's slowest check.
+          # Five shards reduce the measured 739s suite total to about 148s per
+          # runner before setup overhead.
           - shard_index: 0
-            shard_count: 4
-            shard_label: 1/4
+            shard_count: 5
+            shard_label: 1/5
           - shard_index: 1
-            shard_count: 4
-            shard_label: 2/4
+            shard_count: 5
+            shard_label: 2/5
           - shard_index: 2
-            shard_count: 4
-            shard_label: 3/4
+            shard_count: 5
+            shard_label: 3/5
           - shard_index: 3
-            shard_count: 4
-            shard_label: 4/4
+            shard_count: 5
+            shard_label: 4/5
+          - shard_index: 4
+            shard_count: 5
+            shard_label: 5/5
 
     steps:
       - name: Checkout repository

diff --git a/.github/workflows/release-verify.yml b/.github/workflows/release-verify.yml
@@ -109,17 +109,20 @@ jobs:
       matrix:
         include:
           - shard_index: 0
-            shard_count: 4
-            shard_label: 1/4
+            shard_count: 5
+            shard_label: 1/5
           - shard_index: 1
-            shard_count: 4
-            shard_label: 2/4
+            shard_count: 5
+            shard_label: 2/5
           - shard_index: 2
-            shard_count: 4
-            shard_label: 3/4
+            shard_count: 5
+            shard_label: 3/5
           - shard_index: 3
-            shard_count: 4
-            shard_label: 4/4
+            shard_count: 5
+            shard_label: 4/5
+          - shard_index: 4
+            shard_count: 5
+            shard_label: 5/5
 
     steps:
       - name: Checkout repository

diff --git a/AGENTS.md b/AGENTS.md
@@ -29,6 +29,10 @@ Before making changes, read in this order:
 - `packages/adapters/`: agent adapter implementations (Claude, Codex, Cursor, etc.)
 - `packages/adapter-utils/`: shared adapter utilities
 - `packages/plugins/`: plugin system packages
+- `packages/skills-catalog/`: app-shipped skills catalog (`@paperclipai/skills-catalog`)
+- `packages/teams-catalog/`: app-shipped teams catalog (`@paperclipai/teams-catalog`)
+- `cli/`: `paperclipai` CLI package (published bin, agent-facing commands)
+- `skills/`: Paperclip runtime/operational skills (not part of the app catalog)
 - `doc/`: operational and product docs
 
 ## 4. Dev Setup (Auto DB)
@@ -179,48 +183,6 @@ A change is done when all are true:
 4. Docs updated when behavior or commands change
 5. PR description follows the [PR template](.github/PULL_REQUEST_TEMPLATE.md) with all sections filled in (including Model Used)
 
-## 11. Fork-Specific: HenkDz/paperclip
-
-This is a fork of `paperclipai/paperclip` with QoL patches and a **built-in** Hermes adapter story on branch `feat/externalize-hermes-adapter` ([tree](https://github.com/HenkDz/paperclip/tree/feat/externalize-hermes-adapter)).
-
-### Branch Strategy
-
-- `feat/externalize-hermes-adapter` now ships `hermes_local` and `hermes_gateway` as built-in core adapters.
-- Older fork branches may still document plugin-only Hermes; treat this file as authoritative for the current branch.
-
-### Hermes (built-in)
-
-- `hermes_local` is available without Adapter manager installation and runs the local Hermes CLI.
-- `hermes_gateway` is available without Adapter manager installation and calls an already-running Hermes API server.
-- Operators may still install external Hermes packages through Adapter manager to override/shadow the built-ins.
-- Optional: `file:` entry in `~/.paperclip/adapter-plugins.json` remains useful for local development of override packages.
-
-### Local Dev
-
-- Fork runs on port 3101+ (auto-detects if 3100 is taken by upstream instance)
-- `npx vite build` hangs on NTFS — use `node node_modules/vite/bin/vite.js build` instead
-- Server startup from NTFS takes 30-60s — don't assume failure immediately
-- Kill ALL paperclip processes before starting: `pkill -f "paperclip"; pkill -f "tsx.*index.ts"`
-- Vite cache survives `rm -rf dist` — delete both: `rm -rf ui/dist ui/node_modules/.vite`
-
-### Fork QoL Patches (not in upstream)
-
-These are local modifications in the fork's UI. If re-copying source, these must be re-applied:
-
-1. **stderr_group** — amber accordion for MCP init noise in `RunTranscriptView.tsx`
-2. **tool_group** — accordion for consecutive non-terminal tools (write, read, search, browser)
-3. **Dashboard excerpt** — `LatestRunCard` strips markdown, shows first 3 lines/280 chars
-
-### Plugin System
-
-PR #2218 (`feat/external-adapter-phase1`) adds external adapter support. See root `AGENTS.md` for full details.
-
-- Adapters can be loaded as external plugins via `~/.paperclip/adapter-plugins.json`
-- The plugin-loader should have ZERO hardcoded adapter imports — pure dynamic loading
-- `createServerAdapter()` must include ALL optional fields (especially `detectModel`)
-- Built-in UI adapters can shadow external plugin parsers; external override pause/resume should restore the built-in parser.
-- Reference external adapters: Droid (npm); Hermes can also be tested as an override package.
-
 ## Design system
 
 `DESIGN.md` at the repo root is the source of truth for UI design decisions. The token-only rule applies to all `ui/` changes: every color, spacing, radius, type, shadow, and motion value in `ui/src/components/**` and `ui/src/pages/**` comes from the token layer in `ui/src/index.css` — no hex, raw px, arbitrary Tailwind bracket values, or raw `font-size`/`fontSize` declarations in components, outside the documented allowlist in `ui/src/index.css`. Run `pnpm check:token-gates` (`scripts/check-token-gates.mjs`) before committing UI changes — it fails on any violation not covered by that allowlist.
diff --git a/Dockerfile b/Dockerfile
@@ -42,6 +42,11 @@ COPY --parents packages/plugins/sandbox-providers/./*/package.json packages/plug
 COPY packages/plugins/paperclip-plugin-fake-sandbox/package.json packages/plugins/paperclip-plugin-fake-sandbox/
 COPY packages/plugins/plugin-llm-wiki/package.json packages/plugins/plugin-llm-wiki/
 COPY packages/plugins/plugin-workspace-diff/package.json packages/plugins/plugin-workspace-diff/
+# Fork plugins.
+COPY packages/plugins/paperclip-plugin-escalation/package.json packages/plugins/paperclip-plugin-escalation/
+COPY packages/plugins/paperclip-plugin-github-mirror/package.json packages/plugins/paperclip-plugin-github-mirror/
+COPY packages/plugins/paperclip-plugin-run-completion/package.json packages/plugins/paperclip-plugin-run-completion/
+COPY packages/plugins/paperclip-plugin-telegram-notify/package.json packages/plugins/paperclip-plugin-telegram-notify/
 COPY patches/ patches/
 COPY scripts/link-plugin-dev-sdk.mjs scripts/
 

diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@
   <a href="https://github.com/paperclipai/paperclip/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
   <a href="https://github.com/paperclipai/paperclip/stargazers"><img src="https://img.shields.io/github/stars/paperclipai/paperclip?style=flat" alt="Stars" /></a>
   <a href="https://www.star-history.com/paperclipai/paperclip"><img src="https://api.star-history.com/badge?repo=paperclipai/paperclip" alt="Star History Rank" /></a>
-  <a href="https://discord.gg/m4HZY7xNG3"><img src="https://img.shields.io/discord/000000000?label=discord" alt="Discord" /></a>
+  <a href="https://discord.gg/m4HZY7xNG3"><img src="https://img.shields.io/badge/discord-join-7289da" alt="Discord" /></a>
 </p>
 
 <br/>

diff --git a/cli/src/__tests__/agent-jwt-env.test.ts b/cli/src/__tests__/agent-jwt-env.test.ts
@@ -76,4 +76,62 @@ describe("agent jwt env helpers", () => {
     expect(contents).toContain('PAPERCLIP_WORKTREE_COLOR="#439edb"');
     expect(readPaperclipEnvEntries(envPath).PAPERCLIP_WORKTREE_COLOR).toBe("#439edb");
   });
+
+  it("preserves operator content and CRLF while updating only managed entries", () => {
+    const configPath = tempConfigPath();
+    const envPath = resolveAgentJwtEnvFile(configPath);
+    const original = [
+      "# operator comment",
+      "DATABASE_URL='postgres://operator:encoded@localhost/paperclip'",
+      "",
+      "export PAPERCLIP_HOME = '/old path'  # managed path",
+      "PAPERCLIP_DUPLICATE=stale",
+      'PAPERCLIP_DUPLICATE="current"',
+      "UNKNOWN_VALUE=operator-owned",
+      "",
+    ].join("\r\n");
+    fs.writeFileSync(envPath, original, { mode: 0o600 });
+
+    mergePaperclipEnvEntries(
+      {
+        PAPERCLIP_HOME: "/new path",
+        PAPERCLIP_DUPLICATE: "current",
+        PAPERCLIP_WORKTREE_COLOR: "#439edb",
+        DATABASE_URL: "postgres://paperclip-must-not-overwrite",
+      },
+      envPath,
+    );
+
+    const updated = fs.readFileSync(envPath, "utf8");
+    expect(updated).toBe([
+      "# operator comment",
+      "DATABASE_URL='postgres://operator:encoded@localhost/paperclip'",
+      "",
+      'export PAPERCLIP_HOME = "/new path"  # managed path',
+      "PAPERCLIP_DUPLICATE=current",
+      'PAPERCLIP_DUPLICATE="current"',
+      "UNKNOWN_VALUE=operator-owned",
+      'PAPERCLIP_WORKTREE_COLOR="#439edb"',
+      "",
+    ].join("\r\n"));
+    expect(updated.replaceAll("\r\n", "")).not.toContain("\n");
+  });
+
+  it("does not replace the env file when managed values are already current", () => {
+    const configPath = tempConfigPath();
+    const envPath = resolveAgentJwtEnvFile(configPath);
+    const original = [
+      "# preserve this file byte-for-byte",
+      "export PAPERCLIP_HOME = '/same path'",
+      "UNKNOWN=\"operator encoding\"",
+      "",
+    ].join("\n");
+    fs.writeFileSync(envPath, original, { mode: 0o600 });
+    const previousInode = fs.statSync(envPath).ino;
+
+    mergePaperclipEnvEntries({ PAPERCLIP_HOME: "/same path" }, envPath);
+
+    expect(fs.readFileSync(envPath, "utf8")).toBe(original);
+    expect(fs.statSync(envPath).ino).toBe(previousInode);
+  });
 });
diff --git a/cli/src/__tests__/agent-lifecycle.test.ts b/cli/src/__tests__/agent-lifecycle.test.ts
@@ -83,7 +83,15 @@ describe("agent lifecycle commands", () => {
     await run(["agent", "runtime-state:reset-session", AGENT_ID, "--task-key", "task-1"]);
     await run(["agent", "task-sessions", AGENT_ID]);
     await run(["agent", "skills", AGENT_ID]);
-    await run(["agent", "skills:sync", AGENT_ID, "--desired-skills", "paperclip,github"]);
+    await run([
+      "agent",
+      "skills:sync",
+      AGENT_ID,
+      "--desired-skills",
+      "paperclip,github",
+      "--mode",
+      "replace",
+    ]);
     await run(["agent", "instructions-path:update", AGENT_ID, "--payload-json", JSON.stringify({ path: "/tmp/AGENTS.md" })]);
     await run(["agent", "instructions-bundle", AGENT_ID]);
     await run(["agent", "instructions-bundle:update", AGENT_ID, "--payload-json", JSON.stringify({ mode: "managed" })]);

diff --git a/cli/src/__tests__/company-delete.test.ts b/cli/src/__tests__/company-delete.test.ts
@@ -27,6 +27,7 @@ function makeCompany(overrides: Partial<Company>): Company {
     createdAt: new Date(),
     updatedAt: new Date(),
     ...overrides,
+    interactionResolverGovernance: overrides.interactionResolverGovernance ?? {},
   };
 }
 

diff --git a/cli/src/__tests__/company.test.ts b/cli/src/__tests__/company.test.ts
@@ -504,6 +504,17 @@ describe("renderCompanyImportResult", () => {
           { slug: "cto", id: "agent-2", action: "updated", name: "CTO", reason: "replace strategy" },
           { slug: "ops", id: null, action: "skipped", name: "Ops", reason: "skip strategy" },
         ],
+        skills: [
+          {
+            originalKey: "company/source/review",
+            originalSlug: "review",
+            key: "company/target/review-2",
+            slug: "review-2",
+            id: "skill-1",
+            action: "renamed",
+            reason: "rename strategy",
+          },
+        ],
         projects: [
           { slug: "app", id: "project-1", action: "created", name: "App", reason: null },
           { slug: "ops", id: "project-2", action: "updated", name: "Operations", reason: "replace strategy" },
@@ -525,8 +536,10 @@ describe("renderCompanyImportResult", () => {
     expect(rendered).toContain("Company");
     expect(rendered).toContain("https://paperclip.example/PAP/dashboard");
     expect(rendered).toContain("3 agents total (1 created, 1 updated, 1 skipped)");
+    expect(rendered).toContain("1 skill total (1 renamed)");
     expect(rendered).toContain("3 projects total (1 created, 1 updated, 1 skipped)");
     expect(rendered).toContain("Agent results");
+    expect(rendered).toContain("Skill results");
     expect(rendered).toContain("Project results");
     expect(rendered).toContain("Using claude-local adapter");
     expect(rendered).toContain("Review API keys");