diff --git a/PENDING.md b/PENDING.md index e881859..686b87f 100644 --- a/PENDING.md +++ b/PENDING.md @@ -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. diff --git a/SCREENSHOTS_PENDING.md b/SCREENSHOTS_PENDING.md index af6d9c5..cbfadd6 100644 --- a/SCREENSHOTS_PENDING.md +++ b/SCREENSHOTS_PENDING.md @@ -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` | diff --git a/docs/reference/adapters/external-adapters.md b/docs/reference/adapters/external-adapters.md index ae20adc..976223d 100644 --- a/docs/reference/adapters/external-adapters.md +++ b/docs/reference/adapters/external-adapters.md @@ -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). --- diff --git a/docs/reference/adapters/gemini-local.md b/docs/reference/adapters/gemini-local.md index 8960fcb..b4dfd77 100644 --- a/docs/reference/adapters/gemini-local.md +++ b/docs/reference/adapters/gemini-local.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 diff --git a/docs/reference/deploy/docker.md b/docs/reference/deploy/docker.md index 273158d..137d4cf 100644 --- a/docs/reference/deploy/docker.md +++ b/docs/reference/deploy/docker.md @@ -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 ```