mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-07 06:16:07 -10:00
nightly: Gemini Docker bundling + external adapter overrides (paperclip 76c88e5)
- docker.md / gemini-local.md: Gemini CLI now bundled in the official image (GEMINI_SANDBOX=false); backfill opencode_local in bundled list (paperclip #7693) - external-adapters.md: external adapters can override built-in types; document override + fallback lifecycle, correct stale 'cannot be overwritten' note (paperclip #7394) - regenerate PENDING.md / SCREENSHOTS_PENDING.md (18 settings/adapter screenshots stale after instance-settings IA move, paperclip #7680) Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
This commit is contained in:
Aron PrinsandClaude Opus 4.8 committed
1 parent
cec1fda2d0
commit
a665c76e99
5 files changed
+59
-111
No files matched your search
+15
-66
@@ -3,83 +3,32 @@
|
||||
> Regenerated by `/sync-docs` every nightly run. Cumulative from `base_release_tag`.
|
||||
|
||||
- **Base release tag:** `v2026.529.0`
|
||||
- **Parent window:** `v2026.529.0` → parent `master` HEAD `a800140`, effective settled cutoff `a4fa0ea` (24h quarantine)
|
||||
- **Commits in cumulative window:** 119 total; 16 quarantined (younger than 24h, deferred to next run)
|
||||
- **Doc-relevant manifest entries:** 3 applied this run; prior-run entries carried in cumulative window
|
||||
- **Drift candidates:** 0 (`check-drift.mjs` against master — clean)
|
||||
- **Reconciliation candidates:** 0 (nothing previously applied was reverted upstream)
|
||||
- **Genuine new dirs (rename-checked):** `packages/teams-catalog/**` (new), `ui/src/pages/Artifacts.tsx` (new). The `skills/` → `.agents/skills/` move (maintainer skills `diagnose-why-work-stopped`, `paperclip-create-plugin`, `terminal-bench-loop`, plus new `create-issue-interaction-ui`) is a maintainer-tooling relocation, not a user-facing skill bundle — no doc impact. The canonical `skills/paperclip/**` bundle stays at `skills/`.
|
||||
- **Window:** `v2026.529.0` → parent `master` HEAD `0a2230b` (effective HEAD `76c88e5` after 24h quarantine)
|
||||
- **Last run:** 2026-06-09
|
||||
|
||||
## ⏳ Quarantined this run (deferred to next run)
|
||||
## Applied this run (PR tier — adapters/deploy)
|
||||
|
||||
These landed within the last 24h, so they are held back until reverts have time to settle. Expect them in the next nightly manifest:
|
||||
- **Gemini CLI bundled in Docker** (paperclip #7693) — `docs/reference/deploy/docker.md`, `docs/reference/adapters/gemini-local.md`. The official image now bakes in the Gemini CLI (`@google/gemini-cli`) alongside `claude`, `codex`, and `opencode`, and sets `GEMINI_SANDBOX=false`, so `gemini_local` works in-container out of the box. Docker bundled-CLI list also backfilled `opencode_local`.
|
||||
- **External adapters can override built-ins** (paperclip #7394) — `docs/reference/adapters/external-adapters.md`. Corrected the stale "built-ins cannot be overwritten" note and documented the override + fallback lifecycle (`POST /api/adapters/install` accepts a built-in type; `requiresRestart` only on a true reinstall; pause snaps agents back to the built-in; built-ins protected from deletion).
|
||||
|
||||
- **Information Architecture + project/agent visual refresh (experimental)** (`eaef47f4`, #7543) — large UI refresh across `ui/src/pages/Agents.tsx`, `AgentDetail.tsx`, project tiles/icons, `Sidebar`. Behind an experimental flag. Will invalidate many screenshots once settled.
|
||||
- **Checkbox-confirmation issue interactions** (`4d5322c8`, #7649) + **issue interaction selector polish** (`bb880d99`, #7668) — `server/src/services/issue-thread-interactions.ts`, `ui/src/components/IssueThreadInteractionCard.tsx`.
|
||||
- **Video artifact thumbnails** (`86253f52`, #7667) — extends the new Artifacts page (covered below) with inline video previews.
|
||||
- **Guard git-sensitive adapter workspaces** (`7428fb95`, #7644) — `execution-workspace-policy`.
|
||||
- **Prevent invalid agents from receiving assignments/runs** (`71a8464f`, #7663) — new `agent-assignability.ts` / `agent-invokability.ts` services + `packages/shared/src/agent-eligibility.ts`. User-visible: ineligible agents no longer get work. Candidate doc note next run.
|
||||
- **Project icons** (`eaef47f4` + migration `0098_project_icon`) — projects can carry an icon.
|
||||
- **CLI: send `X-Paperclip-Run-Id`** (`8b85fdfa`, #7642) — agents can mutate their issues via the CLI during a run. Minor; likely context-only.
|
||||
- Dependency bumps (storybook, drizzle-kit, tailwindcss) + CI guards — not doc-relevant.
|
||||
## Needs human attention
|
||||
|
||||
## Auto-merge
|
||||
- **Instance settings moved under Company Settings** (paperclip #7680) — navigation/IA change. Routes preserved via compatibility redirects, so no doc URLs break and no prose in `docs/administration/settings.md` is factually wrong. Impact is visual — see ⚠ Screenshots below. Consider a future note on how operators now reach Instance Settings (nested under Company Settings) once screenshots are refreshed.
|
||||
- **Agent action buttons** (paperclip #7679 live-run stop finalization, #7695 clear-error) — granular UI controls in `AgentActionButtons`. Not currently surfaced in docs; flag only.
|
||||
|
||||
_None._ No `.env.example` / config / env-schema additions in the settled window — the env-vars watcher matched nothing.
|
||||
## ⚠ Screenshots
|
||||
|
||||
## PR-tier — applied this run
|
||||
|
||||
### 1. Teams Catalog — installable team templates
|
||||
|
||||
- **Watcher:** skills-catalog (new sibling surface) / cli-commands / rest-routes
|
||||
- **Parent files:** `packages/teams-catalog/**` (new package), `cli/src/commands/client/teams.ts` (new `teams` CLI command), `server/src/routes/teams-catalog.ts` (new routes), `packages/shared/src/types/teams-catalog.ts`, `packages/shared/src/validators/teams-catalog.ts`. (#7550, `fff3832a`)
|
||||
- **Change kind:** added.
|
||||
- **Surface:** A catalog of installable starter teams — `bundled` (always present: `company-defaults`, `product`, `software-development`) and `optional` (e.g. `content`) — each shipping agents, projects, tasks, and skills. Browse/inspect/preview/install via the new `teams` CLI command or the in-app Team Catalog page.
|
||||
- **Docs targets:** `docs/reference/cli/teams.md` (new — CLI reference), `docs/guides/org/team-catalog.md` (new — guide), nav added under CLI and "Your Org & Agents".
|
||||
- **Verification (Phase 5.5):** clean.
|
||||
|
||||
### 2. Company Artifacts page
|
||||
|
||||
- **Watcher:** server-services / rest-routes / web-ui
|
||||
- **Parent files:** `server/src/services/company-artifacts.ts` (new), `packages/shared/src/types/artifact.ts` (new), `packages/shared/src/validators/artifact.ts` (new), `server/src/routes/companies.ts` (new `GET /:companyId/artifacts`), `ui/src/pages/Artifacts.tsx` (new). (#7621, `4693d770`)
|
||||
- **Change kind:** added.
|
||||
- **Surface:** A company-level view of every artifact agents produce — documents, attachments, and work products — filterable by media kind and groupable by task / parent task stacks, with inline previews.
|
||||
- **Docs targets:** `docs/guides/day-to-day/artifacts.md` (new — guide), `docs/reference/api/companies.md` (new "List company artifacts" section), nav added under "Working Day-to-day".
|
||||
- **Verification (Phase 5.5):** clean.
|
||||
|
||||
### 3. Low-trust review containment / trust presets
|
||||
|
||||
- **Watcher:** server-services / schemas
|
||||
- **Parent files:** `packages/shared/src/trust-policy.ts` (new), `packages/shared/src/validators/trust-policy.ts` (new), `server/src/services/trust-preset-resolver.ts` (new), `server/src/services/source-trust.ts` (new), `server/src/services/low-trust-runtime-containment.ts` (new), migration `0097_low_trust_source_trust.sql`, schema changes on `issues` / `issue_comments` / `documents` / `issue_work_products`. (#7530, `dbebf30c`)
|
||||
- **Change kind:** added.
|
||||
- **Surface:** Trust presets (`standard`, `low_trust_review`) that contain less-trusted agents and sources at runtime (isolated workspace, sandbox driver, restricted secrets and tool classes) and quarantine their work products until they're reviewed and promoted.
|
||||
- **Docs targets:** `docs/administration/trust-and-low-trust-review.md` (new — admin page), nav added under "Administration".
|
||||
- **Verification (Phase 5.5):** clean.
|
||||
|
||||
## PR-tier — applied in prior runs (carried in cumulative window)
|
||||
|
||||
These remain in the cumulative diff from `v2026.529.0` and were authored in earlier nightly runs; no re-work needed:
|
||||
|
||||
1. **CLI API-parity handbook** — reference pages under `docs/reference/cli/`.
|
||||
2. **`wireframe` + `last30days` catalog skills** — `docs/reference/skills.md`, `docs/guides/org/skills.md`.
|
||||
3. **Routine scheduled-tick suppression while project is paused** — `docs/reference/api/routines.md`.
|
||||
4. **Company archive cascade pauses agents** — `docs/administration/company.md`, `docs/reference/api/companies.md`.
|
||||
See `SCREENSHOTS_PENDING.md` — 18 entries stale (settings + adapter pages).
|
||||
|
||||
## ⚠ Drift
|
||||
|
||||
_None._ `check-drift.mjs` against master found no documented surfaces missing upstream.
|
||||
None.
|
||||
|
||||
## ⚠ Reconcile
|
||||
|
||||
_None._ No previously-applied doc edit corresponds to a reverted parent commit.
|
||||
- paperclip #7678 ("Refine issue comment wake handoffs") is in-window but its revert (#7765) is held by the 24h quarantine. #7678 is an internal wake mechanism with no user-facing doc, so no edit was made. Once the revert clears quarantine it cancels out of the cumulative diff entirely.
|
||||
|
||||
## Screenshots
|
||||
## Quarantined (held < 24h, processed next run)
|
||||
|
||||
40 tracked captures are stale in the settled window (`AgentDetail.tsx`, `NewAgent.tsx`, `IssueDetail.tsx`, `Routines.tsx`). See `SCREENSHOTS_PENDING.md`. Recapture with `npm run screenshots:refresh` — PNGs land in a PR for human review, never auto-pushed.
|
||||
|
||||
## Orphans (not in nav — informational)
|
||||
|
||||
- `docs/reference/cli/commands.md`
|
||||
- `docs/reference/cli/control-plane-commands.md`
|
||||
|
||||
Pre-existing; likely superseded by the per-command CLI handbook pages. Human decides whether to remove or register.
|
||||
- paperclip #7765 — Revert PR #7678.
|
||||
- paperclip #7766 — Guard document comment wake boundaries.
|
||||
+21
-43
@@ -2,50 +2,28 @@
|
||||
|
||||
> Regenerated by `/sync-docs` each nightly run. Lists screenshots whose `depends_on` parent paths changed in the current settled diff window.
|
||||
|
||||
- **Window:** `v2026.529.0` → `a4fa0ea` (24h-quarantined nightly cutoff; HEAD `a800140`)
|
||||
- **Stale entries:** 40
|
||||
- **Window:** `v2026.529.0` → parent `master` HEAD `0a2230b` (effective HEAD `76c88e5` after 24h quarantine)
|
||||
- **Stale entries:** 18
|
||||
|
||||
Recapture with `npm run screenshots:refresh` (PNGs land in a PR for human review — never auto-pushed).
|
||||
The settings screenshots are stale because instance settings moved under company settings (paperclip #7680) and the adapter manager gained override controls (paperclip #7394). Recapture with `npm run screenshots:refresh` (PNGs land in a PR for human review — never auto-pushed).
|
||||
|
||||
| Screenshot | Route | Changed dependency |
|
||||
|---|---|---|
|
||||
| `dark/agents/agent-detail-idle.png` | `/ACME/agents/{agentId}` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `dark/agents/agent-detail-run-history.png` | `/ACME/agents/{agentId}/runs` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `dark/agents/agent-status-running.png` | `/ACME/agents/{longRunnerAgentId}` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `dark/agents/budget.png` | `/ACME/agents/{agentId}/budget` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `dark/agents/configuration.png` | `/ACME/agents/{agentId}/configuration` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `dark/agents/dashboard.png` | `/ACME/agents/{agentId}/dashboard` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `dark/agents/instructions.png` | `/ACME/agents/{agentId}/instructions` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `dark/agents/new-agent-name-role.png` | `/ACME/agents/new` | `ui/src/pages/NewAgent.tsx` |
|
||||
| `dark/agents/new-agent-reports-to-field.png` | `/ACME/agents/new` | `ui/src/pages/NewAgent.tsx` |
|
||||
| `dark/agents/run-history-in-progress.png` | `/ACME/agents/{longRunnerAgentId}/runs` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `dark/agents/run-transcript-view.png` | `/ACME/agents/{runnerAgentId}/runs/{runnerRunId}` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `dark/agents/runs.png` | `/ACME/agents/{agentId}/runs` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `dark/agents/skills.png` | `/ACME/agents/{agentId}/skills` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `dark/costs/agent-budget-field.png` | `/ACME/agents/{agentId}/budget` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `dark/issues/detail-activity.png` | `/ACME/issues/{issueId}` | `ui/src/pages/IssueDetail.tsx` |
|
||||
| `dark/issues/detail-chat.png` | `/ACME/issues/{issueId}` | `ui/src/pages/IssueDetail.tsx` |
|
||||
| `dark/issues/detail-sidebar.png` | `/ACME/issues/{issueId}` | `ui/src/pages/IssueDetail.tsx` |
|
||||
| `dark/issues/list.png` | `/ACME/issues` | `ui/src/pages/IssueDetail.tsx` |
|
||||
| `dark/routines/list.png` | `/ACME/routines` | `ui/src/pages/Routines.tsx` |
|
||||
| `dark/tasks/task-detail-with-comments.png` | `/ACME/issues/{issueId}` | `ui/src/pages/IssueDetail.tsx` |
|
||||
| `light/agents/agent-detail-idle.png` | `/ACME/agents/{agentId}` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `light/agents/agent-detail-run-history.png` | `/ACME/agents/{agentId}/runs` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `light/agents/agent-status-running.png` | `/ACME/agents/{longRunnerAgentId}` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `light/agents/budget.png` | `/ACME/agents/{agentId}/budget` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `light/agents/configuration.png` | `/ACME/agents/{agentId}/configuration` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `light/agents/dashboard.png` | `/ACME/agents/{agentId}/dashboard` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `light/agents/instructions.png` | `/ACME/agents/{agentId}/instructions` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `light/agents/new-agent-name-role.png` | `/ACME/agents/new` | `ui/src/pages/NewAgent.tsx` |
|
||||
| `light/agents/new-agent-reports-to-field.png` | `/ACME/agents/new` | `ui/src/pages/NewAgent.tsx` |
|
||||
| `light/agents/run-history-in-progress.png` | `/ACME/agents/{longRunnerAgentId}/runs` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `light/agents/run-transcript-view.png` | `/ACME/agents/{runnerAgentId}/runs/{runnerRunId}` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `light/agents/runs.png` | `/ACME/agents/{agentId}/runs` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `light/agents/skills.png` | `/ACME/agents/{agentId}/skills` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `light/costs/agent-budget-field.png` | `/ACME/agents/{agentId}/budget` | `ui/src/pages/AgentDetail.tsx` |
|
||||
| `light/issues/detail-activity.png` | `/ACME/issues/{issueId}` | `ui/src/pages/IssueDetail.tsx` |
|
||||
| `light/issues/detail-chat.png` | `/ACME/issues/{issueId}` | `ui/src/pages/IssueDetail.tsx` |
|
||||
| `light/issues/detail-sidebar.png` | `/ACME/issues/{issueId}` | `ui/src/pages/IssueDetail.tsx` |
|
||||
| `light/issues/list.png` | `/ACME/issues` | `ui/src/pages/IssueDetail.tsx` |
|
||||
| `light/routines/list.png` | `/ACME/routines` | `ui/src/pages/Routines.tsx` |
|
||||
| `light/tasks/task-detail-with-comments.png` | `/ACME/issues/{issueId}` | `ui/src/pages/IssueDetail.tsx` |
|
||||
| `dark/adapters/detail.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
|
||||
| `dark/adapters/health.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
|
||||
| `dark/adapters/install.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
|
||||
| `dark/adapters/list.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
|
||||
| `dark/settings/experimental.png` | `/instance/settings/experimental` | `ui/src/pages/InstanceExperimentalSettings.tsx` |
|
||||
| `dark/settings/instance-access.png` | `/instance/settings/access` | `ui/src/pages/InstanceAccess.tsx` |
|
||||
| `dark/settings/instance-adapters.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
|
||||
| `dark/settings/instance-general.png` | `/instance/settings/general` | `ui/src/pages/InstanceGeneralSettings.tsx` |
|
||||
| `dark/settings/scheduler-heartbeats.png` | `/instance/settings/heartbeats` | `ui/src/pages/InstanceSettings.tsx` |
|
||||
| `light/adapters/detail.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
|
||||
| `light/adapters/health.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
|
||||
| `light/adapters/install.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
|
||||
| `light/adapters/list.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
|
||||
| `light/settings/experimental.png` | `/instance/settings/experimental` | `ui/src/pages/InstanceExperimentalSettings.tsx` |
|
||||
| `light/settings/instance-access.png` | `/instance/settings/access` | `ui/src/pages/InstanceAccess.tsx` |
|
||||
| `light/settings/instance-adapters.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
|
||||
| `light/settings/instance-general.png` | `/instance/settings/general` | `ui/src/pages/InstanceGeneralSettings.tsx` |
|
||||
| `light/settings/scheduler-heartbeats.png` | `/instance/settings/heartbeats` | `ui/src/pages/InstanceSettings.tsx` |
|
||||
@@ -159,7 +159,21 @@ Useful management endpoints:
|
||||
- `POST /api/adapters/:type/reinstall`
|
||||
- `DELETE /api/adapters/:type`
|
||||
|
||||
> **Note:** Built-in adapters cannot be removed or overwritten by external installs.
|
||||
> **Note:** Built-in adapters are protected from deletion. You can still install an external adapter that *overrides* a built-in type (see below), but the built-in itself stays in place as a fallback and can't be removed unless an external override exists for it.
|
||||
|
||||
---
|
||||
|
||||
## Overriding A Built-In
|
||||
|
||||
You can install an external adapter whose `type` matches a built-in — for example, ship your own `hermes_local` to pick up a newer or organization-specific implementation. `POST /api/adapters/install` accepts the override, and the external adapter takes precedence while the built-in stays available as a fallback.
|
||||
|
||||
A few things to know:
|
||||
|
||||
- A first-time override of a built-in type installs without requiring a restart. Reinstalling an override you already have (an existing external plugin record for that type) is the only case that reports `requiresRestart`.
|
||||
- Pausing the override from the Adapter Manager snaps every agent of that type back to the built-in implementation on their next run; resuming restores the external adapter.
|
||||
- Removing the override unregisters the external adapter and falls back to the built-in. The built-in itself is never deleted.
|
||||
|
||||
The operator-facing walkthrough of pausing, resuming, and removing overrides lives in [Settings → Instance: Adapters](../../administration/settings.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -17,6 +17,8 @@
|
||||
- You only need a command runner or script. Use [Process](./process.md).
|
||||
- Gemini CLI is not installed or cannot reach the target working directory.
|
||||
|
||||
> **Running in Docker?** The official Paperclip image pre-bundles the Gemini CLI alongside the other local CLIs, so `gemini_local` works in-container without a manual install. The image also sets `GEMINI_SANDBOX=false` for safe in-container use. You still need to supply credentials — see [Docker](../deploy/docker.md).
|
||||
|
||||
---
|
||||
|
||||
## Common Fields
|
||||
|
||||
@@ -69,10 +69,14 @@ If the bind mount is removed, the instance starts fresh on the next run.
|
||||
|
||||
## LLM Adapter Support
|
||||
|
||||
The Docker image pre-installs the local CLI tools used by the built-in local adapters:
|
||||
The Docker image pre-installs the local CLI tools used by the built-in local adapters, so they work inside the container out of the box:
|
||||
|
||||
- `claude` for `claude_local`
|
||||
- `codex` for `codex_local`
|
||||
- `opencode` for `opencode_local`
|
||||
- `gemini` for `gemini_local`
|
||||
|
||||
The image sets `GEMINI_SANDBOX=false` so the Gemini CLI runs safely inside the container without its own sandbox layer.
|
||||
|
||||
If you want those adapters to run inside the container, pass the relevant API keys:
|
||||
|
||||
@@ -83,6 +87,7 @@ docker run --name paperclip \
|
||||
-e PAPERCLIP_HOME=/paperclip \
|
||||
-e OPENAI_API_KEY=sk-... \
|
||||
-e ANTHROPIC_API_KEY=sk-... \
|
||||
-e GEMINI_API_KEY=... \
|
||||
-v "$(pwd)/data/docker-paperclip:/paperclip" \
|
||||
paperclip-local
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user