Add secrets usage guidance

Co-Authored-By: Paperclip <noreply@paperclip.ing>

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:

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>
   );

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");

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,