Files
PaperClipAI/maps
DottaandClaude Fable 5.2 33fac97cad feat(routines): ship the redesigned routine page and let live webhooks be tested again (#22205)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Routines start agent work on a schedule, from a webhook, or on
demand
> - The routine detail page split one routine across eight sections
behind a section sidebar (overview, triggers, variables, secrets,
delivery, runs, activity, history)
> - People had to hunt through sections to see what a routine does and
to change it, and a finished webhook could not be tested again without
starting the routine
> - This pull request makes the approved two-column routine page, one
Edit dialog and one Webhook dialog the real routed page, and lets a live
webhook go back into test mode
> - The benefit is one page that answers what the routine does, when it
runs, who runs it and what it made, with every change in one dialog

## Linked Issues or Issue Description

**Problem**
The routine detail page spreads one routine over eight sections and a
section sidebar. Changing a routine means visiting several sections,
each with its own save bar. A webhook that is already live cannot be
tested again: the API only accepts `setupPending: false`, so testing a
live webhook starts the routine.

**Proposed solution**
Ship the reviewed design (stories `routine-page-design`,
`routine-edit-dialog-design`, `routine-webhook-dialog-design`) as the
routed page in both UI shells, wired to the real API. Let `PATCH
/api/routine-triggers/:id` accept `setupPending: true` for a live
webhook so the next events are checked but never start the routine.

**Alternatives considered**
Keep the sections and restyle them. The owner rejected this: the section
sidebar should go.

## What Changed

- `/routines/:id` renders `RoutinePage` in both shells
(`RoutineDetail.production.tsx` is removed). Status switch, Repeats
rows, default agent, responsible user, project, Asks for, Secrets, Run
rules, Managed by plugin, Instructions with Show all, copy and the
comment count, and History.
- History is paged: 20 tasks per page from `GET
/companies/:id/issues?originKind=routine_execution&originId=…&sortField=created&sortDir=desc&limit=21&offset=…`,
with a real Load more. Coalesced runs show as "folded into a task".
- A failed refetch keeps the loaded page on screen (`useQueryView`); a
History failure shows `QueryErrorState` in place.
- Header: Edit, "…" (Version history, Audit log, Archive / Restore) and
Run now. In the streamlined desktop shell they sit in the breadcrumb
toolbar; elsewhere above the page.
- Version history (`/routines/:id/history`, restore and restored-webhook
keys kept) and Audit log (`/routines/:id/activity`,
`RoutineAuditActivity`) open as sub-views with a way back. Old section
addresses and `?tab=` redirect to `/routines/:id`.
- Edit dialog saves title, instructions, variables, secrets, agent,
project and responsible user in one request against the revision the
dialog opened with (save conflict shows "changed while you were
editing"). The first schedule is created, changed or removed after that.
Priority and delivery settings are never sent, so saved values stay.
- Webhooks are created, changed, tested and removed (with Undo) right
away from the Edit dialog, with the Webhook dialog nested inside it.
Closing the Webhook dialog ends setup or test mode. A webhook left in
test mode shows "Testing · events don’t run" on the page and offers
Finish testing.
- Responsibility (only with `enableResponsibilities`): the page shows
direct and through-project responsibilities from the link lookup; the
dialog links or unlinks the direct one. With the flag off nothing is
fetched or shown.
- The routines list creates routines with the same dialog in create
mode, filed in the open folder, and opens the new routine page.
- Server: `setupPending: true` on a live webhook enters test mode
(planned by a pure `planTriggerUpdate`, which also gives the activity
action) (422 for other trigger kinds; 409 for a disabled or removed
webhook or an archived routine). Test deliveries keep the last real
delivery as `lastWebhookDelivery.previous`, and finishing testing
restores it. Activity `routine.trigger_test_started`.
- Additions to the reviewed design, from review, so no capability is
lost: the schedule popover has Pause/Resume; standing-check and API rows
open a small popover with Pause/Resume and Remove; removing a trigger
from the page leaves a "… removed. Undo" line under Repeats. Stories:
`StandingCheckOpened`, `ScheduleTriggerPaused(Opened)`,
`RemovedWithUndo`.
- Save is several requests (routine, schedule, responsibility). It
changes only the schedule the form opened with, records each finished
step, and a partial failure says what was saved and that saving again
finishes it. The dialog cannot be dismissed while saving. Failed reads
show a Retry state, never empty choices.
- Removed: the routine section sidebar and contextual sidebar, the
trigger wizard, trigger cards, save bar, section components and their
tests.
- Storybook: the three routine stories moved to `stories/routines` as
current production stories, a new story mounts the routed page against a
fixture API, and stories that used the old page were updated or removed.

## Verification

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/routines-e2e.test.ts` (17/17) and
`src/__tests__/routines-service.test.ts` (105/105).
- `pnpm exec vitest run` on the routine page, routines list, routine
form, webhook instructions, Layout, shell navigation, audit and editor
tests: 275 tests pass.
- `cd ui && npx tsc -p tsconfig.json --noEmit`, `node
scripts/check-token-gates.mjs`, `node scripts/check-maps.mjs`, `node
scripts/storybook-catalog.mjs --check`: pass.
- `pnpm verify` exits 2 (global CI input changed); required CI supplies
the broad coverage.
- Manual: an isolated worktree instance (`pnpm paperclipai worktree init
--empty`, `pnpm dev`) with a seeded routine. Headless Playwright: an old
`/triggers` address redirects, no section sidebar, History shows 20 then
23 after Load more, the schedule popover opens, pause and resume, Edit →
Add webhook → created key → Finish, title save, Test webhook → Finish
testing, Version history, Audit log shows "Started testing a webhook",
phone width has no horizontal overflow, and Create routine from the list
opens the new page. No console errors or failed API calls.

## Risks

- Behaviour change: the section pages are gone. Old links redirect to
the single page.
- The delivery-setting editors (concurrency, catch-up, activity gate)
and priority are removed from the UI. Saved values stay, and the API
still accepts them.
- The create dialog no longer offers a folder picker or delivery
settings. A new routine goes into the folder the list is showing and
takes the default settings.
- Replace key in the Webhook dialog acts at once, as in the reviewed
design. The old confirmation is gone.
- No migration. `lastWebhookDelivery.previous` is an optional field
inside the existing jsonb column.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with
tool use (shell, file edits, headless browser) and subagents for the
server change and the Storybook move.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-18 13:13:15 -06:00
..

Paperclip maps

The maps describe the same capabilities from two perspectives:

  • Feature map: what a person can do, where to reach it, and how to verify the user journey. Preserve its Poteto format.
  • Agent access map: the APIs and agent entry points for those capabilities, their permission boundaries, and access verification.

The chat scenario catalog adds natural-language requests, starting context and expected conversational outcomes for the same capability IDs. It lives with Product E2E as planning data; a scenario reference is neither a registered execution nor evidence that a journey passed.

These are sibling directories under maps/. Each feature file has a same-named agent access companion. Reuse the product map's sub-feature IDs, so tasks/create identifies the same capability in both maps. Product behavior remains governed by the code and its tests; a map cannot grant authority or redefine a permission denial as success.

Capability identifiers

The feature ID is the recipe filename without .md, such as onboarding. The full capability ID joins that feature ID and a Sub-features key with /: the company key in feature-map/onboarding.md is onboarding/company. Its agent-access-map/onboarding.md companion uses the same local company key. The feature-map index lists the existing feature and full capability IDs.

Each child page states Feature ID: `onboarding`. after its introduction or product-map link. In feature recipes, show the full ID beside the parsed local key: - `company`: `onboarding/company` — create a company. In access companions and Storybook verification guidance, keep the existing local heading and put Capability ID: `onboarding/company`. beneath it. These labels make the existing identifiers visible without changing keys, anchors, or ID generation.

Use full capability IDs in cross-feature references, Storybook annotations, tests, issues, PRs, and verification evidence. Both segments use lowercase letters, digits, and hyphens. Keep filenames and keys stable when display titles or navigation labels change; renaming either changes the capability ID.

Entry-point IDs describe a surface, such as web-wizard, and are scoped to their recipe. Reference them with a recipe link, such as onboarding.md#web-wizard, and record the capability exercised separately. Navigation section labels are not capability IDs. See IDs and references for examples.

Access contract

Every business operation needs both an API and a usable agent entry point for an actor authorized to perform it. A dedicated tool is optional when REST, the CLI, an assigned MCP client, or native search_api / call_api already provides the operation. Record which agent surfaces actually have that path; an installed CLI or optional MCP package cannot be assumed available to every native/remote run.

Track these independently:

Dimension Values and meaning
API present, missing, not-applicable, or unreviewed. Use exact methods/paths; distinguish protocols from REST.
Agent access available, partial, missing, restricted, operator-only, not-applicable, or unreviewed. Name the supported surface and actual entry point.
Policy Actor, action/grant, company/resource/ownership scope, responsible-user intersection, run requirements, work modes, and gates relevant to the operation.
Evidence source-only, verified, failed, blocked, or not-run. Source presence and successful board calls are not agent verification.
Review depth baseline records representative operations and known gaps; operation-reviewed enumerates the capability's meaningful operations and their individual access contracts.

Broad capabilities such as task properties must be split into operations before they count as operation-reviewed: renaming, metadata edits, assignment, dependencies, and lifecycle changes can use different tools and permission rules. An available read path cannot certify a write path. List/get/create/update/delete, execution/control, credential handling, and resolution are separate where their authority or transport differs. Do not duplicate request schemas from OpenAPI.

Exceptions and restrictions

Presentation-only state, static developer fixtures, and pre-start/local operator work may use not-applicable for a domain API, with a concrete reason and the existing local path. When a capability combines shared data with presentation, split the operations: browser recents do not exempt resource lookup from API coverage. Promoting local state to a shared feature requires revisiting the entry.

A board-only endpoint is restricted for agent identity, not an automatic exception or a missing API. Cite the enforced policy and record whether the agent can request the authorized human's action and observe its result. An unresolved delegation question remains in Gaps. Company access, a job title, a personal assistant's OAuth grant, or an accepted interaction does not grant board identity. Keep budget, approval, secret and execution authority intact.

Check actual route/service authorization and production tool admission. OpenAPI actor labels and scenario/evaluation tool declarations are supporting metadata; record disagreements rather than using them as proof of access. Native API fallback restrictions, tool field/scope limits, and rollout settings are part of the agent path, even when a legacy agent can call the REST endpoint directly.

Companion file format

Each agent-access-map/<area>.md has an H1, a relative link to its product file, and its feature ID, followed by one H2 backticked local key per product sub-feature. Each capability starts with its full capability ID and contains these fields:

  • Review: baseline or operation-reviewed.
  • API: presence state and exact operation IDs, or a reasoned exception.
  • Agent access: availability state and concrete entry points by surface.
  • Policy: relevant permission and runtime boundaries, with source references.
  • Evidence: evidence state, reviewed commit and sources or executed proof.
  • Verification: allowed/denied assertions and observable result; record what has actually run separately from the proposed recipe.
  • Gaps: missing APIs/paths, discovery drift, unreviewed operations or policy decisions; use none only for the enumerated scope that was reviewed.

For an operation-reviewed capability, use H3 backticked operation IDs and repeat API, Agent access, Policy, Evidence, Verification and Gaps for each operation. Use small operation names such as create, update, read, or run-now. The enclosing capability has Review: operation-reviewed only after its meaningful operations have been enumerated. The following excerpt shows one operation; include the others before using that review label:

## `definition`

Review: `operation-reviewed`.

### `create`

API: `present` — POST /api/companies/{companyId}/routines.
Agent access: `available` — agent REST, CLI routine create and native call_api
under the enabled rollout and active-run/mode gates.
Policy: same company; assigneeAgentId must be the calling agent; cite the
routine authorization and native API policy sources.
Evidence: `source-only` — reviewed commit and source links; no live proof.
Verification: `not-run` — create an owned routine; reject assignment to another
agent; inspect saved configuration, attribution and retry behavior.
Gaps: verify ownership and responsible-user resolution with a permitted agent
context; source presence alone does not qualify this operation.

Keeping the maps synchronized

Add entries only for substantial new features under the feature-map scope rule. Routine fixes, polish, refactors, performance work, and test changes do not require map updates. Correct or remove existing text only when behavior or access changes make it materially inaccurate; keep the correction local to the affected recipe or companion. Preserve IDs across renames where the capability is unchanged; update the affected cross-links together. Indexes discover recipes automatically. An API-only change may update the companion without rewriting unchanged user instructions. Update the corresponding chat scenarios when their request, assumptions or expected outcome changes; use multiple cases for meaningfully different starting conditions rather than treating an API path as conversational coverage.

maintain-verification-skill owns reconciliation of both maps. It follows changed source and authorization, checks real agent reachability, and records product gaps without implementing them during a maintenance pass. The creation skill uses this structure. verify-paperclip consumes the relevant recipes and reports evidence/drift; map editing belongs to maintenance.

Run the structural check after map changes:

node scripts/check-maps.mjs

It checks paired areas/IDs, navigation metadata, required fields, and local references. It does not certify endpoint authorization, production bindings, operation completeness, or live behavior. Source audits must check those against the existing API and tool contracts; avoid a second schema catalog or runtime.

For live access proof, use Paperclip's existing API/runner/MCP fixtures or an owned isolated instance. Use the actual agent identity, target and work mode. Assert the allowed result and relevant denial (another company/private resource, wrong owner, missing grant, invalid run, restricted mode or resolver). Mutations also need persisted state/attribution and retry behavior. Capture evidence using the existing artifact workflow; keep executed run results separate from generated maps/generated/coverage.json, which lists page references.

Local authorship and generated indexes

Change only the recipes, access contracts and stories whose behavior or intent changed. Feature recipes own navigation metadata; stories own small parameters.paperclip annotations. Keep the feature-map README's readable ID index aligned with those sources; it does not register entries for generation. Do not refresh counts in shared READMEs, inventories, fingerprints or review journals.

node scripts/storybook-catalog.mjs validates and generates aggregate navigation, Storybook data, verification routes and the page inventory. All outputs live in ignored maps/generated/, ui/storybook/generated/, and the ignored Storybook preview.tsx wrapper. Start/build and UI typechecking generate their own inputs. A clean merged checkout therefore assembles both branches' changes automatically.

Git provides history and diffs. PRs, issues and CI artifacts retain review/run evidence for the named revision. Capability associations do not create whole-file review dependencies. Keep durable scenario limits in the affected recipe or story.