paperclipai
diff --git a/‎doc/design/COMPONENT-INVENTORY.md‎
Lines changed: 4 additions & 0 deletions b/‎doc/design/COMPONENT-INVENTORY.md‎
Lines changed: 4 additions & 0 deletions
diff --git a/‎docs/api/routines.md‎
Lines changed: 84 additions & 2 deletions b/‎docs/api/routines.md‎
Lines changed: 84 additions & 2 deletions
diff --git a/‎packages/db/src/migrations/0281_true_boom_boom.sql‎
Lines changed: 14 additions & 0 deletions b/‎packages/db/src/migrations/0281_true_boom_boom.sql‎
Lines changed: 14 additions & 0 deletions
@@ -424,3 +424,7 @@ Independently addressable examples live under `Connections/In-task connections`
 - `AnnouncementCard`: image, eyebrow, headline, description, navigation links and dismissal; accepts an announcement and `onDismiss`.
 - `AnnouncementWell`: one app-shell placement that owns eligibility, dismissal sync, modal deferral and toast priority. Use only once in Layout.
 - Preview variants live in `/design-guide` and Storybook under `Announcements/AnnouncementCard`.
+
+## Shared setup wizard (2026-09-19)
+
+`ui/src/components/SetupWizard.tsx` extracts the Slack setup navigation into reusable numbered steps, a portal sidebar, an optional section-menu takeover outlet, and a single-row footer. `SetupWizardSidebarProvider` owns the portal target and takeover lifecycle. Chat exports retain their existing names and defaults for compatibility. The Design Guide demonstrates the components. The production routine trigger wizard and its Storybook previews share the sidebar takeover, navigation, and footer. `routine-triggers/TriggerWizard.tsx`, `TriggerCard.tsx`, and `WebhookFields.tsx` provide the shared trigger setup, compact editable cards, copyable credentials, and agent instructions.
@@ -126,7 +126,11 @@ Three trigger kinds:
 }
 ```
 
-Signing modes: `bearer` (default), `hmac_sha256`. Replay window range: 30–86400 seconds (default 300).
+Signing modes: `bearer` (default), `hmac_sha256`, `github_hmac`, and `none`.
+The replay window applies to `hmac_sha256` only: 30–86400 seconds (default 300).
+Creating a webhook returns `trigger` and one-time `secretMaterial` containing
+`webhookUrl` and `webhookSecret`. Save the secret before closing the dialog.
+Routine details retain the URL; rotate the secret if its value is lost.
 
 **API** — fires only when called explicitly via [Manual Run](#manual-run):
 
@@ -184,7 +188,68 @@ Fires a run immediately, bypassing the schedule. Concurrency policy still applie
 POST /api/routine-triggers/public/{publicId}/fire
 ```
 
-Fires a webhook trigger from an external system. Requires a valid `Authorization` or `X-Paperclip-Signature` + `X-Paperclip-Timestamp` header pair matching the trigger's signing mode.
+Fires a webhook trigger from an external system without a Paperclip login. Send
+`Content-Type: application/json` and a JSON object. The trigger authenticates the
+request using its own secret; an agent or board API key is not a substitute.
+
+| Mode | Headers and signature |
+|------|-----------------------|
+| `bearer` | `Authorization: Bearer <webhookSecret>` |
+| `hmac_sha256` | `X-Paperclip-Timestamp` (Unix seconds or milliseconds) and `X-Paperclip-Signature: sha256=<hex>`; HMAC-SHA256 over the timestamp string, a dot, and the exact body bytes |
+| `github_hmac` | `X-Hub-Signature-256: sha256=<hex>`; HMAC-SHA256 over the exact body bytes, without a timestamp. `X-Paperclip-Signature` is also accepted. Configure GitHub to send JSON. |
+| `none` | No signature. Anyone with the generated URL can fire the trigger; keep it private. |
+
+For a bearer trigger:
+
+```sh
+curl --fail-with-body "$WEBHOOK_URL" \
+  -H "Authorization: Bearer $WEBHOOK_SECRET" \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: deployment-123' \
+  --data-binary '{"event":"deployment","variables":{"environment":"staging"}}'
+```
+
+For a timestamped HMAC trigger, sign and send the same bytes:
+
+```js
+import { createHmac } from "node:crypto";
+const body = JSON.stringify({ variables: { environment: "staging" } });
+const timestamp = String(Math.floor(Date.now() / 1000));
+const signature = createHmac("sha256", process.env.WEBHOOK_SECRET)
+  .update(`${timestamp}.`).update(body).digest("hex");
+const response = await fetch(process.env.WEBHOOK_URL, {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "X-Paperclip-Timestamp": timestamp,
+    "X-Paperclip-Signature": `sha256=${signature}`,
+  },
+  body,
+});
+console.log(response.status, await response.json());
+```
+
+`202` returns the routine run, including its status and linked task. The task
+runs asynchronously, so acceptance does not mean the agent has finished.
+Concurrency policy can coalesce or skip a delivery while work is active.
+Payload fields or a nested `variables` object supply declared routine variables;
+nested values take precedence. The full payload is retained in run history.
+
+For bearer, GitHub HMAC, and unsigned triggers, send a stable `Idempotency-Key`
+when retrying a delivery to receive the original run without creating another
+task. Timestamped HMAC rejects an identical signed delivery with `409`, even
+inside the replay window; stale timestamps and invalid secrets/signatures return
+`401`. Disabled triggers and paused/archived routines return `409`. Missing
+required variables return `422`; non-JSON media types return `415` and invalid
+JSON objects return `400`. Rotating a secret immediately invalidates the old one.
+
+Cloud installations use their canonical public origin for generated URLs.
+Self-hosted installations should set `PAPERCLIP_PUBLIC_URL` to their HTTPS
+origin. The reverse proxy must forward this POST endpoint and its authorization,
+signature, timestamp, and idempotency headers without requiring a browser login.
+For local HTTPS testing, proxy an isolated test instance through Tailscale Serve;
+use Funnel only if the sender is outside the tailnet. Existing routine and agent
+execution controls still apply, including the isolated-worktree execution gate.
 
 ## List Runs
 
@@ -216,3 +281,20 @@ active -> paused -> active
 ```
 
 Archived routines do not fire and cannot be reactivated.
+
+## Routine detail navigation
+
+The routine detail page keeps **Runs** and **Activity** in the routine sidebar. Runs lists the execution issues for that routine using the shared issue list, including issue status, priority, assignee, and search controls. Activity shows the routine, trigger, and run event timeline without leaving the routine page. The overview links to these same local tabs.
+
+
+## Webhook setup and connection checks
+
+Create a webhook trigger with `setupPending: true` to configure it safely. While setup is pending, authenticated deliveries return `202` with `{ "status": "test_received", "test": true, "routineStarted": false, "linkedIssueId": null }`. They never create a routine run, task, or agent wakeup. This state survives refreshes and server restarts, and connection checks also work while the routine is paused. Invalid authentication still returns `401`.
+
+Routine detail exposes `setupPending` and `lastWebhookDelivery` (`status`, `receivedAt`, and `test`) so the wizard can show live connection feedback. The secret is only returned at creation or rotation; it is never stored in browser draft storage or included in routine detail.
+
+Finish setup with `PATCH /api/routine-triggers/{id}` and `{ "setupPending": false }`. Future deliveries use normal routine dispatch and still respect the routine's enabled state. Test events are not dispatched on activation. Retries with the same `Idempotency-Key`, GitHub `X-GitHub-Delivery`, or timestamp-HMAC replay key remain test receipts after activation. Send a unique delivery ID per event so a sender's retries can be recognized. Requests without a delivery ID are new events after activation.
+
+For compatibility, API-created triggers without `setupPending: true` are immediately live. Completed triggers cannot be returned to setup mode. Checking a previously enabled webhook observes real deliveries and can start the routine; the management UI explains this difference.
+
+Trigger cards support removal with Undo. `PATCH` with `{ "archived": true }` excludes a trigger from routine detail and scheduling, and rejects its webhook deliveries. Setting `archived` back to `false` restores the same URL and credentials. `DELETE` remains the permanent deletion API.
@@ -0,0 +1,14 @@
+CREATE TABLE IF NOT EXISTS "routine_webhook_test_receipts" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"trigger_id" uuid NOT NULL,
+	"delivery_key_hash" text NOT NULL,
+	"received_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "routine_triggers" ADD COLUMN IF NOT EXISTS "setup_pending" boolean DEFAULT false NOT NULL;--> statement-breakpoint
+ALTER TABLE "routine_triggers" ADD COLUMN IF NOT EXISTS "archived" boolean DEFAULT false NOT NULL;--> statement-breakpoint
+ALTER TABLE "routine_triggers" ADD COLUMN IF NOT EXISTS "last_webhook_delivery" jsonb;--> statement-breakpoint
+DO $$ BEGIN ALTER TABLE "routine_webhook_test_receipts" ADD CONSTRAINT "routine_webhook_test_receipts_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action; EXCEPTION WHEN duplicate_object THEN NULL; END $$;--> statement-breakpoint
+DO $$ BEGIN ALTER TABLE "routine_webhook_test_receipts" ADD CONSTRAINT "routine_webhook_test_receipts_trigger_id_routine_triggers_id_fk" FOREIGN KEY ("trigger_id") REFERENCES "public"."routine_triggers"("id") ON DELETE cascade ON UPDATE no action; EXCEPTION WHEN duplicate_object THEN NULL; END $$;--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "routine_webhook_test_receipts_delivery_uq" ON "routine_webhook_test_receipts" USING btree ("trigger_id","delivery_key_hash");