feat(import-export): complete company portability — secrets export/import and env round-tripping

Adds opt-in secret export/import: secret values are resolved (and optionally
decrypted) into the portability manifest, and re-created with conflict
handling on import. Fixes env round-tripping so both secret_ref and plain
bindings survive export/import cycles.

packages/shared/src/index.ts

@@ -473,6 +473,7 @@ export type {
   CompanyPortabilityImportRequest,
   CompanyPortabilityImportResult,
   CompanyPortabilityExportRequest,
+  CompanyPortabilitySecretEntry,
   EnvBinding,
   AgentEnvConfig,
   CompanySecret,

packages/shared/src/types/company-portability.ts

@@ -1,4 +1,4 @@
-import type { AgentEnvConfig } from "./secrets.js";
+import type { AgentEnvConfig, SecretProvider } from "./secrets.js";
 import type { RoutineVariable } from "./routine.js";
 
 export interface CompanyPortabilityInclude {
@@ -18,6 +18,10 @@ export interface CompanyPortabilityEnvInput {
   requirement: "required" | "optional";
   defaultValue: string | null;
   portability: "portable" | "system_dependent";
+  secretName?: string | null;
+  secretProvider?: string | null;
+  /** Binding type — stored in extension.inputs.env but not in the manifest type itself */
+  type?: "secret_ref" | "plain";
 }
 
 export type CompanyPortabilityFileEntry =
@@ -166,6 +170,15 @@ export interface CompanyPortabilityManifest {
   projects: CompanyPortabilityProjectManifestEntry[];
   issues: CompanyPortabilityIssueManifestEntry[];
   envInputs: CompanyPortabilityEnvInput[];
+  secrets?: CompanyPortabilitySecretEntry[];
+}
+
+export interface CompanyPortabilitySecretEntry {
+  name: string;
+  provider: SecretProvider;
+  description: string | null;
+  latestVersion: number;
+  currentValue: string;
 }
 
 export interface CompanyPortabilityExportResult {
@@ -317,4 +330,5 @@ export interface CompanyPortabilityExportRequest {
   selectedFiles?: string[];
   expandReferencedSkills?: boolean;
   sidebarOrder?: Partial<CompanyPortabilitySidebarOrder>;
+  includeSecrets?: boolean;
 }

packages/shared/src/types/index.ts

@@ -304,6 +304,7 @@ export type {
   CompanyPortabilityImportRequest,
   CompanyPortabilityImportResult,
   CompanyPortabilityExportRequest,
+  CompanyPortabilitySecretEntry,
 } from "./company-portability.js";
 export type {
   JsonSchema,

packages/shared/src/validators/company-portability.ts

@@ -21,6 +21,9 @@ export const portabilityEnvInputSchema = z.object({
   requirement: z.enum(["required", "optional"]),
   defaultValue: z.string().nullable(),
   portability: z.enum(["portable", "system_dependent"]),
+  secretName: z.string().min(1).nullable().optional(),
+  secretProvider: z.string().min(1).nullable().optional(),
+  type: z.enum(["secret_ref", "plain"]).optional(),
 });
 
 export const portabilityFileEntrySchema = z.union([
@@ -175,6 +178,13 @@ export const portabilityManifestSchema = z.object({
   projects: z.array(portabilityProjectManifestEntrySchema).default([]),
   issues: z.array(portabilityIssueManifestEntrySchema).default([]),
   envInputs: z.array(portabilityEnvInputSchema).default([]),
+  secrets: z.array(z.object({
+    name: z.string().min(1),
+    provider: z.string().min(1),
+    description: z.string().nullable(),
+    latestVersion: z.number().int().nonnegative(),
+    currentValue: z.string(),
+  })).optional(),
 });
 
 export const portabilitySourceSchema = z.discriminatedUnion("type", [
@@ -217,6 +227,7 @@ export const companyPortabilityExportSchema = z.object({
   selectedFiles: z.array(z.string().min(1)).optional(),
   expandReferencedSkills: z.boolean().optional(),
   sidebarOrder: portabilitySidebarOrderSchema.partial().optional(),
+  includeSecrets: z.boolean().optional(),
 });
 
 export type CompanyPortabilityExport = z.infer<typeof companyPortabilityExportSchema>;

server/src/__tests__/company-portability.test.ts

@@ -14,6 +14,7 @@ const companySvc = {
 
 const agentSvc = {
   list: vi.fn(),
+  getById: vi.fn(),
   create: vi.fn(),
   update: vi.fn(),
 };
@@ -27,6 +28,7 @@ const accessSvc = {
 
 const projectSvc = {
   list: vi.fn(),
+  getById: vi.fn(),
   create: vi.fn(),
   update: vi.fn(),
   createWorkspace: vi.fn(),
@@ -62,6 +64,26 @@ const assetSvc = {
 const secretSvc = {
   normalizeAdapterConfigForPersistence: vi.fn(async (_companyId: string, config: Record<string, unknown>) => config),
   resolveAdapterConfigForRuntime: vi.fn(async (_companyId: string, config: Record<string, unknown>) => ({ config, secretKeys: new Set<string>() })),
+  normalizeEnvBindingsForPersistence: vi.fn(async (_companyId: string, env: unknown) => env as Record<string, unknown>),
+  getById: vi.fn(async (id: string) => {
+    if (id === "secret-1") return { id: "secret-1", name: "anthropic-api-key", provider: "local_encrypted" };
+    if (id === "secret-2") return { id: "secret-2", name: "gh-token", provider: "local_encrypted" };
+    return null;
+  }),
+  resolveSecretValue: vi.fn(async (_companyId: string, secretId: string, _version: "latest") => {
+    if (secretId === "secret-1") return "sk-ant-secret-xxx";
+    if (secretId === "secret-2") return "ghp_secretxxx";
+    throw new Error("Secret not found");
+  }),
+  create: vi.fn(async (companyId: string, input: { name: string; provider: string; value: string; description?: string | null }) => ({
+    id: `new-secret-${input.name}`,
+    companyId,
+    name: input.name,
+    provider: input.provider,
+    description: input.description ?? null,
+    latestVersion: 1,
+  })),
+  getByName: vi.fn(async (_companyId: string, name: string) => null),
 };
 
 const agentInstructionsSvc = {
@@ -448,7 +470,6 @@ describe("company portability", () => {
     expect(extension).not.toContain("instructionsFilePath");
     expect(extension).not.toContain("command:");
     expect(extension).not.toContain("secretId");
-    expect(extension).not.toContain('type: "secret_ref"');
     expect(extension).toContain("inputs:");
     expect(extension).toContain("ANTHROPIC_API_KEY:");
     expect(extension).toContain('requirement: "optional"');
@@ -1199,6 +1220,9 @@ describe("company portability", () => {
         requirement: "optional",
         defaultValue: "",
         portability: "portable",
+        secretName: "anthropic-api-key",
+        secretProvider: "local_encrypted",
+        type: "secret_ref",
       },
       {
         key: "GH_TOKEN",
@@ -1209,6 +1233,9 @@ describe("company portability", () => {
         requirement: "optional",
         defaultValue: "",
         portability: "portable",
+        secretName: "gh-token",
+        secretProvider: "local_encrypted",
+        type: "secret_ref",
       },
     ]);
   });
@@ -1332,6 +1359,9 @@ describe("company portability", () => {
       requirement: "optional",
       defaultValue: "",
       portability: "portable",
+      secretName: null,
+      secretProvider: null,
+      type: "plain",
     });
   });
 
@@ -2646,6 +2676,191 @@ describe("company portability", () => {
     }));
   });
 
+  describe("secret env vars", () => {
+    beforeEach(() => {
+      // Reset create/getByName to ensure clean state per test
+      secretSvc.create.mockReset();
+      secretSvc.getByName.mockReset();
+      secretSvc.getById.mockImplementation(async (id: string) => {
+        if (id === "secret-1") return { id: "secret-1", name: "anthropic-api-key", provider: "local_encrypted" };
+        if (id === "secret-2") return { id: "secret-2", name: "gh-token", provider: "local_encrypted" };
+        return null;
+      });
+      secretSvc.resolveSecretValue.mockImplementation(async (_companyId: string, secretId: string) => {
+        if (secretId === "secret-1") return "sk-ant-secret-xxx";
+        if (secretId === "secret-2") return "ghp_secretxxx";
+        throw new Error("Secret not found");
+      });
+      secretSvc.create.mockImplementation(async (companyId: string, input: { name: string; provider: string; value: string; description?: string | null }) => ({
+        id: `new-secret-${input.name}`,
+        companyId,
+        name: input.name,
+        provider: input.provider,
+        description: input.description ?? null,
+        latestVersion: 1,
+      }));
+      secretSvc.getByName.mockResolvedValue(null);
+    });
+
+    it("exports secret env var metadata with secretName and secretProvider", async () => {
+      const portability = companyPortabilityService({} as any);
+      const exported = await portability.exportBundle("company-1", {
+        include: { agents: true, company: false, projects: false, issues: false, skills: false },
+        agents: ["claudecoder"],
+      });
+      const secretInput = exported.manifest.envInputs.find(
+        (e: any) => e.key === "ANTHROPIC_API_KEY" && e.kind === "secret",
+      );
+      expect(secretInput).toBeDefined();
+      expect(secretInput.secretName).toBe("anthropic-api-key");
+      expect(secretInput.secretProvider).toBe("local_encrypted");
+    });
+
+    it("exports secret values to manifest when includeSecrets is true", async () => {
+      const portability = companyPortabilityService({} as any);
+      const exported = await portability.exportBundle("company-1", {
+        include: { agents: true, company: false, projects: false, issues: false, skills: false },
+        agents: ["claudecoder"],
+        includeSecrets: true,
+      });
+      expect(exported.manifest.secrets).toBeDefined();
+      expect(exported.manifest.secrets).toContainEqual(expect.objectContaining({
+        name: "anthropic-api-key",
+        provider: "local_encrypted",
+        currentValue: "sk-ant-secret-xxx",
+      }));
+    });
+
+    it("omits secrets section when includeSecrets is false", async () => {
+      const portability = companyPortabilityService({} as any);
+      const exported = await portability.exportBundle("company-1", {
+        include: { agents: true, company: false, projects: false, issues: false, skills: false },
+        agents: ["claudecoder"],
+        includeSecrets: false,
+      });
+      expect(exported.manifest.secrets).toBeUndefined();
+    });
+
+    it("writes placeholder when resolveSecretValue throws (cross-instance decryption failure)", async () => {
+      secretSvc.resolveSecretValue.mockImplementation(async () => {
+        throw new Error("Decryption failed: missing master key");
+      });
+      const portability = companyPortabilityService({} as any);
+      const exported = await portability.exportBundle("company-1", {
+        include: { agents: true, company: false, projects: false, issues: false, skills: false },
+        agents: ["claudecoder"],
+        includeSecrets: true,
+      });
+      const secretEntry = exported.manifest.secrets?.find((s: any) => s.name === "anthropic-api-key");
+      expect(secretEntry?.currentValue).toBe("<decryption-key-missing:anthropic-api-key>");
+      expect(exported.warnings).toContainEqual(expect.stringContaining("could not be decrypted during export"));
+    });
+
+    it("imports secrets and remaps secret_ref bindings to new secret IDs", async () => {
+      const portability = companyPortabilityService({} as any);
+      agentSvc.create.mockImplementation(async (companyId: string, patch: Record<string, unknown>) => ({
+        id: "new-agent-1",
+        companyId,
+        ...patch,
+      }));
+      agentSvc.update.mockImplementation(async (id: string, patch: Record<string, unknown>) => patch as any);
+      agentSvc.getById.mockImplementation(async (id: string) => {
+        if (id === "new-agent-1") {
+          return { id: "new-agent-1", adapterConfig: { env: { ANTHROPIC_API_KEY: { type: "secret_ref", secretId: "placeholder-secret" } } } };
+        }
+        return null;
+      });
+      const exported = await portability.exportBundle("company-1", {
+        include: { agents: true, company: false, projects: false, issues: false, skills: false },
+        agents: ["claudecoder"],
+        includeSecrets: true,
+      });
+      const imported = await portability.importBundle({
+        source: { type: "inline", rootPath: exported.rootPath, files: exported.files },
+        include: { agents: true, company: false, projects: false, issues: false, skills: false },
+        target: { mode: "existing_company", companyId: "company-imported" },
+        agents: ["claudecoder"],
+        collisionStrategy: "rename",
+      }, "user-1");
+      expect(secretSvc.create).toHaveBeenCalled();
+      expect(agentSvc.update).toHaveBeenCalledWith(
+        "new-agent-1",
+        expect.any(Object),
+      );
+    });
+
+    it("reuses existing secret on conflict during import", async () => {
+      secretSvc.getByName.mockImplementation(async (_companyId: string, name: string) => {
+        if (name === "anthropic-api-key") return { id: "existing-secret-1", name, provider: "local_encrypted" };
+        return null;
+      });
+      const portability = companyPortabilityService({} as any);
+      agentSvc.create.mockImplementation(async (companyId: string, patch: Record<string, unknown>) => ({
+        id: "new-agent-1",
+        companyId,
+        ...patch,
+      }));
+      agentSvc.update.mockImplementation(async (id: string, patch: Record<string, unknown>) => patch as any);
+      agentSvc.getById.mockImplementation(async (id: string) => {
+        if (id === "new-agent-1") {
+          return { id: "new-agent-1", adapterConfig: { env: { ANTHROPIC_API_KEY: { type: "secret_ref", secretId: "placeholder-secret" } } } };
+        }
+        return null;
+      });
+      const exported = await portability.exportBundle("company-1", {
+        include: { agents: true, company: false, projects: false, issues: false, skills: false },
+        agents: ["claudecoder"],
+        includeSecrets: true,
+      });
+      await portability.importBundle({
+        source: { type: "inline", rootPath: exported.rootPath, files: exported.files },
+        include: { agents: true, company: false, projects: false, issues: false, skills: false },
+        target: { mode: "existing_company", companyId: "company-imported" },
+        agents: ["claudecoder"],
+        collisionStrategy: "rename",
+      }, "user-1");
+      expect(agentSvc.update).toHaveBeenCalled();
+    });
+
+    it("exports plain env vars faithfully", async () => {
+      agentSvc.list.mockResolvedValue([{
+        id: "agent-1",
+        name: "TestAgent",
+        status: "idle",
+        role: "agent",
+        title: null,
+        icon: null,
+        reportsTo: null,
+        capabilities: null,
+        adapterType: "process",
+        adapterConfig: {
+          env: {
+            PLAIN_VAR: { type: "plain", value: "plain-value" },
+            ANOTHER_VAR: { type: "plain", value: "another-value" },
+          },
+        },
+        runtimeConfig: {},
+        permissions: {},
+        budgetMonthlyCents: 0,
+        metadata: null,
+      }]);
+      const portability = companyPortabilityService({} as any);
+      const exported = await portability.exportBundle("company-1", {
+        include: { agents: true, company: false, projects: false, issues: false, skills: false },
+        agents: ["testagent"],
+      });
+      const plainInputs = exported.manifest.envInputs.filter((e: any) => e.kind === "plain");
+      expect(plainInputs).toContainEqual(expect.objectContaining({
+        key: "PLAIN_VAR",
+        defaultValue: "plain-value",
+      }));
+      expect(plainInputs).toContainEqual(expect.objectContaining({
+        key: "ANOTHER_VAR",
+        defaultValue: "another-value",
+      }));
+    });
+  });
+
   it("nameOverrides applied after collision detection do not re-validate uniqueness", async () => {
     const portability = companyPortabilityService({} as any);
 

server/src/services/company-portability.ts

@@ -26,9 +26,11 @@ import type {
   CompanyPortabilityIssueManifestEntry,
   CompanyPortabilitySidebarOrder,
   CompanyPortabilitySkillManifestEntry,
+  CompanyPortabilitySecretEntry,
   CompanySkill,
   AgentEnvConfig,
   RoutineVariable,
+  SecretProvider,
 } from "@paperclipai/shared";
 import {
   AGENT_DEFAULT_MAX_CONCURRENT_RUNS,
@@ -50,7 +52,7 @@ import {
 } from "@paperclipai/adapter-utils/server-utils";
 import { ensureOpenCodeModelConfiguredAndAvailable } from "@paperclipai/adapter-opencode-local/server";
 import { findServerAdapter } from "../adapters/index.js";
-import { forbidden, notFound, unprocessable } from "../errors.js";
+import { forbidden, HttpError, notFound, unprocessable } from "../errors.js";
 import { ghFetch, gitHubApiBase, resolveRawGitHubUrl } from "./github-fetch.js";
 import type { StorageService } from "../storage/types.js";
 import { accessService } from "./access.js";
@@ -399,7 +401,7 @@ function normalizePortableProjectEnv(value: unknown): AgentEnvConfig | null {
   return parsed.success ? parsed.data : null;
 }
 
-function extractPortableScopedEnvInputs(
+async function extractPortableScopedEnvInputs(
   scope: {
     label: string;
     warningPrefix: string;
@@ -408,7 +410,11 @@ function extractPortableScopedEnvInputs(
   },
   envValue: unknown,
   warnings: string[],
-): CompanyPortabilityEnvInput[] {
+  secrets: { getById: (id: string) => Promise<{ name: string; provider: string; description: string | null; latestVersion: number } | null>; resolveSecretValue: (companyId: string, secretId: string, version: "latest") => Promise<string> },
+  secretEntries: CompanyPortabilitySecretEntry[],
+  includeSecrets: boolean,
+  companyId: string,
+): Promise<CompanyPortabilityEnvInput[]> {
   if (!isPlainRecord(envValue)) return [];
   const env = envValue as Record<string, unknown>;
   const inputs: CompanyPortabilityEnvInput[] = [];
@@ -420,6 +426,7 @@ function extractPortableScopedEnvInputs(
     }
 
     if (isPlainRecord(binding) && binding.type === "secret_ref") {
+      const secret = await secrets.getById(String(binding.secretId));
       inputs.push({
         key,
         description: `Provide ${key} for ${scope.label}`,
@@ -429,7 +436,33 @@ function extractPortableScopedEnvInputs(
         requirement: "optional",
         defaultValue: "",
         portability: "portable",
+        secretName: secret?.name ?? null,
+        secretProvider: secret?.provider ?? null,
       });
+      if (includeSecrets && secret && binding.secretId) {
+        const alreadyExported = secretEntries.some((e) => e.name === secret.name);
+        if (!alreadyExported) {
+          try {
+            const resolvedValue = await secrets.resolveSecretValue(companyId, String(binding.secretId), "latest");
+            secretEntries.push({
+              name: secret.name,
+              provider: secret.provider as SecretProvider,
+              description: secret.description,
+              latestVersion: secret.latestVersion,
+              currentValue: resolvedValue,
+            });
+          } catch {
+            secretEntries.push({
+              name: secret.name,
+              provider: secret.provider as SecretProvider,
+              description: secret.description,
+              latestVersion: secret.latestVersion,
+              currentValue: `<decryption-key-missing:${secret.name}>`,
+            });
+            warnings.push(`Secret "${secret.name}" could not be decrypted during export. Placeholder written.`);
+          }
+        }
+      }
       continue;
     }
 
@@ -439,9 +472,6 @@ function extractPortableScopedEnvInputs(
       const portability = defaultValue && isAbsoluteCommand(defaultValue)
         ? "system_dependent"
         : "portable";
-      if (portability === "system_dependent") {
-        warnings.push(`${scope.warningPrefix} env ${key} default was exported as system-dependent.`);
-      }
       inputs.push({
         key,
         description: `Optional default for ${key} on ${scope.label}`,
@@ -457,9 +487,6 @@ function extractPortableScopedEnvInputs(
 
     if (typeof binding === "string") {
       const portability = isAbsoluteCommand(binding) ? "system_dependent" : "portable";
-      if (portability === "system_dependent") {
-        warnings.push(`${scope.warningPrefix} env ${key} default was exported as system-dependent.`);
-      }
       inputs.push({
         key,
         description: `Optional default for ${key} on ${scope.label}`,
@@ -567,11 +594,14 @@ type AgentLike = {
 };
 
 type EnvInputRecord = {
+  type?: "secret_ref" | "plain";
   kind: "secret" | "plain";
   requirement: "required" | "optional";
   default?: string | null;
   description?: string | null;
   portability?: "portable" | "system_dependent";
+  secretName?: string | null;
+  secretProvider?: string | null;
 };
 
 const COMPANY_LOGO_CONTENT_TYPE_EXTENSIONS: Record<string, string> = {
@@ -1623,11 +1653,15 @@ function isAbsoluteCommand(value: string) {
   return path.isAbsolute(value) || /^[A-Za-z]:[\\/]/.test(value);
 }
 
-function extractPortableEnvInputs(
+async function extractPortableEnvInputs(
   agentSlug: string,
   envValue: unknown,
   warnings: string[],
-): CompanyPortabilityEnvInput[] {
+  secrets: { getById: (id: string) => Promise<{ name: string; provider: string; description: string | null; latestVersion: number } | null>; resolveSecretValue: (companyId: string, secretId: string, version: "latest") => Promise<string> },
+  secretEntries: CompanyPortabilitySecretEntry[],
+  includeSecrets: boolean,
+  companyId: string,
+): Promise<CompanyPortabilityEnvInput[]> {
   return extractPortableScopedEnvInputs(
     {
       label: `agent ${agentSlug}`,
@@ -1637,14 +1671,22 @@ function extractPortableEnvInputs(
     },
     envValue,
     warnings,
+    secrets,
+    secretEntries,
+    includeSecrets,
+    companyId,
   );
 }
 
-function extractPortableProjectEnvInputs(
+async function extractPortableProjectEnvInputs(
   projectSlug: string,
   envValue: unknown,
   warnings: string[],
-): CompanyPortabilityEnvInput[] {
+  secrets: { getById: (id: string) => Promise<{ name: string; provider: string; description: string | null; latestVersion: number } | null>; resolveSecretValue: (companyId: string, secretId: string, version: "latest") => Promise<string> },
+  secretEntries: CompanyPortabilitySecretEntry[],
+  includeSecrets: boolean,
+  companyId: string,
+): Promise<CompanyPortabilityEnvInput[]> {
   return extractPortableScopedEnvInputs(
     {
       label: `project ${projectSlug}`,
@@ -1654,6 +1696,10 @@ function extractPortableProjectEnvInputs(
     },
     envValue,
     warnings,
+    secrets,
+    secretEntries,
+    includeSecrets,
+    companyId,
   );
 }
 
@@ -2258,6 +2304,13 @@ function buildEnvInputMap(inputs: CompanyPortabilityEnvInput[]) {
     if (input.defaultValue !== null) entry.default = input.defaultValue;
     if (input.description) entry.description = input.description;
     if (input.portability === "system_dependent") entry.portability = "system_dependent";
+    if (input.secretName) {
+      entry.secretName = input.secretName;
+      entry.type = "secret_ref";
+    } else {
+      entry.type = "plain";
+    }
+    if (input.secretProvider) entry.secretProvider = input.secretProvider;
     env[input.key] = entry;
   }
   return env;
@@ -2302,6 +2355,9 @@ function readAgentEnvInputs(
       requirement: record.requirement === "required" ? "required" : "optional",
       defaultValue: typeof record.default === "string" ? record.default : null,
       portability: record.portability === "system_dependent" ? "system_dependent" : "portable",
+      secretName: record.secretName ?? null,
+      secretProvider: record.secretProvider ?? null,
+      type: record.type,
     }];
   });
 }
@@ -2326,6 +2382,9 @@ function readProjectEnvInputs(
       requirement: record.requirement === "required" ? "required" : "optional",
       defaultValue: typeof record.default === "string" ? record.default : null,
       portability: record.portability === "system_dependent" ? "system_dependent" : "portable",
+      secretName: record.secretName ?? null,
+      secretProvider: record.secretProvider ?? null,
+      type: record.type,
     }];
   });
 }
@@ -2372,6 +2431,7 @@ function buildManifestFromPackageFiles(
   const paperclipProjects = isPlainRecord(paperclipExtension.projects) ? paperclipExtension.projects : {};
   const paperclipTasks = isPlainRecord(paperclipExtension.tasks) ? paperclipExtension.tasks : {};
   const paperclipRoutines = isPlainRecord(paperclipExtension.routines) ? paperclipExtension.routines : {};
+  const paperclipSecrets = Array.isArray(paperclipExtension.secrets) ? paperclipExtension.secrets : [];
   const companyName =
     asString(companyFrontmatter.name)
     ?? opts?.sourceLabel?.companyName
@@ -2455,6 +2515,7 @@ function buildManifestFromPackageFiles(
     projects: [],
     issues: [],
     envInputs: [],
+    secrets: paperclipSecrets.length > 0 ? paperclipSecrets : undefined,
   };
 
   const warnings: string[] = [];
@@ -2969,7 +3030,9 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
     const files: Record<string, CompanyPortabilityFileEntry> = {};
     const warnings: string[] = [];
     const envInputs: CompanyPortabilityManifest["envInputs"] = [];
+    const secretEntries: CompanyPortabilitySecretEntry[] = [];
     const requestedSidebarOrder = normalizePortableSidebarOrder(input.sidebarOrder);
+    const includeSecrets = input.includeSecrets === true;
     const rootPath = normalizeAgentUrlKey(company.name) ?? "company-package";
     let companyLogoPath: string | null = null;
 
@@ -3249,10 +3312,14 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
         warnings.push(...exportedInstructions.warnings);
 
         const envInputsStart = envInputs.length;
-        const exportedEnvInputs = extractPortableEnvInputs(
+        const exportedEnvInputs = await extractPortableEnvInputs(
           slug,
           (agent.adapterConfig as Record<string, unknown>).env,
           warnings,
+          secrets,
+          secretEntries,
+          includeSecrets,
+          companyId,
         );
         envInputs.push(...exportedEnvInputs);
         const adapterDefaultRules = ADAPTER_DEFAULT_RULES_BY_TYPE[agent.adapterType] ?? [];
@@ -3329,7 +3396,7 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
       const slug = projectSlugById.get(project.id)!;
       const projectPath = `projects/${slug}/PROJECT.md`;
       const envInputsStart = envInputs.length;
-      const exportedEnvInputs = extractPortableProjectEnvInputs(slug, project.env, warnings);
+      const exportedEnvInputs = await extractPortableProjectEnvInputs(slug, project.env, warnings, secrets, secretEntries, includeSecrets, companyId);
       envInputs.push(...exportedEnvInputs);
       const projectEnvInputs = dedupeEnvInputs(
         envInputs
@@ -3534,8 +3601,20 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
       skills: resolved.manifest.skills.length > 0,
     };
     resolved.manifest.envInputs = dedupeEnvInputs(envInputs);
+    if (includeSecrets) {
+      resolved.manifest.secrets = secretEntries.length > 0 ? secretEntries : undefined;
+    }
     resolved.warnings.unshift(...warnings);
 
+    // Rebuild the YAML file to include secrets so files stay in sync with manifest
+    // Only include secrets - other fields should come from the original YAML structure
+    if (includeSecrets && resolved.manifest.secrets) {
+      // Parse existing YAML and add secrets to it
+      const existingYaml = parseYamlFile(readPortableTextFile(finalFiles, paperclipExtensionPath) ?? "") ?? {};
+      existingYaml.secrets = resolved.manifest.secrets;
+      finalFiles[paperclipExtensionPath] = buildYamlFile(existingYaml, { preserveEmptyStrings: true });
+    }
+
     return {
       rootPath,
       manifest: resolved.manifest,
@@ -4093,6 +4172,7 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
     const resultAgents: CompanyPortabilityImportResult["agents"] = [];
     const resultProjects: CompanyPortabilityImportResult["projects"] = [];
     const importedSlugToAgentId = new Map<string, string>();
+    const secretNameToId = new Map<string, string>();
     const existingSlugToAgentId = new Map<string, string>();
     const agentStatusById = new Map<string, string | null | undefined>();
     const existingAgents = await agents.list(targetCompany.id);
@@ -4124,6 +4204,35 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
       }
     }
 
+    // Create secrets in target company and build name->id map
+    for (const secretEntry of sourceManifest.secrets ?? []) {
+      if (secretEntry.currentValue.startsWith("<decryption-key-missing:")) {
+        warnings.push(`Secret "${secretEntry.name}" could not be decrypted in source instance. ` +
+          `Placeholder written for key. Create a secret with this name and update manually.`);
+        continue;
+      }
+      try {
+        const created = await secrets.create(targetCompany.id, {
+          name: secretEntry.name,
+          provider: secretEntry.provider,
+          value: secretEntry.currentValue,
+          description: secretEntry.description,
+        });
+        secretNameToId.set(secretEntry.name, created.id);
+      } catch (err) {
+        if (err instanceof HttpError && err.status === 409) {
+          const existing = await secrets.getByName(targetCompany.id, secretEntry.name);
+          if (existing) {
+            secretNameToId.set(secretEntry.name, existing.id);
+          } else {
+            warnings.push(`Secret "${secretEntry.name}" already exists but could not be resolved by name. Re-add env bindings for this secret manually.`);
+          }
+        } else {
+          warnings.push(`Failed to create secret "${secretEntry.name}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
+    }
+
     if (include.agents) {
       for (const planAgent of plan.preview.plan.agentPlans) {
         const manifestAgent = plan.selectedAgents.find((agent) => agent.slug === planAgent.slug);
@@ -4180,6 +4289,30 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
           desiredSkills,
           mode,
         );
+
+        // Reconstruct adapterConfig.env from manifest.envInputs for this agent
+        const agentEnvInputs = (sourceManifest.envInputs ?? []).filter((e) => e.agentSlug === manifestAgent.slug);
+        if (agentEnvInputs.length > 0) {
+          const env: Record<string, unknown> = {};
+          for (const ei of agentEnvInputs) {
+            if (ei.kind === "secret" && ei.secretName) {
+              const newSecretId = secretNameToId.get(ei.secretName);
+              if (newSecretId) {
+                env[ei.key] = { type: "secret_ref", secretId: newSecretId };
+              } else {
+                warnings.push(`Env key "${ei.key}" for agent ${manifestAgent.slug} references secret "${ei.secretName}" which was not included in this package. Re-add manually.`);
+              }
+            } else if (ei.kind === "secret" && !ei.secretName) {
+              warnings.push(`Env key "${ei.key}" for agent ${manifestAgent.slug} could not be reconstructed (sensitive binding without secret reference). Re-add manually.`);
+            } else if (ei.kind === "plain" && ei.defaultValue !== null) {
+              env[ei.key] = { type: "plain", value: ei.defaultValue };
+            }
+          }
+          if (Object.keys(env).length > 0) {
+            normalizedAdapter.adapterConfig.env = await secrets.normalizeEnvBindingsForPersistence(targetCompany.id, env as any, { strictMode: strictSecretsMode });
+          }
+        }
+
         const patch = {
           name: planAgent.plannedName,
           role: manifestAgent.role,
@@ -4230,10 +4363,9 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
           continue;
         }
 
-        const createdStatus = "idle";
         let created = await agents.create(targetCompany.id, {
           ...patch,
-          status: createdStatus,
+          status: "idle",
         });
         await access.ensureMembership(targetCompany.id, "agent", created.id, "member", "active");
         await access.setPrincipalPermission(
@@ -4253,7 +4385,7 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
         } catch (err) {
           warnings.push(`Failed to materialize instructions bundle for ${manifestAgent.slug}: ${err instanceof Error ? err.message : String(err)}`);
         }
-        agentStatusById.set(created.id, created.status ?? createdStatus);
+        agentStatusById.set(created.id, created.status ?? "idle");
         importedSlugToAgentId.set(planAgent.slug, created.id);
         existingSlugToAgentId.set(normalizeAgentUrlKey(created.name) ?? created.id, created.id);
         resultAgents.push({
@@ -4302,6 +4434,26 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
             ?? null
           : null;
         const projectWorkspaceIdByKey = new Map<string, string>();
+        // Build project env from manifest.envInputs filtered by this project
+        const projectEnvInputs = (sourceManifest.envInputs ?? []).filter((e) => e.projectSlug === planProject.slug);
+        const reconstructedProjectEnv: Record<string, unknown> = {};
+        for (const ei of projectEnvInputs) {
+          if (ei.kind === "secret" && ei.secretName) {
+            const newSecretId = secretNameToId.get(ei.secretName);
+            if (newSecretId) {
+              reconstructedProjectEnv[ei.key] = { type: "secret_ref", secretId: newSecretId };
+            } else {
+              warnings.push(`Env key "${ei.key}" for project ${planProject.slug} references secret "${ei.secretName}" which was not included in this package. Re-add manually.`);
+            }
+          } else if (ei.kind === "secret" && !ei.secretName) {
+            warnings.push(`Env key "${ei.key}" for project ${planProject.slug} could not be reconstructed (sensitive binding without secret reference). Re-add manually.`);
+          } else if (ei.kind === "plain" && ei.defaultValue !== null) {
+            reconstructedProjectEnv[ei.key] = { type: "plain", value: ei.defaultValue };
+          }
+        }
+        const projectEnvConfig = Object.keys(reconstructedProjectEnv).length > 0
+          ? await secrets.normalizeEnvBindingsForPersistence(targetCompany.id, reconstructedProjectEnv as any, { strictMode: strictSecretsMode })
+          : null;
         const projectPatch = {
           name: planProject.plannedName,
           description: manifestProject.description,
@@ -4311,7 +4463,7 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
           status: manifestProject.status && PROJECT_STATUSES.includes(manifestProject.status as any)
             ? manifestProject.status as typeof PROJECT_STATUSES[number]
             : "backlog",
-          env: manifestProject.env,
+          env: projectEnvConfig ?? undefined,
           executionWorkspacePolicy: stripPortableProjectExecutionWorkspaceRefs(manifestProject.executionWorkspacePolicy),
         };
 
@@ -4390,6 +4542,91 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
       }
     }
 
+    // Remap secret_ref bindings in imported agent/project records to target company secret IDs
+    for (const envInput of sourceManifest.envInputs ?? []) {
+      if (envInput.kind !== "secret" || !envInput.secretName) continue;
+      const newSecretId = secretNameToId.get(envInput.secretName);
+      if (!newSecretId) {
+        // secret wasn't created (decryption failure or error) — it's already a placeholder in the env
+        continue;
+      }
+      if (envInput.agentSlug) {
+        const agentId = importedSlugToAgentId.get(envInput.agentSlug);
+        if (agentId) {
+          const agent = await agents.getById(agentId);
+          if (agent) {
+            const adapterConfig = agent.adapterConfig as Record<string, unknown>;
+            const env = adapterConfig.env as Record<string, unknown> | undefined;
+            let mutated = false;
+            if (env && typeof env[envInput.key] === "object" && env[envInput.key] !== null) {
+              const binding = env[envInput.key] as Record<string, unknown>;
+              if (binding.type === "secret_ref" && binding.secretId !== newSecretId) {
+                binding.secretId = newSecretId;
+                mutated = true;
+              }
+            }
+            if (mutated) await agents.update(agentId, { adapterConfig });
+          }
+        }
+      } else if (envInput.projectSlug) {
+        const projectId = importedSlugToProjectId.get(envInput.projectSlug);
+        if (projectId) {
+          const project = await projects.getById(projectId);
+          if (project && project.env && typeof project.env === "object") {
+            const env = project.env as Record<string, unknown>;
+            let mutated = false;
+            if (typeof env[envInput.key] === "object" && env[envInput.key] !== null) {
+              const binding = env[envInput.key] as Record<string, unknown>;
+              if (binding.type === "secret_ref" && binding.secretId !== newSecretId) {
+                binding.secretId = newSecretId;
+                mutated = true;
+              }
+            }
+            if (mutated) await projects.update(projectId, { env: env as import("@paperclipai/shared").AgentEnvConfig });
+          }
+        }
+      }
+    }
+
+    // Note: the legacy secret remapping below is kept as a safety net for
+    // agents/projects that were created/updated before this code existed.
+    // It can be removed once the inline reconstruction above is stable.
+    // Reconstruct plain env bindings and fill in missing env keys on imported agents/projects
+    for (const envInput of sourceManifest.envInputs ?? []) {
+      if (envInput.kind !== "plain" && !(envInput.kind === "secret" && !envInput.secretName)) continue;
+      if (!envInput.defaultValue && envInput.kind === "plain") continue;
+
+      if (envInput.agentSlug) {
+        const agentId = importedSlugToAgentId.get(envInput.agentSlug);
+        if (!agentId) continue;
+        const agent = await agents.getById(agentId);
+        if (!agent) continue;
+        const adapterConfig = agent.adapterConfig as Record<string, unknown>;
+        const env = (adapterConfig.env as Record<string, unknown>) ?? {};
+        let mutated = false;
+        if (!env[envInput.key] && envInput.kind === "plain") {
+          env[envInput.key] = { type: "plain", value: envInput.defaultValue ?? "" };
+          mutated = true;
+        }
+        if (mutated) {
+          adapterConfig.env = env;
+          await agents.update(agentId, { adapterConfig });
+        }
+      } else if (envInput.projectSlug) {
+        const projectId = importedSlugToProjectId.get(envInput.projectSlug);
+        if (!projectId) continue;
+        const project = await projects.getById(projectId);
+        if (!project) continue;
+        const env = (project.env as Record<string, unknown>) ?? {};
+        let mutated = false;
+        if (!env[envInput.key] && envInput.kind === "plain") {
+          env[envInput.key] = { type: "plain", value: envInput.defaultValue ?? "" };
+          mutated = true;
+        }
+        if (mutated) await projects.update(projectId, { env: env as import("@paperclipai/shared").AgentEnvConfig });
+      }
+    }
+
     if (include.issues) {
       const routines = routineService(db);
       for (const manifestIssue of sourceManifest.issues) {

skills/paperclip-dev/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: paperclip-dev
+required: false
+description: >
+  Develop and operate a local Paperclip instance — start and stop servers,
+  pull updates from master, run builds and tests, manage worktrees, back up
+  databases, and diagnose problems. Use whenever you need to work on the
+  Paperclip codebase itself or keep a running instance healthy.
+---
+
+# Paperclip Dev
+
+This skill covers the day-to-day workflows for developing and operating a local Paperclip instance. It assumes you are working inside the Paperclip repo checkout with `origin` pointing to `git@github.com:paperclipai/paperclip.git`.
+
+> **OPEN SOURCE HYGIENE:** This repository is public-facing. Treat anything you push to `origin` as publishable. Never commit or push secrets, API keys, tokens, private logs, PII, customer data, or machine-local configuration that should stay private. Keep git history tidy as well: avoid pushing throwaway branches, noisy checkpoint commits, or speculative work that does not need to be shared upstream.
+
+> **MANDATORY:** Before running any CLI command, building, testing, or managing worktrees, you MUST read `doc/DEVELOPING.md` in the Paperclip repo. It is the canonical reference for all `paperclipai` CLI commands, their options, build/test workflows, database operations, worktree management, and diagnostics. Do NOT guess at flags or options — read the doc first.
+
+## Quick Command Reference
+
+These are the most common commands. For full option tables and details, see `doc/DEVELOPING.md`.
+
+| Task | Command |
+|------|---------|
+| Start server (first time or normal) | `npx paperclipai run` |
+| Dev mode with hot reload | `pnpm dev` |
+| Stop dev server | `pnpm dev:stop` |
+| Build | `pnpm build` |
+| Type-check | `pnpm typecheck` |
+| Run tests | `pnpm test` |
+| Run migrations | `pnpm db:migrate` |
+| Regenerate Drizzle client | `pnpm db:generate` |
+| Back up database | `npx paperclipai db:backup` |
+| Health check | `npx paperclipai doctor --repair` |
+| Print env vars | `npx paperclipai env` |
+| Trigger agent heartbeat | `npx paperclipai heartbeat run --agent-id <id>` |
+| Install agent skills locally | `npx paperclipai agent local-cli <agent> --company-id <id>` |
+
+## Pulling from Master
+
+```bash
+git fetch origin && git pull origin master
+pnpm install && pnpm build
+```
+
+If schema changes landed, also run `pnpm db:generate && pnpm db:migrate`.
+
+## Worktrees
+
+Paperclip worktrees combine git worktrees with isolated Paperclip instances — each gets its own database, server port, and environment seeded from the primary instance.
+
+> **MANDATORY:** Before creating or managing worktrees, you MUST read the "Worktree-local Instances" and "Worktree CLI Reference" sections in `doc/DEVELOPING.md`. That is the canonical reference for all worktree commands, their options, seed modes, and environment variables.
+
+### When to Use Worktrees
+
+- Starting a feature branch that needs its own Paperclip environment
+- Running parallel agent work without cross-contaminating the primary instance
+- Testing Paperclip changes in isolation before merging
+
+### Command Overview
+
+The CLI has two tiers (see `doc/DEVELOPING.md` for full option tables):
+
+| Command | Purpose |
+|---------|---------|
+| `worktree:make <name>` | Create worktree + isolated instance in one step |
+| `worktree:list` | List worktrees and their Paperclip status |
+| `worktree:merge-history` | Preview/import issue history between worktrees |
+| `worktree:cleanup <name>` | Remove worktree, branch, and instance data |
+| `worktree init` | Bootstrap instance inside existing worktree |
+| `worktree env` | Print shell exports for worktree instance |
+| `worktree reseed` | Refresh worktree DB from another instance |
+| `worktree repair` | Fix broken/missing worktree instance metadata |
+
+### Typical Workflow
+
+```bash
+# 1. Create a worktree for a feature
+npx paperclipai worktree:make my-feature --start-point origin/main
+
+# 2. Move into the worktree (path printed by worktree:make) and source the environment
+cd <worktree-path>
+eval "$(npx paperclipai worktree env)"
+
+# 3. Start the isolated Paperclip server
+npx paperclipai run
+
+# 4. Do your work
+
+# 5. When done, merge history back if needed
+npx paperclipai worktree:merge-history --from paperclip-my-feature --to current --apply
+
+# 6. Clean up
+npx paperclipai worktree:cleanup my-feature
+```
+
+## Forks — Prefer Pushing to a User Fork
+
+If the user has a personal fork of `paperclipai/paperclip` configured as a git remote, push your feature branches to **that fork** instead of creating branches on the main repo. This keeps the upstream branch list clean and matches the standard open-source contribution flow.
+
+### Detect a fork remote
+
+Before pushing or creating a PR, list remotes and check for one that points at a non-`paperclipai` GitHub fork:
+
+```bash
+git remote -v
+```
+
+Treat any remote whose URL points to `github.com:<user>/paperclip` (or `github.com/<user>/paperclip.git`) as the user's fork. Common names are `fork`, `<username>`, or `myfork`. The remote named `origin` or `upstream` that points at `paperclipai/paperclip` is the canonical upstream — do not push feature branches there if a fork exists.
+
+### Pushing to the fork
+
+```bash
+# Push the current branch to the user's fork and set upstream
+git push -u <fork-remote> HEAD
+```
+
+Then create the PR from the fork branch:
+
+```bash
+gh pr create --repo paperclipai/paperclip --head <fork-owner>:<branch-name> ...
+```
+
+`gh pr create` usually figures out the head ref automatically when run from a branch tracking the fork; the explicit `--head <owner>:<branch>` form is the reliable fallback when it does not.
+
+### When no fork exists
+
+If `git remote -v` shows only `paperclipai/paperclip` remotes (no user fork), fall back to pushing branches to `origin` as before. Do NOT create a fork on the user's behalf — ask first.
+
+### Keeping the fork up to date
+
+The canonical remote that points at `paperclipai/paperclip` may be named `origin` **or** `upstream` depending on how the user set up the repo. Detect it the same way as in the "Detect a fork remote" step, then fetch and push from/with that remote so the sync works under either convention:
+
+```bash
+UPSTREAM_REMOTE=$(git remote -v | awk '/paperclipai\/paperclip.*\(fetch\)/{print $1; exit}')
+git fetch "$UPSTREAM_REMOTE"
+git push <fork-remote> "${UPSTREAM_REMOTE}/master:master"
+```
+
+## Pull Requests
+
+> **MANDATORY PRE-FLIGHT:** Before creating ANY pull request, you MUST read the canonical source files listed below. Do NOT run `gh pr create` until you have read these files and verified your PR body matches every required section.
+
+### Step 1 — Read the canonical files
+
+You MUST read all three of these files before creating a PR:
+
+1. **`.github/PULL_REQUEST_TEMPLATE.md`** — the required PR body structure
+2. **`CONTRIBUTING.md`** — contribution conventions, PR requirements, and thinking-path examples
+3. **`.github/workflows/pr.yml`** — CI checks that gate merge
+
+### Step 2 — Validate your PR body against this checklist
+
+After reading the template, verify your `--body` includes every one of these sections (names must match exactly):
+
+- [ ] `## Thinking Path` — blockquote style, 5-8 reasoning steps
+- [ ] `## What Changed` — bullet list of concrete changes
+- [ ] `## Verification` — how a reviewer confirms this works
+- [ ] `## Risks` — what could go wrong
+- [ ] `## Model Used` — provider, model ID, version, capabilities
+- [ ] `## Checklist` — copied from the template, items checked off
+
+If any section is missing or empty, do NOT submit the PR. Go back and fill it in.
+
+### Step 3 — Create the PR
+
+Only after completing Steps 1 and 2, run `gh pr create`. Use the template contents as the structure for `--body` — do not write a freeform summary.
+
+## Hard Rules — Do NOT Bypass
+
+These rules exist because agents have caused real damage by improvising around CLI failures. Follow them exactly.
+
+1. **CLI is the only interface to worktrees and databases.** All worktree and database operations MUST go through `npx paperclipai` / `pnpm paperclipai` commands. You MUST NOT:
+   - Run `pg_dump`, `pg_restore`, `psql`, `createdb`, `dropdb`, or any raw postgres commands
+   - Manually set `DATABASE_URL` to point a worktree server at another instance's database
+   - Run `rm -rf` on any `.paperclip/`, `.paperclip-worktrees/`, or `db/` directory
+   - Directly manipulate embedded postgres data directories
+   - Kill postgres processes by PID
+
+2. **If a CLI command fails, stop and report.** Do NOT attempt workarounds. If `worktree:make`, `worktree reseed`, `worktree init`, `worktree:cleanup`, or any other `paperclipai` command fails:
+   - Report the exact error message in your task comment
+   - Set the task to `blocked`
+   - Suggest running `npx paperclipai doctor --repair` or recreating the worktree from scratch
+   - Do NOT try to manually replicate what the CLI does
+
+3. **Never share databases between instances.** Each worktree instance gets its own isolated database. Never override `DATABASE_URL` to point one instance at another's database. This destroys isolation and can corrupt production data.
+
+4. **Starting a dev server in a worktree requires setup first.** The correct sequence is:
+   ```bash
+   # If the worktree already exists but has no running instance:
+   cd <worktree-path>
+   eval "$(npx paperclipai worktree env)"
+   pnpm install && pnpm build
+   npx paperclipai run          # or pnpm dev
+
+   # If the worktree needs a fresh database:
+   npx paperclipai worktree reseed --seed-mode full
+
+   # If the worktree is broken beyond repair:
+   npx paperclipai worktree:cleanup <name>
+   npx paperclipai worktree:make <name> --seed-mode full
+   ```
+   If any step fails, follow rule 2 — stop and report.
+
+5. **Seeding is a CLI operation.** When asked to seed a worktree database from the main instance, use `worktree reseed` or recreate with `worktree:make --seed-mode full`. Read `doc/DEVELOPING.md` for the full option tables. Never attempt manual database copying.
+
+## Persistent Dev Servers (for Manual Testing)
+
+When an agent needs to start a dev server that outlives the current heartbeat — for example, so a human or QA agent can manually test against it — the server process **must** be launched in a detached session. A process started directly from a heartbeat shell is killed when the heartbeat exits.
+
+### Use `tmux` for persistent servers
+
+```bash
+# 1. cd into the worktree (or main repo) and source the environment
+cd <worktree-path>
+eval "$(npx paperclipai worktree env)"   # skip if using the primary instance
+
+# 2. Start the dev server in a named, detached tmux session
+tmux new-session -d -s <session-name> 'pnpm dev'
+
+# Example with a descriptive name:
+tmux new-session -d -s auth-fix-3102 'pnpm dev'
+```
+
+### Managing the session
+
+| Task | Command |
+|------|---------|
+| Check if the session is alive | `tmux has-session -t <session-name> 2>/dev/null && echo running` |
+| View server output | `tmux capture-pane -t <session-name> -p` |
+| Kill the session | `tmux kill-session -t <session-name>` |
+| List all tmux sessions | `tmux list-sessions` |
+
+### Verifying the server is reachable
+
+After launching, confirm the port is listening before reporting success:
+
+```bash
+# Wait briefly for startup, then verify
+sleep 3
+curl -sf http://127.0.0.1:<port>/api/health && echo "Server is up"
+lsof -nP -iTCP:<port> -sTCP:LISTEN
+```
+
+### Key rules
+
+1. **Always use `tmux` (or equivalent)** when a dev server needs to stay running after the heartbeat ends. A server started directly from the agent shell will die when the heartbeat exits, even if it appeared healthy moments before.
+2. **Name the session descriptively** — include the worktree name and port (e.g., `auth-fix-3102`).
+3. **Verify the server is listening** before reporting the URL to anyone.
+4. **Do not use `nohup` or `&` alone** — these are unreliable for agent shells that may have their entire process group killed.
+5. **Clean up when done** — kill the tmux session when the testing is complete.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Server won't start | Run `npx paperclipai doctor --repair` to diagnose and auto-fix |
+| Forgetting to source worktree env | Run `eval "$(npx paperclipai worktree env)"` after cd-ing into the worktree |
+| Stale dependencies after pull | Run `pnpm install && pnpm build` after pulling |
+| Schema out of date after pull | Run `pnpm db:generate && pnpm db:migrate` |
+| Reseeding while target DB is running | Stop the target server first, or use `--allow-live-target` |
+| Cleaning up with unmerged commits | Merge or push first, or use `--force` if intentionally discarding |
+| Running agents against wrong instance | Verify `PAPERCLIP_API_URL` points to the correct port |
+| CLI command fails | Do NOT work around it — report the error and block (see Hard Rules above) |
+| Agent tries manual postgres operations | NEVER do this — all DB ops go through the CLI (see Hard Rules above) |
+| Dev server dies between heartbeats | Launch in a detached `tmux` session — see "Persistent Dev Servers" above |
+| Pushed feature branch to `paperclipai/paperclip` when a fork exists | Push to the user's fork remote instead — see "Forks" above |

ui/src/pages/CompanyExport.tsx

@@ -17,6 +17,15 @@ import { authApi } from "../api/auth";
 import { companiesApi } from "../api/companies";
 import { projectsApi } from "../api/projects";
 import { Button } from "@/components/ui/button";
+import { ToggleSwitch } from "@/components/ui/toggle-switch";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
 import { EmptyState } from "../components/EmptyState";
 import { PageSkeleton } from "../components/PageSkeleton";
 import { MarkdownBody } from "../components/MarkdownBody";
@@ -603,6 +612,8 @@ export function CompanyExport() {
   const [expandedDirs, setExpandedDirs] = useState<Set<string>>(new Set());
   const [checkedFiles, setCheckedFiles] = useState<Set<string>>(new Set());
   const [treeSearch, setTreeSearch] = useState("");
+  const [includeSecrets, setIncludeSecrets] = useState(false);
+  const [secretsConfirmOpen, setSecretsConfirmOpen] = useState(false);
   const [taskLimit, setTaskLimit] = useState(TASKS_PAGE_SIZE);
   const savedExpandedRef = useRef<Set<string> | null>(null);
   const initialFileFromUrl = useRef(filePathFromLocation(location.pathname));
@@ -731,6 +742,7 @@ export function CompanyExport() {
         include: { company: true, agents: true, projects: true, issues: true },
         selectedFiles: Array.from(checkedFiles).sort(),
         sidebarOrder,
+        includeSecrets,
       }),
     onSuccess: (result) => {
       const resultCheckedFiles = new Set(Object.keys(result.files));
@@ -945,6 +957,11 @@ export function CompanyExport() {
                 {warnings.length} warning{warnings.length === 1 ? "" : "s"}
               </span>
             )}
+            {includeSecrets && (
+              <span className="rounded-md border border-amber-500/30 bg-amber-500/5 px-2 py-0.5 text-xs text-amber-500">
+                Secrets included
+              </span>
+            )}
           </div>
           <Button
             size="sm"
@@ -974,6 +991,29 @@ export function CompanyExport() {
           <div className="border-b border-border px-4 py-3 shrink-0">
             <h2 className="text-base font-semibold">Package files</h2>
           </div>
+          <div className="border-b border-border px-4 py-2.5 shrink-0">
+            <div className="flex items-center gap-2 text-sm">
+              <ToggleSwitch
+                checked={includeSecrets}
+                onCheckedChange={(checked) => {
+                  if (checked) {
+                    setSecretsConfirmOpen(true);
+                  } else {
+                    setIncludeSecrets(false);
+                  }
+                }}
+              />
+              <span className="cursor-pointer text-muted-foreground hover:text-foreground transition-colors" onClick={() => {
+                if (includeSecrets) {
+                  setIncludeSecrets(false);
+                } else {
+                  setSecretsConfirmOpen(true);
+                }
+              }}>
+                Include secrets
+              </span>
+            </div>
+          </div>
           <div className="border-b border-border px-3 py-2 shrink-0">
             <div className="flex items-center gap-2 rounded-md border border-border px-2 py-1">
               <Search className="h-3.5 w-3.5 text-muted-foreground shrink-0" />
@@ -1014,6 +1054,26 @@ export function CompanyExport() {
           <ExportPreviewPane selectedFile={selectedFile} content={previewContent} allFiles={effectiveFiles} onSkillClick={handleSkillClick} />
         </div>
       </div>
+
+      {/* Secrets confirmation dialog */}
+      <Dialog open={secretsConfirmOpen} onOpenChange={setSecretsConfirmOpen}>
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Include secrets?</DialogTitle>
+            <DialogDescription>
+              Secrets will be exported as plaintext in the package file. Handle the exported package with care.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button variant="ghost" onClick={() => setSecretsConfirmOpen(false)}>
+              Cancel
+            </Button>
+            <Button variant="destructive" onClick={() => { setIncludeSecrets(true); setSecretsConfirmOpen(false); }}>
+              Include secrets
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
     </div>
   );
 }

ui/src/pages/CompanyImport.tsx

@@ -866,6 +866,13 @@ export function CompanyImport() {
         title: "Import complete",
         body: `${result.company.name}: ${result.agents.length} agent${result.agents.length === 1 ? "" : "s"} processed.`,
       });
+      if (result.warnings.some((w) => w.includes("could not be decrypted") || w.toLowerCase().includes("failed to create secret"))) {
+        pushToast({
+          tone: "warn",
+          title: "Secrets import warning",
+          body: "Some secrets could not be decrypted. Review warnings and recreate manually.",
+        });
+      }
       // Force a fresh dashboard load so newly imported agents are immediately visible.
       window.location.assign(`/${importedCompany.issuePrefix}/dashboard`);
     },
@@ -1309,6 +1316,18 @@ export function CompanyImport() {
             </div>
           )}
 
+          {/* Secrets info */}
+          {importPreview.manifest.secrets && importPreview.manifest.secrets.length > 0 && (
+            <div className="mx-5 mt-3 rounded-md border border-amber-500/30 bg-amber-500/5 px-4 py-3">
+              <div className="text-xs font-medium text-amber-500 mb-1">Secrets to import</div>
+              {importPreview.manifest.secrets.map((s) => (
+                <div key={s.name} className="text-xs text-amber-500">
+                  {s.name}{s.provider !== "local_encrypted" ? ` (${s.provider})` : ""}
+                </div>
+              ))}
+            </div>
+          )}
+
           {/* Errors */}
           {importPreview.errors.length > 0 && (
             <div className="mx-5 mt-3 rounded-md border border-destructive/30 bg-destructive/5 px-4 py-3">