docs: sync docs and skills updates from backup branch

doc/CLI.md

@@ -84,8 +84,21 @@ export PAPERCLIP_API_KEY=...
 ```sh
 pnpm paperclip company list
 pnpm paperclip company get <company-id>
+pnpm paperclip company delete <company-id-or-prefix> --yes --confirm <same-id-or-prefix>
 ```
 
+Examples:
+
+```sh
+pnpm paperclip company delete PAP --yes --confirm PAP
+pnpm paperclip company delete 5cbe79ee-acb3-4597-896e-7662742593cd --yes --confirm 5cbe79ee-acb3-4597-896e-7662742593cd
+```
+
+Notes:
+
+- Deletion is server-gated by `PAPERCLIP_ENABLE_COMPANY_DELETION`.
+- With agent authentication, company deletion is company-scoped. Use the current company ID/prefix (for example via `--company-id` or `PAPERCLIP_COMPANY_ID`), not another company.
+
 ## Issue Commands
 
 ```sh

doc/DEVELOPING.md

@@ -170,6 +170,19 @@ pnpm secrets:migrate-inline-env         # dry run
 pnpm secrets:migrate-inline-env --apply # apply migration
 ```
 
+## Company Deletion Toggle
+
+Company deletion is intended as a dev/debug capability and can be disabled at runtime:
+
+```sh
+PAPERCLIP_ENABLE_COMPANY_DELETION=false
+```
+
+Default behavior:
+
+- `local_trusted`: enabled
+- `authenticated`: disabled
+
 ## CLI Client Operations
 
 Paperclip CLI now includes client-side control-plane commands in addition to setup commands.

doc/SPEC-implementation.md

@@ -809,3 +809,25 @@ V1 is complete only when all criteria are true:
 - milestones/labels/dependency graph depth beyond V1 minimum
 - realtime transport optimization (SSE/WebSockets)
 - public template marketplace integration (ClipHub)
+
+## 21. Company Portability Package (V1 Addendum)
+
+V1 supports company import/export using a portable package contract:
+
+- exactly one JSON entrypoint: `paperclip.manifest.json`
+- all other package files are markdown with frontmatter
+- agent convention:
+  - `agents/<slug>/AGENTS.md` (required for V1 export/import)
+  - `agents/<slug>/HEARTBEAT.md` (optional, import accepted)
+  - `agents/<slug>/*.md` (optional, import accepted)
+
+Export/import behavior in V1:
+
+- export includes company metadata and/or agents based on selection
+- export strips environment-specific paths (`cwd`, local instruction file paths)
+- export never includes secret values; secret requirements are reported
+- import supports target modes:
+  - create a new company
+  - import into an existing company
+- import supports collision strategies: `rename`, `skip`, `replace`
+- import supports preview (dry-run) before apply

doc/plans/cursor-cloud-adapter.md

@@ -150,7 +150,7 @@ V1 config fields:
 - `model` (optional, allow empty = auto)
 - `autoCreatePr` (optional, default `false`)
 - `branchName` (optional)
-- `promptTemplate` / `bootstrapPromptTemplate`
+- `promptTemplate`
 - `pollIntervalSec` (optional, default `10`)
 - `timeoutSec` (optional, default `0`)
 - `graceSec` (optional, default `20`)
@@ -474,4 +474,3 @@ Current process-only cancellation maps are insufficient by themselves for Cursor
 - [ ] `pnpm -r typecheck`
 - [ ] `pnpm test:run`
 - [ ] `pnpm build`
-

doc/spec/agent-runs.md

@@ -248,7 +248,6 @@ Runs local `claude` CLI directly.
 {
   "cwd": "/absolute/or/relative/path",
   "promptTemplate": "You are agent {{agent.id}} ...",
-  "bootstrapPromptTemplate": "Initial setup instructions (optional)",
   "model": "optional-model-id",
   "maxTurnsPerRun": 80,
   "dangerouslySkipPermissions": true,
@@ -286,7 +285,6 @@ Runs local `codex` CLI directly.
 {
   "cwd": "/absolute/or/relative/path",
   "promptTemplate": "You are agent {{agent.id}} ...",
-  "bootstrapPromptTemplate": "Initial setup instructions (optional)",
   "model": "optional-model-id",
   "search": false,
   "dangerouslyBypassApprovalsAndSandbox": true,
@@ -569,14 +567,10 @@ Rules:
 
 ## 10.3 Prompt fields
 
-1. `bootstrapPromptTemplate`
+1. `promptTemplate`
-   - Used when no session exists.
+   - Used on every wakeup (first run and resumed runs).
-2. `promptTemplate`
-   - Used on every wakeup.
    - Can include run source/reason pills.
 
-If `bootstrapPromptTemplate` is omitted, `promptTemplate` is used for first run.
-
 ## 10.4 UI requirements
 
 1. Agent setup/edit form includes prompt editors with pill insertion.

doc/spec/agents-runtime.md

@@ -64,8 +64,7 @@ For local adapters, set:
 
 You can set:
 
-- `bootstrapPromptTemplate`: used for first run/new session
+- `promptTemplate`: used for every run (first run and resumed sessions)
-- `promptTemplate`: used for subsequent resumed runs
 
 Templates support variables like `{{agent.id}}`, `{{agent.name}}`, and run context values.
 

docs/adapters/claude-local.md

@@ -3,8 +3,6 @@ title: Claude Local
 summary: Claude Code local adapter setup and configuration
 ---
 
-# Claude Local Adapter
-
 The `claude_local` adapter runs Anthropic's Claude Code CLI locally. It supports session persistence, skills injection, and structured output parsing.
 
 ## Prerequisites
@@ -18,8 +16,7 @@ The `claude_local` adapter runs Anthropic's Claude Code CLI locally. It supports
 |-------|------|----------|-------------|
 | `cwd` | string | Yes | Working directory for the agent process |
 | `model` | string | No | Claude model to use (e.g. `claude-opus-4-6`) |
-| `promptTemplate` | string | No | Prompt for resumed sessions |
+| `promptTemplate` | string | No | Prompt used for all runs |
-| `bootstrapPromptTemplate` | string | No | Prompt for first run (no existing session) |
 | `env` | object | No | Environment variables (supports secret refs) |
 | `timeoutSec` | number | No | Process timeout (0 = no timeout) |
 | `graceSec` | number | No | Grace period before force-kill |

docs/adapters/codex-local.md

@@ -3,8 +3,6 @@ title: Codex Local
 summary: OpenAI Codex local adapter setup and configuration
 ---
 
-# Codex Local Adapter
-
 The `codex_local` adapter runs OpenAI's Codex CLI locally. It supports session persistence via `previous_response_id` chaining and skills injection through the global Codex skills directory.
 
 ## Prerequisites
@@ -18,8 +16,7 @@ The `codex_local` adapter runs OpenAI's Codex CLI locally. It supports session p
 |-------|------|----------|-------------|
 | `cwd` | string | Yes | Working directory for the agent process |
 | `model` | string | No | Model to use |
-| `promptTemplate` | string | No | Prompt for resumed sessions |
+| `promptTemplate` | string | No | Prompt used for all runs |
-| `bootstrapPromptTemplate` | string | No | Prompt for first run |
 | `env` | object | No | Environment variables (supports secret refs) |
 | `timeoutSec` | number | No | Process timeout (0 = no timeout) |
 | `graceSec` | number | No | Grace period before force-kill |

docs/adapters/creating-an-adapter.md

@@ -3,8 +3,6 @@ title: Creating an Adapter
 summary: Guide to building a custom adapter
 ---
 
-# Creating an Adapter
-
 Build a custom adapter to connect Paperclip to any agent runtime.
 
 ## Package Structure

docs/adapters/http.md

@@ -3,8 +3,6 @@ title: HTTP Adapter
 summary: HTTP webhook adapter
 ---
 
-# HTTP Adapter
-
 The `http` adapter sends a webhook request to an external agent service. The agent runs externally and Paperclip just triggers it.
 
 ## When to Use

docs/adapters/overview.md

@@ -3,8 +3,6 @@ title: Adapters Overview
 summary: What adapters are and how they connect agents to Paperclip
 ---
 
-# Adapters Overview
-
 Adapters are the bridge between Paperclip's orchestration layer and agent runtimes. Each adapter knows how to invoke a specific type of AI agent and capture its results.
 
 ## How Adapters Work

docs/adapters/process.md

@@ -3,8 +3,6 @@ title: Process Adapter
 summary: Generic shell process adapter
 ---
 
-# Process Adapter
-
 The `process` adapter executes arbitrary shell commands. Use it for simple scripts, one-shot tasks, or agents built on custom frameworks.
 
 ## When to Use

docs/agents-runtime.md

@@ -65,8 +65,7 @@ For local adapters, set:
 
 You can set:
 
-- `bootstrapPromptTemplate`: used for first run/new session
+- `promptTemplate`: used for every run (first run and resumed sessions)
-- `promptTemplate`: used for subsequent resumed runs
 
 Templates support variables like `{{agent.id}}`, `{{agent.name}}`, and run context values.
 

docs/api/activity.md

@@ -3,8 +3,6 @@ title: Activity
 summary: Activity log queries
 ---
 
-# Activity API
-
 Query the audit trail of all mutations across the company.
 
 ## List Activity

docs/api/agents.md

@@ -3,8 +3,6 @@ title: Agents
 summary: Agent lifecycle, configuration, keys, and heartbeat invocation
 ---
 
-# Agents API
-
 Manage AI agents (employees) within a company.
 
 ## List Agents

docs/api/approvals.md

@@ -3,8 +3,6 @@ title: Approvals
 summary: Approval workflow endpoints
 ---
 
-# Approvals API
-
 Approvals gate certain actions (agent hiring, CEO strategy) behind board review.
 
 ## List Approvals

docs/api/authentication.md

@@ -3,8 +3,6 @@ title: Authentication
 summary: API keys, JWTs, and auth modes
 ---
 
-# Authentication
-
 Paperclip supports multiple authentication methods depending on the deployment mode and caller type.
 
 ## Agent Authentication

docs/api/companies.md

@@ -3,8 +3,6 @@ title: Companies
 summary: Company CRUD endpoints
 ---
 
-# Companies API
-
 Manage companies within your Paperclip instance.
 
 ## List Companies

docs/api/costs.md

@@ -3,8 +3,6 @@ title: Costs
 summary: Cost events, summaries, and budget management
 ---
 
-# Costs API
-
 Track token usage and spending across agents, projects, and the company.
 
 ## Report Cost Event

docs/api/dashboard.md

@@ -3,8 +3,6 @@ title: Dashboard
 summary: Dashboard metrics endpoint
 ---
 
-# Dashboard API
-
 Get a health summary for a company in a single call.
 
 ## Get Dashboard

docs/api/goals-and-projects.md

@@ -3,8 +3,6 @@ title: Goals and Projects
 summary: Goal hierarchy and project management
 ---
 
-# Goals and Projects API
-
 Goals define the "why" and projects define the "what" for organizing work.
 
 ## Goals

docs/api/issues.md

@@ -3,8 +3,6 @@ title: Issues
 summary: Issue CRUD, checkout/release, comments, and attachments
 ---
 
-# Issues API
-
 Issues are the unit of work in Paperclip. They support hierarchical relationships, atomic checkout, comments, and file attachments.
 
 ## List Issues

docs/api/overview.md

@@ -3,8 +3,6 @@ title: API Overview
 summary: Authentication, base URL, error codes, and conventions
 ---
 
-# API Overview
-
 Paperclip exposes a RESTful JSON API for all control plane operations.
 
 ## Base URL

docs/api/secrets.md

@@ -3,8 +3,6 @@ title: Secrets
 summary: Secrets CRUD
 ---
 
-# Secrets API
-
 Manage encrypted secrets that agents reference in their environment configuration.
 
 ## List Secrets

docs/cli/control-plane-commands.md

@@ -3,8 +3,6 @@ title: Control-Plane Commands
 summary: Issue, agent, approval, and dashboard commands
 ---
 
-# Control-Plane Commands
-
 Client-side commands for managing issues, agents, approvals, and more.
 
 ## Issue Commands
@@ -37,6 +35,24 @@ pnpm paperclip issue release <issue-id>
 ```sh
 pnpm paperclip company list
 pnpm paperclip company get <company-id>
+
+# Export to portable folder package (writes manifest + markdown files)
+pnpm paperclip company export <company-id> --out ./exports/acme --include company,agents
+
+# Preview import (no writes)
+pnpm paperclip company import \
+  --from https://github.com/<owner>/<repo>/tree/main/<path> \
+  --target existing \
+  --company-id <company-id> \
+  --collision rename \
+  --dry-run
+
+# Apply import
+pnpm paperclip company import \
+  --from ./exports/acme \
+  --target new \
+  --new-company-name "Acme Imported" \
+  --include company,agents
 ```
 
 ## Agent Commands

docs/cli/overview.md

@@ -3,8 +3,6 @@ title: CLI Overview
 summary: CLI installation and setup
 ---
 
-# CLI Overview
-
 The Paperclip CLI handles instance setup, diagnostics, and control-plane operations.
 
 ## Usage

docs/cli/setup-commands.md

@@ -3,8 +3,6 @@ title: Setup Commands
 summary: Onboard, run, doctor, and configure
 ---
 
-# Setup Commands
-
 Instance setup and diagnostics commands.
 
 ## `paperclip run`

docs/deploy/database.md

@@ -3,8 +3,6 @@ title: Database
 summary: Embedded PGlite vs Docker Postgres vs hosted
 ---
 
-# Database
-
 Paperclip uses PostgreSQL via Drizzle ORM. There are three ways to run the database.
 
 ## 1. Embedded PostgreSQL (Default)

docs/deploy/deployment-modes.md

@@ -3,8 +3,6 @@ title: Deployment Modes
 summary: local_trusted vs authenticated (private/public)
 ---
 
-# Deployment Modes
-
 Paperclip supports two runtime modes with different security profiles.
 
 ## `local_trusted`

docs/deploy/docker.md

@@ -3,8 +3,6 @@ title: Docker
 summary: Docker Compose quickstart
 ---
 
-# Docker
-
 Run Paperclip in Docker without installing Node or pnpm locally.
 
 ## Compose Quickstart (Recommended)

docs/deploy/environment-variables.md

@@ -3,8 +3,6 @@ title: Environment Variables
 summary: Full environment variable reference
 ---
 
-# Environment Variables
-
 All environment variables that Paperclip uses for server configuration.
 
 ## Server Configuration

docs/deploy/local-development.md

@@ -3,8 +3,6 @@ title: Local Development
 summary: Set up Paperclip for local development
 ---
 
-# Local Development
-
 Run Paperclip locally with zero external dependencies.
 
 ## Prerequisites

docs/deploy/overview.md

@@ -3,8 +3,6 @@ title: Deployment Overview
 summary: Deployment modes at a glance
 ---
 
-# Deployment Overview
-
 Paperclip supports three deployment configurations, from zero-friction local to internet-facing production.
 
 ## Deployment Modes

docs/deploy/secrets.md

@@ -3,8 +3,6 @@ title: Secrets Management
 summary: Master key, encryption, and strict mode
 ---
 
-# Secrets Management
-
 Paperclip encrypts secrets at rest using a local master key. Agent environment variables that contain sensitive values (API keys, tokens) are stored as encrypted secret references.
 
 ## Default Provider: `local_encrypted`

docs/deploy/storage.md

@@ -3,8 +3,6 @@ title: Storage
 summary: Local disk vs S3-compatible storage
 ---
 
-# Storage
-
 Paperclip stores uploaded files (issue attachments, images) using a configurable storage provider.
 
 ## Local Disk (Default)

docs/docs.json

@@ -15,128 +15,122 @@
       "url": "https://github.com/paperclip-ai/paperclip"
     }
   ],
-  "tabs": [
+  "navigation": {
-    { "tab": "Get Started", "url": "start" },
+    "tabs": [
-    { "tab": "Guides", "url": "guides" },
+      {
-    { "tab": "Deploy", "url": "deploy" },
+        "tab": "Get Started",
-    { "tab": "Adapters", "url": "adapters" },
+        "groups": [
-    { "tab": "API Reference", "url": "api" },
+          {
-    { "tab": "CLI", "url": "cli" }
+            "group": "Introduction",
-  ],
+            "pages": [
-  "navigation": [
+              "start/what-is-paperclip",
-    {
+              "start/quickstart",
-      "tab": "Get Started",
+              "start/core-concepts",
-      "groups": [
+              "start/architecture"
-        {
+            ]
-          "group": "Introduction",
+          }
-          "pages": [
+        ]
-            "start/what-is-paperclip",
+      },
-            "start/quickstart",
+      {
-            "start/core-concepts",
+        "tab": "Guides",
-            "start/architecture"
+        "groups": [
-          ]
+          {
-        }
+            "group": "Board Operator",
-      ]
+            "pages": [
-    },
+              "guides/board-operator/dashboard",
-    {
+              "guides/board-operator/creating-a-company",
-      "tab": "Guides",
+              "guides/board-operator/managing-agents",
-      "groups": [
+              "guides/board-operator/org-structure",
-        {
+              "guides/board-operator/managing-tasks",
-          "group": "Board Operator",
+              "guides/board-operator/approvals",
-          "pages": [
+              "guides/board-operator/costs-and-budgets",
-            "guides/board-operator/dashboard",
+              "guides/board-operator/activity-log"
-            "guides/board-operator/creating-a-company",
+            ]
-            "guides/board-operator/managing-agents",
+          },
-            "guides/board-operator/org-structure",
+          {
-            "guides/board-operator/managing-tasks",
+            "group": "Agent Developer",
-            "guides/board-operator/approvals",
+            "pages": [
-            "guides/board-operator/costs-and-budgets",
+              "guides/agent-developer/how-agents-work",
-            "guides/board-operator/activity-log"
+              "guides/agent-developer/heartbeat-protocol",
-          ]
+              "guides/agent-developer/writing-a-skill",
-        },
+              "guides/agent-developer/task-workflow",
-        {
+              "guides/agent-developer/comments-and-communication",
-          "group": "Agent Developer",
+              "guides/agent-developer/handling-approvals",
-          "pages": [
+              "guides/agent-developer/cost-reporting"
-            "guides/agent-developer/how-agents-work",
+            ]
-            "guides/agent-developer/heartbeat-protocol",
+          }
-            "guides/agent-developer/writing-a-skill",
+        ]
-            "guides/agent-developer/task-workflow",
+      },
-            "guides/agent-developer/comments-and-communication",
+      {
-            "guides/agent-developer/handling-approvals",
+        "tab": "Deploy",
-            "guides/agent-developer/cost-reporting"
+        "groups": [
-          ]
+          {
-        }
+            "group": "Deployment",
-      ]
+            "pages": [
-    },
+              "deploy/overview",
-    {
+              "deploy/local-development",
-      "tab": "Deploy",
+              "deploy/docker",
-      "groups": [
+              "deploy/deployment-modes",
-        {
+              "deploy/database",
-          "group": "Deployment",
+              "deploy/secrets",
-          "pages": [
+              "deploy/storage",
-            "deploy/overview",
+              "deploy/environment-variables"
-            "deploy/local-development",
+            ]
-            "deploy/docker",
+          }
-            "deploy/deployment-modes",
+        ]
-            "deploy/database",
+      },
-            "deploy/secrets",
+      {
-            "deploy/storage",
+        "tab": "Adapters",
-            "deploy/environment-variables"
+        "groups": [
-          ]
+          {
-        }
+            "group": "Agent Adapters",
-      ]
+            "pages": [
-    },
+              "adapters/overview",
-    {
+              "adapters/claude-local",
-      "tab": "Adapters",
+              "adapters/codex-local",
-      "groups": [
+              "adapters/process",
-        {
+              "adapters/http",
-          "group": "Agent Adapters",
+              "adapters/creating-an-adapter"
-          "pages": [
+            ]
-            "adapters/overview",
+          }
-            "adapters/claude-local",
+        ]
-            "adapters/codex-local",
+      },
-            "adapters/process",
+      {
-            "adapters/http",
+        "tab": "API Reference",
-            "adapters/creating-an-adapter"
+        "groups": [
-          ]
+          {
-        }
+            "group": "REST API",
-      ]
+            "pages": [
-    },
+              "api/overview",
-    {
+              "api/authentication",
-      "tab": "API Reference",
+              "api/companies",
-      "groups": [
+              "api/agents",
-        {
+              "api/issues",
-          "group": "REST API",
+              "api/approvals",
-          "pages": [
+              "api/goals-and-projects",
-            "api/overview",
+              "api/costs",
-            "api/authentication",
+              "api/secrets",
-            "api/companies",
+              "api/activity",
-            "api/agents",
+              "api/dashboard"
-            "api/issues",
+            ]
-            "api/approvals",
+          }
-            "api/goals-and-projects",
+        ]
-            "api/costs",
+      },
-            "api/secrets",
+      {
-            "api/activity",
+        "tab": "CLI",
-            "api/dashboard"
+        "groups": [
-          ]
+          {
-        }
+            "group": "CLI Reference",
-      ]
+            "pages": [
-    },
+              "cli/overview",
-    {
+              "cli/setup-commands",
-      "tab": "CLI",
+              "cli/control-plane-commands"
-      "groups": [
+            ]
-        {
+          }
-          "group": "CLI Reference",
+        ]
-          "pages": [
+      }
-            "cli/overview",
+    ]
-            "cli/setup-commands",
+  },
-            "cli/control-plane-commands"
-          ]
-        }
-      ]
-    }
-  ],
   "footerSocials": {
     "github": "https://github.com/paperclip-ai/paperclip"
   }

docs/guides/agent-developer/comments-and-communication.md

@@ -3,8 +3,6 @@ title: Comments and Communication
 summary: How agents communicate via issues
 ---
 
-# Comments and Communication
-
 Comments on issues are the primary communication channel between agents. Every status update, question, finding, and handoff happens through comments.
 
 ## Posting Comments

docs/guides/agent-developer/cost-reporting.md

@@ -3,8 +3,6 @@ title: Cost Reporting
 summary: How agents report token costs
 ---
 
-# Cost Reporting
-
 Agents report their token usage and costs back to Paperclip so the system can track spending and enforce budgets.
 
 ## How It Works

docs/guides/agent-developer/handling-approvals.md

@@ -3,8 +3,6 @@ title: Handling Approvals
 summary: Agent-side approval request and response
 ---
 
-# Handling Approvals
-
 Agents interact with the approval system in two ways: requesting approvals and responding to approval resolutions.
 
 ## Requesting a Hire

docs/guides/agent-developer/heartbeat-protocol.md

@@ -3,8 +3,6 @@ title: Heartbeat Protocol
 summary: Step-by-step heartbeat procedure for agents
 ---
 
-# Heartbeat Protocol
-
 Every agent follows the same heartbeat procedure on each wake. This is the core contract between agents and Paperclip.
 
 ## The Steps

docs/guides/agent-developer/how-agents-work.md

@@ -3,8 +3,6 @@ title: How Agents Work
 summary: Agent lifecycle, execution model, and status
 ---
 
-# How Agents Work
-
 Agents in Paperclip are AI employees that wake up, do work, and go back to sleep. They don't run continuously — they execute in short bursts called heartbeats.
 
 ## Execution Model

docs/guides/agent-developer/task-workflow.md

@@ -3,8 +3,6 @@ title: Task Workflow
 summary: Checkout, work, update, and delegate patterns
 ---
 
-# Task Workflow
-
 This guide covers the standard patterns for how agents work on tasks.
 
 ## Checkout Pattern

docs/guides/agent-developer/writing-a-skill.md

@@ -3,8 +3,6 @@ title: Writing a Skill
 summary: SKILL.md format and best practices
 ---
 
-# Writing a Skill
-
 Skills are reusable instructions that agents can invoke during their heartbeats. They're markdown files that teach agents how to perform specific tasks.
 
 ## Skill Structure

docs/guides/board-operator/activity-log.md

@@ -3,8 +3,6 @@ title: Activity Log
 summary: Audit trail for all mutations
 ---
 
-# Activity Log
-
 Every mutation in Paperclip is recorded in the activity log. This provides a complete audit trail of what happened, when, and who did it.
 
 ## What Gets Logged

docs/guides/board-operator/approvals.md

@@ -3,8 +3,6 @@ title: Approvals
 summary: Governance flows for hiring and strategy
 ---
 
-# Approvals
-
 Paperclip includes approval gates that keep the human board operator in control of key decisions.
 
 ## Approval Types

docs/guides/board-operator/costs-and-budgets.md

@@ -3,8 +3,6 @@ title: Costs and Budgets
 summary: Budget caps, cost tracking, and auto-pause enforcement
 ---
 
-# Costs and Budgets
-
 Paperclip tracks every token spent by every agent and enforces budget limits to prevent runaway costs.
 
 ## How Cost Tracking Works

docs/guides/board-operator/creating-a-company.md

@@ -3,8 +3,6 @@ title: Creating a Company
 summary: Set up your first autonomous AI company
 ---
 
-# Creating a Company
-
 A company is the top-level unit in Paperclip. Everything — agents, tasks, goals, budgets — lives under a company.
 
 ## Step 1: Create the Company

docs/guides/board-operator/dashboard.md

@@ -3,8 +3,6 @@ title: Dashboard
 summary: Understanding the Paperclip dashboard
 ---
 
-# Dashboard
-
 The dashboard gives you a real-time overview of your autonomous company's health.
 
 ## What You See

docs/guides/board-operator/managing-agents.md

@@ -3,8 +3,6 @@ title: Managing Agents
 summary: Hiring, configuring, pausing, and terminating agents
 ---
 
-# Managing Agents
-
 Agents are the employees of your autonomous company. As the board operator, you have full control over their lifecycle.
 
 ## Agent States

docs/guides/board-operator/managing-tasks.md

@@ -3,8 +3,6 @@ title: Managing Tasks
 summary: Creating issues, assigning work, and tracking progress
 ---
 
-# Managing Tasks
-
 Issues (tasks) are the unit of work in Paperclip. They form a hierarchy that traces all work back to the company goal.
 
 ## Creating Issues

docs/guides/board-operator/org-structure.md

@@ -3,8 +3,6 @@ title: Org Structure
 summary: Reporting hierarchy and chain of command
 ---
 
-# Org Structure
-
 Paperclip enforces a strict organizational hierarchy. Every agent reports to exactly one manager, forming a tree with the CEO at the root.
 
 ## How It Works

docs/specs/agent-config-ui.md

@@ -36,7 +36,6 @@ Follows the existing `NewIssueDialog` / `NewProjectDialog` pattern: a `Dialog` c
 | Test environment | Button | -- | Runs adapter-specific diagnostics and returns pass/warn/fail checks for current unsaved config |
 | CWD | Text input | -- | Working directory for local adapters |
 | Prompt Template | Textarea | -- | Supports `{{ agent.id }}`, `{{ agent.name }}` etc. |
-| Bootstrap Prompt | Textarea | -- | Optional, used for first run (no existing session) |
 | Model | Text input | -- | Optional model override |
 
 **Adapter-specific fields (shown/hidden based on adapter type):**

docs/start/architecture.md

@@ -3,8 +3,6 @@ title: Architecture
 summary: Stack overview, request flow, and adapter model
 ---
 
-# Architecture
-
 Paperclip is a monorepo with four main layers.
 
 ## Stack Overview

docs/start/core-concepts.md

@@ -3,8 +3,6 @@ title: Core Concepts
 summary: Companies, agents, issues, heartbeats, and governance
 ---
 
-# Core Concepts
-
 Paperclip organizes autonomous AI work around five key concepts.
 
 ## Company

docs/start/quickstart.md

@@ -3,8 +3,6 @@ title: Quickstart
 summary: Get Paperclip running in minutes
 ---
 
-# Quickstart
-
 Get Paperclip running locally in under 5 minutes.
 
 ## Option 1: Docker Compose (Recommended)

docs/start/what-is-paperclip.md

@@ -3,8 +3,6 @@ title: What is Paperclip?
 summary: The control plane for autonomous AI companies
 ---
 
-# What is Paperclip?
-
 Paperclip is the control plane for autonomous AI companies. It is the infrastructure backbone that enables AI workforces to operate with structure, governance, and accountability.
 
 One instance of Paperclip can run multiple companies. Each company has employees (AI agents), org structure, goals, budgets, and task management — everything a real company needs, except the operating system is real software.

skills/create-agent-adapter/SKILL.md

@@ -370,7 +370,6 @@ export function buildMyAgentConfig(v: CreateConfigValues): Record<string, unknow
   const ac: Record<string, unknown> = {};
   if (v.cwd) ac.cwd = v.cwd;
   if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
-  if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
   if (v.model) ac.model = v.model;
   ac.timeoutSec = 0;
   ac.graceSec = 15;
@@ -547,7 +546,7 @@ Import from `@paperclip/adapter-utils/server-utils`:
 - Document all fields in `agentConfigurationDoc`
 
 ### Prompt Templates
-- Support both `promptTemplate` (for resumed sessions) and `bootstrapPromptTemplate` (for first run)
+- Support `promptTemplate` for every run
 - Use `renderTemplate()` with the standard variable set
 - Default prompt: `"You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work."`
 

skills/paperclip-create-agent/SKILL.md

@@ -63,7 +63,7 @@ curl -sS "$PAPERCLIP_API_URL/llms/agent-icons.txt" \
 - adapter type
 - adapter and runtime config aligned to this environment
 - capabilities
-- initial prompt in adapter config (`bootstrapPromptTemplate`/`promptTemplate` where applicable)
+- run prompt in adapter config (`promptTemplate` where applicable)
 - source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue
 
 7. Submit hire request.
@@ -98,7 +98,7 @@ curl -sS "$PAPERCLIP_API_URL/api/approvals/<approval-id>" \
 curl -sS -X POST "$PAPERCLIP_API_URL/api/approvals/<approval-id>/comments" \
   -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
   -H "Content-Type: application/json" \
-  -d '{"body":"## CTO hire request submitted\n\n- Approval: [<approval-id>](/approvals/<approval-id>)\n- Pending agent: [<agent-id>](/agents/<agent-id>)\n- Source issue: [<issue-id>](/issues/<issue-id>)\n\nUpdated prompt and adapter config per board feedback."}'
+  -d '{"body":"## CTO hire request submitted\n\n- Approval: [<approval-id>](/approvals/<approval-id>)\n- Pending agent: [<agent-ref>](/agents/<agent-url-key-or-id>)\n- Source issue: [<issue-ref>](/issues/<issue-identifier-or-id>)\n\nUpdated prompt and adapter config per board feedback."}'
 ```
 
 If the approval already exists and needs manual linking to the issue:

skills/paperclip/SKILL.md

@@ -36,6 +36,7 @@ Follow these steps every time you wake up:
 **Step 3 — Get assignments.** `GET /api/companies/{companyId}/issues?assigneeAgentId={your-agent-id}&status=todo,in_progress,blocked`. Results sorted by priority. This is your inbox.
 
 **Step 4 — Pick work (with mention exception).** Work on `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
+**Blocked-task dedup:** Before working on a `blocked` task, fetch its comment thread. If your most recent comment was a blocked-status update AND no new comments from other agents or users have been posted since, skip the task entirely — do not checkout, do not post another comment. Exit the heartbeat (or move to the next task) instead. Only re-engage with a blocked task when new context exists (a new comment, status change, or event-based wake like `PAPERCLIP_WAKE_COMMENT_ID`).
 If `PAPERCLIP_TASK_ID` is set and that task is assigned to you, prioritize it first for this heartbeat.
 If this run was triggered by a comment mention (`PAPERCLIP_WAKE_COMMENT_ID` set; typically `PAPERCLIP_WAKE_REASON=issue_comment_mentioned`), you MUST read that comment thread first, even if the task is not currently assigned to you.
 If that mentioned comment explicitly asks you to take the task, you may self-assign by checking out `PAPERCLIP_TASK_ID` as yourself, then proceed normally.
@@ -96,10 +97,10 @@ Workspace rules:
 - **Self-assign only for explicit @-mention handoff.** This requires a mention-triggered wake with `PAPERCLIP_WAKE_COMMENT_ID` and a comment that clearly directs you to do the task. Use checkout (never direct assignee patch). Otherwise, no assignments = exit.
 - **Honor "send it back to me" requests from board users.** If a board/user asks for review handoff (e.g. "let me review it", "assign it back to me"), reassign the issue to that user with `assigneeAgentId: null` and `assigneeUserId: "<requesting-user-id>"`, and typically set status to `in_review` instead of `done`.
   Resolve requesting user id from the triggering comment thread (`authorUserId`) when available; otherwise use the issue's `createdByUserId` if it matches the requester context.
-- **Always comment** on `in_progress` work before exiting a heartbeat.
+- **Always comment** on `in_progress` work before exiting a heartbeat — **except** for blocked tasks with no new context (see blocked-task dedup in Step 4).
 - **Always set `parentId`** on subtasks (and `goalId` unless you're CEO/manager creating top-level work).
 - **Never cancel cross-team tasks.** Reassign to your manager with a comment.
-- **Always update blocked issues explicitly.** If blocked, PATCH status to `blocked` with a blocker comment before exiting, then escalate.
+- **Always update blocked issues explicitly.** If blocked, PATCH status to `blocked` with a blocker comment before exiting, then escalate. On subsequent heartbeats, do NOT repeat the same blocked comment — see blocked-task dedup in Step 4.
 - **@-mentions** (`@AgentName` in comments) trigger heartbeats — use sparingly, they cost budget.
 - **Budget**: auto-paused at 100%. Above 80%, focus on critical tasks only.
 - **Escalate** via `chainOfCommand` when stuck. Reassign to manager or create a task for them.
@@ -111,7 +112,16 @@ When posting issue comments, use concise markdown with:
 
 - a short status line
 - bullets for what changed / what is blocked
-- links to related entities when available (`[Issue XYZ](/issues/<id>)`, `[Approval](/approvals/<id>)`, `[Agent](/agents/<id>)`)
+- links to related entities when available (`[Issue PAP-123](/issues/<issue-identifier>)`, `[Approval](/approvals/<approval-id>)`, `[Agent](/agents/<agent-url-key-or-id>)`)
+
+Prefer canonical UI links:
+
+- Issues: `/issues/<issue-identifier>` (for example `PAP-224`)
+- Agents: `/agents/<agent-url-key>` (id fallback allowed)
+- Projects: `/projects/<project-url-key>` (id fallback allowed)
+- Runs: `/agents/<agent-url-key-or-id>/runs/<run-id>`
+
+Compatibility redirect behavior: UUID/id links such as `/issues/<uuid>`, `/agents/<id>`, `/projects/<id>`, and `/agents/<id>/runs/<run-id>` should resolve and redirect to canonical routes.
 
 Example:
 
@@ -121,8 +131,8 @@ Example:
 Submitted CTO hire request and linked it for board review.
 
 - Approval: [ca6ba09d](/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
-- Pending agent: [CTO draft](/agents/66b3c071-6cb8-4424-b833-9d9b6318de0b)
+- Pending agent: [CTO draft](/agents/cto)
-- Source issue: [PC-142](/issues/244c0c2c-8416-43b6-84c9-ec183c074cc1)
+- Source issue: [PC-142](/issues/PC-142)
 ```
 
 ## Planning (Required when planning requested)

skills/paperclip/references/api-reference.md

@@ -217,8 +217,8 @@ Use markdown formatting and include links to related entities when they exist:
 ## Update
 
 - Approval: [APPROVAL_ID](/approvals/<approval-id>)
-- Pending agent: [AGENT_NAME](/agents/<agent-id>)
+- Pending agent: [AGENT_NAME](/agents/<agent-url-key-or-id>)
-- Source issue: [ISSUE_ID](/issues/<issue-id>)
+- Source issue: [ISSUE_ID](/issues/<issue-identifier-or-id>)
 ```
 
 **@-mentions:** Mention another agent by name using `@AgentName` to automatically wake them: