From 20c0b6186669fbcdbc0fe237427e4b6052dcb381 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Wed, 6 May 2026 14:30:25 -0500
Subject: [PATCH] Add secrets usage guidance

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 docs/deploy/secrets.md               | 24 ++++++++++++++++++++++++
 ui/src/components/EnvVarEditor.tsx   |  3 ++-
 ui/src/pages/Secrets.render.test.tsx |  2 ++
 ui/src/pages/Secrets.tsx             | 22 ++++++++++++++++++++++
 4 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/docs/deploy/secrets.md b/docs/deploy/secrets.md
index 12a0a6ba8fd..6e481c41e12 100644
--- a/docs/deploy/secrets.md
+++ b/docs/deploy/secrets.md
@@ -27,6 +27,30 @@ you bind to an agent as exposed to that agent. Limit blast radius with bindings
 provider supports them, and rotation when an agent transcript or downstream
 system might have captured a value.
 
+## Using Secrets In Runs
+
+Creating a company secret does not automatically create an environment variable.
+You use a secret by binding it into an agent, project, environment, or plugin
+configuration field that supports secret references.
+
+For agent and project environment variables:
+
+1. Create or link the secret in `Company Settings > Secrets`.
+2. Open the agent's `Environment variables` field, or the project's `Env`
+   field.
+3. Add the environment variable key the process expects, such as `GH_TOKEN` or
+   `OPENAI_API_KEY`.
+4. Set the row source to `Secret`, select the stored secret, and choose either
+   `latest` or a pinned version.
+
+At runtime, Paperclip resolves the selected secret server-side and injects the
+resolved value under the env key from the binding row. The stored secret name
+can be human-readable; the binding key is what the agent process receives.
+
+Project env applies to every issue run in that project. When a project env key
+matches an agent env key, the project value wins before Paperclip injects its
+own `PAPERCLIP_*` runtime variables.
+
 ## Default Provider: `local_encrypted`
 
 Secrets are encrypted with a local master key stored at:
diff --git a/ui/src/components/EnvVarEditor.tsx b/ui/src/components/EnvVarEditor.tsx
index fc3f6cd3983..08c7f58b290 100644
--- a/ui/src/components/EnvVarEditor.tsx
+++ b/ui/src/components/EnvVarEditor.tsx
@@ -315,7 +315,8 @@ export function EnvVarEditor({
         );
       })()}
       <p className="text-[11px] text-muted-foreground/60">
-        PAPERCLIP_* variables are injected automatically at runtime.
+        Set KEY to the env var name the process expects, for example GH_TOKEN. Choose Secret to resolve a stored
+        value at run start. PAPERCLIP_* variables are injected automatically.
       </p>
     </div>
   );
diff --git a/ui/src/pages/Secrets.render.test.tsx b/ui/src/pages/Secrets.render.test.tsx
index 12d53e5bd25..29bf8be995b 100644
--- a/ui/src/pages/Secrets.render.test.tsx
+++ b/ui/src/pages/Secrets.render.test.tsx
@@ -177,6 +177,8 @@ describe("Secrets page layout", () => {
     await flushReact();
 
     expect(container.querySelector('input[data-page-search-target="true"][aria-label="Search secrets"]')).not.toBeNull();
+    expect(container.textContent).toContain("Use secrets by binding them to runtime environment variables.");
+    expect(container.textContent).toContain("GH_TOKEN");
     expect(container.querySelectorAll("select")).toHaveLength(0);
     expect(container.textContent).not.toContain("Provider warnings detected");
     expect(container.textContent).not.toContain("2/2 active");
diff --git a/ui/src/pages/Secrets.tsx b/ui/src/pages/Secrets.tsx
index 6e249d7bb2e..9e138a22d92 100644
--- a/ui/src/pages/Secrets.tsx
+++ b/ui/src/pages/Secrets.tsx
@@ -22,6 +22,7 @@ import {
   Trash2,
   X,
   Filter,
+  Info,
 } from "lucide-react";
 import type {
   CompanySecret,
@@ -757,6 +758,7 @@ export function Secrets() {
         />
 
         <TabsContent value="secrets" className="flex min-h-0 flex-1 flex-col gap-3 overflow-hidden">
+          <SecretsHowToUse />
           <div className="flex flex-wrap items-center gap-2">
             <div className="relative w-48 sm:w-64 md:w-80">
               <Search className="pointer-events-none absolute left-2 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground" />
@@ -1436,6 +1438,26 @@ export function Secrets() {
   );
 }
 
+function SecretsHowToUse() {
+  return (
+    <div className="flex items-start gap-2 rounded-md border border-border bg-muted/20 px-3 py-2 text-xs text-muted-foreground">
+      <Info className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+      <div className="space-y-1">
+        <p className="font-medium text-foreground">Use secrets by binding them to runtime environment variables.</p>
+        <p>
+          Create or link a secret here, then open an agent&apos;s Environment variables or a project&apos;s Env field.
+          Add the env key the process expects, for example <code className="font-mono">GH_TOKEN</code>, choose{" "}
+          <span className="font-medium text-foreground">Secret</span>, and select the stored secret version.
+        </p>
+        <p>
+          Paperclip resolves the value server-side when the run starts and injects it as that env var. Project env
+          applies to every issue in the project and overrides agent env on matching keys.
+        </p>
+      </div>
+    </div>
+  );
+}
+
 function SecretsFiltersPopover({
   statusFilter,
   providerFilter,