fix(scripts): guard empty issue helper updates

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

.agents/skills/company-creator/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: company-creator
+description: >
+  Create agent company packages conforming to the Agent Companies specification
+  (agentcompanies/v1). Use when a user wants to create a new agent company from
+  scratch, build a company around an existing git repo or skills collection, or
+  scaffold a team/department of agents. Triggers on: "create a company", "make me
+  a company", "build a company from this repo", "set up an agent company",
+  "create a team of agents", "hire some agents", or when given a repo URL and
+  asked to turn it into a company. Do NOT use for importing an existing company
+  package (use the CLI import command instead) or for modifying a company that
+  is already running in Paperclip.
+---
+
+# Company Creator
+
+Create agent company packages that conform to the Agent Companies specification.
+
+Spec references:
+
+- Normative spec: `docs/companies/companies-spec.md` (read this before generating files)
+- Web spec: https://agentcompanies.io/specification
+- Protocol site: https://agentcompanies.io/
+
+## Two Modes
+
+### Mode 1: Company From Scratch
+
+The user describes what they want. Interview them to flesh out the vision, then generate the package.
+
+### Mode 2: Company From a Repo
+
+The user provides a git repo URL, local path, or tweet. Analyze the repo, then create a company that wraps it.
+
+See [references/from-repo-guide.md](references/from-repo-guide.md) for detailed repo analysis steps.
+
+## Process
+
+### Step 1: Gather Context
+
+Determine which mode applies:
+
+- **From scratch**: What kind of company or team? What domain? What should the agents do?
+- **From repo**: Clone/read the repo. Scan for existing skills, agent configs, README, source structure.
+
+### Step 2: Interview (Use AskUserQuestion)
+
+Do not skip this step. Use AskUserQuestion to align with the user before writing any files.
+
+**For from-scratch companies**, ask about:
+
+- Company purpose and domain (1-2 sentences is fine)
+- What agents they need - propose a hiring plan based on what they described
+- Whether this is a full company (needs a CEO) or a team/department (no CEO required)
+- Any specific skills the agents should have
+- How work flows through the organization (see "Workflow" below)
+- Whether they want projects and starter tasks
+
+**For from-repo companies**, present your analysis and ask:
+
+- Confirm the agents you plan to create and their roles
+- Whether to reference or vendor any discovered skills (default: reference)
+- Any additional agents or skills beyond what the repo provides
+- Company name and any customization
+- Confirm the workflow you inferred from the repo (see "Workflow" below)
+
+**Workflow — how does work move through this company?**
+
+A company is not just a list of agents with skills. It's an organization that takes ideas and turns them into work products. You need to understand the workflow so each agent knows:
+
+- Who gives them work and in what form (a task, a branch, a question, a review request)
+- What they do with it
+- Who they hand off to when they're done, and what that handoff looks like
+- What "done" means for their role
+
+**Not every company is a pipeline.** Infer the right workflow pattern from context:
+
+- **Pipeline** — sequential stages, each agent hands off to the next. Use when the repo/domain has a clear linear process (e.g. plan → build → review → ship → QA, or content ideation → draft → edit → publish).
+- **Hub-and-spoke** — a manager delegates to specialists who report back independently. Use when agents do different kinds of work that don't feed into each other (e.g. a CEO who dispatches to a researcher, a marketer, and an analyst).
+- **Collaborative** — agents work together on the same things as peers. Use for small teams where everyone contributes to the same output (e.g. a design studio, a brainstorming team).
+- **On-demand** — agents are summoned as needed with no fixed flow. Use when agents are more like a toolbox of specialists the user calls directly.
+
+For from-scratch companies, propose a workflow pattern based on what they described and ask if it fits.
+
+For from-repo companies, infer the pattern from the repo's structure. If skills have a clear sequential dependency (like `plan-ceo-review → plan-eng-review → review → ship → qa`), that's a pipeline. If skills are independent capabilities, it's more likely hub-and-spoke or on-demand. State your inference in the interview so the user can confirm or adjust.
+
+**Key interviewing principles:**
+
+- Propose a concrete hiring plan. Don't ask open-ended "what agents do you want?" - suggest specific agents based on context and let the user adjust.
+- Keep it lean. Most users are new to agent companies. A few agents (3-5) is typical for a startup. Don't suggest 10+ agents unless the scope demands it.
+- From-scratch companies should start with a CEO who manages everyone. Teams/departments don't need one.
+- Ask 2-3 focused questions per round, not 10.
+
+### Step 3: Read the Spec
+
+Before generating any files, read the normative spec:
+
+```
+docs/companies/companies-spec.md
+```
+
+Also read the quick reference: [references/companies-spec.md](references/companies-spec.md)
+
+And the example: [references/example-company.md](references/example-company.md)
+
+### Step 4: Generate the Package
+
+Create the directory structure and all files. Follow the spec's conventions exactly.
+
+**Directory structure:**
+
+```
+<company-slug>/
+├── COMPANY.md
+├── agents/
+│   └── <slug>/AGENTS.md
+├── teams/
+│   └── <slug>/TEAM.md        (if teams are needed)
+├── projects/
+│   └── <slug>/PROJECT.md     (if projects are needed)
+├── tasks/
+│   └── <slug>/TASK.md        (if tasks are needed)
+├── skills/
+│   └── <slug>/SKILL.md       (if custom skills are needed)
+└── .paperclip.yaml            (Paperclip vendor extension)
+```
+
+**Rules:**
+
+- Slugs must be URL-safe, lowercase, hyphenated
+- COMPANY.md gets `schema: agentcompanies/v1` - other files inherit it
+- Agent instructions go in the AGENTS.md body, not in .paperclip.yaml
+- Skills referenced by shortname in AGENTS.md resolve to `skills/<shortname>/SKILL.md`
+- For external skills, use `sources` with `usage: referenced` (see spec section 12)
+- Do not export secrets, machine-local paths, or database IDs
+- Omit empty/default fields
+- For companies generated from a repo, add a references footer at the bottom of COMPANY.md body:
+  `Generated from [repo-name](repo-url) with the company-creator skill from [Paperclip](https://github.com/paperclipai/paperclip)`
+
+**Reporting structure:**
+
+- Every agent except the CEO should have `reportsTo` set to their manager's slug
+- The CEO has `reportsTo: null`
+- For teams without a CEO, the top-level agent has `reportsTo: null`
+
+**Writing workflow-aware agent instructions:**
+
+Each AGENTS.md body should include not just what the agent does, but how they fit into the organization's workflow. Include:
+
+1. **Where work comes from** — "You receive feature ideas from the user" or "You pick up tasks assigned to you by the CTO"
+2. **What you produce** — "You produce a technical plan with architecture diagrams" or "You produce a reviewed, approved branch ready for shipping"
+3. **Who you hand off to** — "When your plan is locked, hand off to the Staff Engineer for implementation" or "When review passes, hand off to the Release Engineer to ship"
+4. **What triggers you** — "You are activated when a new feature idea needs product-level thinking" or "You are activated when a branch is ready for pre-landing review"
+
+This turns a collection of agents into an organization that actually works together. Without workflow context, agents operate in isolation — they do their job but don't know what happens before or after them.
+
+Add a concise execution contract to every generated working agent:
+
+- Start actionable work in the same heartbeat and do not stop at a plan unless planning was requested.
+- Leave durable progress in comments, documents, or work products with the next action.
+- Use child issues for long or parallel delegated work instead of polling agents, sessions, or processes.
+- Mark blocked work with the unblock owner and action.
+- Respect budget, pause/cancel, approval gates, and company boundaries.
+
+### Step 5: Confirm Output Location
+
+Ask the user where to write the package. Common options:
+
+- A subdirectory in the current repo
+- A new directory the user specifies
+- The current directory (if it's empty or they confirm)
+
+### Step 6: Write README.md and LICENSE
+
+**README.md** — every company package gets a README. It should be a nice, readable introduction that someone browsing GitHub would appreciate. Include:
+
+- Company name and what it does
+- The workflow / how the company operates
+- Org chart as a markdown list or table showing agents, titles, reporting structure, and skills
+- Brief description of each agent's role
+- Citations and references: link to the source repo (if from-repo), link to the Agent Companies spec (https://agentcompanies.io/specification), and link to Paperclip (https://github.com/paperclipai/paperclip)
+- A "Getting Started" section explaining how to import: `paperclipai company import --from <path>`
+
+**LICENSE** — include a LICENSE file. The copyright holder is the user creating the company, not the upstream repo author (they made the skills, the user is making the company). Use the same license type as the source repo (if from-repo) or ask the user (if from-scratch). Default to MIT if unclear.
+
+### Step 7: Write Files and Summarize
+
+Write all files, then give a brief summary:
+
+- Company name and what it does
+- Agent roster with roles and reporting structure
+- Skills (custom + referenced)
+- Projects and tasks if any
+- The output path
+
+## .paperclip.yaml Guidelines
+
+The `.paperclip.yaml` file is the Paperclip vendor extension. It configures adapters and env inputs per agent.
+
+### Adapter Rules
+
+**Do not specify an adapter unless the repo or user context warrants it.** If you don't know what adapter the user wants, omit the adapter block entirely — Paperclip will use its default. Specifying an unknown adapter type causes an import error.
+
+Paperclip's supported adapter types (these are the ONLY valid values):
+- `claude_local` — Claude Code CLI
+- `codex_local` — Codex CLI
+- `opencode_local` — OpenCode CLI
+- `pi_local` — Pi CLI
+- `cursor` — Cursor
+- `gemini_local` — Gemini CLI
+- `openclaw_gateway` — OpenClaw gateway
+
+Only set an adapter when:
+- The repo or its skills clearly target a specific runtime (e.g. gstack is built for Claude Code, so `claude_local` is appropriate)
+- The user explicitly requests a specific adapter
+- The agent's role requires a specific runtime capability
+
+### Env Inputs Rules
+
+**Do not add boilerplate env variables.** Only add env inputs that the agent actually needs based on its skills or role:
+- `GH_TOKEN` for agents that push code, create PRs, or interact with GitHub
+- API keys only when a skill explicitly requires them
+- Never set `ANTHROPIC_API_KEY` as a default empty env variable — the runtime handles this
+
+Example with adapter (only when warranted):
+```yaml
+schema: paperclip/v1
+agents:
+  release-engineer:
+    adapter:
+      type: claude_local
+      config:
+        model: claude-sonnet-4-6
+    inputs:
+      env:
+        GH_TOKEN:
+          kind: secret
+          requirement: optional
+```
+
+Example — only agents with actual overrides appear:
+```yaml
+schema: paperclip/v1
+agents:
+  release-engineer:
+    inputs:
+      env:
+        GH_TOKEN:
+          kind: secret
+          requirement: optional
+```
+
+In this example, only `release-engineer` appears because it needs `GH_TOKEN`. The other agents (ceo, cto, etc.) have no overrides, so they are omitted entirely from `.paperclip.yaml`.
+
+## External Skill References
+
+When referencing skills from a GitHub repo, always use the references pattern:
+
+```yaml
+metadata:
+  sources:
+    - kind: github-file
+      repo: owner/repo
+      path: path/to/SKILL.md
+      commit: <full SHA from git ls-remote or the repo>
+      attribution: Owner or Org Name
+      license: <from the repo's LICENSE>
+      usage: referenced
+```
+
+Get the commit SHA with:
+
+```bash
+git ls-remote https://github.com/owner/repo HEAD
+```
+
+Do NOT copy external skill content into the package unless the user explicitly asks.

.agents/skills/company-creator/references/companies-spec.md

@@ -0,0 +1,144 @@
+# Agent Companies Specification Reference
+
+The normative specification lives at:
+
+- Web: https://agentcompanies.io/specification
+- Local: docs/companies/companies-spec.md
+
+Read the local spec file before generating any package files. The spec defines the canonical format and all frontmatter fields. Below is a quick-reference summary for common authoring tasks.
+
+## Package Kinds
+
+| File       | Kind    | Purpose                                           |
+| ---------- | ------- | ------------------------------------------------- |
+| COMPANY.md | company | Root entrypoint, org boundary and defaults        |
+| TEAM.md    | team    | Reusable org subtree                              |
+| AGENTS.md  | agent   | One role, instructions, and attached skills       |
+| PROJECT.md | project | Planned work grouping                             |
+| TASK.md    | task    | Portable starter task                             |
+| SKILL.md   | skill   | Agent Skills capability package (do not redefine) |
+
+## Directory Layout
+
+```
+company-package/
+├── COMPANY.md
+├── agents/
+│   └── <slug>/AGENTS.md
+├── teams/
+│   └── <slug>/TEAM.md
+├── projects/
+│   └── <slug>/
+│       ├── PROJECT.md
+│       └── tasks/
+│           └── <slug>/TASK.md
+├── tasks/
+│   └── <slug>/TASK.md
+├── skills/
+│   └── <slug>/SKILL.md
+├── assets/
+├── scripts/
+├── references/
+└── .paperclip.yaml          (optional vendor extension)
+```
+
+## Common Frontmatter Fields
+
+```yaml
+schema: agentcompanies/v1
+kind: company | team | agent | project | task
+slug: url-safe-stable-identity
+name: Human Readable Name
+description: Short description for discovery
+version: 0.1.0
+license: MIT
+authors:
+  - name: Jane Doe
+tags: []
+metadata: {}
+sources: []
+```
+
+- `schema` usually appears only at package root
+- `kind` is optional when filename makes it obvious
+- `slug` must be URL-safe and stable
+- exporters should omit empty or default-valued fields
+
+## COMPANY.md Required Fields
+
+```yaml
+name: Company Name
+description: What this company does
+slug: company-slug
+schema: agentcompanies/v1
+```
+
+Optional: `version`, `license`, `authors`, `goals`, `includes`, `requirements.secrets`
+
+## AGENTS.md Key Fields
+
+```yaml
+name: Agent Name
+title: Role Title
+reportsTo: <agent-slug or null>
+skills:
+  - skill-shortname
+```
+
+- Body content is the agent's default instructions
+- Skills resolve by shortname: `skills/<shortname>/SKILL.md`
+- Do not export machine-specific paths or secrets
+
+## TEAM.md Key Fields
+
+```yaml
+name: Team Name
+description: What this team does
+slug: team-slug
+manager: ../agent-slug/AGENTS.md
+includes:
+  - ../agent-slug/AGENTS.md
+  - ../../skills/skill-slug/SKILL.md
+```
+
+## PROJECT.md Key Fields
+
+```yaml
+name: Project Name
+description: What this project delivers
+owner: agent-slug
+```
+
+## TASK.md Key Fields
+
+```yaml
+name: Task Name
+assignee: agent-slug
+project: project-slug
+schedule:
+  timezone: America/Chicago
+  startsAt: 2026-03-16T09:00:00-05:00
+  recurrence:
+    frequency: weekly
+    interval: 1
+    weekdays: [monday]
+    time: { hour: 9, minute: 0 }
+```
+
+## Source References (for external skills/content)
+
+```yaml
+sources:
+  - kind: github-file
+    repo: owner/repo
+    path: path/to/SKILL.md
+    commit: <full-sha>
+    sha256: <hash>
+    attribution: Owner Name
+    license: MIT
+    usage: referenced
+```
+
+Usage modes: `vendored` (bytes included), `referenced` (pointer only), `mirrored` (cached locally)
+
+Default to `referenced` for third-party content.

.agents/skills/company-creator/references/example-company.md

@@ -0,0 +1,191 @@
+# Example Company Package
+
+A minimal but complete example of an agent company package.
+
+## Directory Structure
+
+```
+lean-dev-shop/
+├── COMPANY.md
+├── agents/
+│   ├── ceo/AGENTS.md
+│   ├── cto/AGENTS.md
+│   └── engineer/AGENTS.md
+├── teams/
+│   └── engineering/TEAM.md
+├── projects/
+│   └── q2-launch/
+│       ├── PROJECT.md
+│       └── tasks/
+│           └── monday-review/TASK.md
+├── tasks/
+│   └── weekly-standup/TASK.md
+├── skills/
+│   └── code-review/SKILL.md
+└── .paperclip.yaml
+```
+
+## COMPANY.md
+
+```markdown
+---
+name: Lean Dev Shop
+description: Small engineering-focused AI company that builds and ships software products
+slug: lean-dev-shop
+schema: agentcompanies/v1
+version: 1.0.0
+license: MIT
+authors:
+  - name: Example Org
+goals:
+  - Build and ship software products
+  - Maintain high code quality
+---
+
+Lean Dev Shop is a small, focused engineering company. The CEO oversees strategy and coordinates work. The CTO leads the engineering team. Engineers build and ship code.
+```
+
+## agents/ceo/AGENTS.md
+
+```markdown
+---
+name: CEO
+title: Chief Executive Officer
+reportsTo: null
+skills:
+  - paperclip
+---
+
+You are the CEO of Lean Dev Shop. You oversee company strategy, coordinate work across the team, and ensure projects ship on time.
+
+Your responsibilities:
+
+- Review and prioritize work across projects
+- Coordinate with the CTO on technical decisions
+- Ensure the company goals are being met
+```
+
+## agents/cto/AGENTS.md
+
+```markdown
+---
+name: CTO
+title: Chief Technology Officer
+reportsTo: ceo
+skills:
+  - code-review
+  - paperclip
+---
+
+You are the CTO of Lean Dev Shop. You lead the engineering team and make technical decisions.
+
+Your responsibilities:
+
+- Set technical direction and architecture
+- Review code and ensure quality standards
+- Mentor engineers and unblock technical challenges
+```
+
+## agents/engineer/AGENTS.md
+
+```markdown
+---
+name: Engineer
+title: Software Engineer
+reportsTo: cto
+skills:
+  - code-review
+  - paperclip
+---
+
+You are a software engineer at Lean Dev Shop. You write code, fix bugs, and ship features.
+
+Your responsibilities:
+
+- Implement features and fix bugs
+- Write tests and documentation
+- Participate in code reviews
+
+Execution contract:
+
+- Start actionable implementation work in the same heartbeat; do not stop at a plan unless planning was requested.
+- Leave durable progress with a clear next action.
+- Use child issues for long or parallel delegated work instead of polling agents, sessions, or processes.
+- Mark blocked work with the unblock owner and action.
+```
+
+## teams/engineering/TEAM.md
+
+```markdown
+---
+name: Engineering
+description: Product and platform engineering team
+slug: engineering
+schema: agentcompanies/v1
+manager: ../../agents/cto/AGENTS.md
+includes:
+  - ../../agents/engineer/AGENTS.md
+  - ../../skills/code-review/SKILL.md
+tags:
+  - engineering
+---
+
+The engineering team builds and maintains all software products.
+```
+
+## projects/q2-launch/PROJECT.md
+
+```markdown
+---
+name: Q2 Launch
+description: Ship the Q2 product launch
+slug: q2-launch
+owner: cto
+---
+
+Deliver all features planned for the Q2 launch, including the new dashboard and API improvements.
+```
+
+## projects/q2-launch/tasks/monday-review/TASK.md
+
+```markdown
+---
+name: Monday Review
+assignee: ceo
+project: q2-launch
+schedule:
+  timezone: America/Chicago
+  startsAt: 2026-03-16T09:00:00-05:00
+  recurrence:
+    frequency: weekly
+    interval: 1
+    weekdays:
+      - monday
+    time:
+      hour: 9
+      minute: 0
+---
+
+Review the status of Q2 Launch project. Check progress on all open tasks, identify blockers, and update priorities for the week.
+```
+
+## skills/code-review/SKILL.md (with external reference)
+
+```markdown
+---
+name: code-review
+description: Thorough code review skill for pull requests and diffs
+metadata:
+  sources:
+    - kind: github-file
+      repo: anthropics/claude-code
+      path: skills/code-review/SKILL.md
+      commit: abc123def456
+      sha256: 3b7e...9a
+      attribution: Anthropic
+      license: MIT
+      usage: referenced
+---
+
+Review code changes for correctness, style, and potential issues.
+```

.agents/skills/company-creator/references/from-repo-guide.md

@@ -0,0 +1,79 @@
+# Creating a Company From an Existing Repository
+
+When a user provides a git repo (URL, local path, or tweet linking to a repo), analyze it and create a company package that wraps its content.
+
+## Analysis Steps
+
+1. **Clone or read the repo** - Use `git clone` for URLs, read directly for local paths
+2. **Scan for existing agent/skill files** - Look for SKILL.md, AGENTS.md, CLAUDE.md, .claude/ directories, or similar agent configuration
+3. **Understand the repo's purpose** - Read README, package.json, main source files to understand what the project does
+4. **Identify natural agent roles** - Based on the repo's structure and purpose, determine what agents would be useful
+
+## Handling Existing Skills
+
+Many repos already contain skills (SKILL.md files). When you find them:
+
+**Default behavior: use references, not copies.**
+
+Instead of copying skill content into your company package, create a source reference:
+
+```yaml
+metadata:
+  sources:
+    - kind: github-file
+      repo: owner/repo
+      path: path/to/SKILL.md
+      commit: <get the current HEAD commit SHA>
+      attribution: <repo owner or org name>
+      license: <from repo's LICENSE file>
+      usage: referenced
+```
+
+To get the commit SHA:
+```bash
+git ls-remote https://github.com/owner/repo HEAD
+```
+
+Only vendor (copy) skills when:
+- The user explicitly asks to copy them
+- The skill is very small and tightly coupled to the company
+- The source repo is private or may become unavailable
+
+## Handling Existing Agent Configurations
+
+If the repo has agent configs (CLAUDE.md, .claude/ directories, codex configs, etc.):
+- Use them as inspiration for AGENTS.md instructions
+- Don't copy them verbatim - adapt them to the Agent Companies format
+- Preserve the intent and key instructions
+
+## Repo-Only Skills (No Agents)
+
+When a repo contains only skills and no agents:
+- Create agents that would naturally use those skills
+- The agents should be minimal - just enough to give the skills a runtime context
+- A single agent may use multiple skills from the repo
+- Name agents based on the domain the skills cover
+
+Example: A repo with `code-review`, `testing`, and `deployment` skills might become:
+- A "Lead Engineer" agent with all three skills
+- Or separate "Reviewer", "QA Engineer", and "DevOps" agents if the skills are distinct enough
+
+## Common Repo Patterns
+
+### Developer Tools / CLI repos
+- Create agents for the tool's primary use cases
+- Reference any existing skills
+- Add a project maintainer or lead agent
+
+### Library / Framework repos
+- Create agents for development, testing, documentation
+- Skills from the repo become agent capabilities
+
+### Full Application repos
+- Map to departments: engineering, product, QA
+- Create a lean team structure appropriate to the project size
+
+### Skills Collection repos (e.g. skills.sh repos)
+- Each skill or skill group gets an agent
+- Create a lightweight company or team wrapper
+- Keep the agent count proportional to the skill diversity

.agents/skills/create-agent-adapter/SKILL.md

@@ -548,7 +548,7 @@ Import from `@paperclipai/adapter-utils/server-utils`:
 ### Prompt Templates
 - 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."`
+- Default prompt should use `DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE` from `@paperclipai/adapter-utils/server-utils` so local adapters share Paperclip's execution contract: act in the same heartbeat, avoid planning-only exits unless requested, leave durable progress and a next action, use child issues instead of polling, mark blockers with owner/action, and respect governance boundaries.
 
 ### Error Handling
 - Differentiate timeout vs process error vs parse failure

.agents/skills/deal-with-security-advisory/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: deal-with-security-advisory
+description: >
+  Handle a GitHub Security Advisory response for Paperclip, including
+  confidential fix development in a temporary private fork, human coordination
+  on advisory-thread comments, CVE request, synchronized advisory publication,
+  and immediate security release steps.
+---
+
+# Security Vulnerability Response Instructions
+
+## ⚠️ CRITICAL: This is a security vulnerability. Everything about this process is confidential until the advisory is published. Do not mention the vulnerability details in any public commit message, PR title, branch name, or comment. Do not push anything to a public branch. Do not discuss specifics in any public channel. Assume anything on the public repo is visible to attackers who will exploit the window between disclosure and user upgrades.
+
+***
+
+## Context
+
+A security vulnerability has been reported via GitHub Security Advisory:
+
+* **Advisory:** {{ghsaId}} (e.g. GHSA-x8hx-rhr2-9rf7)
+* **Reporter:** {{reporterHandle}}
+* **Severity:** {{severity}}
+* **Notes:** {{notes}}
+
+***
+
+## Step 0: Fetch the Advisory Details
+
+Pull the full advisory so you understand the vulnerability before doing anything else:
+
+```
+gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}}
+
+```
+
+Read the `description`, `severity`, `cvss`, and `vulnerabilities` fields. Understand the attack vector before writing code.
+
+## Step 1: Acknowledge the Report
+
+⚠️ **This step requires a human.** The advisory thread does not have a comment API. Ask the human operator to post a comment on the private advisory thread acknowledging the report. Provide them this template:
+
+> Thanks for the report, @{{reporterHandle}}. We've confirmed the issue and are working on a fix. We're targeting a patch release within {{timeframe}}. We'll keep you updated here.
+
+Give your human this template, but still continue
+
+Below we use `gh` tools - you do have access and credentials outside of your sandbox, so use them.
+
+## Step 2: Create the Temporary Private Fork
+
+This is where all fix development happens. Never push to the public repo.
+
+```
+gh api --method POST \
+  repos/paperclipai/paperclip/security-advisories/{{ghsaId}}/forks
+
+```
+
+This returns a repository object for the private fork. Save the `full_name` and `clone_url`.
+
+Clone it and set up your workspace:
+
+```
+# Clone the private fork somewhere outside ~/paperclip
+git clone <clone_url_from_response> ~/security-patch-{{ghsaId}}
+cd ~/security-patch-{{ghsaId}}
+git checkout -b security-fix
+
+```
+
+**Do not edit `~/paperclip`** — the dev server is running off the `~/paperclip` master branch and we don't want to touch it. All work happens in the private fork clone.
+
+**TIPS:**
+
+* Do not commit `pnpm-lock.yaml` — the repo has actions to manage this
+* Do not use descriptive branch names that leak the vulnerability (e.g., no `fix-dns-rebinding-rce`). Use something generic like `security-fix`
+* All work stays in the private fork until publication
+* CI/GitHub Actions will NOT run on the temporary private fork — this is a GitHub limitation by design. You must run tests locally
+
+## Step 3: Develop and Validate the Fix
+
+Write the patch. Same content standards as any PR:
+
+* It must functionally work — **run tests locally** since CI won't run on the private fork
+* Consider the whole codebase, not just the narrow vulnerability path. A patch that fixes one vector but opens another is worse than no patch
+* Ensure backwards compatibility for the database, or be explicit about what breaks
+* Make sure any UI components still look correct if the fix touches them
+* The fix should be minimal and focused — don't bundle unrelated changes into a security patch. Reviewers (and the reporter) should be able to read the diff and understand exactly what changed and why
+
+**Specific to security fixes:**
+
+* Verify the fix actually closes the attack vector described in the advisory. Reproduce the vulnerability first (using the reporter's description), then confirm the patch prevents it
+* Consider adjacent attack vectors — if DNS rebinding is the issue, are there other endpoints or modes with the same class of problem?
+* Do not introduce new dependencies unless absolutely necessary — new deps in a security patch raise eyebrows
+
+Push your fix to the private fork:
+
+```
+git add -A
+git commit -m "Fix security vulnerability"
+git push origin security-fix
+
+```
+
+## Step 4: Coordinate with the Reporter
+
+⚠️ **This step requires a human.** Ask the human operator to post on the advisory thread letting the reporter know the fix is ready and giving them a chance to review. Provide them this template:
+
+> @{{reporterHandle}} — fix is ready in the private fork if you'd like to review before we publish. Planning to release within {{timeframe}}.
+
+Proceed
+
+## Step 5: Request a CVE
+
+This makes vulnerability scanners (npm audit, Snyk, Dependabot) warn users to upgrade. Without it, nobody gets automated notification.
+
+```
+gh api --method POST \
+  repos/paperclipai/paperclip/security-advisories/{{ghsaId}}/cve
+
+```
+
+GitHub is a CVE Numbering Authority and will assign one automatically. The CVE may take a few hours to propagate after the advisory is published.
+
+## Step 6: Publish Everything Simultaneously
+
+This all happens at once — do not stagger these steps. The goal is **zero window** between the vulnerability becoming public knowledge and the fix being available.
+
+### 6a. Verify reporter credit before publishing
+
+```
+gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}} --jq '.credits'
+
+```
+
+If the reporter is not credited, add them:
+
+```
+gh api --method PATCH \
+  repos/paperclipai/paperclip/security-advisories/{{ghsaId}} \
+  --input - << 'EOF'
+{
+  "credits": [
+    {
+      "login": "{{reporterHandle}}",
+      "type": "reporter"
+    }
+  ]
+}
+EOF
+
+```
+
+### 6b. Update the advisory with the patched version and publish
+
+```
+gh api --method PATCH \
+  repos/paperclipai/paperclip/security-advisories/{{ghsaId}} \
+  --input - << 'EOF'
+{
+  "state": "published",
+  "vulnerabilities": [
+    {
+      "package": {
+        "ecosystem": "npm",
+        "name": "paperclip"
+      },
+      "vulnerable_version_range": "< {{patchedVersion}}",
+      "patched_versions": "{{patchedVersion}}"
+    }
+  ]
+}
+EOF
+
+```
+
+Publishing the advisory simultaneously:
+
+* Makes the GHSA public
+* Merges the temporary private fork into your repo
+* Triggers the CVE assignment (if requested in step 5)
+
+### 6c. Cut a release immediately after merge
+
+```
+cd ~/paperclip
+git pull origin master
+
+gh release create v{{patchedVersion}} \
+  --repo paperclipai/paperclip \
+  --title "v{{patchedVersion}} — Security Release" \
+  --notes "## Security Release
+
+This release fixes a critical security vulnerability.
+
+### What was fixed
+{{briefDescription}} (e.g., Remote code execution via DNS rebinding in \`local_trusted\` mode)
+
+### Advisory
+https://github.com/paperclipai/paperclip/security/advisories/{{ghsaId}}
+
+### Credit
+Thanks to @{{reporterHandle}} for responsibly disclosing this vulnerability.
+
+### Action required
+All users running versions prior to {{patchedVersion}} should upgrade immediately."
+
+```
+
+## Step 7: Post-Publication Verification
+
+```
+# Verify the advisory is published and CVE is assigned
+gh api repos/paperclipai/paperclip/security-advisories/{{ghsaId}} \
+  --jq '{state: .state, cve_id: .cve_id, published_at: .published_at}'
+
+# Verify the release exists
+gh release view v{{patchedVersion}} --repo paperclipai/paperclip
+
+```
+
+If the CVE hasn't been assigned yet, that's normal — it can take a few hours.
+
+⚠️ **Human step:** Ask the human operator to post a final comment on the advisory thread confirming publication and thanking the reporter.
+
+Tell the human operator what you did by posting a comment to this task, including:
+
+* The published advisory URL: `https://github.com/paperclipai/paperclip/security/advisories/{{ghsaId}}`
+* The release URL
+* Whether the CVE has been assigned yet
+* All URLs to any pull requests or branches

.agents/skills/doc-maintenance/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: doc-maintenance
+description: >
+  Audit top-level documentation (README, SPEC, PRODUCT) against recent git
+  history to find drift — shipped features missing from docs or features
+  listed as upcoming that already landed. Proposes minimal edits, creates
+  a branch, and opens a PR. Use when asked to review docs for accuracy,
+  after major feature merges, or on a periodic schedule.
+---
+
+# Doc Maintenance Skill
+
+Detect documentation drift and fix it via PR — no rewrites, no churn.
+
+## When to Use
+
+- Periodic doc review (e.g. weekly or after releases)
+- After major feature merges
+- When asked "are our docs up to date?"
+- When asked to audit README / SPEC / PRODUCT accuracy
+
+## Target Documents
+
+| Document | Path | What matters |
+|----------|------|-------------|
+| README | `README.md` | Features table, roadmap, quickstart, "what is" accuracy, "works with" table |
+| SPEC | `doc/SPEC.md` | No false "not supported" claims, major model/schema accuracy |
+| PRODUCT | `doc/PRODUCT.md` | Core concepts, feature list, principles accuracy |
+
+Out of scope: DEVELOPING.md, DATABASE.md, CLI.md, doc/plans/, skill files,
+release notes. These are dev-facing or ephemeral — lower risk of user-facing
+confusion.
+
+## Workflow
+
+### Step 1 — Detect what changed
+
+Find the last review cursor:
+
+```bash
+# Read the last-reviewed commit SHA
+CURSOR_FILE=".doc-review-cursor"
+if [ -f "$CURSOR_FILE" ]; then
+  LAST_SHA=$(cat "$CURSOR_FILE" | head -1)
+else
+  # First run: look back 60 days
+  LAST_SHA=$(git log --format="%H" --after="60 days ago" --reverse | head -1)
+fi
+```
+
+Then gather commits since the cursor:
+
+```bash
+git log "$LAST_SHA"..HEAD --oneline --no-merges
+```
+
+### Step 2 — Classify changes
+
+Scan commit messages and changed files. Categorize into:
+
+- **Feature** — new capabilities (keywords: `feat`, `add`, `implement`, `support`)
+- **Breaking** — removed/renamed things (keywords: `remove`, `breaking`, `drop`, `rename`)
+- **Structural** — new directories, config changes, new adapters, new CLI commands
+
+**Ignore:** refactors, test-only changes, CI config, dependency bumps, doc-only
+changes, style/formatting commits. These don't affect doc accuracy.
+
+For borderline cases, check the actual diff — a commit titled "refactor: X"
+that adds a new public API is a feature.
+
+### Step 3 — Build a change summary
+
+Produce a concise list like:
+
+```
+Since last review (<sha>, <date>):
+- FEATURE: Plugin system merged (runtime, SDK, CLI, slots, event bridge)
+- FEATURE: Project archiving added
+- BREAKING: Removed legacy webhook adapter
+- STRUCTURAL: New .agents/skills/ directory convention
+```
+
+If there are no notable changes, skip to Step 7 (update cursor and exit).
+
+### Step 4 — Audit each target doc
+
+For each target document, read it fully and cross-reference against the change
+summary. Check for:
+
+1. **False negatives** — major shipped features not mentioned at all
+2. **False positives** — features listed as "coming soon" / "roadmap" / "planned"
+   / "not supported" / "TBD" that already shipped
+3. **Quickstart accuracy** — install commands, prereqs, and startup instructions
+   still correct (README only)
+4. **Feature table accuracy** — does the features section reflect current
+   capabilities? (README only)
+5. **Works-with accuracy** — are supported adapters/integrations listed correctly?
+
+Use `references/audit-checklist.md` as the structured checklist.
+Use `references/section-map.md` to know where to look for each feature area.
+
+### Step 5 — Create branch and apply minimal edits
+
+```bash
+# Create a branch for the doc updates
+BRANCH="docs/maintenance-$(date +%Y%m%d)"
+git checkout -b "$BRANCH"
+```
+
+Apply **only** the edits needed to fix drift. Rules:
+
+- **Minimal patches only.** Fix inaccuracies, don't rewrite sections.
+- **Preserve voice and style.** Match the existing tone of each document.
+- **No cosmetic changes.** Don't fix typos, reformat tables, or reorganize
+  sections unless they're part of a factual fix.
+- **No new sections.** If a feature needs a whole new section, note it in the
+  PR description as a follow-up — don't add it in a maintenance pass.
+- **Roadmap items:** Move shipped features out of Roadmap. Add a brief mention
+  in the appropriate existing section if there isn't one already. Don't add
+  long descriptions.
+
+### Step 6 — Open a PR
+
+Commit the changes and open a PR:
+
+```bash
+git add README.md doc/SPEC.md doc/PRODUCT.md .doc-review-cursor
+git commit -m "docs: update documentation for accuracy
+
+- [list each fix briefly]
+
+Co-Authored-By: Paperclip <noreply@paperclip.ing>"
+
+git push -u origin "$BRANCH"
+
+gh pr create \
+  --title "docs: periodic documentation accuracy update" \
+  --body "$(cat <<'EOF'
+## Summary
+Automated doc maintenance pass. Fixes documentation drift detected since
+last review.
+
+### Changes
+- [list each fix]
+
+### Change summary (since last review)
+- [list notable code changes that triggered doc updates]
+
+## Review notes
+- Only factual accuracy fixes — no style/cosmetic changes
+- Preserves existing voice and structure
+- Larger doc additions (new sections, tutorials) noted as follow-ups
+
+🤖 Generated by doc-maintenance skill
+EOF
+)"
+```
+
+### Step 7 — Update the cursor
+
+After a successful audit (whether or not edits were needed), update the cursor:
+
+```bash
+git rev-parse HEAD > .doc-review-cursor
+```
+
+If edits were made, this is already committed in the PR branch. If no edits
+were needed, commit the cursor update to the current branch.
+
+## Change Classification Rules
+
+| Signal | Category | Doc update needed? |
+|--------|----------|-------------------|
+| `feat:`, `add`, `implement`, `support` in message | Feature | Yes if user-facing |
+| `remove`, `drop`, `breaking`, `!:` in message | Breaking | Yes |
+| New top-level directory or config file | Structural | Maybe |
+| `fix:`, `bugfix` | Fix | No (unless it changes behavior described in docs) |
+| `refactor:`, `chore:`, `ci:`, `test:` | Maintenance | No |
+| `docs:` | Doc change | No (already handled) |
+| Dependency bumps only | Maintenance | No |
+
+## Patch Style Guide
+
+- Fix the fact, not the prose
+- If removing a roadmap item, don't leave a gap — remove the bullet cleanly
+- If adding a feature mention, match the format of surrounding entries
+  (e.g. if features are in a table, add a table row)
+- Keep README changes especially minimal — it shouldn't churn often
+- For SPEC/PRODUCT, prefer updating existing statements over adding new ones
+  (e.g. change "not supported in V1" to "supported via X" rather than adding
+  a new section)
+
+## Output
+
+When the skill completes, report:
+
+- How many commits were scanned
+- How many notable changes were found
+- How many doc edits were made (and to which files)
+- PR link (if edits were made)
+- Any follow-up items that need larger doc work

.agents/skills/doc-maintenance/references/audit-checklist.md

@@ -0,0 +1,85 @@
+# Doc Maintenance Audit Checklist
+
+Use this checklist when auditing each target document. For each item, compare
+against the change summary from git history.
+
+## README.md
+
+### Features table
+- [ ] Each feature card reflects a shipped capability
+- [ ] No feature cards for things that don't exist yet
+- [ ] No major shipped features missing from the table
+
+### Roadmap
+- [ ] Nothing listed as "planned" or "coming soon" that already shipped
+- [ ] No removed/cancelled items still listed
+- [ ] Items reflect current priorities (cross-check with recent PRs)
+
+### Quickstart
+- [ ] `npx paperclipai onboard` command is correct
+- [ ] Manual install steps are accurate (clone URL, commands)
+- [ ] Prerequisites (Node version, pnpm version) are current
+- [ ] Server URL and port are correct
+
+### "What is Paperclip" section
+- [ ] High-level description is accurate
+- [ ] Step table (Define goal / Hire team / Approve and run) is correct
+
+### "Works with" table
+- [ ] All supported adapters/runtimes are listed
+- [ ] No removed adapters still listed
+- [ ] Logos and labels match current adapter names
+
+### "Paperclip is right for you if"
+- [ ] Use cases are still accurate
+- [ ] No claims about capabilities that don't exist
+
+### "Why Paperclip is special"
+- [ ] Technical claims are accurate (atomic execution, governance, etc.)
+- [ ] No features listed that were removed or significantly changed
+
+### FAQ
+- [ ] Answers are still correct
+- [ ] No references to removed features or outdated behavior
+
+### Development section
+- [ ] Commands are accurate (`pnpm dev`, `pnpm build`, etc.)
+- [ ] Link to DEVELOPING.md is correct
+
+## doc/SPEC.md
+
+### Company Model
+- [ ] Fields match current schema
+- [ ] Governance model description is accurate
+
+### Agent Model
+- [ ] Adapter types match what's actually supported
+- [ ] Agent configuration description is accurate
+- [ ] No features described as "not supported" or "not V1" that shipped
+
+### Task Model
+- [ ] Task hierarchy description is accurate
+- [ ] Status values match current implementation
+
+### Extensions / Plugins
+- [ ] If plugins are shipped, no "not in V1" or "future" language
+- [ ] Plugin model description matches implementation
+
+### Open Questions
+- [ ] Resolved questions removed or updated
+- [ ] No "TBD" items that have been decided
+
+## doc/PRODUCT.md
+
+### Core Concepts
+- [ ] Company, Employees, Task Management descriptions accurate
+- [ ] Agent Execution modes described correctly
+- [ ] No missing major concepts
+
+### Principles
+- [ ] Principles haven't been contradicted by shipped features
+- [ ] No principles referencing removed capabilities
+
+### User Flow
+- [ ] Dream scenario still reflects actual onboarding
+- [ ] Steps are achievable with current features

.agents/skills/doc-maintenance/references/section-map.md

@@ -0,0 +1,22 @@
+# Section Map
+
+Maps feature areas to specific document sections so the skill knows where to
+look when a feature ships or changes.
+
+| Feature Area | README Section | SPEC Section | PRODUCT Section |
+|-------------|---------------|-------------|----------------|
+| Plugins / Extensions | Features table, Roadmap | Extensions, Agent Model | Core Concepts |
+| Adapters (new runtimes) | "Works with" table, FAQ | Agent Model, Agent Configuration | Employees & Agents, Agent Execution |
+| Governance / Approvals | Features table, "Why special" | Board Governance, Board Approval Gates | Principles |
+| Budget / Cost Control | Features table, "Why special" | Budget Delegation | Company (revenue & expenses) |
+| Task Management | Features table | Task Model | Task Management |
+| Org Chart / Hierarchy | Features table | Agent Model (reporting) | Employees & Agents |
+| Multi-Company | Features table, FAQ | Company Model | Company |
+| Heartbeats | Features table, FAQ | Agent Execution | Agent Execution |
+| CLI Commands | Development section | — | — |
+| Onboarding / Quickstart | Quickstart, FAQ | — | User Flow |
+| Skills / Skill Injection | "Why special" | — | — |
+| Company Templates | "Why special", Roadmap (ClipMart) | — | — |
+| Mobile / UI | Features table | — | — |
+| Project Archiving | — | — | — |
+| OpenClaw Integration | "Works with" table, FAQ | Agent Model | Agent Execution |

.agents/skills/pr-report/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: pr-report
+description: >
+  Review a pull request or contribution deeply, explain it tutorial-style for a
+  maintainer, and produce a polished report artifact such as HTML or Markdown.
+  Use when asked to analyze a PR, explain a contributor's design decisions,
+  compare it with similar systems, or prepare a merge recommendation.
+---
+
+# PR Report Skill
+
+Produce a maintainer-grade review of a PR, branch, or large contribution.
+
+Default posture:
+
+- understand the change before judging it
+- explain the system as built, not just the diff
+- separate architectural problems from product-scope objections
+- make a concrete recommendation, not a vague impression
+
+## When to Use
+
+Use this skill when the user asks for things like:
+
+- "review this PR deeply"
+- "explain this contribution to me"
+- "make me a report or webpage for this PR"
+- "compare this design to similar systems"
+- "should I merge this?"
+
+## Outputs
+
+Common outputs:
+
+- standalone HTML report in `tmp/reports/...`
+- Markdown report in `report/` or another requested folder
+- short maintainer summary in chat
+
+If the user asks for a webpage, build a polished standalone HTML artifact with
+clear sections and readable visual hierarchy.
+
+Resources bundled with this skill:
+
+- `references/style-guide.md` for visual direction and report presentation rules
+- `assets/html-report-starter.html` for a reusable standalone HTML/CSS starter
+
+## Workflow
+
+### 1. Acquire and frame the target
+
+Work from local code when possible, not just the GitHub PR page.
+
+Gather:
+
+- target branch or worktree
+- diff size and changed subsystems
+- relevant repo docs, specs, and invariants
+- contributor intent if it is documented in PR text or design docs
+
+Start by answering: what is this change *trying* to become?
+
+### 2. Build a mental model of the system
+
+Do not stop at file-by-file notes. Reconstruct the design:
+
+- what new runtime or contract exists
+- which layers changed: db, shared types, server, UI, CLI, docs
+- lifecycle: install, startup, execution, UI, failure, disablement
+- trust boundary: what code runs where, under what authority
+
+For large contributions, include a tutorial-style section that teaches the
+system from first principles.
+
+### 3. Review like a maintainer
+
+Findings come first. Order by severity.
+
+Prioritize:
+
+- behavioral regressions
+- trust or security gaps
+- misleading abstractions
+- lifecycle and operational risks
+- coupling that will be hard to unwind
+- missing tests or unverifiable claims
+
+Always cite concrete file references when possible.
+
+### 4. Distinguish the objection type
+
+Be explicit about whether a concern is:
+
+- product direction
+- architecture
+- implementation quality
+- rollout strategy
+- documentation honesty
+
+Do not hide an architectural objection inside a scope objection.
+
+### 5. Compare to external precedents when needed
+
+If the contribution introduces a framework or platform concept, compare it to
+similar open-source systems.
+
+When comparing:
+
+- prefer official docs or source
+- focus on extension boundaries, context passing, trust model, and UI ownership
+- extract lessons, not just similarities
+
+Good comparison questions:
+
+- Who owns lifecycle?
+- Who owns UI composition?
+- Is context explicit or ambient?
+- Are plugins trusted code or sandboxed code?
+- Are extension points named and typed?
+
+### 6. Make the recommendation actionable
+
+Do not stop at "merge" or "do not merge."
+
+Choose one:
+
+- merge as-is
+- merge after specific redesign
+- salvage specific pieces
+- keep as design research
+
+If rejecting or narrowing, say what should be kept.
+
+Useful recommendation buckets:
+
+- keep the protocol/type model
+- redesign the UI boundary
+- narrow the initial surface area
+- defer third-party execution
+- ship a host-owned extension-point model first
+
+### 7. Build the artifact
+
+Suggested report structure:
+
+1. Executive summary
+2. What the PR actually adds
+3. Tutorial: how the system works
+4. Strengths
+5. Main findings
+6. Comparisons
+7. Recommendation
+
+For HTML reports:
+
+- use intentional typography and color
+- make navigation easy for long reports
+- favor strong section headings and small reference labels
+- avoid generic dashboard styling
+
+Before building from scratch, read `references/style-guide.md`.
+If a fast polished starter is helpful, begin from `assets/html-report-starter.html`
+and replace the placeholder content with the actual report.
+
+### 8. Verify before handoff
+
+Check:
+
+- artifact path exists
+- findings still match the actual code
+- any requested forbidden strings are absent from generated output
+- if tests were not run, say so explicitly
+
+## Review Heuristics
+
+### Plugin and platform work
+
+Watch closely for:
+
+- docs claiming sandboxing while runtime executes trusted host processes
+- module-global state used to smuggle React context
+- hidden dependence on render order
+- plugins reaching into host internals instead of using explicit APIs
+- "capabilities" that are really policy labels on top of fully trusted code
+
+### Good signs
+
+- typed contracts shared across layers
+- explicit extension points
+- host-owned lifecycle
+- honest trust model
+- narrow first rollout with room to grow
+
+## Final Response
+
+In chat, summarize:
+
+- where the report is
+- your overall call
+- the top one or two reasons
+- whether verification or tests were skipped
+
+Keep the chat summary shorter than the report itself.

.agents/skills/pr-report/assets/html-report-starter.html

@@ -0,0 +1,426 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>PR Report Starter</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=Newsreader:opsz,wght@6..72,500;6..72,700&display=swap"
+      rel="stylesheet"
+    />
+    <style>
+      :root {
+        --bg: #f4efe5;
+        --paper: rgba(255, 251, 244, 0.88);
+        --paper-strong: #fffaf1;
+        --ink: #1f1b17;
+        --muted: #6a6257;
+        --line: rgba(31, 27, 23, 0.12);
+        --accent: #9c4729;
+        --accent-soft: rgba(156, 71, 41, 0.1);
+        --good: #2f6a42;
+        --warn: #946200;
+        --bad: #8c2f25;
+        --shadow: 0 22px 60px rgba(52, 37, 19, 0.1);
+        --radius: 20px;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      html {
+        scroll-behavior: smooth;
+      }
+
+      body {
+        margin: 0;
+        color: var(--ink);
+        font-family: "IBM Plex Sans", sans-serif;
+        background:
+          radial-gradient(circle at top left, rgba(156, 71, 41, 0.12), transparent 34rem),
+          radial-gradient(circle at top right, rgba(47, 106, 66, 0.08), transparent 28rem),
+          linear-gradient(180deg, #efe6d6 0%, var(--bg) 48%, #ece5d8 100%);
+      }
+
+      .shell {
+        width: min(1360px, calc(100vw - 32px));
+        margin: 24px auto;
+        display: grid;
+        grid-template-columns: 280px minmax(0, 1fr);
+        gap: 24px;
+      }
+
+      .panel {
+        background: var(--paper);
+        backdrop-filter: blur(12px);
+        border: 1px solid var(--line);
+        border-radius: var(--radius);
+        box-shadow: var(--shadow);
+      }
+
+      .nav {
+        position: sticky;
+        top: 20px;
+        align-self: start;
+        padding: 22px;
+      }
+
+      .eyebrow {
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+        font-size: 11px;
+        font-weight: 700;
+        color: var(--accent);
+      }
+
+      .nav h1,
+      .hero h1,
+      h2,
+      h3 {
+        font-family: "Newsreader", serif;
+        line-height: 0.96;
+        margin: 0;
+      }
+
+      .nav h1 {
+        font-size: 2rem;
+        margin-top: 10px;
+      }
+
+      .nav p {
+        color: var(--muted);
+        font-size: 0.95rem;
+        line-height: 1.5;
+      }
+
+      .nav ul {
+        list-style: none;
+        padding: 0;
+        margin: 18px 0 0;
+        display: grid;
+        gap: 10px;
+      }
+
+      .nav a {
+        display: block;
+        color: var(--ink);
+        text-decoration: none;
+        padding: 10px 12px;
+        border-radius: 12px;
+        border: 1px solid transparent;
+        background: rgba(255, 255, 255, 0.35);
+      }
+
+      .nav a:hover {
+        border-color: var(--line);
+        background: rgba(255, 255, 255, 0.75);
+      }
+
+      .meta-block {
+        margin-top: 20px;
+        padding-top: 18px;
+        border-top: 1px solid var(--line);
+        color: var(--muted);
+        font-size: 0.86rem;
+        line-height: 1.5;
+      }
+
+      main {
+        display: grid;
+        gap: 24px;
+      }
+
+      section {
+        padding: 26px 28px 28px;
+      }
+
+      .hero {
+        padding: 28px;
+        overflow: hidden;
+        position: relative;
+      }
+
+      .hero::after {
+        content: "";
+        position: absolute;
+        inset: auto -3rem -6rem auto;
+        width: 18rem;
+        height: 18rem;
+        border-radius: 50%;
+        background: radial-gradient(circle, rgba(156, 71, 41, 0.14), transparent 68%);
+        pointer-events: none;
+      }
+
+      .hero h1 {
+        font-size: clamp(2.6rem, 5vw, 4.6rem);
+        max-width: 12ch;
+        margin-top: 12px;
+      }
+
+      .lede {
+        margin-top: 16px;
+        max-width: 70ch;
+        font-size: 1.05rem;
+        line-height: 1.65;
+        color: #2b2723;
+      }
+
+      .hero-grid,
+      .card-grid,
+      .two-col {
+        display: grid;
+        gap: 14px;
+      }
+
+      .hero-grid {
+        margin-top: 24px;
+        grid-template-columns: repeat(4, minmax(0, 1fr));
+      }
+
+      .card-grid {
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+      }
+
+      .two-col {
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+      }
+
+      .metric,
+      .card,
+      .finding {
+        padding: 18px;
+        background: rgba(255, 255, 255, 0.68);
+        border: 1px solid var(--line);
+        border-radius: 18px;
+      }
+
+      .metric .label {
+        color: var(--muted);
+        font-size: 0.82rem;
+        text-transform: uppercase;
+        letter-spacing: 0.08em;
+      }
+
+      .metric .value {
+        margin-top: 8px;
+        font-size: 1.45rem;
+        font-weight: 700;
+      }
+
+      h2 {
+        font-size: 2rem;
+        margin-bottom: 16px;
+      }
+
+      h3 {
+        font-size: 1.3rem;
+        margin-bottom: 10px;
+      }
+
+      p {
+        margin: 0 0 14px;
+        line-height: 1.65;
+      }
+
+      ul,
+      ol {
+        margin: 0;
+        padding-left: 20px;
+        line-height: 1.65;
+      }
+
+      li + li {
+        margin-top: 8px;
+      }
+
+      .badge-row {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+        margin: 18px 0 8px;
+      }
+
+      .badge {
+        display: inline-flex;
+        align-items: center;
+        gap: 8px;
+        padding: 8px 10px;
+        border-radius: 999px;
+        font-size: 0.82rem;
+        font-weight: 700;
+        border: 1px solid var(--line);
+        background: rgba(255, 255, 255, 0.68);
+      }
+
+      .badge.good {
+        color: var(--good);
+      }
+
+      .badge.warn {
+        color: var(--warn);
+      }
+
+      .badge.bad {
+        color: var(--bad);
+      }
+
+      .quote {
+        margin-top: 18px;
+        padding: 18px;
+        border-left: 4px solid var(--accent);
+        border-radius: 14px;
+        background: var(--accent-soft);
+      }
+
+      .severity {
+        display: inline-flex;
+        margin-bottom: 12px;
+        padding: 6px 10px;
+        border-radius: 999px;
+        font-size: 0.78rem;
+        font-weight: 700;
+        text-transform: uppercase;
+        letter-spacing: 0.08em;
+      }
+
+      .severity.high {
+        background: rgba(140, 47, 37, 0.12);
+        color: var(--bad);
+      }
+
+      .severity.medium {
+        background: rgba(148, 98, 0, 0.12);
+        color: var(--warn);
+      }
+
+      .severity.low {
+        background: rgba(47, 106, 66, 0.12);
+        color: var(--good);
+      }
+
+      .ref {
+        color: var(--muted);
+        font-size: 0.82rem;
+        line-height: 1.5;
+      }
+
+      @media (max-width: 980px) {
+        .shell {
+          grid-template-columns: 1fr;
+        }
+
+        .nav {
+          position: static;
+        }
+
+        .hero-grid,
+        .card-grid,
+        .two-col {
+          grid-template-columns: 1fr;
+        }
+
+        .hero h1 {
+          max-width: 100%;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <div class="shell">
+      <aside class="panel nav">
+        <div class="eyebrow">Maintainer Report</div>
+        <h1>Report Title</h1>
+        <p>Replace this with a concise description of what the report covers.</p>
+        <ul>
+          <li><a href="#summary">Summary</a></li>
+          <li><a href="#tutorial">Tutorial</a></li>
+          <li><a href="#findings">Findings</a></li>
+          <li><a href="#recommendation">Recommendation</a></li>
+        </ul>
+        <div class="meta-block">
+          Replace with project metadata, review date, or scope notes.
+        </div>
+      </aside>
+
+      <main>
+        <section class="panel hero" id="summary">
+          <div class="eyebrow">Executive Summary</div>
+          <h1>Use the hero for the clearest one-line judgment.</h1>
+          <p class="lede">
+            Replace this with the short explanation of what the contribution does, why it matters,
+            and what the core maintainer question is.
+          </p>
+          <div class="badge-row">
+            <span class="badge good">Strength</span>
+            <span class="badge warn">Tradeoff</span>
+            <span class="badge bad">Risk</span>
+          </div>
+          <div class="hero-grid">
+            <div class="metric">
+              <div class="label">Overall Call</div>
+              <div class="value">Placeholder</div>
+            </div>
+            <div class="metric">
+              <div class="label">Main Concern</div>
+              <div class="value">Placeholder</div>
+            </div>
+            <div class="metric">
+              <div class="label">Best Part</div>
+              <div class="value">Placeholder</div>
+            </div>
+            <div class="metric">
+              <div class="label">Weakest Part</div>
+              <div class="value">Placeholder</div>
+            </div>
+          </div>
+          <div class="quote">
+            Use this block for the thesis, a sharp takeaway, or a key cited point.
+          </div>
+        </section>
+
+        <section class="panel" id="tutorial">
+          <h2>Tutorial Section</h2>
+          <div class="two-col">
+            <div class="card">
+              <h3>Concept Card</h3>
+              <p>Use cards for mental models, subsystems, or comparison slices.</p>
+              <div class="ref">path/to/file.ts:10</div>
+            </div>
+            <div class="card">
+              <h3>Second Card</h3>
+              <p>Keep cards fairly dense. This template is about style, not fixed structure.</p>
+              <div class="ref">path/to/file.ts:20</div>
+            </div>
+          </div>
+        </section>
+
+        <section class="panel" id="findings">
+          <h2>Findings</h2>
+          <article class="finding">
+            <div class="severity high">High</div>
+            <h3>Finding Title</h3>
+            <p>Use findings for the sharpest judgment calls and risks.</p>
+            <div class="ref">path/to/file.ts:30</div>
+          </article>
+        </section>
+
+        <section class="panel" id="recommendation">
+          <h2>Recommendation</h2>
+          <div class="card-grid">
+            <div class="card">
+              <h3>Path Forward</h3>
+              <p>Use this area for merge guidance, salvage plan, or rollout advice.</p>
+            </div>
+            <div class="card">
+              <h3>What To Keep</h3>
+              <p>Call out the parts worth preserving even if the whole proposal should not land.</p>
+            </div>
+          </div>
+        </section>
+      </main>
+    </div>
+  </body>
+</html>

.agents/skills/pr-report/references/style-guide.md

@@ -0,0 +1,149 @@
+# PR Report Style Guide
+
+Use this guide when the user wants a report artifact, especially a webpage.
+
+## Goal
+
+Make the report feel like an editorial review, not an internal admin dashboard.
+The page should make a long technical argument easy to scan without looking
+generic or overdesigned.
+
+## Visual Direction
+
+Preferred tone:
+
+- editorial
+- warm
+- serious
+- high-contrast
+- handcrafted, not corporate SaaS
+
+Avoid:
+
+- default app-shell layouts
+- purple gradients on white
+- generic card dashboards
+- cramped pages with weak hierarchy
+- novelty fonts that hurt readability
+
+## Typography
+
+Recommended pattern:
+
+- one expressive serif or display face for major headings
+- one sturdy sans-serif for body copy and UI labels
+
+Good combinations:
+
+- Newsreader + IBM Plex Sans
+- Source Serif 4 + Instrument Sans
+- Fraunces + Public Sans
+- Libre Baskerville + Work Sans
+
+Rules:
+
+- headings should feel deliberate and large
+- body copy should stay comfortable for long reading
+- reference labels and badges should use smaller dense sans text
+
+## Layout
+
+Recommended structure:
+
+- a sticky side or top navigation for long reports
+- one strong hero summary at the top
+- panel or paper-like sections for each major topic
+- multi-column card grids for comparisons and strengths
+- single-column body text for findings and recommendations
+
+Use generous spacing. Long-form technical reports need breathing room.
+
+## Color
+
+Prefer muted paper-like backgrounds with one warm accent and one cool counterweight.
+
+Suggested token categories:
+
+- `--bg`
+- `--paper`
+- `--ink`
+- `--muted`
+- `--line`
+- `--accent`
+- `--good`
+- `--warn`
+- `--bad`
+
+The accent should highlight navigation, badges, and important labels. Do not
+let accent colors dominate body text.
+
+## Useful UI Elements
+
+Include small reusable styles for:
+
+- summary metrics
+- badges
+- quotes or callouts
+- finding cards
+- severity labels
+- reference labels
+- comparison cards
+- responsive two-column sections
+
+## Motion
+
+Keep motion restrained.
+
+Good:
+
+- soft fade/slide-in on first load
+- hover response on nav items or cards
+
+Bad:
+
+- constant animation
+- floating blobs
+- decorative motion with no reading benefit
+
+## Content Presentation
+
+Even when the user wants design polish, clarity stays primary.
+
+Good structure for long reports:
+
+1. executive summary
+2. what changed
+3. tutorial explanation
+4. strengths
+5. findings
+6. comparisons
+7. recommendation
+
+The exact headings can change. The important thing is to separate explanation
+from judgment.
+
+## References
+
+Reference labels should be visually quiet but easy to spot.
+
+Good pattern:
+
+- small muted text
+- monospace or compact sans
+- keep them close to the paragraph they support
+
+## Starter Usage
+
+If you need a fast polished base, start from:
+
+- `assets/html-report-starter.html`
+
+Customize:
+
+- fonts
+- color tokens
+- hero copy
+- section ordering
+- card density
+
+Do not preserve the placeholder sections if they do not fit the actual report.

.agents/skills/prcheckloop/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: prcheckloop
+description: >
+  Iteratively gets a GitHub pull request's checks green. Detects the PR for the
+  current branch or uses a provided PR number, waits for every check on the
+  latest head SHA to appear and finish, investigates failing checks, fixes
+  actionable code or test issues, pushes, and repeats. Escalates with a precise
+  blocker when failures are external, flaky, or not safely fixable. Use when a
+  PR still has unsuccessful checks after review fixes, including after greploop.
+---
+
+# PRCheckloop
+
+Get a GitHub PR to a fully green check state, or exit with a concrete blocker.
+
+## Scope
+
+- GitHub PRs only. If the repo is GitLab, stop and use `check-pr`.
+- Focus on checks for the latest PR head SHA, not old commits.
+- Focus on CI/status checks, not review comments or PR template cleanup.
+- If the user also wants review-comment cleanup, pair this with `check-pr`.
+
+## Inputs
+
+- **PR number** (optional): If not provided, detect the PR for the current branch.
+- **Max iterations**: default `5`.
+
+## Workflow
+
+### 1. Identify the PR
+
+If no PR number is provided, detect it from the current branch:
+
+```bash
+gh pr view --json number,headRefName,headRefOid,url,isDraft
+```
+
+If needed, switch to the PR branch before making changes.
+
+Stop early if:
+
+- `gh` is not authenticated
+- there is no PR for the branch
+- the repo is not hosted on GitHub
+
+### 2. Track the latest head SHA
+
+Always work against the current PR head SHA:
+
+```bash
+PR_JSON=$(gh pr view "$PR_NUMBER" --json number,headRefName,headRefOid,url)
+HEAD_SHA=$(echo "$PR_JSON" | jq -r .headRefOid)
+PR_URL=$(echo "$PR_JSON" | jq -r .url)
+```
+
+Ignore failing checks from older SHAs. After every push, refresh `HEAD_SHA` and
+restart the inspection loop.
+
+### 3. Inventory checks for that SHA
+
+Fetch both GitHub check runs and legacy commit status contexts:
+
+```bash
+gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/check-runs?per_page=100"
+gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/status"
+```
+
+For a compact PR-level view, this GraphQL payload is useful:
+
+```bash
+gh api graphql -f query='
+query($owner:String!, $repo:String!, $pr:Int!) {
+  repository(owner:$owner, name:$repo) {
+    pullRequest(number:$pr) {
+      headRefOid
+      url
+      statusCheckRollup {
+        contexts(first:100) {
+          nodes {
+            __typename
+            ... on CheckRun { name status conclusion detailsUrl workflowName }
+            ... on StatusContext { context state targetUrl description }
+          }
+        }
+      }
+    }
+  }
+}' -F owner=OWNER -F repo=REPO -F pr="$PR_NUMBER"
+```
+
+### 4. Wait for checks to actually run
+
+After a new push, checks can take a moment to appear. Poll every 15-30 seconds
+until one of these is true:
+
+- checks have appeared and every item is in a terminal state
+- checks have appeared and at least one failed
+- no checks appear after a reasonable wait, usually 2 minutes
+
+Treat these as terminal success states:
+
+- check runs: `SUCCESS`, `NEUTRAL`, `SKIPPED`
+- status contexts: `SUCCESS`
+
+Treat these as pending:
+
+- check runs: `QUEUED`, `PENDING`, `WAITING`, `REQUESTED`, `IN_PROGRESS`
+- status contexts: `PENDING`
+
+Treat these as failures:
+
+- check runs: `FAILURE`, `TIMED_OUT`, `CANCELLED`, `ACTION_REQUIRED`, `STARTUP_FAILURE`, `STALE`
+- status contexts: `FAILURE`, `ERROR`
+
+If no checks appear for the latest SHA, inspect `.github/workflows/`, workflow
+path filters, and branch protection expectations. If the missing check cannot be
+caused or fixed from the repo, escalate.
+
+### 5. Investigate failing checks
+
+For GitHub Actions failures, inspect runs and failed logs for the current SHA:
+
+```bash
+gh run list --commit "$HEAD_SHA" --json databaseId,workflowName,status,conclusion,url,headSha
+gh run view <RUN_ID> --json databaseId,name,workflowName,status,conclusion,jobs,url,headSha
+gh run view <RUN_ID> --log-failed
+```
+
+For each failing check, classify it:
+
+| Failure type | Action |
+|---|---|
+| Code/test regression | Reproduce locally, fix, and verify |
+| Lint/type/build mismatch | Run the matching local command from the workflow and fix it |
+| Flake or transient infra issue | Rerun once if evidence supports flakiness |
+| External service/status app failure | Escalate with the details URL and owner guess |
+| Missing secret/permission/branch protection issue | Escalate immediately |
+
+Only rerun a failed job once without code changes. Do not loop on reruns.
+
+### 6. Fix actionable failures
+
+If the failure is actionable from the checked-out code:
+
+1. Read the workflow or failing command to identify the real gate.
+2. Reproduce locally where reasonable.
+3. Make the smallest correct fix.
+4. Run focused verification first, then broader verification if needed.
+5. Commit in a logical commit.
+6. Push before re-checking the PR.
+
+Do not stop at a local fix. The loop is only complete when the remote PR checks
+for the new head SHA are green.
+
+### 7. Push and repeat
+
+After each fix:
+
+```bash
+git push
+sleep 5
+```
+
+Then refresh the PR metadata, get the new `HEAD_SHA`, and restart from Step 3.
+
+Exit the loop only when:
+
+- all checks for the latest head SHA are green, or
+- a blocker remains after reasonable repair effort, or
+- the max iteration count is reached
+
+### 8. Escalate blockers precisely
+
+If you cannot get the PR green, report:
+
+- PR URL
+- latest head SHA
+- exact failing or missing check names
+- details URLs
+- what you already tried
+- why it is blocked
+- who should likely unblock it
+- the next concrete action
+
+Good blocker examples:
+
+- external status app outage
+- missing GitHub secret or permission
+- required check name mismatch in branch protection
+- persistent flake after one rerun
+- failure needs credentials or infrastructure access you do not have
+
+## Output
+
+When the skill completes, report:
+
+- PR URL and branch
+- final head SHA
+- green/pending/failing check summary
+- fixes made and verification run
+- whether changes were pushed
+- blocker summary if not fully green
+
+## Notes
+
+- This skill is intentionally narrower than `check-pr`: it is a repair loop for
+  PR checks.
+- This skill complements `greploop`: Greptile can be perfect while CI is still
+  red.

.agents/skills/release-changelog/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: release-changelog
+description: >
+  Generate the stable Paperclip release changelog at releases/vYYYY.MDD.P.md by
+  reading commits, changesets, and merged PR context since the last stable tag.
+---
+
+# Release Changelog Skill
+
+Generate the user-facing changelog for the **stable** Paperclip release.
+
+## Versioning Model
+
+Paperclip uses **calendar versioning (calver)**:
+
+- Stable releases: `YYYY.MDD.P` (e.g. `2026.318.0`)
+- Canary releases: `YYYY.MDD.P-canary.N` (e.g. `2026.318.1-canary.0`)
+- Git tags: `vYYYY.MDD.P` for stable, `canary/vYYYY.MDD.P-canary.N` for canary
+
+There are no major/minor/patch bumps. The stable version is derived from the
+intended release date (UTC) plus the next same-day stable patch slot.
+
+Output:
+
+- `releases/vYYYY.MDD.P.md`
+
+Important rules:
+
+- even if there are canary releases such as `2026.318.1-canary.0`, the changelog file stays `releases/v2026.318.1.md`
+- do not derive versions from semver bump types
+- do not create canary changelog files
+
+## Step 0 — Idempotency Check
+
+Before generating anything, check whether the file already exists:
+
+```bash
+ls releases/vYYYY.MDD.P.md 2>/dev/null
+```
+
+If it exists:
+
+1. read it first
+2. present it to the reviewer
+3. ask whether to keep it, regenerate it, or update specific sections
+4. never overwrite it silently
+
+## Step 1 — Determine the Stable Range
+
+Find the last stable tag:
+
+```bash
+git tag --list 'v*' --sort=-version:refname | head -1
+git log v{last}..HEAD --oneline --no-merges
+```
+
+The stable version comes from one of:
+
+- an explicit maintainer request
+- `./scripts/release.sh stable --date YYYY-MM-DD --print-version`
+- the release plan already agreed in `doc/RELEASING.md`
+
+Do not derive the changelog version from a canary tag or prerelease suffix.
+Do not derive major/minor/patch bumps from API intent — calver uses the date and same-day stable slot.
+
+## Step 2 — Gather the Raw Inputs
+
+Collect release data from:
+
+1. git commits since the last stable tag
+2. `.changeset/*.md` files
+3. merged PRs via `gh` when available
+
+Useful commands:
+
+```bash
+git log v{last}..HEAD --oneline --no-merges
+git log v{last}..HEAD --format="%H %s" --no-merges
+ls .changeset/*.md | grep -v README.md
+gh pr list --state merged --search "merged:>={last-tag-date}" --json number,title,body,labels
+```
+
+## Step 3 — Detect Breaking Changes
+
+Look for:
+
+- destructive migrations
+- removed or changed API fields/endpoints
+- renamed or removed config keys
+- `BREAKING:` or `BREAKING CHANGE:` commit signals
+
+Key commands:
+
+```bash
+git diff --name-only v{last}..HEAD -- packages/db/src/migrations/
+git diff v{last}..HEAD -- packages/db/src/schema/
+git diff v{last}..HEAD -- server/src/routes/ server/src/api/
+git log v{last}..HEAD --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true
+```
+
+If breaking changes are detected, flag them prominently — they must appear in the
+Breaking Changes section with an upgrade path.
+
+## Step 4 — Categorize for Users
+
+Use these stable changelog sections:
+
+- `Breaking Changes`
+- `Highlights`
+- `Improvements`
+- `Fixes`
+- `Upgrade Guide` when needed
+
+Exclude purely internal refactors, CI changes, and docs-only work unless they materially affect users.
+
+Guidelines:
+
+- group related commits into one user-facing entry
+- write from the user perspective
+- keep highlights short and concrete
+- spell out upgrade actions for breaking changes
+
+### Inline PR and contributor attribution
+
+When a bullet item clearly maps to a merged pull request, add inline attribution at the
+end of the entry in this format:
+
+```
+- **Feature name** — Description. ([#123](https://github.com/paperclipai/paperclip/pull/123), @contributor1, @contributor2)
+```
+
+Rules:
+
+- Only add a PR link when you can confidently trace the bullet to a specific merged PR.
+  Use merge commit messages (`Merge pull request #N from user/branch`) to map PRs.
+- List the contributor(s) who authored the PR. Use GitHub usernames, not real names or emails.
+- If multiple PRs contributed to a single bullet, list them all: `([#10](url), [#12](url), @user1, @user2)`.
+- If you cannot determine the PR number or contributor with confidence, omit the attribution
+  parenthetical — do not guess.
+- Core maintainer commits that don't have an external PR can omit the parenthetical.
+
+## Step 5 — Write the File
+
+Template:
+
+```markdown
+# vYYYY.MDD.P
+
+> Released: YYYY-MM-DD
+
+## Breaking Changes
+
+## Highlights
+
+## Improvements
+
+## Fixes
+
+## Upgrade Guide
+
+## Contributors
+
+Thank you to everyone who contributed to this release!
+
+@username1, @username2, @username3
+```
+
+Omit empty sections except `Highlights`, `Improvements`, and `Fixes`, which should usually exist.
+
+The `Contributors` section should always be included. List every person who authored
+commits in the release range, @-mentioning them by their **GitHub username** (not their
+real name or email). To find GitHub usernames:
+
+1. Extract usernames from merge commit messages: `git log v{last}..HEAD --oneline --merges` — the branch prefix (e.g. `from username/branch`) gives the GitHub username.
+2. For noreply emails like `user@users.noreply.github.com`, the username is the part before `@`.
+3. For contributors whose username is ambiguous, check `gh api users/{guess}` or the PR page.
+
+**Never expose contributor email addresses.** Use `@username` only.
+
+Exclude bot accounts (e.g. `lockfile-bot`, `dependabot`) from the list. List contributors
+in alphabetical order by GitHub username (case-insensitive).
+
+## Step 6 — Review Before Release
+
+Before handing it off:
+
+1. confirm the heading is the stable version only
+2. confirm there is no `-canary` language in the title or filename
+3. confirm any breaking changes have an upgrade path
+4. present the draft for human sign-off
+
+This skill never publishes anything. It only prepares the stable changelog artifact.

.agents/skills/release/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: release
+description: >
+  Coordinate a full Paperclip release across engineering verification, npm,
+  GitHub, smoke testing, and announcement follow-up. Use when leadership asks
+  to ship a release, not merely to discuss versioning.
+---
+
+# Release Coordination Skill
+
+Run the full Paperclip maintainer release workflow, not just an npm publish.
+
+This skill coordinates:
+
+- stable changelog drafting via `release-changelog`
+- canary verification and publish status from `master`
+- Docker smoke testing via `scripts/docker-onboard-smoke.sh`
+- manual stable promotion from a chosen source ref
+- GitHub Release creation
+- website / announcement follow-up tasks
+
+## Trigger
+
+Use this skill when leadership asks for:
+
+- "do a release"
+- "ship the release"
+- "promote this canary to stable"
+- "cut the stable release"
+
+## Preconditions
+
+Before proceeding, verify all of the following:
+
+1. `.agents/skills/release-changelog/SKILL.md` exists and is usable.
+2. The repo working tree is clean, including untracked files.
+3. There is at least one canary or candidate commit since the last stable tag.
+4. The candidate SHA has passed the verification gate or is about to.
+5. If manifests changed, the CI-owned `pnpm-lock.yaml` refresh is already merged on `master`.
+6. npm publish rights are available through GitHub trusted publishing, or through local npm auth for emergency/manual use.
+7. If running through Paperclip, you have issue context for status updates and follow-up task creation.
+
+If any precondition fails, stop and report the blocker.
+
+## Inputs
+
+Collect these inputs up front:
+
+- whether the target is a canary check or a stable promotion
+- the candidate `source_ref` for stable
+- whether the stable run is dry-run or live
+- release issue / company context for website and announcement follow-up
+
+## Step 0 — Release Model
+
+Paperclip now uses a commit-driven release model:
+
+1. every push to `master` publishes a canary automatically
+2. canaries use `YYYY.MDD.P-canary.N`
+3. stable releases use `YYYY.MDD.P`
+4. the middle slot is `MDD`, where `M` is the UTC month and `DD` is the zero-padded UTC day
+5. the stable patch slot increments when more than one stable ships on the same UTC date
+6. stable releases are manually promoted from a chosen tested commit or canary source commit
+7. only stable releases get `releases/vYYYY.MDD.P.md`, git tag `vYYYY.MDD.P`, and a GitHub Release
+
+Critical consequences:
+
+- do not use release branches as the default path
+- do not derive major/minor/patch bumps
+- do not create canary changelog files
+- do not create canary GitHub Releases
+
+## Step 1 — Choose the Candidate
+
+For canary validation:
+
+- inspect the latest successful canary run on `master`
+- record the canary version and source SHA
+
+For stable promotion:
+
+1. choose the tested source ref
+2. confirm it is the exact SHA you want to promote
+3. resolve the target stable version with `./scripts/release.sh stable --date YYYY-MM-DD --print-version`
+
+Useful commands:
+
+```bash
+git tag --list 'v*' --sort=-version:refname | head -1
+git log --oneline --no-merges
+npm view paperclipai@canary version
+```
+
+## Step 2 — Draft the Stable Changelog
+
+Stable changelog files live at:
+
+- `releases/vYYYY.MDD.P.md`
+
+Invoke `release-changelog` and generate or update the stable notes only.
+
+Rules:
+
+- review the draft with a human before publish
+- preserve manual edits if the file already exists
+- keep the filename stable-only
+- do not create a canary changelog file
+
+## Step 3 — Verify the Candidate SHA
+
+Run the standard gate:
+
+```bash
+pnpm -r typecheck
+pnpm test:run
+pnpm build
+```
+
+If the GitHub release workflow will run the publish, it can rerun this gate. Still report local status if you checked it.
+
+For PRs that touch release logic, the repo also runs a canary release dry-run in CI. That is a release-specific guard, not a substitute for the standard gate.
+
+## Step 4 — Validate the Canary
+
+The normal canary path is automatic from `master` via:
+
+- `.github/workflows/release.yml`
+
+Confirm:
+
+1. verification passed
+2. npm canary publish succeeded
+3. git tag `canary/vYYYY.MDD.P-canary.N` exists
+
+Useful checks:
+
+```bash
+npm view paperclipai@canary version
+git tag --list 'canary/v*' --sort=-version:refname | head -5
+```
+
+## Step 5 — Smoke Test the Canary
+
+Run:
+
+```bash
+PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
+```
+
+Useful isolated variant:
+
+```bash
+HOST_PORT=3232 DATA_DIR=./data/release-smoke-canary PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
+```
+
+Confirm:
+
+1. install succeeds
+2. onboarding completes without crashes
+3. the server boots
+4. the UI loads
+5. basic company creation and dashboard load work
+
+If smoke testing fails:
+
+- stop the stable release
+- fix the issue on `master`
+- wait for the next automatic canary
+- rerun smoke testing
+
+## Step 6 — Preview or Publish Stable
+
+The normal stable path is manual `workflow_dispatch` on:
+
+- `.github/workflows/release.yml`
+
+Inputs:
+
+- `source_ref`
+- `stable_date`
+- `dry_run`
+
+Before live stable:
+
+1. resolve the target stable version with `./scripts/release.sh stable --date YYYY-MM-DD --print-version`
+2. ensure `releases/vYYYY.MDD.P.md` exists on the source ref
+3. run the stable workflow in dry-run mode first when practical
+4. then run the real stable publish
+
+The stable workflow:
+
+- re-verifies the exact source ref
+- computes the next stable patch slot for the chosen UTC date
+- publishes `YYYY.MDD.P` under dist-tag `latest`
+- creates git tag `vYYYY.MDD.P`
+- creates or updates the GitHub Release from `releases/vYYYY.MDD.P.md`
+
+Local emergency/manual commands:
+
+```bash
+./scripts/release.sh stable --dry-run
+./scripts/release.sh stable
+git push public-gh refs/tags/vYYYY.MDD.P
+./scripts/create-github-release.sh YYYY.MDD.P
+```
+
+## Step 7 — Finish the Other Surfaces
+
+Create or verify follow-up work for:
+
+- website changelog publishing
+- launch post / social announcement
+- release summary in Paperclip issue context
+
+These should reference the stable release, not the canary.
+
+## Failure Handling
+
+If the canary is bad:
+
+- publish another canary, do not ship stable
+
+If stable npm publish succeeds but tag push or GitHub release creation fails:
+
+- fix the git/GitHub issue immediately from the same release result
+- do not republish the same version
+
+If `latest` is bad after stable publish:
+
+```bash
+./scripts/rollback-latest.sh <last-good-version>
+```
+
+Then fix forward with a new stable release.
+
+## Output
+
+When the skill completes, provide:
+
+- candidate SHA and tested canary version, if relevant
+- stable version, if promoted
+- verification status
+- npm status
+- smoke-test status
+- git tag / GitHub Release status
+- website / announcement follow-up status
+- rollback recommendation if anything is still partially complete

.changeset/README.md

@@ -1,8 +0,0 @@
-# Changesets
-
-Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
-with multi-package repos, or single-package repos to help you version and publish your code. You can
-find the full documentation for it [in our repository](https://github.com/changesets/changesets).
-
-We have a quick list of common questions to get you started engaging with this project in
-[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

.changeset/config.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.3/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": false,
-  "fixed": [["@paperclipai/*", "paperclipai"]],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "master",
-  "updateInternalDependencies": "patch",
-  "ignore": ["@paperclipai/ui"]
-}

.claude/skills/company-creator

@@ -0,0 +1 @@
+../../.agents/skills/company-creator

.env.example

@@ -1,3 +1,7 @@
 DATABASE_URL=postgres://paperclip:paperclip@localhost:5432/paperclip
 PORT=3100
 SERVE_UI=false
+BETTER_AUTH_SECRET=paperclip-dev-secret
+
+# Discord webhook for daily merge digest (scripts/discord-daily-digest.sh)
+# DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

.github/CODEOWNERS

@@ -0,0 +1,17 @@
+# Replace @cryppadotta if a different maintainer or team should own release infrastructure.
+
+.github/** @cryppadotta @devinfoley
+scripts/release*.sh @cryppadotta @devinfoley
+scripts/release-*.mjs @cryppadotta @devinfoley
+scripts/create-github-release.sh @cryppadotta @devinfoley
+scripts/rollback-latest.sh @cryppadotta @devinfoley
+doc/RELEASING.md @cryppadotta @devinfoley
+doc/PUBLISHING.md @cryppadotta @devinfoley
+doc/RELEASE-AUTOMATION-SETUP.md @cryppadotta @devinfoley
+
+# Package files — dependency changes require review
+# package.json matches recursively at all depths (covers root + all workspaces)
+package.json @cryppadotta @devinfoley
+pnpm-lock.yaml @cryppadotta @devinfoley
+pnpm-workspace.yaml @cryppadotta @devinfoley
+.npmrc @cryppadotta @devinfoley

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,68 @@
+## Thinking Path
+
+<!--
+  Required. Trace your reasoning from the top of the project down to this
+  specific change. Start with what Paperclip is, then narrow through the
+  subsystem, the problem, and why this PR exists. Use blockquote style.
+  Aim for 5–8 steps. See CONTRIBUTING.md for full examples.
+-->
+
+> - Paperclip orchestrates AI agents for zero-human companies
+> - [Which subsystem or capability is involved]
+> - [What problem or gap exists]
+> - [Why it needs to be addressed]
+> - This pull request ...
+> - The benefit is ...
+
+## What Changed
+
+<!-- Bullet list of concrete changes. One bullet per logical unit. -->
+
+-
+
+## Verification
+
+<!--
+  How can a reviewer confirm this works? Include test commands, manual
+  steps, or both. For UI changes, include before/after screenshots.
+-->
+
+-
+
+## Risks
+
+<!--
+  What could go wrong? Mention migration safety, breaking changes,
+  behavioral shifts, or "Low risk" if genuinely minor.
+-->
+
+-
+
+> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`.
+
+## Model Used
+
+<!--
+  Required. Specify which AI model was used to produce or assist with
+  this change. Be as descriptive as possible — include:
+    • Provider and model name (e.g., Claude, GPT, Gemini, Codex)
+    • Exact model ID or version (e.g., claude-opus-4-6, gpt-4-turbo-2024-04-09)
+    • Context window size if relevant (e.g., 1M context)
+    • Reasoning/thinking mode if applicable (e.g., extended thinking, chain-of-thought)
+    • Any other relevant capability details (e.g., tool use, code execution)
+  If no AI model was used, write "None — human-authored".
+-->
+
+-
+
+## Checklist
+
+- [ ] I have included a thinking path that traces from project context to this change
+- [ ] I have specified the model used (with version and capability details)
+- [ ] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
+- [ ] I have run tests locally and they pass
+- [ ] I have added or updated tests where applicable
+- [ ] If this change affects the UI, I have included before/after screenshots
+- [ ] I have updated relevant documentation to reflect my changes
+- [ ] I have considered and documented any risks above
+- [ ] I will address all Greptile and reviewer comments before requesting merge

.github/workflows/docker.yml

@@ -0,0 +1,55 @@
+name: Docker
+
+on:
+  push:
+    branches:
+      - "master"
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    concurrency:
+      group: docker-${{ github.ref }}
+      cancel-in-progress: true
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/e2e.yml

@@ -0,0 +1,44 @@
+name: E2E Tests
+
+on:
+  workflow_dispatch:
+    inputs:
+      skip_llm:
+        description: "Skip LLM-dependent assertions (default: true)"
+        type: boolean
+        default: true
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      PAPERCLIP_E2E_SKIP_LLM: ${{ inputs.skip_llm && 'true' || 'false' }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: npx playwright install --with-deps chromium
+
+      - name: Run e2e tests
+        run: pnpm run test:e2e
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: |
+            tests/e2e/playwright-report/
+            tests/e2e/test-results/
+          retention-days: 14

.github/workflows/pr.yml

@@ -0,0 +1,186 @@
+name: PR
+
+on:
+  pull_request:
+    branches:
+      - master
+
+concurrency:
+  group: pr-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  policy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Block manual lockfile edits
+        if: github.head_ref != 'chore/refresh-lockfile'
+        run: |
+          changed="$(git diff --name-only "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}")"
+          if printf '%s\n' "$changed" | grep -qx 'pnpm-lock.yaml'; then
+            echo "Do not commit pnpm-lock.yaml in pull requests. CI owns lockfile updates."
+            exit 1
+          fi
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Validate Dockerfile deps stage
+        run: |
+          missing=0
+
+          # Extract only the deps stage from the Dockerfile
+          deps_stage="$(awk '/^FROM .* AS deps$/{found=1; next} found && /^FROM /{exit} found{print}' Dockerfile)"
+
+          if [ -z "$deps_stage" ]; then
+            echo "::error::Could not extract deps stage from Dockerfile (expected 'FROM ... AS deps')"
+            exit 1
+          fi
+
+          # Derive workspace search roots from pnpm-workspace.yaml (exclude dev-only packages)
+          search_roots="$(grep '^ *- ' pnpm-workspace.yaml | sed 's/^ *- //' | sed 's/\*$//' | grep -v 'examples' | grep -v 'create-paperclip-plugin' | tr '\n' ' ')"
+
+          if [ -z "$search_roots" ]; then
+            echo "::error::Could not derive workspace roots from pnpm-workspace.yaml"
+            exit 1
+          fi
+
+          # Check all workspace package.json files are copied in the deps stage
+          for pkg in $(find $search_roots -maxdepth 2 -name package.json -not -path '*/examples/*' -not -path '*/create-paperclip-plugin/*' -not -path '*/node_modules/*' 2>/dev/null | sort -u); do
+            dir="$(dirname "$pkg")"
+            if ! echo "$deps_stage" | grep -q "^COPY ${dir}/package.json"; then
+              echo "::error::Dockerfile deps stage missing: COPY ${pkg} ${dir}/"
+              missing=1
+            fi
+          done
+
+          # Check patches directory is copied if it exists
+          if [ -d patches ] && ! echo "$deps_stage" | grep -q '^COPY patches/'; then
+            echo "::error::Dockerfile deps stage missing: COPY patches/ patches/"
+            missing=1
+          fi
+
+          if [ "$missing" -eq 1 ]; then
+            echo "Dockerfile deps stage is out of sync. Update it to include the missing files."
+            exit 1
+          fi
+
+      - name: Validate dependency resolution when manifests change
+        run: |
+          changed="$(git diff --name-only "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}")"
+          manifest_pattern='(^|/)package\.json$|^pnpm-workspace\.yaml$|^\.npmrc$|^pnpmfile\.(cjs|js|mjs)$'
+          if printf '%s\n' "$changed" | grep -Eq "$manifest_pattern"; then
+            pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile
+          fi
+
+  verify:
+    needs: [policy]
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm -r typecheck
+
+      - name: Run tests
+        run: pnpm test:run
+
+      - name: Build
+        run: pnpm build
+
+      - name: Release canary dry run
+        run: |
+          git checkout -B master HEAD
+          git checkout -- pnpm-lock.yaml
+          ./scripts/release.sh canary --skip-verify --dry-run
+
+  e2e:
+    needs: [policy]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Install Playwright
+        run: npx playwright install --with-deps chromium
+
+      - name: Generate Paperclip config
+        run: |
+          mkdir -p ~/.paperclip/instances/default
+          cat > ~/.paperclip/instances/default/config.json << 'CONF'
+          {
+            "$meta": { "version": 1, "updatedAt": "2026-01-01T00:00:00.000Z", "source": "onboard" },
+            "database": { "mode": "embedded-postgres" },
+            "logging": { "mode": "file" },
+            "server": { "deploymentMode": "local_trusted", "host": "127.0.0.1", "port": 3100 },
+            "auth": { "baseUrlMode": "auto" },
+            "storage": { "provider": "local_disk" },
+            "secrets": { "provider": "local_encrypted", "strictMode": false }
+          }
+          CONF
+
+      - name: Run e2e tests
+        env:
+          PAPERCLIP_E2E_SKIP_LLM: "true"
+        run: pnpm run test:e2e
+
+      - name: Upload Playwright report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: |
+            tests/e2e/playwright-report/
+            tests/e2e/test-results/
+          retention-days: 14

.github/workflows/refresh-lockfile.yml

@@ -0,0 +1,96 @@
+name: Refresh Lockfile
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+concurrency:
+  group: refresh-lockfile-master
+  cancel-in-progress: false
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Refresh pnpm lockfile
+        run: pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile
+
+      - name: Fail on unexpected file changes
+        run: |
+          changed="$(git status --porcelain)"
+          if [ -z "$changed" ]; then
+            echo "Lockfile is already up to date."
+            exit 0
+          fi
+          if printf '%s\n' "$changed" | grep -Fvq ' pnpm-lock.yaml'; then
+            echo "Unexpected files changed during lockfile refresh:"
+            echo "$changed"
+            exit 1
+          fi
+
+      - name: Create or update pull request
+        id: upsert-pr
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO_OWNER: ${{ github.repository_owner }}
+        run: |
+          if git diff --quiet -- pnpm-lock.yaml; then
+            echo "Lockfile unchanged, nothing to do."
+            echo "pr_url=" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          BRANCH="chore/refresh-lockfile"
+          git config user.name "lockfile-bot"
+          git config user.email "lockfile-bot@users.noreply.github.com"
+
+          git checkout -B "$BRANCH"
+          git add pnpm-lock.yaml
+          git commit -m "chore(lockfile): refresh pnpm-lock.yaml"
+          git push --force origin "$BRANCH"
+
+          # Only reuse an open PR from this repository owner, not a fork with the same branch name.
+          pr_url="$(
+            gh pr list --state open --head "$BRANCH" --json url,headRepositoryOwner \
+              --jq ".[] | select(.headRepositoryOwner.login == \"$REPO_OWNER\") | .url" |
+            head -n 1
+          )"
+          if [ -z "$pr_url" ]; then
+            pr_url="$(gh pr create \
+              --head "$BRANCH" \
+              --title "chore(lockfile): refresh pnpm-lock.yaml" \
+              --body "Auto-generated lockfile refresh after dependencies changed on master. This PR only updates pnpm-lock.yaml.")"
+            echo "Created new PR: $pr_url"
+          else
+            echo "PR already exists: $pr_url"
+          fi
+          echo "pr_url=$pr_url" >> "$GITHUB_OUTPUT"
+
+      - name: Enable auto-merge for lockfile PR
+        if: steps.upsert-pr.outputs.pr_url != ''
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh pr merge --auto --squash --delete-branch "${{ steps.upsert-pr.outputs.pr_url }}"

.github/workflows/release-smoke.yml

@@ -0,0 +1,118 @@
+name: Release Smoke
+
+on:
+  workflow_dispatch:
+    inputs:
+      paperclip_version:
+        description: Published Paperclip dist-tag to test
+        required: true
+        default: canary
+        type: choice
+        options:
+          - canary
+          - latest
+      host_port:
+        description: Host port for the Docker smoke container
+        required: false
+        default: "3232"
+        type: string
+      artifact_name:
+        description: Artifact name for uploaded diagnostics
+        required: false
+        default: release-smoke
+        type: string
+  workflow_call:
+    inputs:
+      paperclip_version:
+        required: true
+        type: string
+      host_port:
+        required: false
+        default: "3232"
+        type: string
+      artifact_name:
+        required: false
+        default: release-smoke
+        type: string
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Install Playwright browser
+        run: npx playwright install --with-deps chromium
+
+      - name: Launch Docker smoke harness
+        run: |
+          metadata_file="$RUNNER_TEMP/release-smoke.env"
+          HOST_PORT="${{ inputs.host_port }}" \
+          DATA_DIR="$RUNNER_TEMP/release-smoke-data" \
+          PAPERCLIPAI_VERSION="${{ inputs.paperclip_version }}" \
+          SMOKE_DETACH=true \
+          SMOKE_METADATA_FILE="$metadata_file" \
+          ./scripts/docker-onboard-smoke.sh
+          set -a
+          source "$metadata_file"
+          set +a
+          {
+            echo "SMOKE_BASE_URL=$SMOKE_BASE_URL"
+            echo "SMOKE_ADMIN_EMAIL=$SMOKE_ADMIN_EMAIL"
+            echo "SMOKE_ADMIN_PASSWORD=$SMOKE_ADMIN_PASSWORD"
+            echo "SMOKE_CONTAINER_NAME=$SMOKE_CONTAINER_NAME"
+            echo "SMOKE_DATA_DIR=$SMOKE_DATA_DIR"
+            echo "SMOKE_IMAGE_NAME=$SMOKE_IMAGE_NAME"
+            echo "SMOKE_PAPERCLIPAI_VERSION=$SMOKE_PAPERCLIPAI_VERSION"
+            echo "SMOKE_METADATA_FILE=$metadata_file"
+          } >> "$GITHUB_ENV"
+
+      - name: Run release smoke Playwright suite
+        env:
+          PAPERCLIP_RELEASE_SMOKE_BASE_URL: ${{ env.SMOKE_BASE_URL }}
+          PAPERCLIP_RELEASE_SMOKE_EMAIL: ${{ env.SMOKE_ADMIN_EMAIL }}
+          PAPERCLIP_RELEASE_SMOKE_PASSWORD: ${{ env.SMOKE_ADMIN_PASSWORD }}
+        run: pnpm run test:release-smoke
+
+      - name: Capture Docker logs
+        if: always()
+        run: |
+          if [[ -n "${SMOKE_CONTAINER_NAME:-}" ]]; then
+            docker logs "$SMOKE_CONTAINER_NAME" >"$RUNNER_TEMP/docker-onboard-smoke.log" 2>&1 || true
+          fi
+
+      - name: Upload diagnostics
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ inputs.artifact_name }}
+          path: |
+            ${{ runner.temp }}/docker-onboard-smoke.log
+            ${{ env.SMOKE_METADATA_FILE }}
+            tests/release-smoke/playwright-report/
+            tests/release-smoke/test-results/
+          retention-days: 14
+
+      - name: Stop Docker smoke container
+        if: always()
+        run: |
+          if [[ -n "${SMOKE_CONTAINER_NAME:-}" ]]; then
+            docker rm -f "$SMOKE_CONTAINER_NAME" >/dev/null 2>&1 || true
+          fi

.github/workflows/release.yml

@@ -0,0 +1,261 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+    inputs:
+      source_ref:
+        description: Commit SHA, branch, or tag to publish as stable
+        required: true
+        type: string
+        default: master
+      stable_date:
+        description: Enter a UTC date in YYYY-MM-DD format, for example 2026-03-18. Do not enter a version string. The workflow will resolve that date to a stable version such as 2026.318.0, then 2026.318.1 for the next same-day stable.
+        required: false
+        type: string
+      dry_run:
+        description: Preview the stable release without publishing
+        required: true
+        type: boolean
+        default: false
+
+concurrency:
+  group: release-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  verify_canary:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm -r typecheck
+
+      - name: Run tests
+        run: pnpm test:run
+
+      - name: Build
+        run: pnpm build
+
+  publish_canary:
+    if: github.event_name == 'push'
+    needs: verify_canary
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    environment: npm-canary
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Restore tracked install-time changes
+        run: git checkout -- pnpm-lock.yaml
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Publish canary
+        env:
+          GITHUB_ACTIONS: "true"
+        run: ./scripts/release.sh canary --skip-verify
+
+      - name: Push canary tag
+        run: |
+          tag="$(git tag --points-at HEAD | grep '^canary/v' | head -1)"
+          if [ -z "$tag" ]; then
+            echo "Error: no canary tag points at HEAD after release." >&2
+            exit 1
+          fi
+          git push origin "refs/tags/${tag}"
+
+  verify_stable:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.source_ref }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm -r typecheck
+
+      - name: Run tests
+        run: pnpm test:run
+
+      - name: Build
+        run: pnpm build
+
+  preview_stable:
+    if: github.event_name == 'workflow_dispatch' && inputs.dry_run
+    needs: verify_stable
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.source_ref }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Dry-run stable release
+        env:
+          GITHUB_ACTIONS: "true"
+        run: |
+          args=(stable --skip-verify --dry-run)
+          if [ -n "${{ inputs.stable_date }}" ]; then
+            args+=(--date "${{ inputs.stable_date }}")
+          fi
+          ./scripts/release.sh "${args[@]}"
+
+  publish_stable:
+    if: github.event_name == 'workflow_dispatch' && !inputs.dry_run
+    needs: verify_stable
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    environment: npm-stable
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.source_ref }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --no-frozen-lockfile
+
+      - name: Restore tracked install-time changes
+        run: git checkout -- pnpm-lock.yaml
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Publish stable
+        env:
+          GITHUB_ACTIONS: "true"
+        run: |
+          args=(stable --skip-verify)
+          if [ -n "${{ inputs.stable_date }}" ]; then
+            args+=(--date "${{ inputs.stable_date }}")
+          fi
+          ./scripts/release.sh "${args[@]}"
+
+      - name: Push stable tag
+        run: |
+          tag="$(git tag --points-at HEAD | grep '^v' | head -1)"
+          if [ -z "$tag" ]; then
+            echo "Error: no stable tag points at HEAD after release." >&2
+            exit 1
+          fi
+          git push origin "refs/tags/${tag}"
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PUBLISH_REMOTE: origin
+        run: |
+          version="$(git tag --points-at HEAD | grep '^v' | head -1 | sed 's/^v//')"
+          if [ -z "$version" ]; then
+            echo "Error: no v* tag points at HEAD after stable release." >&2
+            exit 1
+          fi
+          ./scripts/create-github-release.sh "$version"

.gitignore

@@ -1,4 +1,7 @@
+node_modules
 node_modules/
+**/node_modules
+**/node_modules/
 dist/
 .env
 *.tsbuildinfo
@@ -31,9 +34,24 @@ server/src/**/*.js.map
 server/src/**/*.d.ts
 server/src/**/*.d.ts.map
 tmp/
+feedback-export-*
+diagnostics/
 
 # Editor / tool temp files
 *.tmp
 .vscode/
 .claude/settings.local.json
-.paperclip-local/
+.paperclip-local/
+/.idea/
+/.agents/
+
+# Doc maintenance cursor
+.doc-review-cursor
+
+# Playwright
+tests/e2e/test-results/
+tests/e2e/playwright-report/
+tests/release-smoke/test-results/
+tests/release-smoke/playwright-report/
+.superset/
+.claude/worktrees/

.mailmap

@@ -1 +1,3 @@
-Dotta <bippadotta@protonmail.com> Forgotten <forgottenrunes@protonmail.com>
+Dotta <bippadotta@protonmail.com> <34892728+cryppadotta@users.noreply.github.com>
+Dotta <bippadotta@protonmail.com> <forgottenrunes@protonmail.com>
+Dotta <bippadotta@protonmail.com> <dotta@example.com>

AGENTS.md

@@ -26,6 +26,9 @@ Before making changes, read in this order:
 - `ui/`: React + Vite board UI
 - `packages/db/`: Drizzle schema, migrations, DB clients
 - `packages/shared/`: shared types, constants, validators, API path constants
+- `packages/adapters/`: agent adapter implementations (Claude, Codex, Cursor, etc.)
+- `packages/adapter-utils/`: shared adapter utilities
+- `packages/plugins/`: plugin system packages
 - `doc/`: operational and product docs
 
 ## 4. Dev Setup (Auto DB)
@@ -78,6 +81,9 @@ If you change schema/API behavior, update all impacted layers:
 4. Do not replace strategic docs wholesale unless asked.
 Prefer additive updates. Keep `doc/SPEC.md` and `doc/SPEC-implementation.md` aligned.
 
+5. Keep repo plan docs dated and centralized.
+When you are creating a plan file in the repository itself, new plan documents belong in `doc/plans/` and should use `YYYY-MM-DD-slug.md` filenames. This does not replace Paperclip issue planning: if a Paperclip issue asks for a plan, update the issue `plan` document per the `paperclip` skill instead of creating a repo markdown file.
+
 ## 6. Database Change Workflow
 
 When changing data model:
@@ -102,6 +108,21 @@ Notes:
 
 ## 7. Verification Before Hand-off
 
+Default local/agent test path:
+
+```sh
+pnpm test
+```
+
+This is the cheap default and only runs the Vitest suite. Browser suites stay opt-in:
+
+```sh
+pnpm test:e2e
+pnpm test:release-smoke
+```
+
+Run the browser suites only when your change touches them or when you are explicitly verifying CI/release flows.
+
 Run this full check before claiming done:
 
 ```sh
@@ -132,7 +153,18 @@ When adding endpoints:
 - Use company selection context for company-scoped pages
 - Surface failures clearly; do not silently ignore API errors
 
-## 10. Definition of Done
+## 10. Pull Request Requirements
+
+When creating a pull request (via `gh pr create` or any other method), you **must** read and fill in every section of [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md). Do not craft ad-hoc PR bodies — use the template as the structure for your PR description. Required sections:
+
+- **Thinking Path** — trace reasoning from project context to this change (see `CONTRIBUTING.md` for examples)
+- **What Changed** — bullet list of concrete changes
+- **Verification** — how a reviewer can confirm it works
+- **Risks** — what could go wrong
+- **Model Used** — the AI model that produced or assisted with the change (provider, exact model ID, context window, capabilities). Write "None — human-authored" if no AI was used.
+- **Checklist** — all items checked
+
+## 11. Definition of Done
 
 A change is done when all are true:
 
@@ -140,3 +172,45 @@ A change is done when all are true:
 2. Typecheck, tests, and build pass
 3. Contracts are synced across db/shared/server/ui
 4. Docs updated when behavior or commands change
+5. PR description follows the [PR template](.github/PULL_REQUEST_TEMPLATE.md) with all sections filled in (including Model Used)
+
+## 11. Fork-Specific: HenkDz/paperclip
+
+This is a fork of `paperclipai/paperclip` with QoL patches and an **external-only** Hermes adapter story on branch `feat/externalize-hermes-adapter` ([tree](https://github.com/HenkDz/paperclip/tree/feat/externalize-hermes-adapter)).
+
+### Branch Strategy
+
+- `feat/externalize-hermes-adapter` → core has **no** `hermes-paperclip-adapter` dependency and **no** built-in `hermes_local` registration. Install Hermes via the Adapter Plugin manager (`@henkey/hermes-paperclip-adapter` or a `file:` path).
+- Older fork branches may still document built-in Hermes; treat this file as authoritative for the externalize branch.
+
+### Hermes (plugin only)
+
+- Register through **Board → Adapter manager** (same as Droid). Type remains `hermes_local` once the package is loaded.
+- UI uses generic **config-schema** + **ui-parser.js** from the package — no Hermes imports in `server/` or `ui/` source.
+- Optional: `file:` entry in `~/.paperclip/adapter-plugins.json` for local dev of the adapter repo.
+
+### Local Dev
+
+- Fork runs on port 3101+ (auto-detects if 3100 is taken by upstream instance)
+- `npx vite build` hangs on NTFS — use `node node_modules/vite/bin/vite.js build` instead
+- Server startup from NTFS takes 30-60s — don't assume failure immediately
+- Kill ALL paperclip processes before starting: `pkill -f "paperclip"; pkill -f "tsx.*index.ts"`
+- Vite cache survives `rm -rf dist` — delete both: `rm -rf ui/dist ui/node_modules/.vite`
+
+### Fork QoL Patches (not in upstream)
+
+These are local modifications in the fork's UI. If re-copying source, these must be re-applied:
+
+1. **stderr_group** — amber accordion for MCP init noise in `RunTranscriptView.tsx`
+2. **tool_group** — accordion for consecutive non-terminal tools (write, read, search, browser)
+3. **Dashboard excerpt** — `LatestRunCard` strips markdown, shows first 3 lines/280 chars
+
+### Plugin System
+
+PR #2218 (`feat/external-adapter-phase1`) adds external adapter support. See root `AGENTS.md` for full details.
+
+- Adapters can be loaded as external plugins via `~/.paperclip/adapter-plugins.json`
+- The plugin-loader should have ZERO hardcoded adapter imports — pure dynamic loading
+- `createServerAdapter()` must include ALL optional fields (especially `detectModel`)
+- Built-in UI adapters can shadow external plugin parsers — remove built-in when fully externalizing
+- Reference external adapters: Hermes (`@henkey/hermes-paperclip-adapter` or `file:`) and Droid (npm)

CONTRIBUTING.md

@@ -0,0 +1,109 @@
+# Contributing Guide
+
+Thanks for wanting to contribute!
+
+We really appreciate both small fixes and thoughtful larger changes.
+
+## Two Paths to Get Your Pull Request Accepted
+
+### Path 1: Small, Focused Changes (Fastest way to get merged)
+
+- Pick **one** clear thing to fix/improve
+- Touch the **smallest possible number of files**
+- Make sure the change is very targeted and easy to review
+- All tests pass and CI is green
+- Greptile score is 5/5 with all comments addressed
+- Use the [PR template](.github/PULL_REQUEST_TEMPLATE.md)
+
+These almost always get merged quickly when they're clean.
+
+### Path 2: Bigger or Impactful Changes
+
+- **First** talk about it in Discord → #dev channel  
+  → Describe what you're trying to solve  
+  → Share rough ideas / approach
+- Once there's rough agreement, build it
+- In your PR include:
+  - Before / After screenshots (or short video if UI/behavior change)
+  - Clear description of what & why
+  - Proof it works (manual testing notes)
+  - All tests passing and CI green
+  - Greptile score 5/5 with all comments addressed
+  - [PR template](.github/PULL_REQUEST_TEMPLATE.md) fully filled out
+
+PRs that follow this path are **much** more likely to be accepted, even when they're large.
+
+## PR Requirements (all PRs)
+
+### Use the PR Template
+
+Every pull request **must** follow the PR template at [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md). If you create a PR via the GitHub API or other tooling that bypasses the template, copy its contents into your PR description manually. The template includes required sections: Thinking Path, What Changed, Verification, Risks, Model Used, and a Checklist.
+
+### Model Used (Required)
+
+Every PR must include a **Model Used** section specifying which AI model produced or assisted with the change. Include the provider, exact model ID/version, context window size, and any relevant capability details (e.g., reasoning mode, tool use). If no AI was used, write "None — human-authored". This applies to all contributors — human and AI alike.
+
+### Tests Must Pass
+
+All tests must pass before a PR can be merged. Run them locally first and verify CI is green after pushing.
+
+### Greptile Review
+
+We use [Greptile](https://greptile.com) for automated code review. Your PR must achieve a **5/5 Greptile score** with **all Greptile comments addressed** before it can be merged. If Greptile leaves comments, fix or respond to each one and request a re-review.
+
+## Feature Contributions
+
+We actively manage the core Paperclip feature roadmap.
+
+Uncoordinated feature PRs against the core product may be closed, even when the implementation is thoughtful and high quality. That is about roadmap ownership, product coherence, and long-term maintenance commitment, not a judgment about the effort.
+
+If you want to contribute a feature:
+
+- Check [ROADMAP.md](ROADMAP.md) first
+- Start the discussion in Discord -> `#dev` before writing code
+- If the idea fits as an extension, prefer building it with the [plugin system](doc/plugins/PLUGIN_SPEC.md)
+- If you want to show a possible direction, reference implementations are welcome as feedback, but they generally will not be merged directly into core
+
+Bugs, docs improvements, and small targeted improvements are still the easiest path to getting merged, and we really do appreciate them.
+
+## General Rules (both paths)
+
+- Write clear commit messages
+- Keep PR title + description meaningful
+- One PR = one logical change (unless it's a small related group)
+- Run tests locally first
+- Be kind in discussions 😄
+
+## Writing a Good PR message
+
+Your PR description must follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md). All sections are required. The "thinking path" at the top explains from the top of the project down to what you fixed. E.g.:
+
+### Thinking Path Example 1:
+
+> - Paperclip orchestrates ai-agents for zero-human companies
+> - There are many types of adapters for each LLM model provider
+> - But LLM's have a context limit and not all agents can automatically compact their context
+> - So we need to have an adapter-specific configuration for which adapters can and cannot automatically compact their context
+> - This pull request adds per-adapter configuration of compaction, either auto or paperclip managed
+> - That way we can get optimal performance from any adapter/provider in Paperclip
+
+### Thinking Path Example 2:
+
+> - Paperclip orchestrates ai-agents for zero-human companies
+> - But humans want to watch the agents and oversee their work
+> - Human users also operate in teams and so they need their own logins, profiles, views etc.
+> - So we have a multi-user system for humans
+> - But humans want to be able to update their own profile picture and avatar
+> - But the avatar upload form wasn't saving the avatar to the file storage system
+> - So this PR fixes the avatar upload form to use the file storage service
+> - The benefit is we don't have a one-off file storage for just one aspect of the system, which would cause confusion and extra configuration
+
+Then have the rest of your normal PR message after the Thinking Path.
+
+This should include details about what you did, why you did it, why it matters & the benefits, how we can verify it works, and any risks.
+
+Please include screenshots if possible if you have a visible change. (use something like the [agent-browser skill](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md) or similar to take screenshots). Ideally, you include before and after screenshots.
+
+Questions? Just ask in #dev — we're happy to help.
+
+Happy hacking!

Dockerfile

@@ -1,8 +1,15 @@
-FROM node:20-bookworm-slim AS base
+FROM node:lts-trixie-slim AS base
+ARG USER_UID=1000
+ARG USER_GID=1000
 RUN apt-get update \
-  && apt-get install -y --no-install-recommends ca-certificates curl git \
-  && rm -rf /var/lib/apt/lists/*
-RUN corepack enable
+  && apt-get install -y --no-install-recommends ca-certificates gosu curl gh git wget ripgrep python3 \
+  && rm -rf /var/lib/apt/lists/* \
+  && corepack enable
+
+# Modify the existing node user/group to have the specified UID/GID to match host user
+RUN usermod -u $USER_UID --non-unique node \
+  && groupmod -g $USER_GID --non-unique node \
+  && usermod -g $USER_GID -d /paperclip node
 
 FROM base AS deps
 WORKDIR /app
@@ -13,21 +20,42 @@ COPY ui/package.json ui/
 COPY packages/shared/package.json packages/shared/
 COPY packages/db/package.json packages/db/
 COPY packages/adapter-utils/package.json packages/adapter-utils/
+COPY packages/mcp-server/package.json packages/mcp-server/
 COPY packages/adapters/claude-local/package.json packages/adapters/claude-local/
 COPY packages/adapters/codex-local/package.json packages/adapters/codex-local/
+COPY packages/adapters/cursor-local/package.json packages/adapters/cursor-local/
+COPY packages/adapters/gemini-local/package.json packages/adapters/gemini-local/
+COPY packages/adapters/openclaw-gateway/package.json packages/adapters/openclaw-gateway/
+COPY packages/adapters/opencode-local/package.json packages/adapters/opencode-local/
+COPY packages/adapters/pi-local/package.json packages/adapters/pi-local/
+COPY packages/plugins/sdk/package.json packages/plugins/sdk/
+COPY patches/ patches/
+
 RUN pnpm install --frozen-lockfile
 
 FROM base AS build
 WORKDIR /app
 COPY --from=deps /app /app
 COPY . .
-RUN pnpm --filter @paperclip/ui build
-RUN pnpm --filter @paperclip/server build
+RUN pnpm --filter @paperclipai/ui build
+RUN pnpm --filter @paperclipai/plugin-sdk build
+RUN pnpm --filter @paperclipai/server build
+RUN test -f server/dist/index.js || (echo "ERROR: server build output missing" && exit 1)
 
 FROM base AS production
+ARG USER_UID=1000
+ARG USER_GID=1000
 WORKDIR /app
-COPY --from=build /app /app
-RUN npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/codex@latest
+COPY --chown=node:node --from=build /app /app
+RUN npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/codex@latest opencode-ai \
+  && apt-get update \
+  && apt-get install -y --no-install-recommends openssh-client jq \
+  && rm -rf /var/lib/apt/lists/* \
+  && mkdir -p /paperclip \
+  && chown node:node /paperclip
+
+COPY scripts/docker-entrypoint.sh /usr/local/bin/
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
 
 ENV NODE_ENV=production \
   HOME=/paperclip \
@@ -36,11 +64,15 @@ ENV NODE_ENV=production \
   SERVE_UI=true \
   PAPERCLIP_HOME=/paperclip \
   PAPERCLIP_INSTANCE_ID=default \
+  USER_UID=${USER_UID} \
+  USER_GID=${USER_GID} \
   PAPERCLIP_CONFIG=/paperclip/instances/default/config.json \
-  PAPERCLIP_DEPLOYMENT_MODE=local_trusted \
-  PAPERCLIP_DEPLOYMENT_EXPOSURE=private
+  PAPERCLIP_DEPLOYMENT_MODE=authenticated \
+  PAPERCLIP_DEPLOYMENT_EXPOSURE=private \
+  OPENCODE_ALLOW_ALL_MODELS=true
 
 VOLUME ["/paperclip"]
 EXPOSE 3100
 
+ENTRYPOINT ["docker-entrypoint.sh"]
 CMD ["node", "--import", "./server/node_modules/tsx/dist/loader.mjs", "server/dist/index.js"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paperclip AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -177,6 +177,16 @@ Open source. Self-hosted. No Paperclip account required.
 npx paperclipai onboard --yes
 ```
 
+That quickstart path now defaults to trusted local loopback mode for the fastest first run. To start in authenticated/private mode instead, choose a bind preset explicitly:
+
+```bash
+npx paperclipai onboard --yes --bind lan
+# or:
+npx paperclipai onboard --yes --bind tailnet
+```
+
+If you already have Paperclip configured, rerunning `onboard` keeps the existing config in place. Use `paperclipai configure` to edit settings.
+
 Or manually:
 
 ```bash
@@ -218,33 +228,73 @@ By default, agents run on scheduled heartbeats and event-based triggers (task as
 ## Development
 
 ```bash
-pnpm dev              # Full dev (API + UI)
+pnpm dev              # Full dev (API + UI, watch mode)
+pnpm dev:once         # Full dev without file watching
 pnpm dev:server       # Server only
 pnpm build            # Build all
 pnpm typecheck        # Type checking
-pnpm test:run         # Run tests
+pnpm test             # Cheap default test run (Vitest only)
+pnpm test:watch       # Vitest watch mode
+pnpm test:e2e         # Playwright browser suite
 pnpm db:generate      # Generate DB migration
 pnpm db:migrate       # Apply migrations
 ```
 
+`pnpm test` does not run Playwright. Browser suites stay separate and are typically run only when working on those flows or in CI.
+
 See [doc/DEVELOPING.md](doc/DEVELOPING.md) for the full development guide.
 
 <br/>
 
 ## Roadmap
 
-- 🛒 **Clipmart** — Download and share entire company architectures
-- 🧩 **Plugin System** — Embed custom plugins (e.g. Reporting, Knowledge Base) into Paperclip
-- ☁️ **Cloud Agent Adapters** — Add more adapters for cloud-hosted agents
+- ✅ Plugin system (e.g. add a knowledge base, custom tracing, queues, etc)
+- ✅ Get OpenClaw / claw-style agent employees
+- ✅ companies.sh - import and export entire organizations
+- ✅ Easy AGENTS.md configurations
+- ✅ Skills Manager
+- ✅ Scheduled Routines
+- ✅ Better Budgeting
+- ✅ Agent Reviews and Approvals
+- ⚪ Multiple Human Users
+- ⚪ Cloud / Sandbox agents (e.g. Cursor / e2b agents)
+- ⚪ Artifacts & Work Products
+- ⚪ Memory / Knowledge
+- ⚪ Enforced Outcomes
+- ⚪ MAXIMIZER MODE
+- ⚪ Deep Planning
+- ⚪ Work Queues
+- ⚪ Self-Organization
+- ⚪ Automatic Organizational Learning
+- ⚪ CEO Chat
+- ⚪ Cloud deployments
+- ⚪ Desktop App
+
+This is the short roadmap preview. See the full roadmap in [ROADMAP.md](ROADMAP.md).
 
 <br/>
 
+## Community & Plugins
+
+Find Plugins and more at [awesome-paperclip](https://github.com/gsxdsm/awesome-paperclip)
+
+## Telemetry
+
+Paperclip collects anonymous usage telemetry to help us understand how the product is used and improve it. No personal information, issue content, prompts, file paths, or secrets are ever collected. Private repository references are hashed with a per-install salt before being sent.
+
+Telemetry is **enabled by default** and can be disabled with any of the following:
+
+| Method               | How                                                     |
+| -------------------- | ------------------------------------------------------- |
+| Environment variable | `PAPERCLIP_TELEMETRY_DISABLED=1`                        |
+| Standard convention  | `DO_NOT_TRACK=1`                                        |
+| CI environments      | Automatically disabled when `CI=true`                   |
+| Config file          | Set `telemetry.enabled: false` in your Paperclip config |
+
 ## Contributing
 
 We welcome contributions. See the [contributing guide](CONTRIBUTING.md) for details.
 
-<!-- TODO: add CONTRIBUTING.md -->
-
 <br/>
 
 ## Community
@@ -259,6 +309,10 @@ We welcome contributions. See the [contributing guide](CONTRIBUTING.md) for deta
 
 MIT &copy; 2026 Paperclip
 
+## Star History
+
+[![Star History Chart](https://api.star-history.com/image?repos=paperclipai/paperclip&type=date&legend=top-left)](https://www.star-history.com/?repos=paperclipai%2Fpaperclip&type=date&legend=top-left)
+
 <br/>
 
 ---

ROADMAP.md

@@ -0,0 +1,97 @@
+# Roadmap
+
+This document expands the roadmap preview in `README.md`.
+
+Paperclip is still moving quickly. The list below is directional, not promised, and priorities may shift as we learn from users and from operating real AI companies with the product.
+
+We value community involvement and want to make sure contributor energy goes toward areas where it can land.
+
+We may accept contributions in the areas below, but if you want to work on roadmap-level core features, please coordinate with us first in Discord (`#dev`) before writing code. Bugs, docs, polish, and tightly scoped improvements are still the easiest contributions to merge.
+
+If you want to extend Paperclip today, the best path is often the [plugin system](doc/plugins/PLUGIN_SPEC.md). Community reference implementations are also useful feedback even when they are not merged directly into core.
+
+## Milestones
+
+### ✅ Plugin system
+
+Paperclip should keep a thin core and rich edges. Plugins are the path for optional capabilities like knowledge bases, custom tracing, queues, doc editors, and other product-specific surfaces that do not need to live in the control plane itself.
+
+### ✅ Get OpenClaw / claw-style agent employees
+
+Paperclip should be able to hire and manage real claw-style agent workers, not just a narrow built-in runtime. This is part of the larger "bring your own agent" story and keeps the control plane useful across different agent ecosystems.
+
+### ✅ companies.sh - import and export entire organizations
+
+Reusable companies matter. Import/export is the foundation for moving org structures, agent definitions, and reusable company setups between environments and eventually for broader company-template distribution.
+
+### ✅ Easy AGENTS.md configurations
+
+Agent setup should feel repo-native and legible. Simple `AGENTS.md`-style configuration lowers the barrier to getting an agent team running and makes it easier for contributors to understand how a company is wired together.
+
+### ✅ Skills Manager
+
+Agents need a practical way to discover, install, and use skills without every setup becoming bespoke. The skills layer is part of making Paperclip companies more reusable and easier to operate.
+
+### ✅ Scheduled Routines
+
+Recurring work should be native. Routine tasks like reports, reviews, and other periodic work need first-class scheduling so the company keeps operating even when no human is manually kicking work off.
+
+### ✅ Better Budgeting
+
+Budgets are a core control-plane feature, not an afterthought. Better budgeting means clearer spend visibility, safer hard stops, and better operator control over how autonomy turns into real cost.
+
+### ✅ Agent Reviews and Approvals
+
+Paperclip should support explicit review and approval stages as first-class workflow steps, not just ad hoc comments. That means reviewer routing, approval gates, change requests, and durable audit trails that fit the same task model as the rest of the control plane.
+
+### ⚪ Multiple Human Users
+
+Paperclip needs a clearer path from solo operator to real human teams. That means shared board access, safer collaboration, and a better model for several humans supervising the same autonomous company.
+
+### ⚪ Cloud / Sandbox agents (e.g. Cursor / e2b agents)
+
+We want agents to run in more remote and sandboxed environments while preserving the same Paperclip control-plane model. This makes the system safer, more flexible, and more useful outside a single trusted local machine.
+
+### ⚪ Artifacts & Work Products
+
+Paperclip should make outputs first-class. That means generated artifacts, previews, deployable outputs, and the handoff from "agent did work" to "here is the result" should become more visible and easier to operate.
+
+### ⚪ Memory / Knowledge
+
+We want a stronger memory and knowledge surface for companies, agents, and projects. That includes durable memory, better recall of prior decisions and context, and a clearer path for knowledge-style capabilities without turning Paperclip into a generic chat app.
+
+### ⚪ Enforced Outcomes
+
+Paperclip should get stricter about what counts as finished work. Tasks, approvals, and execution flows should resolve to clear outcomes like merged code, published artifacts, shipped docs, or explicit decisions instead of stopping at vague status updates.
+
+### ⚪ MAXIMIZER MODE
+
+This is the direction for higher-autonomy execution: more aggressive delegation, deeper follow-through, and stronger operating loops with clear budgets, visibility, and governance. The point is not hidden autonomy; the point is more output per human supervisor.
+
+### ⚪ Deep Planning
+
+Some work needs more than a task description before execution starts. Deeper planning means stronger issue documents, revisionable plans, and clearer review loops for strategy-heavy work before agents begin execution.
+
+### ⚪ Work Queues
+
+Paperclip should support queue-style work streams for repeatable inputs like support, triage, review, and backlog intake. That would make it easier to route work continuously without turning every system into a one-off workflow.
+
+### ⚪ Self-Organization
+
+As companies grow, agents should be able to propose useful structural changes such as role adjustments, delegation changes, and new recurring routines. The goal is adaptive organizations that still stay within governance and approval boundaries.
+
+### ⚪ Automatic Organizational Learning
+
+Paperclip should get better at turning completed work into reusable organizational knowledge. That includes capturing playbooks, recurring fixes, and decision patterns so future work starts from what the company has already learned.
+
+### ⚪ CEO Chat
+
+We want a lighter-weight way to talk to leadership agents, but those conversations should still resolve to real work objects like plans, issues, approvals, or decisions. This should improve interaction without changing the core task-and-comments model.
+
+### ⚪ Cloud deployments
+
+Local-first remains important, but Paperclip also needs a cleaner shared deployment story. Teams should be able to run the same product in hosted or semi-hosted environments without changing the mental model.
+
+### ⚪ Desktop App
+
+A desktop app can make Paperclip feel more accessible and persistent for day-to-day operators. The goal is easier access, better local ergonomics, and a smoother default experience for users who want the control plane always close at hand.

SECURITY.md

@@ -0,0 +1,8 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities through GitHub's Security Advisory feature:
+[https://github.com/paperclipai/paperclip/security/advisories/new](https://github.com/paperclipai/paperclip/security/advisories/new)
+
+Do not open public issues for security vulnerabilities.

adapter-plugin.md

@@ -0,0 +1,143 @@
+- Created branch: feat/external-adapter-phase1
+
+   I started phase 1 in the most merge-friendly way I could: small central changes, reusing existing registry patterns instead of inventing a whole new plugin system up front.
+
+   What I changed
+
+   1. Server adapter registry is now mutable
+   Files:
+  - server/src/adapters/registry.ts
+  - server/src/adapters/index.ts
+
+   Added:
+  - registerServerAdapter(adapter)
+  - unregisterServerAdapter(type)
+  - requireServerAdapter(type)
+
+   Kept the existing built-in registry shape, but changed initialization so built-ins are registered into a mutable map on startup.
+
+   Why this is merge-friendly:
+  - existing built-in adapter definitions stay where they already are
+  - existing lookup helpers still exist
+  - no big architectural rewrite yet
+
+   1. Runtime adapter validation moved to server routes
+   File:
+  - server/src/routes/agents.ts
+
+   Added:
+  - assertKnownAdapterType(...)
+
+   Used it in:
+  - /companies/:companyId/adapters/:type/models
+  - /companies/:companyId/adapters/:type/detect-model
+  - /companies/:companyId/adapters/:type/test-environment
+  - POST /companies/:companyId/agents
+  - POST /companies/:companyId/agent-hires
+  - PATCH /agents/:id when adapterType is touched
+
+   Why:
+  - shared schemas can now allow external adapter strings
+  - server becomes the real source of truth for “is this adapter actually registered?”
+
+   1. Shared adapterType validation is now open-ended for inputs
+   Files:
+  - packages/shared/src/adapter-type.ts
+  - packages/shared/src/validators/agent.ts
+  - packages/shared/src/validators/access.ts
+  - packages/shared/src/index.ts
+
+   Changed input validation from hardcoded z.enum(AGENT_ADAPTER_TYPES) to:
+  - agentAdapterTypeSchema
+  - optionalAgentAdapterTypeSchema
+
+   These accept any non-empty string.
+
+   Important:
+  - I did not remove AGENT_ADAPTER_TYPES from constants
+  - I did not change the built-in type unions yet
+  - this keeps the change minimal and limits blast radius
+
+   So:
+  - input payloads can carry external adapter types
+  - actual acceptance still depends on server registry validation
+
+   1. UI adapter registry is now mutable too
+   Files:
+  - ui/src/adapters/registry.ts
+  - ui/src/adapters/index.ts
+
+   Added:
+  - registerUIAdapter(adapter)
+  - unregisterUIAdapter(type)
+  - findUIAdapter(type)
+
+   Built-ins are still registered from the same file, same pattern as server.
+
+   1. Began switching UI adapter lists toward the registry
+   Files:
+  - ui/src/adapters/metadata.ts
+  - ui/src/components/AgentConfigForm.tsx
+  - ui/src/pages/NewAgent.tsx
+
+   Changed:
+  - AgentConfigForm adapter list now comes from registered UI adapters via metadata helper
+  - NewAgent supported adapter set now derives from listUIAdapters()
+
+   Why:
+  - phase 1 should start reducing hardcoded UI lists
+  - but without rewriting every page at once
+
+   1. Tests added first, then implementation
+   New tests:
+  - server/src/__tests__/adapter-registry.test.ts
+  - server/src/__tests__/agent-adapter-validation-routes.test.ts
+  - ui/src/adapters/registry.test.ts
+  - packages/shared/src/adapter-types.test.ts
+
+   Small test mock fix:
+  - server/src/__tests__/agent-skills-routes.test.ts
+
+   Current status
+
+   The branch is created and the phase-1 code is started.
+
+   I also followed TDD in spirit:
+  - wrote failing tests first for missing register/unregister APIs
+  - then implemented the registry changes
+
+   What is not finished yet
+
+   I have not finished the green/stabilization pass yet.
+
+   I still need to:
+  - run the targeted tests again after the implementation changes
+  - fix any TS / mocking fallout
+  - decide how far to take phase-1 UI wiring in this branch before stopping
+
+   Also, I intentionally did not yet touch the bigger hardcoded surfaces like:
+  - NewAgentDialog
+  - OnboardingWizard
+  - InviteLanding
+  - duplicated adapterLabels maps
+  - plugin manifest / plugin loader adapter contributions
+
+   That is deliberate.
+   For merge safety, I started with the smallest useful seam:
+  - dynamic server registry
+  - dynamic UI registry
+  - runtime validation based on registry
+  - first couple of UI consumers
+
+   One note
+   There was already an unrelated dirty change in:
+  - server/scripts/dev-watch.ts
+
+   I left that alone and did not make phase-1 changes there.
+
+   Recommended next move
+   I should keep going on this same branch and do the stabilization pass:
+   1. rerun server/ui/shared targeted tests
+   2. fix failures
+   3. run typechecks
+   4. then extend the same registry-driven approach to the next safest UI surfaces

cli/CHANGELOG.md

@@ -1,5 +1,58 @@
 # paperclipai
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+  - @paperclipai/adapter-claude-local@0.3.1
+  - @paperclipai/adapter-codex-local@0.3.1
+  - @paperclipai/adapter-cursor-local@0.3.1
+  - @paperclipai/adapter-gemini-local@0.3.1
+  - @paperclipai/adapter-openclaw-gateway@0.3.1
+  - @paperclipai/adapter-opencode-local@0.3.1
+  - @paperclipai/adapter-pi-local@0.3.1
+  - @paperclipai/db@0.3.1
+  - @paperclipai/shared@0.3.1
+  - @paperclipai/server@0.3.1
+
+## 0.3.0
+
+### Minor Changes
+
+- Stable release preparation for 0.3.0
+
+### Patch Changes
+
+- Updated dependencies [6077ae6]
+- Updated dependencies
+  - @paperclipai/shared@0.3.0
+  - @paperclipai/adapter-utils@0.3.0
+  - @paperclipai/adapter-claude-local@0.3.0
+  - @paperclipai/adapter-codex-local@0.3.0
+  - @paperclipai/adapter-cursor-local@0.3.0
+  - @paperclipai/adapter-openclaw-gateway@0.3.0
+  - @paperclipai/adapter-opencode-local@0.3.0
+  - @paperclipai/adapter-pi-local@0.3.0
+  - @paperclipai/db@0.3.0
+  - @paperclipai/server@0.3.0
+
+## 0.2.7
+
+### Patch Changes
+
+- Version bump (patch)
+- Updated dependencies
+  - @paperclipai/shared@0.2.7
+  - @paperclipai/adapter-utils@0.2.7
+  - @paperclipai/db@0.2.7
+  - @paperclipai/adapter-claude-local@0.2.7
+  - @paperclipai/adapter-codex-local@0.2.7
+  - @paperclipai/adapter-openclaw@0.2.7
+  - @paperclipai/server@0.2.7
+
 ## 0.2.6
 
 ### Patch Changes

cli/README.md

@@ -0,0 +1,304 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/paperclipai/paperclip/master/doc/assets/header.png" alt="Paperclip — runs your business" width="720" />
+</p>
+
+<p align="center">
+  <a href="#quickstart"><strong>Quickstart</strong></a> &middot;
+  <a href="https://paperclip.ing/docs"><strong>Docs</strong></a> &middot;
+  <a href="https://github.com/paperclipai/paperclip"><strong>GitHub</strong></a> &middot;
+  <a href="https://discord.gg/m4HZY7xNG3"><strong>Discord</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/paperclipai/paperclip/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
+  <a href="https://github.com/paperclipai/paperclip/stargazers"><img src="https://img.shields.io/github/stars/paperclipai/paperclip?style=flat" alt="Stars" /></a>
+  <a href="https://discord.gg/m4HZY7xNG3"><img src="https://img.shields.io/discord/000000000?label=discord" alt="Discord" /></a>
+</p>
+
+<br/>
+
+<div align="center">
+  <video src="https://github.com/user-attachments/assets/773bdfb2-6d1e-4e30-8c5f-3487d5b70c8f" width="600" controls></video>
+</div>
+
+<br/>
+
+## What is Paperclip?
+
+# Open-source orchestration for zero-human companies
+
+**If OpenClaw is an _employee_, Paperclip is the _company_**
+
+Paperclip is a Node.js server and React UI that orchestrates a team of AI agents to run a business. Bring your own agents, assign goals, and track your agents' work and costs from one dashboard.
+
+It looks like a task manager — but under the hood it has org charts, budgets, governance, goal alignment, and agent coordination.
+
+**Manage business goals, not pull requests.**
+
+|        | Step            | Example                                                            |
+| ------ | --------------- | ------------------------------------------------------------------ |
+| **01** | Define the goal | _"Build the #1 AI note-taking app to $1M MRR."_                    |
+| **02** | Hire the team   | CEO, CTO, engineers, designers, marketers — any bot, any provider. |
+| **03** | Approve and run | Review strategy. Set budgets. Hit go. Monitor from the dashboard.  |
+
+<br/>
+
+> **COMING SOON: Clipmart** — Download and run entire companies with one click. Browse pre-built company templates — full org structures, agent configs, and skills — and import them into your Paperclip instance in seconds.
+
+<br/>
+
+<div align="center">
+<table>
+  <tr>
+    <td align="center"><strong>Works<br/>with</strong></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/paperclipai/paperclip/master/doc/assets/logos/openclaw.svg" width="32" alt="OpenClaw" /><br/><sub>OpenClaw</sub></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/paperclipai/paperclip/master/doc/assets/logos/claude.svg" width="32" alt="Claude" /><br/><sub>Claude Code</sub></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/paperclipai/paperclip/master/doc/assets/logos/codex.svg" width="32" alt="Codex" /><br/><sub>Codex</sub></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/paperclipai/paperclip/master/doc/assets/logos/cursor.svg" width="32" alt="Cursor" /><br/><sub>Cursor</sub></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/paperclipai/paperclip/master/doc/assets/logos/bash.svg" width="32" alt="Bash" /><br/><sub>Bash</sub></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/paperclipai/paperclip/master/doc/assets/logos/http.svg" width="32" alt="HTTP" /><br/><sub>HTTP</sub></td>
+  </tr>
+</table>
+
+<em>If it can receive a heartbeat, it's hired.</em>
+
+</div>
+
+<br/>
+
+## Paperclip is right for you if
+
+- ✅ You want to build **autonomous AI companies**
+- ✅ You **coordinate many different agents** (OpenClaw, Codex, Claude, Cursor) toward a common goal
+- ✅ You have **20 simultaneous Claude Code terminals** open and lose track of what everyone is doing
+- ✅ You want agents running **autonomously 24/7**, but still want to audit work and chime in when needed
+- ✅ You want to **monitor costs** and enforce budgets
+- ✅ You want a process for managing agents that **feels like using a task manager**
+- ✅ You want to manage your autonomous businesses **from your phone**
+
+<br/>
+
+## Features
+
+<table>
+<tr>
+<td align="center" width="33%">
+<h3>🔌 Bring Your Own Agent</h3>
+Any agent, any runtime, one org chart. If it can receive a heartbeat, it's hired.
+</td>
+<td align="center" width="33%">
+<h3>🎯 Goal Alignment</h3>
+Every task traces back to the company mission. Agents know <em>what</em> to do and <em>why</em>.
+</td>
+<td align="center" width="33%">
+<h3>💓 Heartbeats</h3>
+Agents wake on a schedule, check work, and act. Delegation flows up and down the org chart.
+</td>
+</tr>
+<tr>
+<td align="center">
+<h3>💰 Cost Control</h3>
+Monthly budgets per agent. When they hit the limit, they stop. No runaway costs.
+</td>
+<td align="center">
+<h3>🏢 Multi-Company</h3>
+One deployment, many companies. Complete data isolation. One control plane for your portfolio.
+</td>
+<td align="center">
+<h3>🎫 Ticket System</h3>
+Every conversation traced. Every decision explained. Full tool-call tracing and immutable audit log.
+</td>
+</tr>
+<tr>
+<td align="center">
+<h3>🛡️ Governance</h3>
+You're the board. Approve hires, override strategy, pause or terminate any agent — at any time.
+</td>
+<td align="center">
+<h3>📊 Org Chart</h3>
+Hierarchies, roles, reporting lines. Your agents have a boss, a title, and a job description.
+</td>
+<td align="center">
+<h3>📱 Mobile Ready</h3>
+Monitor and manage your autonomous businesses from anywhere.
+</td>
+</tr>
+</table>
+
+<br/>
+
+## Problems Paperclip solves
+
+| Without Paperclip                                                                                                                     | With Paperclip                                                                                                                         |
+| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| ❌ You have 20 Claude Code tabs open and can't track which one does what. On reboot you lose everything.                              | ✅ Tasks are ticket-based, conversations are threaded, sessions persist across reboots.                                                |
+| ❌ You manually gather context from several places to remind your bot what you're actually doing.                                     | ✅ Context flows from the task up through the project and company goals — your agent always knows what to do and why.                  |
+| ❌ Folders of agent configs are disorganized and you're re-inventing task management, communication, and coordination between agents. | ✅ Paperclip gives you org charts, ticketing, delegation, and governance out of the box — so you run a company, not a pile of scripts. |
+| ❌ Runaway loops waste hundreds of dollars of tokens and max your quota before you even know what happened.                           | ✅ Cost tracking surfaces token budgets and throttles agents when they're out. Management prioritizes with budgets.                    |
+| ❌ You have recurring jobs (customer support, social, reports) and have to remember to manually kick them off.                        | ✅ Heartbeats handle regular work on a schedule. Management supervises.                                                                |
+| ❌ You have an idea, you have to find your repo, fire up Claude Code, keep a tab open, and babysit it.                                | ✅ Add a task in Paperclip. Your coding agent works on it until it's done. Management reviews their work.                              |
+
+<br/>
+
+## Why Paperclip is special
+
+Paperclip handles the hard orchestration details correctly.
+
+|                                   |                                                                                                               |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| **Atomic execution.**             | Task checkout and budget enforcement are atomic, so no double-work and no runaway spend.                      |
+| **Persistent agent state.**       | Agents resume the same task context across heartbeats instead of restarting from scratch.                     |
+| **Runtime skill injection.**      | Agents can learn Paperclip workflows and project context at runtime, without retraining.                      |
+| **Governance with rollback.**     | Approval gates are enforced, config changes are revisioned, and bad changes can be rolled back safely.        |
+| **Goal-aware execution.**         | Tasks carry full goal ancestry so agents consistently see the "why," not just a title.                        |
+| **Portable company templates.**   | Export/import orgs, agents, and skills with secret scrubbing and collision handling.                          |
+| **True multi-company isolation.** | Every entity is company-scoped, so one deployment can run many companies with separate data and audit trails. |
+
+<br/>
+
+## What Paperclip is not
+
+|                              |                                                                                                                      |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **Not a chatbot.**           | Agents have jobs, not chat windows.                                                                                  |
+| **Not an agent framework.**  | We don't tell you how to build agents. We tell you how to run a company made of them.                                |
+| **Not a workflow builder.**  | No drag-and-drop pipelines. Paperclip models companies — with org charts, goals, budgets, and governance.            |
+| **Not a prompt manager.**    | Agents bring their own prompts, models, and runtimes. Paperclip manages the organization they work in.               |
+| **Not a single-agent tool.** | This is for teams. If you have one agent, you probably don't need Paperclip. If you have twenty — you definitely do. |
+| **Not a code review tool.**  | Paperclip orchestrates work, not pull requests. Bring your own review process.                                       |
+
+<br/>
+
+## Quickstart
+
+Open source. Self-hosted. No Paperclip account required.
+
+```bash
+npx paperclipai onboard --yes
+```
+
+That quickstart path now defaults to trusted local loopback mode for the fastest first run. To start in authenticated/private mode instead, choose a bind preset explicitly:
+
+```bash
+npx paperclipai onboard --yes --bind lan
+# or:
+npx paperclipai onboard --yes --bind tailnet
+```
+
+If you already have Paperclip configured, rerunning `onboard` keeps the existing config in place. Use `paperclipai configure` to edit settings.
+
+Or manually:
+
+```bash
+git clone https://github.com/paperclipai/paperclip.git
+cd paperclip
+pnpm install
+pnpm dev
+```
+
+This starts the API server at `http://localhost:3100`. An embedded PostgreSQL database is created automatically — no setup required.
+
+> **Requirements:** Node.js 20+, pnpm 9.15+
+
+<br/>
+
+## FAQ
+
+**What does a typical setup look like?**
+Locally, a single Node.js process manages an embedded Postgres and local file storage. For production, point it at your own Postgres and deploy however you like. Configure projects, agents, and goals — the agents take care of the rest.
+
+If you're a solo-entreprenuer you can use Tailscale to access Paperclip on the go. Then later you can deploy to e.g. Vercel when you need it.
+
+**Can I run multiple companies?**
+Yes. A single deployment can run an unlimited number of companies with complete data isolation.
+
+**How is Paperclip different from agents like OpenClaw or Claude Code?**
+Paperclip _uses_ those agents. It orchestrates them into a company — with org charts, budgets, goals, governance, and accountability.
+
+**Why should I use Paperclip instead of just pointing my OpenClaw to Asana or Trello?**
+Agent orchestration has subtleties in how you coordinate who has work checked out, how to maintain sessions, monitoring costs, establishing governance - Paperclip does this for you.
+
+(Bring-your-own-ticket-system is on the Roadmap)
+
+**Do agents run continuously?**
+By default, agents run on scheduled heartbeats and event-based triggers (task assignment, @-mentions). You can also hook in continuous agents like OpenClaw. You bring your agent and Paperclip coordinates.
+
+<br/>
+
+## Development
+
+```bash
+pnpm dev              # Full dev (API + UI, watch mode)
+pnpm dev:once         # Full dev without file watching
+pnpm dev:server       # Server only
+pnpm build            # Build all
+pnpm typecheck        # Type checking
+pnpm test             # Cheap default test run (Vitest only)
+pnpm test:watch       # Vitest watch mode
+pnpm test:e2e         # Playwright browser suite
+pnpm db:generate      # Generate DB migration
+pnpm db:migrate       # Apply migrations
+```
+
+`pnpm test` does not run Playwright. Browser suites stay separate and are typically run only when working on those flows or in CI.
+
+See [doc/DEVELOPING.md](https://github.com/paperclipai/paperclip/blob/master/doc/DEVELOPING.md) for the full development guide.
+
+<br/>
+
+## Roadmap
+
+- ✅ Plugin system (e.g. add a knowledge base, custom tracing, queues, etc)
+- ✅ Get OpenClaw / claw-style agent employees
+- ✅ companies.sh - import and export entire organizations
+- ✅ Easy AGENTS.md configurations
+- ✅ Skills Manager
+- ✅ Scheduled Routines
+- ✅ Better Budgeting
+- ⚪ Artifacts & Deployments
+- ⚪ CEO Chat
+- ⚪ MAXIMIZER MODE
+- ⚪ Multiple Human Users
+- ⚪ Cloud / Sandbox agents (e.g. Cursor / e2b agents)
+- ⚪ Cloud deployments
+- ⚪ Desktop App
+
+<br/>
+
+## Community & Plugins
+
+Find Plugins and more at [awesome-paperclip](https://github.com/gsxdsm/awesome-paperclip)
+
+## Contributing
+
+We welcome contributions. See the [contributing guide](https://github.com/paperclipai/paperclip/blob/master/CONTRIBUTING.md) for details.
+
+<br/>
+
+## Community
+
+- [Discord](https://discord.gg/m4HZY7xNG3) — Join the community
+- [GitHub Issues](https://github.com/paperclipai/paperclip/issues) — bugs and feature requests
+- [GitHub Discussions](https://github.com/paperclipai/paperclip/discussions) — ideas and RFC
+
+<br/>
+
+## License
+
+MIT &copy; 2026 Paperclip
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/image?repos=paperclipai/paperclip&type=date&legend=top-left)](https://www.star-history.com/?repos=paperclipai%2Fpaperclip&type=date&legend=top-left)
+
+<br/>
+
+---
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/paperclipai/paperclip/master/doc/assets/footer.jpg" alt="" width="720" />
+</p>
+
+<p align="center">
+  <sub>Open source under MIT. Built for people who want to run companies, not babysit agents.</sub>
+</p>

cli/esbuild.config.mjs

@@ -21,7 +21,7 @@ const workspacePaths = [
   "packages/adapter-utils",
   "packages/adapters/claude-local",
   "packages/adapters/codex-local",
-  "packages/adapters/openclaw",
+  "packages/adapters/openclaw-gateway",
 ];
 
 // Workspace packages that should NOT be bundled — they'll be published

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclipai",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "Paperclip CLI — orchestrate AI agent teams to run a business",
   "type": "module",
   "bin": {
@@ -16,10 +16,13 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/paperclipai/paperclip.git",
+    "url": "https://github.com/paperclipai/paperclip",
     "directory": "cli"
   },
   "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
   "files": [
     "dist"
   ],
@@ -36,7 +39,11 @@
     "@clack/prompts": "^0.10.0",
     "@paperclipai/adapter-claude-local": "workspace:*",
     "@paperclipai/adapter-codex-local": "workspace:*",
-    "@paperclipai/adapter-openclaw": "workspace:*",
+    "@paperclipai/adapter-cursor-local": "workspace:*",
+    "@paperclipai/adapter-gemini-local": "workspace:*",
+    "@paperclipai/adapter-opencode-local": "workspace:*",
+    "@paperclipai/adapter-pi-local": "workspace:*",
+    "@paperclipai/adapter-openclaw-gateway": "workspace:*",
     "@paperclipai/adapter-utils": "workspace:*",
     "@paperclipai/db": "workspace:*",
     "@paperclipai/server": "workspace:*",
@@ -44,6 +51,7 @@
     "drizzle-orm": "0.38.4",
     "dotenv": "^17.0.1",
     "commander": "^13.1.0",
+    "embedded-postgres": "^18.1.0-beta.16",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {

cli/src/__tests__/agent-jwt-env.test.ts

@@ -4,7 +4,9 @@ import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
   ensureAgentJwtSecret,
+  mergePaperclipEnvEntries,
   readAgentJwtSecretFromEnv,
+  readPaperclipEnvEntries,
   resolveAgentJwtEnvFile,
 } from "../config/env.js";
 import { agentJwtSecretCheck } from "../checks/agent-jwt-secret-check.js";
@@ -58,4 +60,20 @@ describe("agent jwt env helpers", () => {
     const result = agentJwtSecretCheck(configPath);
     expect(result.status).toBe("pass");
   });
+
+  it("quotes hash-prefixed env values so dotenv round-trips them", () => {
+    const configPath = tempConfigPath();
+    const envPath = resolveAgentJwtEnvFile(configPath);
+
+    mergePaperclipEnvEntries(
+      {
+        PAPERCLIP_WORKTREE_COLOR: "#439edb",
+      },
+      envPath,
+    );
+
+    const contents = fs.readFileSync(envPath, "utf-8");
+    expect(contents).toContain('PAPERCLIP_WORKTREE_COLOR="#439edb"');
+    expect(readPaperclipEnvEntries(envPath).PAPERCLIP_WORKTREE_COLOR).toBe("#439edb");
+  });
 });

cli/src/__tests__/allowed-hostname.test.ts

@@ -21,6 +21,12 @@ function writeBaseConfig(configPath: string) {
       mode: "embedded-postgres",
       embeddedPostgresDataDir: "/tmp/paperclip-db",
       embeddedPostgresPort: 54329,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: "/tmp/paperclip-backups",
+      },
     },
     logging: {
       mode: "file",
@@ -36,6 +42,10 @@ function writeBaseConfig(configPath: string) {
     },
     auth: {
       baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+    telemetry: {
+      enabled: true,
     },
     storage: {
       provider: "local_disk",
@@ -68,4 +78,3 @@ describe("allowed-hostname command", () => {
     expect(raw.server.allowedHostnames).toEqual(["dotta-macbook-pro"]);
   });
 });
-

cli/src/__tests__/auth-command-registration.test.ts

@@ -0,0 +1,16 @@
+import { Command } from "commander";
+import { describe, expect, it } from "vitest";
+import { registerClientAuthCommands } from "../commands/client/auth.js";
+
+describe("registerClientAuthCommands", () => {
+  it("registers auth commands without duplicate company-id flags", () => {
+    const program = new Command();
+    const auth = program.command("auth");
+
+    expect(() => registerClientAuthCommands(auth)).not.toThrow();
+
+    const login = auth.commands.find((command) => command.name() === "login");
+    expect(login).toBeDefined();
+    expect(login?.options.filter((option) => option.long === "--company-id")).toHaveLength(1);
+  });
+});

cli/src/__tests__/board-auth.test.ts

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  getStoredBoardCredential,
+  readBoardAuthStore,
+  removeStoredBoardCredential,
+  setStoredBoardCredential,
+} from "../client/board-auth.js";
+
+function createTempAuthPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-cli-auth-"));
+  return path.join(dir, "auth.json");
+}
+
+describe("board auth store", () => {
+  it("returns an empty store when the file does not exist", () => {
+    const authPath = createTempAuthPath();
+    expect(readBoardAuthStore(authPath)).toEqual({
+      version: 1,
+      credentials: {},
+    });
+  });
+
+  it("stores and retrieves credentials by normalized api base", () => {
+    const authPath = createTempAuthPath();
+    setStoredBoardCredential({
+      apiBase: "http://localhost:3100/",
+      token: "token-123",
+      userId: "user-1",
+      storePath: authPath,
+    });
+
+    expect(getStoredBoardCredential("http://localhost:3100", authPath)).toMatchObject({
+      apiBase: "http://localhost:3100",
+      token: "token-123",
+      userId: "user-1",
+    });
+  });
+
+  it("removes stored credentials", () => {
+    const authPath = createTempAuthPath();
+    setStoredBoardCredential({
+      apiBase: "http://localhost:3100",
+      token: "token-123",
+      storePath: authPath,
+    });
+
+    expect(removeStoredBoardCredential("http://localhost:3100", authPath)).toBe(true);
+    expect(getStoredBoardCredential("http://localhost:3100", authPath)).toBeNull();
+  });
+});

cli/src/__tests__/company-delete.test.ts

@@ -8,12 +8,20 @@ function makeCompany(overrides: Partial<Company>): Company {
     name: "Alpha",
     description: null,
     status: "active",
+    pauseReason: null,
+    pausedAt: null,
     issuePrefix: "ALP",
     issueCounter: 1,
     budgetMonthlyCents: 0,
     spentMonthlyCents: 0,
     requireBoardApprovalForNewAgents: false,
+    feedbackDataSharingEnabled: false,
+    feedbackDataSharingConsentAt: null,
+    feedbackDataSharingConsentByUserId: null,
+    feedbackDataSharingTermsVersion: null,
     brandColor: null,
+    logoAssetId: null,
+    logoUrl: null,
     createdAt: new Date(),
     updatedAt: new Date(),
     ...overrides,

cli/src/__tests__/company-import-export-e2e.test.ts

@@ -0,0 +1,502 @@
+import { execFile, spawn } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { createStoredZipArchive } from "./helpers/zip.js";
+
+const execFileAsync = promisify(execFile);
+type ServerProcess = ReturnType<typeof spawn>;
+
+async function getAvailablePort(): Promise<number> {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Failed to allocate test port")));
+        return;
+      }
+      const { port } = address;
+      server.close((error) => {
+        if (error) reject(error);
+        else resolve(port);
+      });
+    });
+  });
+}
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres company import/export e2e tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+function writeTestConfig(configPath: string, tempRoot: string, port: number, connectionString: string) {
+  const config = {
+    $meta: {
+      version: 1,
+      updatedAt: new Date().toISOString(),
+      source: "doctor",
+    },
+    database: {
+      mode: "postgres",
+      connectionString,
+      embeddedPostgresDataDir: path.join(tempRoot, "embedded-db"),
+      embeddedPostgresPort: 54329,
+      backup: {
+        enabled: false,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: path.join(tempRoot, "backups"),
+      },
+    },
+    logging: {
+      mode: "file",
+      logDir: path.join(tempRoot, "logs"),
+    },
+    server: {
+      deploymentMode: "local_trusted",
+      exposure: "private",
+      host: "127.0.0.1",
+      port,
+      allowedHostnames: [],
+      serveUi: false,
+    },
+    auth: {
+      baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+    storage: {
+      provider: "local_disk",
+      localDisk: {
+        baseDir: path.join(tempRoot, "storage"),
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted",
+      strictMode: false,
+      localEncrypted: {
+        keyFilePath: path.join(tempRoot, "secrets", "master.key"),
+      },
+    },
+  };
+
+  mkdirSync(path.dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+function createServerEnv(configPath: string, port: number, connectionString: string) {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) {
+    if (key.startsWith("PAPERCLIP_")) {
+      delete env[key];
+    }
+  }
+  delete env.DATABASE_URL;
+  delete env.PORT;
+  delete env.HOST;
+  delete env.SERVE_UI;
+  delete env.HEARTBEAT_SCHEDULER_ENABLED;
+
+  env.PAPERCLIP_CONFIG = configPath;
+  env.DATABASE_URL = connectionString;
+  env.HOST = "127.0.0.1";
+  env.PORT = String(port);
+  env.SERVE_UI = "false";
+  env.PAPERCLIP_DB_BACKUP_ENABLED = "false";
+  env.HEARTBEAT_SCHEDULER_ENABLED = "false";
+  env.PAPERCLIP_MIGRATION_AUTO_APPLY = "true";
+  env.PAPERCLIP_UI_DEV_MIDDLEWARE = "false";
+
+  return env;
+}
+
+function createCliEnv() {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) {
+    if (key.startsWith("PAPERCLIP_")) {
+      delete env[key];
+    }
+  }
+  delete env.DATABASE_URL;
+  delete env.PORT;
+  delete env.HOST;
+  delete env.SERVE_UI;
+  delete env.PAPERCLIP_DB_BACKUP_ENABLED;
+  delete env.HEARTBEAT_SCHEDULER_ENABLED;
+  delete env.PAPERCLIP_MIGRATION_AUTO_APPLY;
+  delete env.PAPERCLIP_UI_DEV_MIDDLEWARE;
+  return env;
+}
+
+function collectTextFiles(root: string, current: string, files: Record<string, string>) {
+  for (const entry of readdirSync(current, { withFileTypes: true })) {
+    const absolutePath = path.join(current, entry.name);
+    if (entry.isDirectory()) {
+      collectTextFiles(root, absolutePath, files);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const relativePath = path.relative(root, absolutePath).replace(/\\/g, "/");
+    files[relativePath] = readFileSync(absolutePath, "utf8");
+  }
+}
+
+async function stopServerProcess(child: ServerProcess | null) {
+  if (!child || child.exitCode !== null) return;
+  child.kill("SIGTERM");
+  await new Promise<void>((resolve) => {
+    child.once("exit", () => resolve());
+    setTimeout(() => {
+      if (child.exitCode === null) {
+        child.kill("SIGKILL");
+      }
+    }, 5_000);
+  });
+}
+
+async function api<T>(baseUrl: string, pathname: string, init?: RequestInit): Promise<T> {
+  const res = await fetch(`${baseUrl}${pathname}`, init);
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Request failed ${res.status} ${pathname}: ${text}`);
+  }
+  return text ? JSON.parse(text) as T : (null as T);
+}
+
+async function runCliJson<T>(args: string[], opts: { apiBase: string; configPath: string }) {
+  const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+  const result = await execFileAsync(
+    "pnpm",
+    ["--silent", "paperclipai", ...args, "--api-base", opts.apiBase, "--config", opts.configPath, "--json"],
+    {
+      cwd: repoRoot,
+      env: createCliEnv(),
+      maxBuffer: 10 * 1024 * 1024,
+    },
+  );
+  const stdout = result.stdout.trim();
+  const jsonStart = stdout.search(/[\[{]/);
+  if (jsonStart === -1) {
+    throw new Error(`CLI did not emit JSON.\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`);
+  }
+  return JSON.parse(stdout.slice(jsonStart)) as T;
+}
+
+async function waitForServer(
+  apiBase: string,
+  child: ServerProcess,
+  output: { stdout: string[]; stderr: string[] },
+) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < 30_000) {
+    if (child.exitCode !== null) {
+      throw new Error(
+        `paperclipai run exited before healthcheck succeeded.\nstdout:\n${output.stdout.join("")}\nstderr:\n${output.stderr.join("")}`,
+      );
+    }
+
+    try {
+      const res = await fetch(`${apiBase}/api/health`);
+      if (res.ok) return;
+    } catch {
+      // Server is still starting.
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+
+  throw new Error(
+    `Timed out waiting for ${apiBase}/api/health.\nstdout:\n${output.stdout.join("")}\nstderr:\n${output.stderr.join("")}`,
+  );
+}
+
+describeEmbeddedPostgres("paperclipai company import/export e2e", () => {
+  let tempRoot = "";
+  let configPath = "";
+  let exportDir = "";
+  let apiBase = "";
+  let serverProcess: ServerProcess | null = null;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempRoot = mkdtempSync(path.join(os.tmpdir(), "paperclip-company-cli-e2e-"));
+    configPath = path.join(tempRoot, "config", "config.json");
+    exportDir = path.join(tempRoot, "exported-company");
+
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-company-cli-db-");
+
+    const port = await getAvailablePort();
+    writeTestConfig(configPath, tempRoot, port, tempDb.connectionString);
+    apiBase = `http://127.0.0.1:${port}`;
+
+    const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+    const output = { stdout: [] as string[], stderr: [] as string[] };
+    const child = spawn(
+      "pnpm",
+      ["paperclipai", "run", "--config", configPath],
+      {
+        cwd: repoRoot,
+        env: createServerEnv(configPath, port, tempDb.connectionString),
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+    serverProcess = child;
+    child.stdout?.on("data", (chunk) => {
+      output.stdout.push(String(chunk));
+    });
+    child.stderr?.on("data", (chunk) => {
+      output.stderr.push(String(chunk));
+    });
+
+    await waitForServer(apiBase, child, output);
+  }, 60_000);
+
+  afterAll(async () => {
+    await stopServerProcess(serverProcess);
+    await tempDb?.cleanup();
+    if (tempRoot) {
+      rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("exports a company package and imports it into new and existing companies", async () => {
+    expect(serverProcess).not.toBeNull();
+
+    const sourceCompany = await api<{ id: string; name: string; issuePrefix: string }>(apiBase, "/api/companies", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name: `CLI Export Source ${Date.now()}` }),
+    });
+
+    const sourceAgent = await api<{ id: string; name: string }>(
+      apiBase,
+      `/api/companies/${sourceCompany.id}/agents`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          name: "Export Engineer",
+          role: "engineer",
+          adapterType: "claude_local",
+          adapterConfig: {
+            promptTemplate: "You verify company portability.",
+          },
+        }),
+      },
+    );
+
+    const sourceProject = await api<{ id: string; name: string }>(
+      apiBase,
+      `/api/companies/${sourceCompany.id}/projects`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          name: "Portability Verification",
+          status: "in_progress",
+        }),
+      },
+    );
+
+    const largeIssueDescription = `Round-trip the company package through the CLI.\n\n${"portable-data ".repeat(12_000)}`;
+
+    const sourceIssue = await api<{ id: string; title: string; identifier: string }>(
+      apiBase,
+      `/api/companies/${sourceCompany.id}/issues`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          title: "Validate company import/export",
+          description: largeIssueDescription,
+          status: "todo",
+          projectId: sourceProject.id,
+          assigneeAgentId: sourceAgent.id,
+        }),
+      },
+    );
+
+    const exportResult = await runCliJson<{
+      ok: boolean;
+      out: string;
+      filesWritten: number;
+    }>(
+      [
+        "company",
+        "export",
+        sourceCompany.id,
+        "--out",
+        exportDir,
+        "--include",
+        "company,agents,projects,issues",
+      ],
+      { apiBase, configPath },
+    );
+
+    expect(exportResult.ok).toBe(true);
+    expect(exportResult.filesWritten).toBeGreaterThan(0);
+    expect(readFileSync(path.join(exportDir, "COMPANY.md"), "utf8")).toContain(sourceCompany.name);
+    expect(readFileSync(path.join(exportDir, ".paperclip.yaml"), "utf8")).toContain('schema: "paperclip/v1"');
+
+    const importedNew = await runCliJson<{
+      company: { id: string; name: string; action: string };
+      agents: Array<{ id: string | null; action: string; name: string }>;
+    }>(
+      [
+        "company",
+        "import",
+        exportDir,
+        "--target",
+        "new",
+        "--new-company-name",
+        `Imported ${sourceCompany.name}`,
+        "--include",
+        "company,agents,projects,issues",
+        "--yes",
+      ],
+      { apiBase, configPath },
+    );
+
+    expect(importedNew.company.action).toBe("created");
+    expect(importedNew.agents).toHaveLength(1);
+    expect(importedNew.agents[0]?.action).toBe("created");
+
+    const importedAgents = await api<Array<{ id: string; name: string }>>(
+      apiBase,
+      `/api/companies/${importedNew.company.id}/agents`,
+    );
+    const importedProjects = await api<Array<{ id: string; name: string }>>(
+      apiBase,
+      `/api/companies/${importedNew.company.id}/projects`,
+    );
+    const importedIssues = await api<Array<{ id: string; title: string; identifier: string }>>(
+      apiBase,
+      `/api/companies/${importedNew.company.id}/issues`,
+    );
+
+    expect(importedAgents.map((agent) => agent.name)).toContain(sourceAgent.name);
+    expect(importedProjects.map((project) => project.name)).toContain(sourceProject.name);
+    expect(importedIssues.map((issue) => issue.title)).toContain(sourceIssue.title);
+
+    const previewExisting = await runCliJson<{
+      errors: string[];
+      plan: {
+        companyAction: string;
+        agentPlans: Array<{ action: string }>;
+        projectPlans: Array<{ action: string }>;
+        issuePlans: Array<{ action: string }>;
+      };
+    }>(
+      [
+        "company",
+        "import",
+        exportDir,
+        "--target",
+        "existing",
+        "--company-id",
+        importedNew.company.id,
+        "--include",
+        "company,agents,projects,issues",
+        "--collision",
+        "rename",
+        "--dry-run",
+      ],
+      { apiBase, configPath },
+    );
+
+    expect(previewExisting.errors).toEqual([]);
+    expect(previewExisting.plan.companyAction).toBe("none");
+    expect(previewExisting.plan.agentPlans.some((plan) => plan.action === "create")).toBe(true);
+    expect(previewExisting.plan.projectPlans.some((plan) => plan.action === "create")).toBe(true);
+    expect(previewExisting.plan.issuePlans.some((plan) => plan.action === "create")).toBe(true);
+
+    const importedExisting = await runCliJson<{
+      company: { id: string; action: string };
+      agents: Array<{ id: string | null; action: string; name: string }>;
+    }>(
+      [
+        "company",
+        "import",
+        exportDir,
+        "--target",
+        "existing",
+        "--company-id",
+        importedNew.company.id,
+        "--include",
+        "company,agents,projects,issues",
+        "--collision",
+        "rename",
+        "--yes",
+      ],
+      { apiBase, configPath },
+    );
+
+    expect(importedExisting.company.action).toBe("unchanged");
+    expect(importedExisting.agents.some((agent) => agent.action === "created")).toBe(true);
+
+    const twiceImportedAgents = await api<Array<{ id: string; name: string }>>(
+      apiBase,
+      `/api/companies/${importedNew.company.id}/agents`,
+    );
+    const twiceImportedProjects = await api<Array<{ id: string; name: string }>>(
+      apiBase,
+      `/api/companies/${importedNew.company.id}/projects`,
+    );
+    const twiceImportedIssues = await api<Array<{ id: string; title: string; identifier: string }>>(
+      apiBase,
+      `/api/companies/${importedNew.company.id}/issues`,
+    );
+
+    expect(twiceImportedAgents).toHaveLength(2);
+    expect(new Set(twiceImportedAgents.map((agent) => agent.name)).size).toBe(2);
+    expect(twiceImportedProjects).toHaveLength(2);
+    expect(twiceImportedIssues).toHaveLength(2);
+
+    const zipPath = path.join(tempRoot, "exported-company.zip");
+    const portableFiles: Record<string, string> = {};
+    collectTextFiles(exportDir, exportDir, portableFiles);
+    writeFileSync(zipPath, createStoredZipArchive(portableFiles, "paperclip-demo"));
+
+    const importedFromZip = await runCliJson<{
+      company: { id: string; name: string; action: string };
+      agents: Array<{ id: string | null; action: string; name: string }>;
+    }>(
+      [
+        "company",
+        "import",
+        zipPath,
+        "--target",
+        "new",
+        "--new-company-name",
+        `Zip Imported ${sourceCompany.name}`,
+        "--include",
+        "company,agents,projects,issues",
+        "--yes",
+      ],
+      { apiBase, configPath },
+    );
+
+    expect(importedFromZip.company.action).toBe("created");
+    expect(importedFromZip.agents.some((agent) => agent.action === "created")).toBe(true);
+  }, 60_000);
+});

cli/src/__tests__/company-import-url.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import {
+  isGithubShorthand,
+  looksLikeRepoUrl,
+  isHttpUrl,
+  normalizeGithubImportSource,
+} from "../commands/client/company.js";
+
+describe("isHttpUrl", () => {
+  it("matches http URLs", () => {
+    expect(isHttpUrl("http://example.com/foo")).toBe(true);
+  });
+
+  it("matches https URLs", () => {
+    expect(isHttpUrl("https://example.com/foo")).toBe(true);
+  });
+
+  it("rejects local paths", () => {
+    expect(isHttpUrl("/tmp/my-company")).toBe(false);
+    expect(isHttpUrl("./relative")).toBe(false);
+  });
+});
+
+describe("looksLikeRepoUrl", () => {
+  it("matches GitHub URLs", () => {
+    expect(looksLikeRepoUrl("https://github.com/org/repo")).toBe(true);
+  });
+
+  it("rejects URLs without owner/repo path", () => {
+    expect(looksLikeRepoUrl("https://example.com/foo")).toBe(false);
+  });
+
+  it("rejects local paths", () => {
+    expect(looksLikeRepoUrl("/tmp/my-company")).toBe(false);
+  });
+});
+
+describe("isGithubShorthand", () => {
+  it("matches owner/repo/path shorthands", () => {
+    expect(isGithubShorthand("paperclipai/companies/gstack")).toBe(true);
+    expect(isGithubShorthand("paperclipai/companies")).toBe(true);
+  });
+
+  it("rejects local-looking paths", () => {
+    expect(isGithubShorthand("./exports/acme")).toBe(false);
+    expect(isGithubShorthand("/tmp/acme")).toBe(false);
+    expect(isGithubShorthand("C:\\temp\\acme")).toBe(false);
+  });
+});
+
+describe("normalizeGithubImportSource", () => {
+  it("normalizes shorthand imports to canonical GitHub sources", () => {
+    expect(normalizeGithubImportSource("paperclipai/companies/gstack")).toBe(
+      "https://github.com/paperclipai/companies?ref=main&path=gstack",
+    );
+  });
+
+  it("applies --ref to shorthand imports", () => {
+    expect(normalizeGithubImportSource("paperclipai/companies/gstack", "feature/demo")).toBe(
+      "https://github.com/paperclipai/companies?ref=feature%2Fdemo&path=gstack",
+    );
+  });
+
+  it("applies --ref to existing GitHub tree URLs without losing the package path", () => {
+    expect(
+      normalizeGithubImportSource(
+        "https://github.com/paperclipai/companies/tree/main/gstack",
+        "release/2026-03-23",
+      ),
+    ).toBe(
+      "https://github.com/paperclipai/companies?ref=release%2F2026-03-23&path=gstack",
+    );
+  });
+});

cli/src/__tests__/company-import-zip.test.ts

@@ -0,0 +1,44 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { resolveInlineSourceFromPath } from "../commands/client/company.js";
+import { createStoredZipArchive } from "./helpers/zip.js";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+describe("resolveInlineSourceFromPath", () => {
+  it("imports portable files from a zip archive instead of scanning the parent directory", async () => {
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-company-import-zip-"));
+    tempDirs.push(tempDir);
+
+    const archivePath = path.join(tempDir, "paperclip-demo.zip");
+    const archive = createStoredZipArchive(
+      {
+        "COMPANY.md": "# Company\n",
+        ".paperclip.yaml": "schema: paperclip/v1\n",
+        "agents/ceo/AGENT.md": "# CEO\n",
+        "notes/todo.txt": "ignore me\n",
+      },
+      "paperclip-demo",
+    );
+    await writeFile(archivePath, archive);
+
+    const resolved = await resolveInlineSourceFromPath(archivePath);
+
+    expect(resolved).toEqual({
+      rootPath: "paperclip-demo",
+      files: {
+        "COMPANY.md": "# Company\n",
+        ".paperclip.yaml": "schema: paperclip/v1\n",
+        "agents/ceo/AGENT.md": "# CEO\n",
+      },
+    });
+  });
+});

cli/src/__tests__/company.test.ts

@@ -0,0 +1,599 @@
+import { describe, expect, it } from "vitest";
+import type { CompanyPortabilityPreviewResult } from "@paperclipai/shared";
+import {
+  buildCompanyDashboardUrl,
+  buildDefaultImportAdapterOverrides,
+  buildDefaultImportSelectionState,
+  buildImportSelectionCatalog,
+  buildSelectedFilesFromImportSelection,
+  renderCompanyImportPreview,
+  renderCompanyImportResult,
+  resolveCompanyImportApplyConfirmationMode,
+  resolveCompanyImportApiPath,
+} from "../commands/client/company.js";
+
+describe("resolveCompanyImportApiPath", () => {
+  it("uses company-scoped preview route for existing-company dry runs", () => {
+    expect(
+      resolveCompanyImportApiPath({
+        dryRun: true,
+        targetMode: "existing_company",
+        companyId: "company-123",
+      }),
+    ).toBe("/api/companies/company-123/imports/preview");
+  });
+
+  it("uses company-scoped apply route for existing-company imports", () => {
+    expect(
+      resolveCompanyImportApiPath({
+        dryRun: false,
+        targetMode: "existing_company",
+        companyId: "company-123",
+      }),
+    ).toBe("/api/companies/company-123/imports/apply");
+  });
+
+  it("keeps global routes for new-company imports", () => {
+    expect(
+      resolveCompanyImportApiPath({
+        dryRun: true,
+        targetMode: "new_company",
+      }),
+    ).toBe("/api/companies/import/preview");
+
+    expect(
+      resolveCompanyImportApiPath({
+        dryRun: false,
+        targetMode: "new_company",
+      }),
+    ).toBe("/api/companies/import");
+  });
+
+  it("throws when an existing-company import is missing a company id", () => {
+    expect(() =>
+      resolveCompanyImportApiPath({
+        dryRun: true,
+        targetMode: "existing_company",
+        companyId: " ",
+      })
+    ).toThrow(/require a companyId/i);
+  });
+});
+
+describe("resolveCompanyImportApplyConfirmationMode", () => {
+  it("skips confirmation when --yes is set", () => {
+    expect(
+      resolveCompanyImportApplyConfirmationMode({
+        yes: true,
+        interactive: false,
+        json: false,
+      }),
+    ).toBe("skip");
+  });
+
+  it("prompts in interactive text mode when --yes is not set", () => {
+    expect(
+      resolveCompanyImportApplyConfirmationMode({
+        yes: false,
+        interactive: true,
+        json: false,
+      }),
+    ).toBe("prompt");
+  });
+
+  it("requires --yes for non-interactive apply", () => {
+    expect(() =>
+      resolveCompanyImportApplyConfirmationMode({
+        yes: false,
+        interactive: false,
+        json: false,
+      })
+    ).toThrow(/non-interactive terminal requires --yes/i);
+  });
+
+  it("requires --yes for json apply", () => {
+    expect(() =>
+      resolveCompanyImportApplyConfirmationMode({
+        yes: false,
+        interactive: false,
+        json: true,
+      })
+    ).toThrow(/with --json requires --yes/i);
+  });
+});
+
+describe("buildCompanyDashboardUrl", () => {
+  it("preserves the configured base path when building a dashboard URL", () => {
+    expect(buildCompanyDashboardUrl("https://paperclip.example/app/", "PAP")).toBe(
+      "https://paperclip.example/app/PAP/dashboard",
+    );
+  });
+});
+
+describe("renderCompanyImportPreview", () => {
+  it("summarizes the preview with counts, selection info, and truncated examples", () => {
+    const preview: CompanyPortabilityPreviewResult = {
+      include: {
+        company: true,
+        agents: true,
+        projects: true,
+        issues: true,
+        skills: true,
+      },
+      targetCompanyId: "company-123",
+      targetCompanyName: "Imported Co",
+      collisionStrategy: "rename",
+      selectedAgentSlugs: ["ceo", "cto", "eng-1", "eng-2", "eng-3", "eng-4", "eng-5"],
+      plan: {
+        companyAction: "update",
+        agentPlans: [
+          { slug: "ceo", action: "create", plannedName: "CEO", existingAgentId: null, reason: null },
+          { slug: "cto", action: "update", plannedName: "CTO", existingAgentId: "agent-2", reason: "replace strategy" },
+          { slug: "eng-1", action: "skip", plannedName: "Engineer 1", existingAgentId: "agent-3", reason: "skip strategy" },
+          { slug: "eng-2", action: "create", plannedName: "Engineer 2", existingAgentId: null, reason: null },
+          { slug: "eng-3", action: "create", plannedName: "Engineer 3", existingAgentId: null, reason: null },
+          { slug: "eng-4", action: "create", plannedName: "Engineer 4", existingAgentId: null, reason: null },
+          { slug: "eng-5", action: "create", plannedName: "Engineer 5", existingAgentId: null, reason: null },
+        ],
+        projectPlans: [
+          { slug: "alpha", action: "create", plannedName: "Alpha", existingProjectId: null, reason: null },
+        ],
+        issuePlans: [
+          { slug: "kickoff", action: "create", plannedTitle: "Kickoff", reason: null },
+        ],
+      },
+      manifest: {
+        schemaVersion: 1,
+        generatedAt: "2026-03-23T17:00:00.000Z",
+        source: {
+          companyId: "company-src",
+          companyName: "Source Co",
+        },
+        includes: {
+          company: true,
+          agents: true,
+          projects: true,
+          issues: true,
+          skills: true,
+        },
+        company: {
+          path: "COMPANY.md",
+          name: "Source Co",
+          description: null,
+          brandColor: null,
+          logoPath: null,
+          requireBoardApprovalForNewAgents: false,
+          feedbackDataSharingEnabled: false,
+          feedbackDataSharingConsentAt: null,
+          feedbackDataSharingConsentByUserId: null,
+          feedbackDataSharingTermsVersion: null,
+        },
+        sidebar: {
+          agents: ["ceo"],
+          projects: ["alpha"],
+        },
+        agents: [
+          {
+            slug: "ceo",
+            name: "CEO",
+            path: "agents/ceo/AGENT.md",
+            skills: [],
+            role: "ceo",
+            title: null,
+            icon: null,
+            capabilities: null,
+            reportsToSlug: null,
+            adapterType: "codex_local",
+            adapterConfig: {},
+            runtimeConfig: {},
+            permissions: {},
+            budgetMonthlyCents: 0,
+            metadata: null,
+          },
+        ],
+        skills: [
+          {
+            key: "skill-a",
+            slug: "skill-a",
+            name: "Skill A",
+            path: "skills/skill-a/SKILL.md",
+            description: null,
+            sourceType: "inline",
+            sourceLocator: null,
+            sourceRef: null,
+            trustLevel: null,
+            compatibility: null,
+            metadata: null,
+            fileInventory: [],
+          },
+        ],
+        projects: [
+          {
+            slug: "alpha",
+            name: "Alpha",
+            path: "projects/alpha/PROJECT.md",
+            description: null,
+            ownerAgentSlug: null,
+            leadAgentSlug: null,
+            targetDate: null,
+            color: null,
+            status: null,
+            executionWorkspacePolicy: null,
+            workspaces: [],
+            env: null,
+            metadata: null,
+          },
+        ],
+        issues: [
+          {
+            slug: "kickoff",
+            identifier: null,
+            title: "Kickoff",
+            path: "projects/alpha/issues/kickoff/TASK.md",
+            projectSlug: "alpha",
+            projectWorkspaceKey: null,
+            assigneeAgentSlug: "ceo",
+            description: null,
+            recurring: false,
+            routine: null,
+            legacyRecurrence: null,
+            status: null,
+            priority: null,
+            labelIds: [],
+            billingCode: null,
+            executionWorkspaceSettings: null,
+            assigneeAdapterOverrides: null,
+            metadata: null,
+          },
+        ],
+        envInputs: [
+          {
+            key: "OPENAI_API_KEY",
+            description: null,
+            agentSlug: "ceo",
+            projectSlug: null,
+            kind: "secret",
+            requirement: "required",
+            defaultValue: null,
+            portability: "portable",
+          },
+        ],
+      },
+      files: {
+        "COMPANY.md": "# Source Co",
+      },
+      envInputs: [
+        {
+          key: "OPENAI_API_KEY",
+          description: null,
+          agentSlug: "ceo",
+          projectSlug: null,
+          kind: "secret",
+          requirement: "required",
+          defaultValue: null,
+          portability: "portable",
+        },
+      ],
+      warnings: ["One warning"],
+      errors: ["One error"],
+    };
+
+    const rendered = renderCompanyImportPreview(preview, {
+      sourceLabel: "GitHub: https://github.com/paperclipai/companies/demo",
+      targetLabel: "Imported Co (company-123)",
+      infoMessages: ["Using claude-local adapter"],
+    });
+
+    expect(rendered).toContain("Include");
+    expect(rendered).toContain("company, projects, tasks, agents, skills");
+    expect(rendered).toContain("7 agents total");
+    expect(rendered).toContain("1 project total");
+    expect(rendered).toContain("1 task total");
+    expect(rendered).toContain("skills: 1 skill packaged");
+    expect(rendered).toContain("+1 more");
+    expect(rendered).toContain("Using claude-local adapter");
+    expect(rendered).toContain("Warnings");
+    expect(rendered).toContain("Errors");
+  });
+});
+
+describe("renderCompanyImportResult", () => {
+  it("summarizes import results with created, updated, and skipped counts", () => {
+    const rendered = renderCompanyImportResult(
+      {
+        company: {
+          id: "company-123",
+          name: "Imported Co",
+          action: "updated",
+        },
+        agents: [
+          { slug: "ceo", id: "agent-1", action: "created", name: "CEO", reason: null },
+          { slug: "cto", id: "agent-2", action: "updated", name: "CTO", reason: "replace strategy" },
+          { slug: "ops", id: null, action: "skipped", name: "Ops", reason: "skip strategy" },
+        ],
+        projects: [
+          { slug: "app", id: "project-1", action: "created", name: "App", reason: null },
+          { slug: "ops", id: "project-2", action: "updated", name: "Operations", reason: "replace strategy" },
+          { slug: "archive", id: null, action: "skipped", name: "Archive", reason: "skip strategy" },
+        ],
+        envInputs: [],
+        warnings: ["Review API keys"],
+      },
+      {
+        targetLabel: "Imported Co (company-123)",
+        companyUrl: "https://paperclip.example/PAP/dashboard",
+        infoMessages: ["Using claude-local adapter"],
+      },
+    );
+
+    expect(rendered).toContain("Company");
+    expect(rendered).toContain("https://paperclip.example/PAP/dashboard");
+    expect(rendered).toContain("3 agents total (1 created, 1 updated, 1 skipped)");
+    expect(rendered).toContain("3 projects total (1 created, 1 updated, 1 skipped)");
+    expect(rendered).toContain("Agent results");
+    expect(rendered).toContain("Project results");
+    expect(rendered).toContain("Using claude-local adapter");
+    expect(rendered).toContain("Review API keys");
+  });
+});
+
+describe("import selection catalog", () => {
+  it("defaults to everything and keeps project selection separate from task selection", () => {
+    const preview: CompanyPortabilityPreviewResult = {
+      include: {
+        company: true,
+        agents: true,
+        projects: true,
+        issues: true,
+        skills: true,
+      },
+      targetCompanyId: "company-123",
+      targetCompanyName: "Imported Co",
+      collisionStrategy: "rename",
+      selectedAgentSlugs: ["ceo"],
+      plan: {
+        companyAction: "create",
+        agentPlans: [],
+        projectPlans: [],
+        issuePlans: [],
+      },
+      manifest: {
+        schemaVersion: 1,
+        generatedAt: "2026-03-23T18:00:00.000Z",
+        source: {
+          companyId: "company-src",
+          companyName: "Source Co",
+        },
+        includes: {
+          company: true,
+          agents: true,
+          projects: true,
+          issues: true,
+          skills: true,
+        },
+        company: {
+          path: "COMPANY.md",
+          name: "Source Co",
+          description: null,
+          brandColor: null,
+          logoPath: "images/company-logo.png",
+          requireBoardApprovalForNewAgents: false,
+          feedbackDataSharingEnabled: false,
+          feedbackDataSharingConsentAt: null,
+          feedbackDataSharingConsentByUserId: null,
+          feedbackDataSharingTermsVersion: null,
+        },
+        sidebar: {
+          agents: ["ceo"],
+          projects: ["alpha"],
+        },
+        agents: [
+          {
+            slug: "ceo",
+            name: "CEO",
+            path: "agents/ceo/AGENT.md",
+            skills: [],
+            role: "ceo",
+            title: null,
+            icon: null,
+            capabilities: null,
+            reportsToSlug: null,
+            adapterType: "codex_local",
+            adapterConfig: {},
+            runtimeConfig: {},
+            permissions: {},
+            budgetMonthlyCents: 0,
+            metadata: null,
+          },
+        ],
+        skills: [
+          {
+            key: "skill-a",
+            slug: "skill-a",
+            name: "Skill A",
+            path: "skills/skill-a/SKILL.md",
+            description: null,
+            sourceType: "inline",
+            sourceLocator: null,
+            sourceRef: null,
+            trustLevel: null,
+            compatibility: null,
+            metadata: null,
+            fileInventory: [{ path: "skills/skill-a/helper.md", kind: "doc" }],
+          },
+        ],
+        projects: [
+          {
+            slug: "alpha",
+            name: "Alpha",
+            path: "projects/alpha/PROJECT.md",
+            description: null,
+            ownerAgentSlug: null,
+            leadAgentSlug: null,
+            targetDate: null,
+            color: null,
+            status: null,
+            executionWorkspacePolicy: null,
+            workspaces: [],
+            env: null,
+            metadata: null,
+          },
+        ],
+        issues: [
+          {
+            slug: "kickoff",
+            identifier: null,
+            title: "Kickoff",
+            path: "projects/alpha/issues/kickoff/TASK.md",
+            projectSlug: "alpha",
+            projectWorkspaceKey: null,
+            assigneeAgentSlug: "ceo",
+            description: null,
+            recurring: false,
+            routine: null,
+            legacyRecurrence: null,
+            status: null,
+            priority: null,
+            labelIds: [],
+            billingCode: null,
+            executionWorkspaceSettings: null,
+            assigneeAdapterOverrides: null,
+            metadata: null,
+          },
+        ],
+        envInputs: [],
+      },
+      files: {
+        "COMPANY.md": "# Source Co",
+        "README.md": "# Readme",
+        ".paperclip.yaml": "schema: paperclip/v1\n",
+        "images/company-logo.png": {
+          encoding: "base64",
+          data: "",
+          contentType: "image/png",
+        },
+        "projects/alpha/PROJECT.md": "# Alpha",
+        "projects/alpha/notes.md": "project notes",
+        "projects/alpha/issues/kickoff/TASK.md": "# Kickoff",
+        "projects/alpha/issues/kickoff/details.md": "task details",
+        "agents/ceo/AGENT.md": "# CEO",
+        "agents/ceo/prompt.md": "prompt",
+        "skills/skill-a/SKILL.md": "# Skill A",
+        "skills/skill-a/helper.md": "helper",
+      },
+      envInputs: [],
+      warnings: [],
+      errors: [],
+    };
+
+    const catalog = buildImportSelectionCatalog(preview);
+    const state = buildDefaultImportSelectionState(catalog);
+
+    expect(state.company).toBe(true);
+    expect(state.projects.has("alpha")).toBe(true);
+    expect(state.issues.has("kickoff")).toBe(true);
+    expect(state.agents.has("ceo")).toBe(true);
+    expect(state.skills.has("skill-a")).toBe(true);
+
+    state.company = false;
+    state.issues.clear();
+    state.agents.clear();
+    state.skills.clear();
+
+    const selectedFiles = buildSelectedFilesFromImportSelection(catalog, state);
+
+    expect(selectedFiles).toContain(".paperclip.yaml");
+    expect(selectedFiles).toContain("projects/alpha/PROJECT.md");
+    expect(selectedFiles).toContain("projects/alpha/notes.md");
+    expect(selectedFiles).not.toContain("projects/alpha/issues/kickoff/TASK.md");
+    expect(selectedFiles).not.toContain("projects/alpha/issues/kickoff/details.md");
+  });
+});
+
+describe("default adapter overrides", () => {
+  it("maps process-only imported agents to claude_local", () => {
+    const preview: CompanyPortabilityPreviewResult = {
+      include: {
+        company: false,
+        agents: true,
+        projects: false,
+        issues: false,
+        skills: false,
+      },
+      targetCompanyId: null,
+      targetCompanyName: null,
+      collisionStrategy: "rename",
+      selectedAgentSlugs: ["legacy-agent", "explicit-agent"],
+      plan: {
+        companyAction: "none",
+        agentPlans: [],
+        projectPlans: [],
+        issuePlans: [],
+      },
+      manifest: {
+        schemaVersion: 1,
+        generatedAt: "2026-03-23T18:20:00.000Z",
+        source: null,
+        includes: {
+          company: false,
+          agents: true,
+          projects: false,
+          issues: false,
+          skills: false,
+        },
+        company: null,
+        sidebar: null,
+        agents: [
+          {
+            slug: "legacy-agent",
+            name: "Legacy Agent",
+            path: "agents/legacy-agent/AGENT.md",
+            skills: [],
+            role: "agent",
+            title: null,
+            icon: null,
+            capabilities: null,
+            reportsToSlug: null,
+            adapterType: "process",
+            adapterConfig: {},
+            runtimeConfig: {},
+            permissions: {},
+            budgetMonthlyCents: 0,
+            metadata: null,
+          },
+          {
+            slug: "explicit-agent",
+            name: "Explicit Agent",
+            path: "agents/explicit-agent/AGENT.md",
+            skills: [],
+            role: "agent",
+            title: null,
+            icon: null,
+            capabilities: null,
+            reportsToSlug: null,
+            adapterType: "codex_local",
+            adapterConfig: {},
+            runtimeConfig: {},
+            permissions: {},
+            budgetMonthlyCents: 0,
+            metadata: null,
+          },
+        ],
+        skills: [],
+        projects: [],
+        issues: [],
+        envInputs: [],
+      },
+      files: {},
+      envInputs: [],
+      warnings: [],
+      errors: [],
+    };
+
+    expect(buildDefaultImportAdapterOverrides(preview)).toEqual({
+      "legacy-agent": {
+        adapterType: "claude_local",
+      },
+    });
+  });
+});

cli/src/__tests__/doctor.test.ts

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { doctor } from "../commands/doctor.js";
+import { writeConfig } from "../config/store.js";
+import type { PaperclipConfig } from "../config/schema.js";
+
+const ORIGINAL_ENV = { ...process.env };
+
+function createTempConfig(): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-doctor-"));
+  const configPath = path.join(root, ".paperclip", "config.json");
+  const runtimeRoot = path.join(root, "runtime");
+
+  const config: PaperclipConfig = {
+    $meta: {
+      version: 1,
+      updatedAt: "2026-03-10T00:00:00.000Z",
+      source: "configure",
+    },
+    database: {
+      mode: "embedded-postgres",
+      embeddedPostgresDataDir: path.join(runtimeRoot, "db"),
+      embeddedPostgresPort: 55432,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: path.join(runtimeRoot, "backups"),
+      },
+    },
+    logging: {
+      mode: "file",
+      logDir: path.join(runtimeRoot, "logs"),
+    },
+    server: {
+      deploymentMode: "local_trusted",
+      exposure: "private",
+      host: "127.0.0.1",
+      port: 3199,
+      allowedHostnames: [],
+      serveUi: true,
+    },
+    auth: {
+      baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+    telemetry: {
+      enabled: true,
+    },
+    storage: {
+      provider: "local_disk",
+      localDisk: {
+        baseDir: path.join(runtimeRoot, "storage"),
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted",
+      strictMode: false,
+      localEncrypted: {
+        keyFilePath: path.join(runtimeRoot, "secrets", "master.key"),
+      },
+    },
+  };
+
+  writeConfig(config, configPath);
+  return configPath;
+}
+
+describe("doctor", () => {
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
+    delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
+    delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
+  });
+
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  it("re-runs repairable checks so repaired failures do not remain blocking", async () => {
+    const configPath = createTempConfig();
+
+    const summary = await doctor({
+      config: configPath,
+      repair: true,
+      yes: true,
+    });
+
+    expect(summary.failed).toBe(0);
+    expect(summary.warned).toBe(0);
+    expect(process.env.PAPERCLIP_AGENT_JWT_SECRET).toBeTruthy();
+  });
+});

cli/src/__tests__/feedback.test.ts

@@ -0,0 +1,177 @@
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, readFile } from "node:fs/promises";
+import { Command } from "commander";
+import { describe, expect, it } from "vitest";
+import type { FeedbackTrace } from "@paperclipai/shared";
+import { readZipArchive } from "../commands/client/zip.js";
+import {
+  buildFeedbackTraceQuery,
+  registerFeedbackCommands,
+  renderFeedbackReport,
+  summarizeFeedbackTraces,
+  writeFeedbackExportBundle,
+} from "../commands/client/feedback.js";
+
+function makeTrace(overrides: Partial<FeedbackTrace> = {}): FeedbackTrace {
+  return {
+    id: "trace-12345678",
+    companyId: "company-123",
+    feedbackVoteId: "vote-12345678",
+    issueId: "issue-123",
+    projectId: "project-123",
+    issueIdentifier: "PAP-123",
+    issueTitle: "Fix the feedback command",
+    authorUserId: "user-123",
+    targetType: "issue_comment",
+    targetId: "comment-123",
+    vote: "down",
+    status: "pending",
+    destination: "paperclip_labs_feedback_v1",
+    exportId: null,
+    consentVersion: "feedback-data-sharing-v1",
+    schemaVersion: "1",
+    bundleVersion: "1",
+    payloadVersion: "1",
+    payloadDigest: null,
+    payloadSnapshot: {
+      vote: {
+        value: "down",
+        reason: "Needed more detail",
+      },
+    },
+    targetSummary: {
+      label: "Comment",
+      excerpt: "The first answer was too vague.",
+      authorAgentId: "agent-123",
+      authorUserId: null,
+      createdAt: new Date("2026-03-31T12:00:00.000Z"),
+      documentKey: null,
+      documentTitle: null,
+      revisionNumber: null,
+    },
+    redactionSummary: null,
+    attemptCount: 0,
+    lastAttemptedAt: null,
+    exportedAt: null,
+    failureReason: null,
+    createdAt: new Date("2026-03-31T12:01:00.000Z"),
+    updatedAt: new Date("2026-03-31T12:02:00.000Z"),
+    ...overrides,
+  };
+}
+
+describe("registerFeedbackCommands", () => {
+  it("registers the top-level feedback commands", () => {
+    const program = new Command();
+
+    expect(() => registerFeedbackCommands(program)).not.toThrow();
+
+    const feedback = program.commands.find((command) => command.name() === "feedback");
+    expect(feedback).toBeDefined();
+    expect(feedback?.commands.map((command) => command.name())).toEqual(["report", "export"]);
+    expect(feedback?.commands[0]?.options.filter((option) => option.long === "--company-id")).toHaveLength(1);
+  });
+});
+
+describe("buildFeedbackTraceQuery", () => {
+  it("encodes all supported filters", () => {
+    expect(
+      buildFeedbackTraceQuery({
+        targetType: "issue_comment",
+        vote: "down",
+        status: "pending",
+        projectId: "project-123",
+        issueId: "issue-123",
+        from: "2026-03-31T00:00:00.000Z",
+        to: "2026-03-31T23:59:59.999Z",
+        sharedOnly: true,
+      }),
+    ).toBe(
+      "?targetType=issue_comment&vote=down&status=pending&projectId=project-123&issueId=issue-123&from=2026-03-31T00%3A00%3A00.000Z&to=2026-03-31T23%3A59%3A59.999Z&sharedOnly=true&includePayload=true",
+    );
+  });
+});
+
+describe("renderFeedbackReport", () => {
+  it("includes summary counts and the optional reason", () => {
+    const traces = [
+      makeTrace(),
+      makeTrace({
+        id: "trace-87654321",
+        feedbackVoteId: "vote-87654321",
+        vote: "up",
+        status: "local_only",
+        payloadSnapshot: {
+          vote: {
+            value: "up",
+            reason: null,
+          },
+        },
+      }),
+    ];
+
+    const report = renderFeedbackReport({
+      apiBase: "http://127.0.0.1:3100",
+      companyId: "company-123",
+      traces,
+      summary: summarizeFeedbackTraces(traces),
+      includePayloads: false,
+    });
+
+    expect(report).toContain("Paperclip Feedback Report");
+    expect(report).toContain("thumbs up");
+    expect(report).toContain("thumbs down");
+    expect(report).toContain("Needed more detail");
+  });
+});
+
+describe("writeFeedbackExportBundle", () => {
+  it("writes votes, traces, a manifest, and a zip archive", async () => {
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-feedback-export-"));
+    const outputDir = path.join(tempDir, "feedback-export");
+    const traces = [
+      makeTrace(),
+      makeTrace({
+        id: "trace-abcdef12",
+        feedbackVoteId: "vote-abcdef12",
+        issueIdentifier: "PAP-124",
+        issueId: "issue-124",
+        vote: "up",
+        status: "local_only",
+        payloadSnapshot: {
+          vote: {
+            value: "up",
+            reason: null,
+          },
+        },
+      }),
+    ];
+
+    const exported = await writeFeedbackExportBundle({
+      apiBase: "http://127.0.0.1:3100",
+      companyId: "company-123",
+      traces,
+      outputDir,
+    });
+
+    expect(exported.manifest.summary.total).toBe(2);
+    expect(exported.manifest.summary.withReason).toBe(1);
+
+    const manifest = JSON.parse(await readFile(path.join(outputDir, "index.json"), "utf8")) as {
+      files: { votes: string[]; traces: string[]; zip: string };
+    };
+    expect(manifest.files.votes).toHaveLength(2);
+    expect(manifest.files.traces).toHaveLength(2);
+
+    const archive = await readFile(exported.zipPath);
+    const zip = await readZipArchive(archive);
+    expect(Object.keys(zip.files)).toEqual(
+      expect.arrayContaining([
+        "index.json",
+        `votes/${manifest.files.votes[0]}`,
+        `traces/${manifest.files.traces[0]}`,
+      ]),
+    );
+  });
+});

cli/src/__tests__/helpers/embedded-postgres.ts

@@ -0,0 +1,6 @@
+export {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+  type EmbeddedPostgresTestDatabase,
+  type EmbeddedPostgresTestSupport,
+} from "@paperclipai/db";

cli/src/__tests__/helpers/zip.ts

@@ -0,0 +1,87 @@
+function writeUint16(target: Uint8Array, offset: number, value: number) {
+  target[offset] = value & 0xff;
+  target[offset + 1] = (value >>> 8) & 0xff;
+}
+
+function writeUint32(target: Uint8Array, offset: number, value: number) {
+  target[offset] = value & 0xff;
+  target[offset + 1] = (value >>> 8) & 0xff;
+  target[offset + 2] = (value >>> 16) & 0xff;
+  target[offset + 3] = (value >>> 24) & 0xff;
+}
+
+function crc32(bytes: Uint8Array) {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit += 1) {
+      crc = (crc & 1) === 1 ? (crc >>> 1) ^ 0xedb88320 : crc >>> 1;
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+export function createStoredZipArchive(files: Record<string, string>, rootPath: string) {
+  const encoder = new TextEncoder();
+  const localChunks: Uint8Array[] = [];
+  const centralChunks: Uint8Array[] = [];
+  let localOffset = 0;
+  let entryCount = 0;
+
+  for (const [relativePath, content] of Object.entries(files).sort(([left], [right]) => left.localeCompare(right))) {
+    const fileName = encoder.encode(`${rootPath}/${relativePath}`);
+    const body = encoder.encode(content);
+    const checksum = crc32(body);
+
+    const localHeader = new Uint8Array(30 + fileName.length);
+    writeUint32(localHeader, 0, 0x04034b50);
+    writeUint16(localHeader, 4, 20);
+    writeUint16(localHeader, 6, 0x0800);
+    writeUint16(localHeader, 8, 0);
+    writeUint32(localHeader, 14, checksum);
+    writeUint32(localHeader, 18, body.length);
+    writeUint32(localHeader, 22, body.length);
+    writeUint16(localHeader, 26, fileName.length);
+    localHeader.set(fileName, 30);
+
+    const centralHeader = new Uint8Array(46 + fileName.length);
+    writeUint32(centralHeader, 0, 0x02014b50);
+    writeUint16(centralHeader, 4, 20);
+    writeUint16(centralHeader, 6, 20);
+    writeUint16(centralHeader, 8, 0x0800);
+    writeUint16(centralHeader, 10, 0);
+    writeUint32(centralHeader, 16, checksum);
+    writeUint32(centralHeader, 20, body.length);
+    writeUint32(centralHeader, 24, body.length);
+    writeUint16(centralHeader, 28, fileName.length);
+    writeUint32(centralHeader, 42, localOffset);
+    centralHeader.set(fileName, 46);
+
+    localChunks.push(localHeader, body);
+    centralChunks.push(centralHeader);
+    localOffset += localHeader.length + body.length;
+    entryCount += 1;
+  }
+
+  const centralDirectoryLength = centralChunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const archive = new Uint8Array(
+    localChunks.reduce((sum, chunk) => sum + chunk.length, 0) + centralDirectoryLength + 22,
+  );
+  let offset = 0;
+  for (const chunk of localChunks) {
+    archive.set(chunk, offset);
+    offset += chunk.length;
+  }
+  const centralDirectoryOffset = offset;
+  for (const chunk of centralChunks) {
+    archive.set(chunk, offset);
+    offset += chunk.length;
+  }
+  writeUint32(archive, offset, 0x06054b50);
+  writeUint16(archive, offset + 8, entryCount);
+  writeUint16(archive, offset + 10, entryCount);
+  writeUint32(archive, offset + 12, centralDirectoryLength);
+  writeUint32(archive, offset + 16, centralDirectoryOffset);
+
+  return archive;
+}

cli/src/__tests__/http.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { ApiRequestError, PaperclipApiClient } from "../client/http.js";
+import { ApiConnectionError, ApiRequestError, PaperclipApiClient } from "../client/http.js";
 
 describe("PaperclipApiClient", () => {
   afterEach(() => {
@@ -58,4 +58,49 @@ describe("PaperclipApiClient", () => {
       details: { issueId: "1" },
     } satisfies Partial<ApiRequestError>);
   });
+
+  it("throws ApiConnectionError with recovery guidance when fetch fails", async () => {
+    const fetchMock = vi.fn().mockRejectedValue(new TypeError("fetch failed"));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const client = new PaperclipApiClient({ apiBase: "http://localhost:3100" });
+
+    await expect(client.post("/api/companies/import/preview", {})).rejects.toBeInstanceOf(ApiConnectionError);
+    await expect(client.post("/api/companies/import/preview", {})).rejects.toMatchObject({
+      url: "http://localhost:3100/api/companies/import/preview",
+      method: "POST",
+      causeMessage: "fetch failed",
+    } satisfies Partial<ApiConnectionError>);
+    await expect(client.post("/api/companies/import/preview", {})).rejects.toThrow(
+      /Could not reach the Paperclip API\./,
+    );
+    await expect(client.post("/api/companies/import/preview", {})).rejects.toThrow(
+      /curl http:\/\/localhost:3100\/api\/health/,
+    );
+    await expect(client.post("/api/companies/import/preview", {})).rejects.toThrow(
+      /pnpm dev|pnpm paperclipai run/,
+    );
+  });
+
+  it("retries once after interactive auth recovery", async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(new Response(JSON.stringify({ error: "Board access required" }), { status: 403 }))
+      .mockResolvedValueOnce(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const recoverAuth = vi.fn().mockResolvedValue("board-token-123");
+    const client = new PaperclipApiClient({
+      apiBase: "http://localhost:3100",
+      recoverAuth,
+    });
+
+    const result = await client.post<{ ok: boolean }>("/api/test", { hello: "world" });
+
+    expect(result).toEqual({ ok: true });
+    expect(recoverAuth).toHaveBeenCalledOnce();
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    const retryHeaders = fetchMock.mock.calls[1]?.[1]?.headers as Record<string, string>;
+    expect(retryHeaders.authorization).toBe("Bearer board-token-123");
+  });
 });

cli/src/__tests__/network-bind.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { resolveRuntimeBind, validateConfiguredBindMode } from "@paperclipai/shared";
+import { buildPresetServerConfig } from "../config/server-bind.js";
+
+describe("network bind helpers", () => {
+  it("rejects non-loopback bind modes in local_trusted", () => {
+    expect(
+      validateConfiguredBindMode({
+        deploymentMode: "local_trusted",
+        deploymentExposure: "private",
+        bind: "lan",
+        host: "0.0.0.0",
+      }),
+    ).toContain("local_trusted requires server.bind=loopback");
+  });
+
+  it("resolves tailnet bind using the detected tailscale address", () => {
+    const resolved = resolveRuntimeBind({
+      bind: "tailnet",
+      host: "127.0.0.1",
+      tailnetBindHost: "100.64.0.8",
+    });
+
+    expect(resolved.errors).toEqual([]);
+    expect(resolved.host).toBe("100.64.0.8");
+  });
+
+  it("requires a custom bind host when bind=custom", () => {
+    const resolved = resolveRuntimeBind({
+      bind: "custom",
+      host: "127.0.0.1",
+    });
+
+    expect(resolved.errors).toContain("server.customBindHost is required when server.bind=custom");
+  });
+
+  it("stores the detected tailscale address for tailnet presets", () => {
+    process.env.PAPERCLIP_TAILNET_BIND_HOST = "100.64.0.8";
+
+    const preset = buildPresetServerConfig("tailnet", {
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    });
+
+    expect(preset.server.host).toBe("100.64.0.8");
+
+    delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
+  });
+
+  it("falls back to loopback when no tailscale address is available for tailnet presets", () => {
+    delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
+
+    const preset = buildPresetServerConfig("tailnet", {
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    });
+
+    expect(preset.server.host).toBe("127.0.0.1");
+  });
+});

cli/src/__tests__/onboard.test.ts

@@ -0,0 +1,166 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { onboard } from "../commands/onboard.js";
+import type { PaperclipConfig } from "../config/schema.js";
+
+const ORIGINAL_ENV = { ...process.env };
+
+function createExistingConfigFixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-"));
+  const runtimeRoot = path.join(root, "runtime");
+  const configPath = path.join(root, ".paperclip", "config.json");
+  const config: PaperclipConfig = {
+    $meta: {
+      version: 1,
+      updatedAt: "2026-03-29T00:00:00.000Z",
+      source: "configure",
+    },
+    database: {
+      mode: "embedded-postgres",
+      embeddedPostgresDataDir: path.join(runtimeRoot, "db"),
+      embeddedPostgresPort: 54329,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: path.join(runtimeRoot, "backups"),
+      },
+    },
+    logging: {
+      mode: "file",
+      logDir: path.join(runtimeRoot, "logs"),
+    },
+    server: {
+      deploymentMode: "local_trusted",
+      exposure: "private",
+      host: "127.0.0.1",
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    },
+    auth: {
+      baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+    telemetry: {
+      enabled: true,
+    },
+    storage: {
+      provider: "local_disk",
+      localDisk: {
+        baseDir: path.join(runtimeRoot, "storage"),
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted",
+      strictMode: false,
+      localEncrypted: {
+        keyFilePath: path.join(runtimeRoot, "secrets", "master.key"),
+      },
+    },
+  };
+
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+
+  return { configPath, configText: fs.readFileSync(configPath, "utf8") };
+}
+
+function createFreshConfigPath() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-fresh-"));
+  return path.join(root, ".paperclip", "config.json");
+}
+
+describe("onboard", () => {
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
+    delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
+    delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
+  });
+
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+  });
+
+  it("preserves an existing config when rerun without flags", async () => {
+    const fixture = createExistingConfigFixture();
+
+    await onboard({ config: fixture.configPath });
+
+    expect(fs.readFileSync(fixture.configPath, "utf8")).toBe(fixture.configText);
+    expect(fs.existsSync(`${fixture.configPath}.backup`)).toBe(false);
+    expect(fs.existsSync(path.join(path.dirname(fixture.configPath), ".env"))).toBe(true);
+  });
+
+  it("preserves an existing config when rerun with --yes", async () => {
+    const fixture = createExistingConfigFixture();
+
+    await onboard({ config: fixture.configPath, yes: true, invokedByRun: true });
+
+    expect(fs.readFileSync(fixture.configPath, "utf8")).toBe(fixture.configText);
+    expect(fs.existsSync(`${fixture.configPath}.backup`)).toBe(false);
+    expect(fs.existsSync(path.join(path.dirname(fixture.configPath), ".env"))).toBe(true);
+  });
+
+  it("keeps --yes onboarding on local trusted loopback defaults", async () => {
+    const configPath = createFreshConfigPath();
+    process.env.HOST = "0.0.0.0";
+    process.env.PAPERCLIP_BIND = "lan";
+
+    await onboard({ config: configPath, yes: true, invokedByRun: true });
+
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
+    expect(raw.server.deploymentMode).toBe("local_trusted");
+    expect(raw.server.exposure).toBe("private");
+    expect(raw.server.bind).toBe("loopback");
+    expect(raw.server.host).toBe("127.0.0.1");
+  });
+
+  it("supports authenticated/private quickstart bind presets", async () => {
+    const configPath = createFreshConfigPath();
+    process.env.PAPERCLIP_TAILNET_BIND_HOST = "100.64.0.8";
+
+    await onboard({ config: configPath, yes: true, invokedByRun: true, bind: "tailnet" });
+
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
+    expect(raw.server.deploymentMode).toBe("authenticated");
+    expect(raw.server.exposure).toBe("private");
+    expect(raw.server.bind).toBe("tailnet");
+    expect(raw.server.host).toBe("100.64.0.8");
+  });
+
+  it("keeps tailnet quickstart on loopback until tailscale is available", async () => {
+    const configPath = createFreshConfigPath();
+    delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
+
+    await onboard({ config: configPath, yes: true, invokedByRun: true, bind: "tailnet" });
+
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
+    expect(raw.server.deploymentMode).toBe("authenticated");
+    expect(raw.server.exposure).toBe("private");
+    expect(raw.server.bind).toBe("tailnet");
+    expect(raw.server.host).toBe("127.0.0.1");
+  });
+
+  it("ignores deployment env overrides during --yes quickstart", async () => {
+    const configPath = createFreshConfigPath();
+    process.env.PAPERCLIP_DEPLOYMENT_MODE = "authenticated";
+
+    await onboard({ config: configPath, yes: true, invokedByRun: true });
+
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
+    expect(raw.server.deploymentMode).toBe("local_trusted");
+    expect(raw.server.exposure).toBe("private");
+    expect(raw.server.bind).toBe("loopback");
+    expect(raw.server.host).toBe("127.0.0.1");
+  });
+});

cli/src/__tests__/routines.test.ts

@@ -0,0 +1,249 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { eq } from "drizzle-orm";
+import {
+  agents,
+  companies,
+  createDb,
+  projects,
+  routines,
+} from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { disableAllRoutinesInConfig } from "../commands/routines.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres routines CLI tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+function writeTestConfig(configPath: string, tempRoot: string, connectionString: string) {
+  const config = {
+    $meta: {
+      version: 1,
+      updatedAt: new Date().toISOString(),
+      source: "doctor" as const,
+    },
+    database: {
+      mode: "postgres" as const,
+      connectionString,
+      embeddedPostgresDataDir: path.join(tempRoot, "embedded-db"),
+      embeddedPostgresPort: 54329,
+      backup: {
+        enabled: false,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: path.join(tempRoot, "backups"),
+      },
+    },
+    logging: {
+      mode: "file" as const,
+      logDir: path.join(tempRoot, "logs"),
+    },
+    server: {
+      deploymentMode: "local_trusted" as const,
+      exposure: "private" as const,
+      host: "127.0.0.1",
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: false,
+    },
+    auth: {
+      baseUrlMode: "auto" as const,
+      disableSignUp: false,
+    },
+    storage: {
+      provider: "local_disk" as const,
+      localDisk: {
+        baseDir: path.join(tempRoot, "storage"),
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted" as const,
+      strictMode: false,
+      localEncrypted: {
+        keyFilePath: path.join(tempRoot, "secrets", "master.key"),
+      },
+    },
+  };
+
+  mkdirSync(path.dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+describeEmbeddedPostgres("disableAllRoutinesInConfig", () => {
+  let db!: ReturnType<typeof createDb>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+  let tempRoot = "";
+  let configPath = "";
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-routines-cli-db-");
+    db = createDb(tempDb.connectionString);
+    tempRoot = mkdtempSync(path.join(os.tmpdir(), "paperclip-routines-cli-config-"));
+    configPath = path.join(tempRoot, "config.json");
+    writeTestConfig(configPath, tempRoot, tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(routines);
+    await db.delete(projects);
+    await db.delete(agents);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+    if (tempRoot) {
+      rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("pauses only non-archived routines for the selected company", async () => {
+    const companyId = randomUUID();
+    const otherCompanyId = randomUUID();
+    const projectId = randomUUID();
+    const otherProjectId = randomUUID();
+    const agentId = randomUUID();
+    const otherAgentId = randomUUID();
+    const activeRoutineId = randomUUID();
+    const pausedRoutineId = randomUUID();
+    const archivedRoutineId = randomUUID();
+    const otherCompanyRoutineId = randomUUID();
+
+    await db.insert(companies).values([
+      {
+        id: companyId,
+        name: "Paperclip",
+        issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+        requireBoardApprovalForNewAgents: false,
+      },
+      {
+        id: otherCompanyId,
+        name: "Other company",
+        issuePrefix: `T${otherCompanyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+        requireBoardApprovalForNewAgents: false,
+      },
+    ]);
+
+    await db.insert(agents).values([
+      {
+        id: agentId,
+        companyId,
+        name: "Coder",
+        adapterType: "process",
+        adapterConfig: {},
+        runtimeConfig: {},
+        permissions: {},
+      },
+      {
+        id: otherAgentId,
+        companyId: otherCompanyId,
+        name: "Other coder",
+        adapterType: "process",
+        adapterConfig: {},
+        runtimeConfig: {},
+        permissions: {},
+      },
+    ]);
+
+    await db.insert(projects).values([
+      {
+        id: projectId,
+        companyId,
+        name: "Project",
+        status: "in_progress",
+      },
+      {
+        id: otherProjectId,
+        companyId: otherCompanyId,
+        name: "Other project",
+        status: "in_progress",
+      },
+    ]);
+
+    await db.insert(routines).values([
+      {
+        id: activeRoutineId,
+        companyId,
+        projectId,
+        assigneeAgentId: agentId,
+        title: "Active routine",
+        status: "active",
+      },
+      {
+        id: pausedRoutineId,
+        companyId,
+        projectId,
+        assigneeAgentId: agentId,
+        title: "Paused routine",
+        status: "paused",
+      },
+      {
+        id: archivedRoutineId,
+        companyId,
+        projectId,
+        assigneeAgentId: agentId,
+        title: "Archived routine",
+        status: "archived",
+      },
+      {
+        id: otherCompanyRoutineId,
+        companyId: otherCompanyId,
+        projectId: otherProjectId,
+        assigneeAgentId: otherAgentId,
+        title: "Other company routine",
+        status: "active",
+      },
+    ]);
+
+    const result = await disableAllRoutinesInConfig({
+      config: configPath,
+      companyId,
+    });
+
+    expect(result).toMatchObject({
+      companyId,
+      totalRoutines: 3,
+      pausedCount: 1,
+      alreadyPausedCount: 1,
+      archivedCount: 1,
+    });
+
+    const companyRoutines = await db
+      .select({
+        id: routines.id,
+        status: routines.status,
+      })
+      .from(routines)
+      .where(eq(routines.companyId, companyId));
+    const statusById = new Map(companyRoutines.map((routine) => [routine.id, routine.status]));
+
+    expect(statusById.get(activeRoutineId)).toBe("paused");
+    expect(statusById.get(pausedRoutineId)).toBe("paused");
+    expect(statusById.get(archivedRoutineId)).toBe("archived");
+
+    const otherCompanyRoutine = await db
+      .select({
+        status: routines.status,
+      })
+      .from(routines)
+      .where(eq(routines.id, otherCompanyRoutineId));
+    expect(otherCompanyRoutine[0]?.status).toBe("active");
+  });
+});

cli/src/__tests__/telemetry.test.ts

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const ORIGINAL_ENV = { ...process.env };
+const CI_ENV_VARS = ["CI", "CONTINUOUS_INTEGRATION", "BUILD_NUMBER", "GITHUB_ACTIONS", "GITLAB_CI"];
+
+function makeConfigPath(root: string, enabled: boolean): string {
+  const configPath = path.join(root, ".paperclip", "config.json");
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify({
+    $meta: {
+      version: 1,
+      updatedAt: "2026-03-31T00:00:00.000Z",
+      source: "configure",
+    },
+    database: {
+      mode: "embedded-postgres",
+      embeddedPostgresDataDir: path.join(root, "runtime", "db"),
+      embeddedPostgresPort: 54329,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: path.join(root, "runtime", "backups"),
+      },
+    },
+    logging: {
+      mode: "file",
+      logDir: path.join(root, "runtime", "logs"),
+    },
+    server: {
+      deploymentMode: "local_trusted",
+      exposure: "private",
+      host: "127.0.0.1",
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    },
+    auth: {
+      baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+    telemetry: {
+      enabled,
+    },
+    storage: {
+      provider: "local_disk",
+      localDisk: {
+        baseDir: path.join(root, "runtime", "storage"),
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted",
+      strictMode: false,
+      localEncrypted: {
+        keyFilePath: path.join(root, "runtime", "secrets", "master.key"),
+      },
+    },
+  }, null, 2));
+  return configPath;
+}
+
+describe("cli telemetry", () => {
+  beforeEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    for (const key of CI_ENV_VARS) {
+      delete process.env[key];
+    }
+    vi.stubGlobal("fetch", vi.fn(async () => ({ ok: true })));
+  });
+
+  afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  it("respects telemetry.enabled=false from the config file", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-cli-telemetry-"));
+    const configPath = makeConfigPath(root, false);
+    process.env.PAPERCLIP_HOME = path.join(root, "home");
+    process.env.PAPERCLIP_INSTANCE_ID = "telemetry-test";
+
+    const { initTelemetryFromConfigFile } = await import("../telemetry.js");
+    const client = initTelemetryFromConfigFile(configPath);
+
+    expect(client).toBeNull();
+    expect(fs.existsSync(path.join(root, "home", "instances", "telemetry-test", "telemetry", "state.json"))).toBe(false);
+  });
+
+  it("creates telemetry state only after the first event is tracked", async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-cli-telemetry-"));
+    process.env.PAPERCLIP_HOME = path.join(root, "home");
+    process.env.PAPERCLIP_INSTANCE_ID = "telemetry-test";
+
+    const { initTelemetry, flushTelemetry } = await import("../telemetry.js");
+    const client = initTelemetry({ enabled: true });
+    const statePath = path.join(root, "home", "instances", "telemetry-test", "telemetry", "state.json");
+
+    expect(client).not.toBeNull();
+    expect(fs.existsSync(statePath)).toBe(false);
+
+    client!.track("install.started", { setupMode: "quickstart" });
+
+    expect(fs.existsSync(statePath)).toBe(true);
+
+    await flushTelemetry();
+  });
+});

cli/src/__tests__/worktree-merge-history.test.ts

@@ -0,0 +1,492 @@
+import { describe, expect, it } from "vitest";
+import { buildWorktreeMergePlan, parseWorktreeMergeScopes } from "../commands/worktree-merge-history-lib.js";
+
+function makeIssue(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "issue-1",
+    companyId: "company-1",
+    projectId: null,
+    projectWorkspaceId: null,
+    goalId: "goal-1",
+    parentId: null,
+    title: "Issue",
+    description: null,
+    status: "todo",
+    priority: "medium",
+    assigneeAgentId: null,
+    assigneeUserId: null,
+    checkoutRunId: null,
+    executionRunId: null,
+    executionAgentNameKey: null,
+    executionLockedAt: null,
+    createdByAgentId: null,
+    createdByUserId: "local-board",
+    issueNumber: 1,
+    identifier: "PAP-1",
+    requestDepth: 0,
+    billingCode: null,
+    assigneeAdapterOverrides: null,
+    executionWorkspaceId: null,
+    executionWorkspacePreference: null,
+    executionWorkspaceSettings: null,
+    startedAt: null,
+    completedAt: null,
+    cancelledAt: null,
+    hiddenAt: null,
+    createdAt: new Date("2026-03-20T00:00:00.000Z"),
+    updatedAt: new Date("2026-03-20T00:00:00.000Z"),
+    ...overrides,
+  } as any;
+}
+
+function makeComment(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "comment-1",
+    companyId: "company-1",
+    issueId: "issue-1",
+    authorAgentId: null,
+    authorUserId: "local-board",
+    body: "hello",
+    createdAt: new Date("2026-03-20T00:00:00.000Z"),
+    updatedAt: new Date("2026-03-20T00:00:00.000Z"),
+    ...overrides,
+  } as any;
+}
+
+function makeIssueDocument(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "issue-document-1",
+    companyId: "company-1",
+    issueId: "issue-1",
+    documentId: "document-1",
+    key: "plan",
+    linkCreatedAt: new Date("2026-03-20T00:00:00.000Z"),
+    linkUpdatedAt: new Date("2026-03-20T00:00:00.000Z"),
+    title: "Plan",
+    format: "markdown",
+    latestBody: "# Plan",
+    latestRevisionId: "revision-1",
+    latestRevisionNumber: 1,
+    createdByAgentId: null,
+    createdByUserId: "local-board",
+    updatedByAgentId: null,
+    updatedByUserId: "local-board",
+    documentCreatedAt: new Date("2026-03-20T00:00:00.000Z"),
+    documentUpdatedAt: new Date("2026-03-20T00:00:00.000Z"),
+    ...overrides,
+  } as any;
+}
+
+function makeDocumentRevision(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "revision-1",
+    companyId: "company-1",
+    documentId: "document-1",
+    revisionNumber: 1,
+    body: "# Plan",
+    changeSummary: null,
+    createdByAgentId: null,
+    createdByUserId: "local-board",
+    createdAt: new Date("2026-03-20T00:00:00.000Z"),
+    ...overrides,
+  } as any;
+}
+
+function makeAttachment(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "attachment-1",
+    companyId: "company-1",
+    issueId: "issue-1",
+    issueCommentId: null,
+    assetId: "asset-1",
+    provider: "local_disk",
+    objectKey: "company-1/issues/issue-1/2026/03/20/asset.png",
+    contentType: "image/png",
+    byteSize: 12,
+    sha256: "deadbeef",
+    originalFilename: "asset.png",
+    createdByAgentId: null,
+    createdByUserId: "local-board",
+    assetCreatedAt: new Date("2026-03-20T00:00:00.000Z"),
+    assetUpdatedAt: new Date("2026-03-20T00:00:00.000Z"),
+    attachmentCreatedAt: new Date("2026-03-20T00:00:00.000Z"),
+    attachmentUpdatedAt: new Date("2026-03-20T00:00:00.000Z"),
+    ...overrides,
+  } as any;
+}
+
+function makeProject(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "project-1",
+    companyId: "company-1",
+    goalId: null,
+    name: "Project",
+    description: null,
+    status: "in_progress",
+    leadAgentId: null,
+    targetDate: null,
+    color: "#22c55e",
+    pauseReason: null,
+    pausedAt: null,
+    executionWorkspacePolicy: null,
+    archivedAt: null,
+    createdAt: new Date("2026-03-20T00:00:00.000Z"),
+    updatedAt: new Date("2026-03-20T00:00:00.000Z"),
+    ...overrides,
+  } as any;
+}
+
+function makeProjectWorkspace(overrides: Record<string, unknown> = {}) {
+  return {
+    id: "workspace-1",
+    companyId: "company-1",
+    projectId: "project-1",
+    name: "Workspace",
+    sourceType: "local_path",
+    cwd: "/tmp/project",
+    repoUrl: "https://github.com/example/project.git",
+    repoRef: "main",
+    defaultRef: "main",
+    visibility: "default",
+    setupCommand: null,
+    cleanupCommand: null,
+    remoteProvider: null,
+    remoteWorkspaceRef: null,
+    sharedWorkspaceKey: null,
+    metadata: null,
+    isPrimary: true,
+    createdAt: new Date("2026-03-20T00:00:00.000Z"),
+    updatedAt: new Date("2026-03-20T00:00:00.000Z"),
+    ...overrides,
+  } as any;
+}
+
+describe("worktree merge history planner", () => {
+  it("parses default scopes", () => {
+    expect(parseWorktreeMergeScopes(undefined)).toEqual(["issues", "comments"]);
+    expect(parseWorktreeMergeScopes("issues")).toEqual(["issues"]);
+  });
+
+  it("dedupes nested worktree issues by preserved source uuid", () => {
+    const sharedIssue = makeIssue({ id: "issue-a", identifier: "PAP-10", title: "Shared" });
+    const branchOneIssue = makeIssue({
+      id: "issue-b",
+      identifier: "PAP-22",
+      title: "Branch one issue",
+      createdAt: new Date("2026-03-20T01:00:00.000Z"),
+    });
+    const branchTwoIssue = makeIssue({
+      id: "issue-c",
+      identifier: "PAP-23",
+      title: "Branch two issue",
+      createdAt: new Date("2026-03-20T02:00:00.000Z"),
+    });
+
+    const plan = buildWorktreeMergePlan({
+      companyId: "company-1",
+      companyName: "Paperclip",
+      issuePrefix: "PAP",
+      previewIssueCounterStart: 500,
+      scopes: ["issues", "comments"],
+      sourceIssues: [sharedIssue, branchOneIssue, branchTwoIssue],
+      targetIssues: [sharedIssue, branchOneIssue],
+      sourceComments: [],
+      targetComments: [],
+      targetAgents: [],
+      targetProjects: [],
+      targetProjectWorkspaces: [],
+      targetGoals: [{ id: "goal-1" }] as any,
+    });
+
+    expect(plan.counts.issuesToInsert).toBe(1);
+    expect(plan.issuePlans.filter((item) => item.action === "insert").map((item) => item.source.id)).toEqual(["issue-c"]);
+    expect(plan.issuePlans.find((item) => item.source.id === "issue-c" && item.action === "insert")).toMatchObject({
+      previewIdentifier: "PAP-501",
+    });
+  });
+
+  it("clears missing references and coerces in_progress without an assignee", () => {
+    const plan = buildWorktreeMergePlan({
+      companyId: "company-1",
+      companyName: "Paperclip",
+      issuePrefix: "PAP",
+      previewIssueCounterStart: 10,
+      scopes: ["issues"],
+      sourceIssues: [
+        makeIssue({
+          id: "issue-x",
+          identifier: "PAP-99",
+          status: "in_progress",
+          assigneeAgentId: "agent-missing",
+          projectId: "project-missing",
+          projectWorkspaceId: "workspace-missing",
+          goalId: "goal-missing",
+        }),
+      ],
+      targetIssues: [],
+      sourceComments: [],
+      targetComments: [],
+      targetAgents: [],
+      targetProjects: [],
+      targetProjectWorkspaces: [],
+      targetGoals: [],
+    });
+
+    const insert = plan.issuePlans[0] as any;
+    expect(insert.targetStatus).toBe("todo");
+    expect(insert.targetAssigneeAgentId).toBeNull();
+    expect(insert.targetProjectId).toBeNull();
+    expect(insert.targetProjectWorkspaceId).toBeNull();
+    expect(insert.targetGoalId).toBeNull();
+    expect(insert.adjustments).toEqual([
+      "clear_assignee_agent",
+      "clear_project",
+      "clear_project_workspace",
+      "clear_goal",
+      "coerce_in_progress_to_todo",
+    ]);
+  });
+
+  it("applies an explicit project mapping override instead of clearing the project", () => {
+    const plan = buildWorktreeMergePlan({
+      companyId: "company-1",
+      companyName: "Paperclip",
+      issuePrefix: "PAP",
+      previewIssueCounterStart: 10,
+      scopes: ["issues"],
+      sourceIssues: [
+        makeIssue({
+          id: "issue-project-map",
+          identifier: "PAP-77",
+          projectId: "source-project-1",
+          projectWorkspaceId: "source-workspace-1",
+        }),
+      ],
+      targetIssues: [],
+      sourceComments: [],
+      targetComments: [],
+      targetAgents: [],
+      targetProjects: [{ id: "target-project-1", name: "Mapped project", status: "in_progress" }] as any,
+      targetProjectWorkspaces: [],
+      targetGoals: [{ id: "goal-1" }] as any,
+      projectIdOverrides: {
+        "source-project-1": "target-project-1",
+      },
+    });
+
+    const insert = plan.issuePlans[0] as any;
+    expect(insert.targetProjectId).toBe("target-project-1");
+    expect(insert.projectResolution).toBe("mapped");
+    expect(insert.mappedProjectName).toBe("Mapped project");
+    expect(insert.targetProjectWorkspaceId).toBeNull();
+    expect(insert.adjustments).toEqual(["clear_project_workspace"]);
+  });
+
+  it("plans selected project imports and preserves project workspace links", () => {
+    const sourceProject = makeProject({
+      id: "source-project-1",
+      name: "Paperclip Evals",
+      goalId: "goal-1",
+    });
+    const sourceWorkspace = makeProjectWorkspace({
+      id: "source-workspace-1",
+      projectId: "source-project-1",
+      cwd: "/Users/dotta/paperclip-evals",
+      repoUrl: "https://github.com/paperclipai/paperclip-evals.git",
+    });
+
+    const plan = buildWorktreeMergePlan({
+      companyId: "company-1",
+      companyName: "Paperclip",
+      issuePrefix: "PAP",
+      previewIssueCounterStart: 10,
+      scopes: ["issues"],
+      sourceIssues: [
+        makeIssue({
+          id: "issue-project-import",
+          identifier: "PAP-88",
+          projectId: "source-project-1",
+          projectWorkspaceId: "source-workspace-1",
+        }),
+      ],
+      targetIssues: [],
+      sourceComments: [],
+      targetComments: [],
+      sourceProjects: [sourceProject],
+      sourceProjectWorkspaces: [sourceWorkspace],
+      targetAgents: [],
+      targetProjects: [],
+      targetProjectWorkspaces: [],
+      targetGoals: [{ id: "goal-1" }] as any,
+      importProjectIds: ["source-project-1"],
+    });
+
+    expect(plan.counts.projectsToImport).toBe(1);
+    expect(plan.projectImports[0]).toMatchObject({
+      source: { id: "source-project-1", name: "Paperclip Evals" },
+      targetGoalId: "goal-1",
+      workspaces: [{ id: "source-workspace-1" }],
+    });
+
+    const insert = plan.issuePlans[0] as any;
+    expect(insert.targetProjectId).toBe("source-project-1");
+    expect(insert.targetProjectWorkspaceId).toBe("source-workspace-1");
+    expect(insert.projectResolution).toBe("imported");
+    expect(insert.mappedProjectName).toBe("Paperclip Evals");
+    expect(insert.adjustments).toEqual([]);
+  });
+
+  it("imports comments onto shared or newly imported issues while skipping existing comments", () => {
+    const sharedIssue = makeIssue({ id: "issue-a", identifier: "PAP-10" });
+    const newIssue = makeIssue({
+      id: "issue-b",
+      identifier: "PAP-11",
+      createdAt: new Date("2026-03-20T01:00:00.000Z"),
+    });
+    const existingComment = makeComment({ id: "comment-existing", issueId: "issue-a" });
+    const sharedIssueComment = makeComment({ id: "comment-shared", issueId: "issue-a" });
+    const newIssueComment = makeComment({
+      id: "comment-new-issue",
+      issueId: "issue-b",
+      authorAgentId: "missing-agent",
+      createdAt: new Date("2026-03-20T01:05:00.000Z"),
+    });
+
+    const plan = buildWorktreeMergePlan({
+      companyId: "company-1",
+      companyName: "Paperclip",
+      issuePrefix: "PAP",
+      previewIssueCounterStart: 10,
+      scopes: ["issues", "comments"],
+      sourceIssues: [sharedIssue, newIssue],
+      targetIssues: [sharedIssue],
+      sourceComments: [existingComment, sharedIssueComment, newIssueComment],
+      targetComments: [existingComment],
+      targetAgents: [],
+      targetProjects: [],
+      targetProjectWorkspaces: [],
+      targetGoals: [{ id: "goal-1" }] as any,
+    });
+
+    expect(plan.counts.commentsToInsert).toBe(2);
+    expect(plan.counts.commentsExisting).toBe(1);
+    expect(plan.commentPlans.filter((item) => item.action === "insert").map((item) => item.source.id)).toEqual([
+      "comment-shared",
+      "comment-new-issue",
+    ]);
+    expect(plan.adjustments.clear_author_agent).toBe(1);
+  });
+
+  it("merges document revisions onto an existing shared document and renumbers conflicts", () => {
+    const sharedIssue = makeIssue({ id: "issue-a", identifier: "PAP-10" });
+    const sourceDocument = makeIssueDocument({
+      issueId: "issue-a",
+      documentId: "document-a",
+      latestBody: "# Branch plan",
+      latestRevisionId: "revision-branch-2",
+      latestRevisionNumber: 2,
+      documentUpdatedAt: new Date("2026-03-20T02:00:00.000Z"),
+      linkUpdatedAt: new Date("2026-03-20T02:00:00.000Z"),
+    });
+    const targetDocument = makeIssueDocument({
+      issueId: "issue-a",
+      documentId: "document-a",
+      latestBody: "# Main plan",
+      latestRevisionId: "revision-main-2",
+      latestRevisionNumber: 2,
+      documentUpdatedAt: new Date("2026-03-20T01:00:00.000Z"),
+      linkUpdatedAt: new Date("2026-03-20T01:00:00.000Z"),
+    });
+    const sourceRevisionOne = makeDocumentRevision({ documentId: "document-a", id: "revision-1" });
+    const sourceRevisionTwo = makeDocumentRevision({
+      documentId: "document-a",
+      id: "revision-branch-2",
+      revisionNumber: 2,
+      body: "# Branch plan",
+      createdAt: new Date("2026-03-20T02:00:00.000Z"),
+    });
+    const targetRevisionOne = makeDocumentRevision({ documentId: "document-a", id: "revision-1" });
+    const targetRevisionTwo = makeDocumentRevision({
+      documentId: "document-a",
+      id: "revision-main-2",
+      revisionNumber: 2,
+      body: "# Main plan",
+      createdAt: new Date("2026-03-20T01:00:00.000Z"),
+    });
+
+    const plan = buildWorktreeMergePlan({
+      companyId: "company-1",
+      companyName: "Paperclip",
+      issuePrefix: "PAP",
+      previewIssueCounterStart: 10,
+      scopes: ["issues", "comments"],
+      sourceIssues: [sharedIssue],
+      targetIssues: [sharedIssue],
+      sourceComments: [],
+      targetComments: [],
+      sourceDocuments: [sourceDocument],
+      targetDocuments: [targetDocument],
+      sourceDocumentRevisions: [sourceRevisionOne, sourceRevisionTwo],
+      targetDocumentRevisions: [targetRevisionOne, targetRevisionTwo],
+      sourceAttachments: [],
+      targetAttachments: [],
+      targetAgents: [],
+      targetProjects: [],
+      targetProjectWorkspaces: [],
+      targetGoals: [{ id: "goal-1" }] as any,
+    });
+
+    expect(plan.counts.documentsToMerge).toBe(1);
+    expect(plan.counts.documentRevisionsToInsert).toBe(1);
+    expect(plan.documentPlans[0]).toMatchObject({
+      action: "merge_existing",
+      latestRevisionId: "revision-branch-2",
+      latestRevisionNumber: 3,
+    });
+    const mergePlan = plan.documentPlans[0] as any;
+    expect(mergePlan.revisionsToInsert).toHaveLength(1);
+    expect(mergePlan.revisionsToInsert[0]).toMatchObject({
+      source: { id: "revision-branch-2" },
+      targetRevisionNumber: 3,
+    });
+  });
+
+  it("imports attachments while clearing missing comment and author references", () => {
+    const sharedIssue = makeIssue({ id: "issue-a", identifier: "PAP-10" });
+    const attachment = makeAttachment({
+      issueId: "issue-a",
+      issueCommentId: "comment-missing",
+      createdByAgentId: "agent-missing",
+    });
+
+    const plan = buildWorktreeMergePlan({
+      companyId: "company-1",
+      companyName: "Paperclip",
+      issuePrefix: "PAP",
+      previewIssueCounterStart: 10,
+      scopes: ["issues"],
+      sourceIssues: [sharedIssue],
+      targetIssues: [sharedIssue],
+      sourceComments: [],
+      targetComments: [],
+      sourceDocuments: [],
+      targetDocuments: [],
+      sourceDocumentRevisions: [],
+      targetDocumentRevisions: [],
+      sourceAttachments: [attachment],
+      targetAttachments: [],
+      targetAgents: [],
+      targetProjects: [],
+      targetProjectWorkspaces: [],
+      targetGoals: [{ id: "goal-1" }] as any,
+    });
+
+    expect(plan.counts.attachmentsToInsert).toBe(1);
+    expect(plan.adjustments.clear_attachment_agent).toBe(1);
+    expect(plan.attachmentPlans[0]).toMatchObject({
+      action: "insert",
+      targetIssueCommentId: null,
+      targetCreatedByAgentId: null,
+    });
+  });
+});

cli/src/adapters/registry.ts

@@ -1,7 +1,11 @@
 import type { CLIAdapterModule } from "@paperclipai/adapter-utils";
 import { printClaudeStreamEvent } from "@paperclipai/adapter-claude-local/cli";
 import { printCodexStreamEvent } from "@paperclipai/adapter-codex-local/cli";
-import { printOpenClawStreamEvent } from "@paperclipai/adapter-openclaw/cli";
+import { printCursorStreamEvent } from "@paperclipai/adapter-cursor-local/cli";
+import { printGeminiStreamEvent } from "@paperclipai/adapter-gemini-local/cli";
+import { printOpenCodeStreamEvent } from "@paperclipai/adapter-opencode-local/cli";
+import { printPiStreamEvent } from "@paperclipai/adapter-pi-local/cli";
+import { printOpenClawGatewayStreamEvent } from "@paperclipai/adapter-openclaw-gateway/cli";
 import { processCLIAdapter } from "./process/index.js";
 import { httpCLIAdapter } from "./http/index.js";
 
@@ -15,13 +19,43 @@ const codexLocalCLIAdapter: CLIAdapterModule = {
   formatStdoutEvent: printCodexStreamEvent,
 };
 
-const openclawCLIAdapter: CLIAdapterModule = {
-  type: "openclaw",
-  formatStdoutEvent: printOpenClawStreamEvent,
+const openCodeLocalCLIAdapter: CLIAdapterModule = {
+  type: "opencode_local",
+  formatStdoutEvent: printOpenCodeStreamEvent,
+};
+
+const piLocalCLIAdapter: CLIAdapterModule = {
+  type: "pi_local",
+  formatStdoutEvent: printPiStreamEvent,
+};
+
+const cursorLocalCLIAdapter: CLIAdapterModule = {
+  type: "cursor",
+  formatStdoutEvent: printCursorStreamEvent,
+};
+
+const geminiLocalCLIAdapter: CLIAdapterModule = {
+  type: "gemini_local",
+  formatStdoutEvent: printGeminiStreamEvent,
+};
+
+const openclawGatewayCLIAdapter: CLIAdapterModule = {
+  type: "openclaw_gateway",
+  formatStdoutEvent: printOpenClawGatewayStreamEvent,
 };
 
 const adaptersByType = new Map<string, CLIAdapterModule>(
-  [claudeLocalCLIAdapter, codexLocalCLIAdapter, openclawCLIAdapter, processCLIAdapter, httpCLIAdapter].map((a) => [a.type, a]),
+  [
+    claudeLocalCLIAdapter,
+    codexLocalCLIAdapter,
+    openCodeLocalCLIAdapter,
+    piLocalCLIAdapter,
+    cursorLocalCLIAdapter,
+    geminiLocalCLIAdapter,
+    openclawGatewayCLIAdapter,
+    processCLIAdapter,
+    httpCLIAdapter,
+  ].map((a) => [a.type, a]),
 );
 
 export function getCLIAdapter(type: string): CLIAdapterModule {

cli/src/checks/deployment-auth-check.ts

@@ -1,24 +1,21 @@
+import { inferBindModeFromHost } from "@paperclipai/shared";
 import type { PaperclipConfig } from "../config/schema.js";
 import type { CheckResult } from "./index.js";
 
-function isLoopbackHost(host: string) {
-  const normalized = host.trim().toLowerCase();
-  return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";
-}
-
 export function deploymentAuthCheck(config: PaperclipConfig): CheckResult {
   const mode = config.server.deploymentMode;
   const exposure = config.server.exposure;
   const auth = config.auth;
+  const bind = config.server.bind ?? inferBindModeFromHost(config.server.host);
 
   if (mode === "local_trusted") {
-    if (!isLoopbackHost(config.server.host)) {
+    if (bind !== "loopback") {
       return {
         name: "Deployment/auth mode",
         status: "fail",
-        message: `local_trusted requires loopback host binding (found ${config.server.host})`,
+        message: `local_trusted requires loopback binding (found ${bind})`,
         canRepair: false,
-        repairHint: "Run `paperclipai configure --section server` and set host to 127.0.0.1",
+        repairHint: "Run `paperclipai configure --section server` and choose Local trusted / loopback reachability",
       };
     }
     return {
@@ -86,6 +83,6 @@ export function deploymentAuthCheck(config: PaperclipConfig): CheckResult {
   return {
     name: "Deployment/auth mode",
     status: "pass",
-    message: `Mode ${mode}/${exposure} with auth URL mode ${auth.baseUrlMode}`,
+    message: `Mode ${mode}/${exposure} with bind ${bind} and auth URL mode ${auth.baseUrlMode}`,
   };
 }

cli/src/client/board-auth.ts

@@ -0,0 +1,282 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import pc from "picocolors";
+import { buildCliCommandLabel } from "./command-label.js";
+import { resolveDefaultCliAuthPath } from "../config/home.js";
+
+type RequestedAccess = "board" | "instance_admin_required";
+
+interface BoardAuthCredential {
+  apiBase: string;
+  token: string;
+  createdAt: string;
+  updatedAt: string;
+  userId?: string | null;
+}
+
+interface BoardAuthStore {
+  version: 1;
+  credentials: Record<string, BoardAuthCredential>;
+}
+
+interface CreateChallengeResponse {
+  id: string;
+  token: string;
+  boardApiToken: string;
+  approvalPath: string;
+  approvalUrl: string | null;
+  pollPath: string;
+  expiresAt: string;
+  suggestedPollIntervalMs: number;
+}
+
+interface ChallengeStatusResponse {
+  id: string;
+  status: "pending" | "approved" | "cancelled" | "expired";
+  command: string;
+  clientName: string | null;
+  requestedAccess: RequestedAccess;
+  requestedCompanyId: string | null;
+  requestedCompanyName: string | null;
+  approvedAt: string | null;
+  cancelledAt: string | null;
+  expiresAt: string;
+  approvedByUser: { id: string; name: string; email: string } | null;
+}
+
+function defaultBoardAuthStore(): BoardAuthStore {
+  return {
+    version: 1,
+    credentials: {},
+  };
+}
+
+function toStringOrNull(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function normalizeApiBase(apiBase: string): string {
+  return apiBase.trim().replace(/\/+$/, "");
+}
+
+export function resolveBoardAuthStorePath(overridePath?: string): string {
+  if (overridePath?.trim()) return path.resolve(overridePath.trim());
+  if (process.env.PAPERCLIP_AUTH_STORE?.trim()) return path.resolve(process.env.PAPERCLIP_AUTH_STORE.trim());
+  return resolveDefaultCliAuthPath();
+}
+
+export function readBoardAuthStore(storePath?: string): BoardAuthStore {
+  const filePath = resolveBoardAuthStorePath(storePath);
+  if (!fs.existsSync(filePath)) return defaultBoardAuthStore();
+
+  const raw = JSON.parse(fs.readFileSync(filePath, "utf8")) as Partial<BoardAuthStore> | null;
+  const credentials = raw?.credentials && typeof raw.credentials === "object" ? raw.credentials : {};
+  const normalized: Record<string, BoardAuthCredential> = {};
+
+  for (const [key, value] of Object.entries(credentials)) {
+    if (typeof value !== "object" || value === null) continue;
+    const record = value as unknown as Record<string, unknown>;
+    const apiBase = toStringOrNull(record.apiBase);
+    const token = toStringOrNull(record.token);
+    const createdAt = toStringOrNull(record.createdAt);
+    const updatedAt = toStringOrNull(record.updatedAt);
+    if (!apiBase || !token || !createdAt || !updatedAt) continue;
+    normalized[normalizeApiBase(key)] = {
+      apiBase,
+      token,
+      createdAt,
+      updatedAt,
+      userId: toStringOrNull(record.userId),
+    };
+  }
+
+  return {
+    version: 1,
+    credentials: normalized,
+  };
+}
+
+export function writeBoardAuthStore(store: BoardAuthStore, storePath?: string): void {
+  const filePath = resolveBoardAuthStorePath(storePath);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+}
+
+export function getStoredBoardCredential(apiBase: string, storePath?: string): BoardAuthCredential | null {
+  const store = readBoardAuthStore(storePath);
+  return store.credentials[normalizeApiBase(apiBase)] ?? null;
+}
+
+export function setStoredBoardCredential(input: {
+  apiBase: string;
+  token: string;
+  userId?: string | null;
+  storePath?: string;
+}): BoardAuthCredential {
+  const normalizedApiBase = normalizeApiBase(input.apiBase);
+  const store = readBoardAuthStore(input.storePath);
+  const now = new Date().toISOString();
+  const existing = store.credentials[normalizedApiBase];
+  const credential: BoardAuthCredential = {
+    apiBase: normalizedApiBase,
+    token: input.token.trim(),
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+    userId: input.userId ?? existing?.userId ?? null,
+  };
+  store.credentials[normalizedApiBase] = credential;
+  writeBoardAuthStore(store, input.storePath);
+  return credential;
+}
+
+export function removeStoredBoardCredential(apiBase: string, storePath?: string): boolean {
+  const normalizedApiBase = normalizeApiBase(apiBase);
+  const store = readBoardAuthStore(storePath);
+  if (!store.credentials[normalizedApiBase]) return false;
+  delete store.credentials[normalizedApiBase];
+  writeBoardAuthStore(store, storePath);
+  return true;
+}
+
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function requestJson<T>(url: string, init?: RequestInit): Promise<T> {
+  const headers = new Headers(init?.headers ?? undefined);
+  if (init?.body !== undefined && !headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  if (!headers.has("accept")) {
+    headers.set("accept", "application/json");
+  }
+
+  const response = await fetch(url, {
+    ...init,
+    headers,
+  });
+
+  if (!response.ok) {
+    const body = await response.json().catch(() => null);
+    const message =
+      body && typeof body === "object" && typeof (body as { error?: unknown }).error === "string"
+        ? (body as { error: string }).error
+        : `Request failed: ${response.status}`;
+    throw new Error(message);
+  }
+
+  return response.json() as Promise<T>;
+}
+
+export function openUrl(url: string): boolean {
+  const platform = process.platform;
+  try {
+    if (platform === "darwin") {
+      const child = spawn("open", [url], { detached: true, stdio: "ignore" });
+      child.unref();
+      return true;
+    }
+    if (platform === "win32") {
+      const child = spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" });
+      child.unref();
+      return true;
+    }
+    const child = spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function loginBoardCli(params: {
+  apiBase: string;
+  requestedAccess: RequestedAccess;
+  requestedCompanyId?: string | null;
+  clientName?: string | null;
+  command?: string;
+  storePath?: string;
+  print?: boolean;
+}): Promise<{ token: string; approvalUrl: string; userId?: string | null }> {
+  const apiBase = normalizeApiBase(params.apiBase);
+  const createUrl = `${apiBase}/api/cli-auth/challenges`;
+  const command = params.command?.trim() || buildCliCommandLabel();
+
+  const challenge = await requestJson<CreateChallengeResponse>(createUrl, {
+    method: "POST",
+    body: JSON.stringify({
+      command,
+      clientName: params.clientName?.trim() || "paperclipai cli",
+      requestedAccess: params.requestedAccess,
+      requestedCompanyId: params.requestedCompanyId?.trim() || null,
+    }),
+  });
+
+  const approvalUrl = challenge.approvalUrl ?? `${apiBase}${challenge.approvalPath}`;
+  if (params.print !== false) {
+    console.error(pc.bold("Board authentication required"));
+    console.error(`Open this URL in your browser to approve CLI access:\n${approvalUrl}`);
+  }
+
+  const opened = openUrl(approvalUrl);
+  if (params.print !== false && opened) {
+    console.error(pc.dim("Opened the approval page in your browser."));
+  }
+
+  const expiresAtMs = Date.parse(challenge.expiresAt);
+  const pollMs = Math.max(500, challenge.suggestedPollIntervalMs || 1000);
+
+  while (Number.isFinite(expiresAtMs) ? Date.now() < expiresAtMs : true) {
+    const status = await requestJson<ChallengeStatusResponse>(
+      `${apiBase}/api${challenge.pollPath}?token=${encodeURIComponent(challenge.token)}`,
+    );
+
+    if (status.status === "approved") {
+      const me = await requestJson<{ userId: string; user?: { id: string } | null }>(
+        `${apiBase}/api/cli-auth/me`,
+        {
+          headers: {
+            authorization: `Bearer ${challenge.boardApiToken}`,
+          },
+        },
+      );
+      setStoredBoardCredential({
+        apiBase,
+        token: challenge.boardApiToken,
+        userId: me.userId ?? me.user?.id ?? null,
+        storePath: params.storePath,
+      });
+      return {
+        token: challenge.boardApiToken,
+        approvalUrl,
+        userId: me.userId ?? me.user?.id ?? null,
+      };
+    }
+
+    if (status.status === "cancelled") {
+      throw new Error("CLI auth challenge was cancelled.");
+    }
+    if (status.status === "expired") {
+      throw new Error("CLI auth challenge expired before approval.");
+    }
+
+    await sleep(pollMs);
+  }
+
+  throw new Error("CLI auth challenge expired before approval.");
+}
+
+export async function revokeStoredBoardCredential(params: {
+  apiBase: string;
+  token: string;
+}): Promise<void> {
+  const apiBase = normalizeApiBase(params.apiBase);
+  await requestJson<{ revoked: boolean }>(`${apiBase}/api/cli-auth/revoke-current`, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${params.token}`,
+    },
+    body: JSON.stringify({}),
+  });
+}

cli/src/client/command-label.ts

@@ -0,0 +1,4 @@
+export function buildCliCommandLabel(): string {
+  const args = process.argv.slice(2);
+  return args.length > 0 ? `paperclipai ${args.join(" ")}` : "paperclipai";
+}

cli/src/client/http.ts

@@ -13,25 +13,54 @@ export class ApiRequestError extends Error {
   }
 }
 
+export class ApiConnectionError extends Error {
+  url: string;
+  method: string;
+  causeMessage?: string;
+
+  constructor(input: {
+    apiBase: string;
+    path: string;
+    method: string;
+    cause?: unknown;
+  }) {
+    const url = buildUrl(input.apiBase, input.path);
+    const causeMessage = formatConnectionCause(input.cause);
+    super(buildConnectionErrorMessage({ apiBase: input.apiBase, url, method: input.method, causeMessage }));
+    this.url = url;
+    this.method = input.method;
+    this.causeMessage = causeMessage;
+  }
+}
+
 interface RequestOptions {
   ignoreNotFound?: boolean;
 }
 
+interface RecoverAuthInput {
+  path: string;
+  method: string;
+  error: ApiRequestError;
+}
+
 interface ApiClientOptions {
   apiBase: string;
   apiKey?: string;
   runId?: string;
+  recoverAuth?: (input: RecoverAuthInput) => Promise<string | null>;
 }
 
 export class PaperclipApiClient {
   readonly apiBase: string;
-  readonly apiKey?: string;
+  apiKey?: string;
   readonly runId?: string;
+  readonly recoverAuth?: (input: RecoverAuthInput) => Promise<string | null>;
 
   constructor(opts: ApiClientOptions) {
     this.apiBase = opts.apiBase.replace(/\/+$/, "");
     this.apiKey = opts.apiKey?.trim() || undefined;
     this.runId = opts.runId?.trim() || undefined;
+    this.recoverAuth = opts.recoverAuth;
   }
 
   get<T>(path: string, opts?: RequestOptions): Promise<T | null> {
@@ -56,8 +85,18 @@ export class PaperclipApiClient {
     return this.request<T>(path, { method: "DELETE" }, opts);
   }
 
-  private async request<T>(path: string, init: RequestInit, opts?: RequestOptions): Promise<T | null> {
+  setApiKey(apiKey: string | undefined) {
+    this.apiKey = apiKey?.trim() || undefined;
+  }
+
+  private async request<T>(
+    path: string,
+    init: RequestInit,
+    opts?: RequestOptions,
+    hasRetriedAuth = false,
+  ): Promise<T | null> {
     const url = buildUrl(this.apiBase, path);
+    const method = String(init.method ?? "GET").toUpperCase();
 
     const headers: Record<string, string> = {
       accept: "application/json",
@@ -76,17 +115,39 @@ export class PaperclipApiClient {
       headers["x-paperclip-run-id"] = this.runId;
     }
 
-    const response = await fetch(url, {
-      ...init,
-      headers,
-    });
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        ...init,
+        headers,
+      });
+    } catch (error) {
+      throw new ApiConnectionError({
+        apiBase: this.apiBase,
+        path,
+        method,
+        cause: error,
+      });
+    }
 
     if (opts?.ignoreNotFound && response.status === 404) {
       return null;
     }
 
     if (!response.ok) {
-      throw await toApiError(response);
+      const apiError = await toApiError(response);
+      if (!hasRetriedAuth && this.recoverAuth) {
+        const recoveredToken = await this.recoverAuth({
+          path,
+          method,
+          error: apiError,
+        });
+        if (recoveredToken) {
+          this.setApiKey(recoveredToken);
+          return this.request<T>(path, init, opts, true);
+        }
+      }
+      throw apiError;
     }
 
     if (response.status === 204) {
@@ -104,8 +165,10 @@ export class PaperclipApiClient {
 
 function buildUrl(apiBase: string, path: string): string {
   const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  const [pathname, query] = normalizedPath.split("?");
   const url = new URL(apiBase);
-  url.pathname = `${url.pathname.replace(/\/+$/, "")}${normalizedPath}`;
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}${pathname}`;
+  if (query) url.search = query;
   return url.toString();
 }
 
@@ -134,6 +197,50 @@ async function toApiError(response: Response): Promise<ApiRequestError> {
   return new ApiRequestError(response.status, `Request failed with status ${response.status}`, undefined, parsed);
 }
 
+function buildConnectionErrorMessage(input: {
+  apiBase: string;
+  url: string;
+  method: string;
+  causeMessage?: string;
+}): string {
+  const healthUrl = buildHealthCheckUrl(input.url);
+  const lines = [
+    "Could not reach the Paperclip API.",
+    "",
+    `Request: ${input.method} ${input.url}`,
+  ];
+  if (input.causeMessage) {
+    lines.push(`Cause: ${input.causeMessage}`);
+  }
+  lines.push(
+    "",
+    "This usually means the Paperclip server is not running, the configured URL is wrong, or the request is being blocked before it reaches Paperclip.",
+    "",
+    "Try:",
+    "- Start Paperclip with `pnpm dev` or `pnpm paperclipai run`.",
+    `- Verify the server is reachable with \`curl ${healthUrl}\`.`,
+    `- If Paperclip is running elsewhere, pass \`--api-base ${input.apiBase.replace(/\/+$/, "")}\` or set \`PAPERCLIP_API_URL\`.`,
+  );
+  return lines.join("\n");
+}
+
+function buildHealthCheckUrl(requestUrl: string): string {
+  const url = new URL(requestUrl);
+  url.pathname = `${url.pathname.replace(/\/+$/, "").replace(/\/api(?:\/.*)?$/, "")}/api/health`;
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
+function formatConnectionCause(error: unknown): string | undefined {
+  if (!error) return undefined;
+  if (error instanceof Error) {
+    return error.message.trim() || error.name;
+  }
+  const message = String(error).trim();
+  return message || undefined;
+}
+
 function toStringRecord(headers: HeadersInit | undefined): Record<string, string> {
   if (!headers) return {};
   if (Array.isArray(headers)) {

cli/src/commands/allowed-hostname.ts

@@ -26,6 +26,9 @@ export async function addAllowedHostname(host: string, opts: { config?: string }
     p.log.info(`Hostname ${pc.cyan(normalized)} is already allowed.`);
   } else {
     p.log.success(`Added allowed hostname: ${pc.cyan(normalized)}`);
+    p.log.message(
+      pc.dim("Restart the Paperclip server for this change to take effect."),
+    );
   }
 
   if (!(config.server.deploymentMode === "authenticated" && config.server.exposure === "private")) {

cli/src/commands/auth-bootstrap-ceo.ts

@@ -3,6 +3,8 @@ import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { and, eq, gt, isNull } from "drizzle-orm";
 import { createDb, instanceUserRoles, invites } from "@paperclipai/db";
+import { inferBindModeFromHost } from "@paperclipai/shared";
+import { loadPaperclipEnvFile } from "../config/env.js";
 import { readConfig, resolveConfigPath } from "../config/store.js";
 
 function hashToken(token: string) {
@@ -13,7 +15,8 @@ function createInviteToken() {
   return `pcp_bootstrap_${randomBytes(24).toString("hex")}`;
 }
 
-function resolveDbUrl(configPath?: string) {
+function resolveDbUrl(configPath?: string, explicitDbUrl?: string) {
+  if (explicitDbUrl) return explicitDbUrl;
   const config = readConfig(configPath);
   if (process.env.DATABASE_URL) return process.env.DATABASE_URL;
   if (config?.database.mode === "postgres" && config.database.connectionString) {
@@ -28,13 +31,23 @@ function resolveDbUrl(configPath?: string) {
 
 function resolveBaseUrl(configPath?: string, explicitBaseUrl?: string) {
   if (explicitBaseUrl) return explicitBaseUrl.replace(/\/+$/, "");
+  const fromEnv =
+    process.env.PAPERCLIP_PUBLIC_URL ??
+    process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL ??
+    process.env.BETTER_AUTH_URL ??
+    process.env.BETTER_AUTH_BASE_URL;
+  if (fromEnv?.trim()) return fromEnv.trim().replace(/\/+$/, "");
   const config = readConfig(configPath);
   if (config?.auth.baseUrlMode === "explicit" && config.auth.publicBaseUrl) {
     return config.auth.publicBaseUrl.replace(/\/+$/, "");
   }
-  const host = config?.server.host ?? "localhost";
+  const bind = config?.server.bind ?? inferBindModeFromHost(config?.server.host);
+  const host =
+    bind === "custom"
+      ? config?.server.customBindHost ?? config?.server.host ?? "localhost"
+      : config?.server.host ?? "localhost";
   const port = config?.server.port ?? 3100;
-  const publicHost = host === "0.0.0.0" ? "localhost" : host;
+  const publicHost = host === "0.0.0.0" || bind === "lan" ? "localhost" : host;
   return `http://${publicHost}:${port}`;
 }
 
@@ -43,8 +56,10 @@ export async function bootstrapCeoInvite(opts: {
   force?: boolean;
   expiresHours?: number;
   baseUrl?: string;
+  dbUrl?: string;
 }) {
   const configPath = resolveConfigPath(opts.config);
+  loadPaperclipEnvFile(configPath);
   const config = readConfig(configPath);
   if (!config) {
     p.log.error(`No config found at ${configPath}. Run ${pc.cyan("paperclip onboard")} first.`);
@@ -56,7 +71,7 @@ export async function bootstrapCeoInvite(opts: {
     return;
   }
 
-  const dbUrl = resolveDbUrl(configPath);
+  const dbUrl = resolveDbUrl(configPath, opts.dbUrl);
   if (!dbUrl) {
     p.log.error(
       "Could not resolve database connection for bootstrap.",
@@ -65,6 +80,11 @@ export async function bootstrapCeoInvite(opts: {
   }
 
   const db = createDb(dbUrl);
+  const closableDb = db as typeof db & {
+    $client?: {
+      end?: (options?: { timeout?: number }) => Promise<void>;
+    };
+  };
   try {
     const existingAdminCount = await db
       .select()
@@ -112,5 +132,7 @@ export async function bootstrapCeoInvite(opts: {
   } catch (err) {
     p.log.error(`Could not create bootstrap invite: ${err instanceof Error ? err.message : String(err)}`);
     p.log.info("If using embedded-postgres, start the Paperclip server and run this command again.");
+  } finally {
+    await closableDb.$client?.end?.({ timeout: 5 }).catch(() => undefined);
   }
 }

cli/src/commands/client/agent.ts

@@ -1,5 +1,13 @@
 import { Command } from "commander";
 import type { Agent } from "@paperclipai/shared";
+import {
+  removeMaintainerOnlySkillSymlinks,
+  resolvePaperclipSkillsDir,
+} from "@paperclipai/adapter-utils/server-utils";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import {
   addCommonClientOptions,
   formatInlineRecord,
@@ -13,6 +21,141 @@ interface AgentListOptions extends BaseClientOptions {
   companyId?: string;
 }
 
+interface AgentLocalCliOptions extends BaseClientOptions {
+  companyId?: string;
+  keyName?: string;
+  installSkills?: boolean;
+}
+
+interface CreatedAgentKey {
+  id: string;
+  name: string;
+  token: string;
+  createdAt: string;
+}
+
+interface SkillsInstallSummary {
+  tool: "codex" | "claude";
+  target: string;
+  linked: string[];
+  removed: string[];
+  skipped: string[];
+  failed: Array<{ name: string; error: string }>;
+}
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+function codexSkillsHome(): string {
+  const fromEnv = process.env.CODEX_HOME?.trim();
+  const base = fromEnv && fromEnv.length > 0 ? fromEnv : path.join(os.homedir(), ".codex");
+  return path.join(base, "skills");
+}
+
+function claudeSkillsHome(): string {
+  const fromEnv = process.env.CLAUDE_HOME?.trim();
+  const base = fromEnv && fromEnv.length > 0 ? fromEnv : path.join(os.homedir(), ".claude");
+  return path.join(base, "skills");
+}
+
+async function installSkillsForTarget(
+  sourceSkillsDir: string,
+  targetSkillsDir: string,
+  tool: "codex" | "claude",
+): Promise<SkillsInstallSummary> {
+  const summary: SkillsInstallSummary = {
+    tool,
+    target: targetSkillsDir,
+    linked: [],
+    removed: [],
+    skipped: [],
+    failed: [],
+  };
+
+  await fs.mkdir(targetSkillsDir, { recursive: true });
+  const entries = await fs.readdir(sourceSkillsDir, { withFileTypes: true });
+  summary.removed = await removeMaintainerOnlySkillSymlinks(
+    targetSkillsDir,
+    entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name),
+  );
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const source = path.join(sourceSkillsDir, entry.name);
+    const target = path.join(targetSkillsDir, entry.name);
+    const existing = await fs.lstat(target).catch(() => null);
+    if (existing) {
+      if (existing.isSymbolicLink()) {
+        let linkedPath: string | null = null;
+        try {
+          linkedPath = await fs.readlink(target);
+        } catch (err) {
+          await fs.unlink(target);
+          try {
+            await fs.symlink(source, target);
+            summary.linked.push(entry.name);
+            continue;
+          } catch (linkErr) {
+            summary.failed.push({
+              name: entry.name,
+              error:
+                err instanceof Error && linkErr instanceof Error
+                  ? `${err.message}; then ${linkErr.message}`
+                  : err instanceof Error
+                    ? err.message
+                    : `Failed to recover broken symlink: ${String(err)}`,
+            });
+            continue;
+          }
+        }
+
+        const resolvedLinkedPath = path.isAbsolute(linkedPath)
+          ? linkedPath
+          : path.resolve(path.dirname(target), linkedPath);
+        const linkedTargetExists = await fs
+          .stat(resolvedLinkedPath)
+          .then(() => true)
+          .catch(() => false);
+
+        if (!linkedTargetExists) {
+          await fs.unlink(target);
+        } else {
+          summary.skipped.push(entry.name);
+          continue;
+        }
+      } else {
+        summary.skipped.push(entry.name);
+        continue;
+      }
+    }
+
+    try {
+      await fs.symlink(source, target);
+      summary.linked.push(entry.name);
+    } catch (err) {
+      summary.failed.push({
+        name: entry.name,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return summary;
+}
+
+function buildAgentEnvExports(input: {
+  apiBase: string;
+  companyId: string;
+  agentId: string;
+  apiKey: string;
+}): string {
+  const escaped = (value: string) => value.replace(/'/g, "'\"'\"'");
+  return [
+    `export PAPERCLIP_API_URL='${escaped(input.apiBase)}'`,
+    `export PAPERCLIP_COMPANY_ID='${escaped(input.companyId)}'`,
+    `export PAPERCLIP_AGENT_ID='${escaped(input.agentId)}'`,
+    `export PAPERCLIP_API_KEY='${escaped(input.apiKey)}'`,
+  ].join("\n");
+}
+
 export function registerAgentCommands(program: Command): void {
   const agent = program.command("agent").description("Agent operations");
 
@@ -71,4 +214,102 @@ export function registerAgentCommands(program: Command): void {
         }
       }),
   );
+
+  addCommonClientOptions(
+    agent
+      .command("local-cli")
+      .description(
+        "Create an agent API key, install local Paperclip skills for Codex/Claude, and print shell exports",
+      )
+      .argument("<agentRef>", "Agent ID or shortname/url-key")
+      .requiredOption("-C, --company-id <id>", "Company ID")
+      .option("--key-name <name>", "API key label", "local-cli")
+      .option(
+        "--no-install-skills",
+        "Skip installing Paperclip skills into ~/.codex/skills and ~/.claude/skills",
+      )
+      .action(async (agentRef: string, opts: AgentLocalCliOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts, { requireCompany: true });
+          const query = new URLSearchParams({ companyId: ctx.companyId ?? "" });
+          const agentRow = await ctx.api.get<Agent>(
+            `/api/agents/${encodeURIComponent(agentRef)}?${query.toString()}`,
+          );
+          if (!agentRow) {
+            throw new Error(`Agent not found: ${agentRef}`);
+          }
+
+          const now = new Date().toISOString().replaceAll(":", "-");
+          const keyName = opts.keyName?.trim() ? opts.keyName.trim() : `local-cli-${now}`;
+          const key = await ctx.api.post<CreatedAgentKey>(`/api/agents/${agentRow.id}/keys`, { name: keyName });
+          if (!key) {
+            throw new Error("Failed to create API key");
+          }
+
+          const installSummaries: SkillsInstallSummary[] = [];
+          if (opts.installSkills !== false) {
+            const skillsDir = await resolvePaperclipSkillsDir(__moduleDir, [path.resolve(process.cwd(), "skills")]);
+            if (!skillsDir) {
+              throw new Error(
+                "Could not locate local Paperclip skills directory. Expected ./skills in the repo checkout.",
+              );
+            }
+
+            installSummaries.push(
+              await installSkillsForTarget(skillsDir, codexSkillsHome(), "codex"),
+              await installSkillsForTarget(skillsDir, claudeSkillsHome(), "claude"),
+            );
+          }
+
+          const exportsText = buildAgentEnvExports({
+            apiBase: ctx.api.apiBase,
+            companyId: agentRow.companyId,
+            agentId: agentRow.id,
+            apiKey: key.token,
+          });
+
+          if (ctx.json) {
+            printOutput(
+              {
+                agent: {
+                  id: agentRow.id,
+                  name: agentRow.name,
+                  urlKey: agentRow.urlKey,
+                  companyId: agentRow.companyId,
+                },
+                key: {
+                  id: key.id,
+                  name: key.name,
+                  createdAt: key.createdAt,
+                  token: key.token,
+                },
+                skills: installSummaries,
+                exports: exportsText,
+              },
+              { json: true },
+            );
+            return;
+          }
+
+          console.log(`Agent: ${agentRow.name} (${agentRow.id})`);
+          console.log(`API key created: ${key.name} (${key.id})`);
+          if (installSummaries.length > 0) {
+            for (const summary of installSummaries) {
+              console.log(
+                `${summary.tool}: linked=${summary.linked.length} removed=${summary.removed.length} skipped=${summary.skipped.length} failed=${summary.failed.length} target=${summary.target}`,
+              );
+              for (const failed of summary.failed) {
+                console.log(`  failed ${failed.name}: ${failed.error}`);
+              }
+            }
+          }
+          console.log("");
+          console.log("# Run this in your shell before launching codex/claude:");
+          console.log(exportsText);
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+    { includeCompany: false },
+  );
 }

cli/src/commands/client/auth.ts

@@ -0,0 +1,113 @@
+import type { Command } from "commander";
+import {
+  getStoredBoardCredential,
+  loginBoardCli,
+  removeStoredBoardCredential,
+  revokeStoredBoardCredential,
+} from "../../client/board-auth.js";
+import {
+  addCommonClientOptions,
+  handleCommandError,
+  printOutput,
+  resolveCommandContext,
+  type BaseClientOptions,
+} from "./common.js";
+
+interface AuthLoginOptions extends BaseClientOptions {
+  instanceAdmin?: boolean;
+}
+
+interface AuthLogoutOptions extends BaseClientOptions {}
+interface AuthWhoamiOptions extends BaseClientOptions {}
+
+export function registerClientAuthCommands(auth: Command): void {
+  addCommonClientOptions(
+    auth
+      .command("login")
+      .description("Authenticate the CLI for board-user access")
+      .option("--instance-admin", "Request instance-admin approval instead of plain board access", false)
+      .action(async (opts: AuthLoginOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const login = await loginBoardCli({
+            apiBase: ctx.api.apiBase,
+            requestedAccess: opts.instanceAdmin ? "instance_admin_required" : "board",
+            requestedCompanyId: ctx.companyId ?? null,
+            command: "paperclipai auth login",
+          });
+          printOutput(
+            {
+              ok: true,
+              apiBase: ctx.api.apiBase,
+              userId: login.userId ?? null,
+              approvalUrl: login.approvalUrl,
+            },
+            { json: ctx.json },
+          );
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+    { includeCompany: true },
+  );
+
+  addCommonClientOptions(
+    auth
+      .command("logout")
+      .description("Remove the stored board-user credential for this API base")
+      .action(async (opts: AuthLogoutOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const credential = getStoredBoardCredential(ctx.api.apiBase);
+          if (!credential) {
+            printOutput({ ok: true, apiBase: ctx.api.apiBase, revoked: false, removedLocalCredential: false }, { json: ctx.json });
+            return;
+          }
+          let revoked = false;
+          try {
+            await revokeStoredBoardCredential({
+              apiBase: ctx.api.apiBase,
+              token: credential.token,
+            });
+            revoked = true;
+          } catch {
+            // Remove the local credential even if the server-side revoke fails.
+          }
+          const removedLocalCredential = removeStoredBoardCredential(ctx.api.apiBase);
+          printOutput(
+            {
+              ok: true,
+              apiBase: ctx.api.apiBase,
+              revoked,
+              removedLocalCredential,
+            },
+            { json: ctx.json },
+          );
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  addCommonClientOptions(
+    auth
+      .command("whoami")
+      .description("Show the current board-user identity for this API base")
+      .action(async (opts: AuthWhoamiOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const me = await ctx.api.get<{
+            user: { id: string; name: string; email: string } | null;
+            userId: string;
+            isInstanceAdmin: boolean;
+            companyIds: string[];
+            source: string;
+            keyId: string | null;
+          }>("/api/cli-auth/me");
+          printOutput(me, { json: ctx.json });
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+}

cli/src/commands/client/common.ts

@@ -1,5 +1,7 @@
 import pc from "picocolors";
 import type { Command } from "commander";
+import { getStoredBoardCredential, loginBoardCli } from "../../client/board-auth.js";
+import { buildCliCommandLabel } from "../../client/command-label.js";
 import { readConfig } from "../../config/store.js";
 import { readContext, resolveProfile, type ClientContextProfile } from "../../client/context.js";
 import { ApiRequestError, PaperclipApiClient } from "../../client/http.js";
@@ -53,10 +55,12 @@ export function resolveCommandContext(
     profile.apiBase ||
     inferApiBaseFromConfig(options.config);
 
-  const apiKey =
+  const explicitApiKey =
     options.apiKey?.trim() ||
     process.env.PAPERCLIP_API_KEY?.trim() ||
     readKeyFromProfileEnv(profile);
+  const storedBoardCredential = explicitApiKey ? null : getStoredBoardCredential(apiBase);
+  const apiKey = explicitApiKey || storedBoardCredential?.token;
 
   const companyId =
     options.companyId?.trim() ||
@@ -69,7 +73,27 @@ export function resolveCommandContext(
     );
   }
 
-  const api = new PaperclipApiClient({ apiBase, apiKey });
+  const api = new PaperclipApiClient({
+    apiBase,
+    apiKey,
+    recoverAuth: explicitApiKey || !canAttemptInteractiveBoardAuth()
+      ? undefined
+      : async ({ error }) => {
+          const requestedAccess = error.message.includes("Instance admin required")
+            ? "instance_admin_required"
+            : "board";
+          if (!shouldRecoverBoardAuth(error)) {
+            return null;
+          }
+          const login = await loginBoardCli({
+            apiBase,
+            requestedAccess,
+            requestedCompanyId: companyId ?? null,
+            command: buildCliCommandLabel(),
+          });
+          return login.token;
+        },
+  });
   return {
     api,
     companyId,
@@ -79,6 +103,16 @@ export function resolveCommandContext(
   };
 }
 
+function shouldRecoverBoardAuth(error: ApiRequestError): boolean {
+  if (error.status === 401) return true;
+  if (error.status !== 403) return false;
+  return error.message.includes("Board access required") || error.message.includes("Instance admin required");
+}
+
+function canAttemptInteractiveBoardAuth(): boolean {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
 export function printOutput(data: unknown, opts: { json?: boolean; label?: string } = {}): void {
   if (opts.json) {
     console.log(JSON.stringify(data, null, 2));

cli/src/commands/client/feedback.ts

@@ -0,0 +1,645 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import pc from "picocolors";
+import { Command } from "commander";
+import type { Company, FeedbackTrace, FeedbackTraceBundle } from "@paperclipai/shared";
+import {
+  addCommonClientOptions,
+  handleCommandError,
+  printOutput,
+  resolveCommandContext,
+  type BaseClientOptions,
+  type ResolvedClientContext,
+} from "./common.js";
+
+interface FeedbackFilterOptions extends BaseClientOptions {
+  targetType?: string;
+  vote?: string;
+  status?: string;
+  projectId?: string;
+  issueId?: string;
+  from?: string;
+  to?: string;
+  sharedOnly?: boolean;
+}
+
+export interface FeedbackTraceQueryOptions {
+  targetType?: string;
+  vote?: string;
+  status?: string;
+  projectId?: string;
+  issueId?: string;
+  from?: string;
+  to?: string;
+  sharedOnly?: boolean;
+}
+
+interface FeedbackReportOptions extends FeedbackFilterOptions {
+  payloads?: boolean;
+}
+
+interface FeedbackExportOptions extends FeedbackFilterOptions {
+  out?: string;
+}
+
+interface FeedbackSummary {
+  total: number;
+  thumbsUp: number;
+  thumbsDown: number;
+  withReason: number;
+  statuses: Record<string, number>;
+}
+
+interface FeedbackExportManifest {
+  exportedAt: string;
+  serverUrl: string;
+  companyId: string;
+  summary: FeedbackSummary & {
+    uniqueIssues: number;
+    issues: string[];
+  };
+  files: {
+    votes: string[];
+    traces: string[];
+    fullTraces: string[];
+    zip: string;
+  };
+}
+
+interface FeedbackExportResult {
+  outputDir: string;
+  zipPath: string;
+  manifest: FeedbackExportManifest;
+}
+
+export function registerFeedbackCommands(program: Command): void {
+  const feedback = program.command("feedback").description("Inspect and export local feedback traces");
+
+  addCommonClientOptions(
+    feedback
+      .command("report")
+      .description("Render a terminal report for company feedback traces")
+      .option("-C, --company-id <id>", "Company ID (overrides context default)")
+      .option("--target-type <type>", "Filter by target type")
+      .option("--vote <vote>", "Filter by vote value")
+      .option("--status <status>", "Filter by trace status")
+      .option("--project-id <id>", "Filter by project ID")
+      .option("--issue-id <id>", "Filter by issue ID")
+      .option("--from <iso8601>", "Only include traces created at or after this timestamp")
+      .option("--to <iso8601>", "Only include traces created at or before this timestamp")
+      .option("--shared-only", "Only include traces eligible for sharing/export")
+      .option("--payloads", "Include raw payload dumps in the terminal report", false)
+      .action(async (opts: FeedbackReportOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const companyId = await resolveFeedbackCompanyId(ctx, opts.companyId);
+          const traces = await fetchCompanyFeedbackTraces(ctx, companyId, opts);
+          const summary = summarizeFeedbackTraces(traces);
+          if (ctx.json) {
+            printOutput(
+              {
+                apiBase: ctx.api.apiBase,
+                companyId,
+                summary,
+                traces,
+              },
+              { json: true },
+            );
+            return;
+          }
+          console.log(renderFeedbackReport({
+            apiBase: ctx.api.apiBase,
+            companyId,
+            traces,
+            summary,
+            includePayloads: Boolean(opts.payloads),
+          }));
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+    { includeCompany: false },
+  );
+
+  addCommonClientOptions(
+    feedback
+      .command("export")
+      .description("Export feedback votes and raw trace bundles into a folder plus zip archive")
+      .option("-C, --company-id <id>", "Company ID (overrides context default)")
+      .option("--target-type <type>", "Filter by target type")
+      .option("--vote <vote>", "Filter by vote value")
+      .option("--status <status>", "Filter by trace status")
+      .option("--project-id <id>", "Filter by project ID")
+      .option("--issue-id <id>", "Filter by issue ID")
+      .option("--from <iso8601>", "Only include traces created at or after this timestamp")
+      .option("--to <iso8601>", "Only include traces created at or before this timestamp")
+      .option("--shared-only", "Only include traces eligible for sharing/export")
+      .option("--out <path>", "Output directory (default: ./feedback-export-<timestamp>)")
+      .action(async (opts: FeedbackExportOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const companyId = await resolveFeedbackCompanyId(ctx, opts.companyId);
+          const traces = await fetchCompanyFeedbackTraces(ctx, companyId, opts);
+          const outputDir = path.resolve(opts.out?.trim() || defaultFeedbackExportDirName());
+          const exported = await writeFeedbackExportBundle({
+            apiBase: ctx.api.apiBase,
+            companyId,
+            traces,
+            outputDir,
+            traceBundleFetcher: (trace) => fetchFeedbackTraceBundle(ctx, trace.id),
+          });
+          if (ctx.json) {
+            printOutput(
+              {
+                companyId,
+                outputDir: exported.outputDir,
+                zipPath: exported.zipPath,
+                summary: exported.manifest.summary,
+              },
+              { json: true },
+            );
+            return;
+          }
+          console.log(renderFeedbackExportSummary(exported));
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+    { includeCompany: false },
+  );
+}
+
+export async function resolveFeedbackCompanyId(
+  ctx: ResolvedClientContext,
+  explicitCompanyId?: string,
+): Promise<string> {
+  const direct = explicitCompanyId?.trim() || ctx.companyId?.trim();
+  if (direct) return direct;
+  const companies = (await ctx.api.get<Company[]>("/api/companies")) ?? [];
+  const companyId = companies[0]?.id?.trim();
+  if (!companyId) {
+    throw new Error(
+      "Company ID is required. Pass --company-id, set PAPERCLIP_COMPANY_ID, or configure a CLI context default.",
+    );
+  }
+  return companyId;
+}
+
+export function buildFeedbackTraceQuery(opts: FeedbackTraceQueryOptions, includePayload = true): string {
+  const params = new URLSearchParams();
+  if (opts.targetType) params.set("targetType", opts.targetType);
+  if (opts.vote) params.set("vote", opts.vote);
+  if (opts.status) params.set("status", opts.status);
+  if (opts.projectId) params.set("projectId", opts.projectId);
+  if (opts.issueId) params.set("issueId", opts.issueId);
+  if (opts.from) params.set("from", opts.from);
+  if (opts.to) params.set("to", opts.to);
+  if (opts.sharedOnly) params.set("sharedOnly", "true");
+  if (includePayload) params.set("includePayload", "true");
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
+
+export function normalizeFeedbackTraceExportFormat(value: string | undefined): "json" | "ndjson" {
+  if (!value || value === "ndjson") return "ndjson";
+  if (value === "json") return "json";
+  throw new Error(`Unsupported export format: ${value}`);
+}
+
+export function serializeFeedbackTraces(traces: FeedbackTrace[], format: string | undefined): string {
+  if (normalizeFeedbackTraceExportFormat(format) === "json") {
+    return JSON.stringify(traces, null, 2);
+  }
+  return traces.map((trace) => JSON.stringify(trace)).join("\n");
+}
+
+export async function fetchCompanyFeedbackTraces(
+  ctx: ResolvedClientContext,
+  companyId: string,
+  opts: FeedbackFilterOptions,
+): Promise<FeedbackTrace[]> {
+  return (
+    (await ctx.api.get<FeedbackTrace[]>(
+      `/api/companies/${companyId}/feedback-traces${buildFeedbackTraceQuery(opts, true)}`,
+    )) ?? []
+  );
+}
+
+export async function fetchFeedbackTraceBundle(
+  ctx: ResolvedClientContext,
+  traceId: string,
+): Promise<FeedbackTraceBundle> {
+  const bundle = await ctx.api.get<FeedbackTraceBundle>(`/api/feedback-traces/${traceId}/bundle`);
+  if (!bundle) {
+    throw new Error(`Feedback trace bundle ${traceId} not found`);
+  }
+  return bundle;
+}
+
+export function summarizeFeedbackTraces(traces: FeedbackTrace[]): FeedbackSummary {
+  const statuses: Record<string, number> = {};
+  let thumbsUp = 0;
+  let thumbsDown = 0;
+  let withReason = 0;
+
+  for (const trace of traces) {
+    if (trace.vote === "up") thumbsUp += 1;
+    if (trace.vote === "down") thumbsDown += 1;
+    if (readFeedbackReason(trace)) withReason += 1;
+    statuses[trace.status] = (statuses[trace.status] ?? 0) + 1;
+  }
+
+  return {
+    total: traces.length,
+    thumbsUp,
+    thumbsDown,
+    withReason,
+    statuses,
+  };
+}
+
+export function renderFeedbackReport(input: {
+  apiBase: string;
+  companyId: string;
+  traces: FeedbackTrace[];
+  summary: FeedbackSummary;
+  includePayloads: boolean;
+}): string {
+  const lines: string[] = [];
+  lines.push("");
+  lines.push(pc.bold(pc.magenta("Paperclip Feedback Report")));
+  lines.push(pc.dim(new Date().toISOString()));
+  lines.push(horizontalRule());
+  lines.push(`${pc.dim("Server:")}  ${input.apiBase}`);
+  lines.push(`${pc.dim("Company:")} ${input.companyId}`);
+  lines.push("");
+
+  if (input.traces.length === 0) {
+    lines.push(pc.yellow("[!!] No feedback traces found."));
+    lines.push("");
+    return lines.join("\n");
+  }
+
+  lines.push(pc.bold(pc.cyan("Summary")));
+  lines.push(horizontalRule());
+  lines.push(`  ${pc.green(pc.bold(String(input.summary.thumbsUp)))}  thumbs up`);
+  lines.push(`  ${pc.red(pc.bold(String(input.summary.thumbsDown)))}  thumbs down`);
+  lines.push(`  ${pc.yellow(pc.bold(String(input.summary.withReason)))}  downvotes with a reason`);
+  lines.push(`  ${pc.bold(String(input.summary.total))}  total traces`);
+  lines.push("");
+  lines.push(pc.dim("Export status:"));
+  for (const status of ["pending", "sent", "local_only", "failed"]) {
+    lines.push(`  ${padRight(status, 10)} ${input.summary.statuses[status] ?? 0}`);
+  }
+  lines.push("");
+  lines.push(pc.bold(pc.cyan("Trace Details")));
+  lines.push(horizontalRule());
+
+  for (const trace of input.traces) {
+    const voteColor = trace.vote === "up" ? pc.green : pc.red;
+    const voteIcon = trace.vote === "up" ? "^" : "v";
+    const issueRef = trace.issueIdentifier ?? trace.issueId;
+    const label = trace.targetSummary.label?.trim() || trace.targetType;
+    const excerpt = compactText(trace.targetSummary.excerpt);
+    const reason = readFeedbackReason(trace);
+    lines.push(
+      `  ${voteColor(voteIcon)} ${pc.bold(issueRef)} ${pc.dim(compactText(trace.issueTitle, 64))}`,
+    );
+    lines.push(
+      `    ${pc.dim("Trace:")} ${trace.id.slice(0, 8)}  ${pc.dim("Status:")} ${trace.status}  ${pc.dim("Date:")} ${formatTimestamp(trace.createdAt)}`,
+    );
+    lines.push(`    ${pc.dim("Target:")} ${label}`);
+    if (excerpt) {
+      lines.push(`    ${pc.dim("Excerpt:")} ${excerpt}`);
+    }
+    if (reason) {
+      lines.push(`    ${pc.yellow(pc.bold("Reason:"))} ${pc.yellow(reason)}`);
+    }
+    lines.push("");
+  }
+
+  if (input.includePayloads) {
+    lines.push(pc.bold(pc.cyan("Raw Payloads")));
+    lines.push(horizontalRule());
+    for (const trace of input.traces) {
+      if (!trace.payloadSnapshot) continue;
+      const issueRef = trace.issueIdentifier ?? trace.issueId;
+      lines.push(`  ${pc.bold(`${issueRef} (${trace.id.slice(0, 8)})`)}`);
+      const body = JSON.stringify(trace.payloadSnapshot, null, 2)?.split("\n") ?? [];
+      for (const line of body) {
+        lines.push(`    ${pc.dim(line)}`);
+      }
+      lines.push("");
+    }
+  }
+
+  lines.push(horizontalRule());
+  lines.push(pc.dim(`Report complete. ${input.traces.length} trace(s) displayed.`));
+  lines.push("");
+  return lines.join("\n");
+}
+
+export async function writeFeedbackExportBundle(input: {
+  apiBase: string;
+  companyId: string;
+  traces: FeedbackTrace[];
+  outputDir: string;
+  traceBundleFetcher?: (trace: FeedbackTrace) => Promise<FeedbackTraceBundle>;
+}): Promise<FeedbackExportResult> {
+  await ensureEmptyOutputDirectory(input.outputDir);
+  await mkdir(path.join(input.outputDir, "votes"), { recursive: true });
+  await mkdir(path.join(input.outputDir, "traces"), { recursive: true });
+  await mkdir(path.join(input.outputDir, "full-traces"), { recursive: true });
+
+  const summary = summarizeFeedbackTraces(input.traces);
+  const voteFiles: string[] = [];
+  const traceFiles: string[] = [];
+  const fullTraceDirs: string[] = [];
+  const fullTraceFiles: string[] = [];
+  const issueSet = new Set<string>();
+
+  for (const trace of input.traces) {
+    const issueRef = sanitizeFileSegment(trace.issueIdentifier ?? trace.issueId);
+    const voteRecord = buildFeedbackVoteRecord(trace);
+    const voteFileName = `${issueRef}-${trace.feedbackVoteId.slice(0, 8)}.json`;
+    const traceFileName = `${issueRef}-${trace.id.slice(0, 8)}.json`;
+    voteFiles.push(voteFileName);
+    traceFiles.push(traceFileName);
+    issueSet.add(trace.issueIdentifier ?? trace.issueId);
+    await writeFile(
+      path.join(input.outputDir, "votes", voteFileName),
+      `${JSON.stringify(voteRecord, null, 2)}\n`,
+      "utf8",
+    );
+    await writeFile(
+      path.join(input.outputDir, "traces", traceFileName),
+      `${JSON.stringify(trace, null, 2)}\n`,
+      "utf8",
+    );
+
+    if (input.traceBundleFetcher) {
+      const bundle = await input.traceBundleFetcher(trace);
+      const bundleDirName = `${issueRef}-${trace.id.slice(0, 8)}`;
+      const bundleDir = path.join(input.outputDir, "full-traces", bundleDirName);
+      await mkdir(bundleDir, { recursive: true });
+      fullTraceDirs.push(bundleDirName);
+      await writeFile(
+        path.join(bundleDir, "bundle.json"),
+        `${JSON.stringify(bundle, null, 2)}\n`,
+        "utf8",
+      );
+      fullTraceFiles.push(path.posix.join("full-traces", bundleDirName, "bundle.json"));
+      for (const file of bundle.files) {
+        const targetPath = path.join(bundleDir, file.path);
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await writeFile(targetPath, file.contents, "utf8");
+        fullTraceFiles.push(path.posix.join("full-traces", bundleDirName, file.path.replace(/\\/g, "/")));
+      }
+    }
+  }
+
+  const zipPath = `${input.outputDir}.zip`;
+  const manifest: FeedbackExportManifest = {
+    exportedAt: new Date().toISOString(),
+    serverUrl: input.apiBase,
+    companyId: input.companyId,
+    summary: {
+      ...summary,
+      uniqueIssues: issueSet.size,
+      issues: Array.from(issueSet).sort((left, right) => left.localeCompare(right)),
+    },
+    files: {
+      votes: voteFiles.slice().sort((left, right) => left.localeCompare(right)),
+      traces: traceFiles.slice().sort((left, right) => left.localeCompare(right)),
+      fullTraces: fullTraceDirs.slice().sort((left, right) => left.localeCompare(right)),
+      zip: path.basename(zipPath),
+    },
+  };
+
+  await writeFile(
+    path.join(input.outputDir, "index.json"),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    "utf8",
+  );
+  const archiveFiles = await collectJsonFilesForArchive(input.outputDir, [
+    "index.json",
+    ...manifest.files.votes.map((file) => path.posix.join("votes", file)),
+    ...manifest.files.traces.map((file) => path.posix.join("traces", file)),
+    ...fullTraceFiles,
+  ]);
+  await writeFile(zipPath, createStoredZipArchive(archiveFiles, path.basename(input.outputDir)));
+
+  return {
+    outputDir: input.outputDir,
+    zipPath,
+    manifest,
+  };
+}
+
+export function renderFeedbackExportSummary(exported: FeedbackExportResult): string {
+  const lines: string[] = [];
+  lines.push("");
+  lines.push(pc.bold(pc.magenta("Paperclip Feedback Export")));
+  lines.push(pc.dim(exported.manifest.exportedAt));
+  lines.push(horizontalRule());
+  lines.push(`${pc.dim("Company:")} ${exported.manifest.companyId}`);
+  lines.push(`${pc.dim("Output:")}  ${exported.outputDir}`);
+  lines.push(`${pc.dim("Archive:")} ${exported.zipPath}`);
+  lines.push("");
+  lines.push(pc.bold("Export Summary"));
+  lines.push(horizontalRule());
+  lines.push(`  ${pc.green(pc.bold(String(exported.manifest.summary.thumbsUp)))}  thumbs up`);
+  lines.push(`  ${pc.red(pc.bold(String(exported.manifest.summary.thumbsDown)))}  thumbs down`);
+  lines.push(`  ${pc.yellow(pc.bold(String(exported.manifest.summary.withReason)))}  with reason`);
+  lines.push(`  ${pc.bold(String(exported.manifest.summary.uniqueIssues))}  unique issues`);
+  lines.push("");
+  lines.push(pc.dim("Files:"));
+  lines.push(`  ${path.join(exported.outputDir, "index.json")}`);
+  lines.push(`  ${path.join(exported.outputDir, "votes")} (${exported.manifest.files.votes.length} files)`);
+  lines.push(`  ${path.join(exported.outputDir, "traces")} (${exported.manifest.files.traces.length} files)`);
+  lines.push(`  ${path.join(exported.outputDir, "full-traces")} (${exported.manifest.files.fullTraces.length} bundles)`);
+  lines.push(`  ${exported.zipPath}`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+function readFeedbackReason(trace: FeedbackTrace): string | null {
+  const payload = asRecord(trace.payloadSnapshot);
+  const vote = asRecord(payload?.vote);
+  const reason = vote?.reason;
+  return typeof reason === "string" && reason.trim() ? reason.trim() : null;
+}
+
+function buildFeedbackVoteRecord(trace: FeedbackTrace) {
+  return {
+    voteId: trace.feedbackVoteId,
+    traceId: trace.id,
+    issueId: trace.issueId,
+    issueIdentifier: trace.issueIdentifier,
+    issueTitle: trace.issueTitle,
+    vote: trace.vote,
+    targetType: trace.targetType,
+    targetId: trace.targetId,
+    targetSummary: trace.targetSummary,
+    status: trace.status,
+    consentVersion: trace.consentVersion,
+    createdAt: trace.createdAt,
+    updatedAt: trace.updatedAt,
+    reason: readFeedbackReason(trace),
+  };
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function compactText(value: string | null | undefined, maxLength = 88): string | null {
+  if (!value) return null;
+  const compact = value.replace(/\s+/g, " ").trim();
+  if (!compact) return null;
+  if (compact.length <= maxLength) return compact;
+  return `${compact.slice(0, maxLength - 3)}...`;
+}
+
+function formatTimestamp(value: unknown): string {
+  if (value instanceof Date) return value.toISOString().slice(0, 19).replace("T", " ");
+  if (typeof value === "string") return value.slice(0, 19).replace("T", " ");
+  return "-";
+}
+
+function horizontalRule(): string {
+  return pc.dim("-".repeat(72));
+}
+
+function padRight(value: string, width: number): string {
+  return `${value}${" ".repeat(Math.max(0, width - value.length))}`;
+}
+
+function defaultFeedbackExportDirName(): string {
+  const iso = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+  return `feedback-export-${iso}`;
+}
+
+async function ensureEmptyOutputDirectory(outputDir: string): Promise<void> {
+  try {
+    const info = await stat(outputDir);
+    if (!info.isDirectory()) {
+      throw new Error(`Output path already exists and is not a directory: ${outputDir}`);
+    }
+    const entries = await readdir(outputDir);
+    if (entries.length > 0) {
+      throw new Error(`Output directory already exists and is not empty: ${outputDir}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "";
+    if (/ENOENT/.test(message)) {
+      await mkdir(outputDir, { recursive: true });
+      return;
+    }
+    throw error;
+  }
+}
+
+async function collectJsonFilesForArchive(
+  outputDir: string,
+  relativePaths: string[],
+): Promise<Record<string, string>> {
+  const files: Record<string, string> = {};
+  for (const relativePath of relativePaths) {
+    const normalized = relativePath.replace(/\\/g, "/");
+    files[normalized] = await readFile(path.join(outputDir, normalized), "utf8");
+  }
+  return files;
+}
+
+function sanitizeFileSegment(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "feedback";
+}
+
+function writeUint16(target: Uint8Array, offset: number, value: number) {
+  target[offset] = value & 0xff;
+  target[offset + 1] = (value >>> 8) & 0xff;
+}
+
+function writeUint32(target: Uint8Array, offset: number, value: number) {
+  target[offset] = value & 0xff;
+  target[offset + 1] = (value >>> 8) & 0xff;
+  target[offset + 2] = (value >>> 16) & 0xff;
+  target[offset + 3] = (value >>> 24) & 0xff;
+}
+
+function crc32(bytes: Uint8Array) {
+  let crc = 0xffffffff;
+  for (const byte of bytes) {
+    crc ^= byte;
+    for (let bit = 0; bit < 8; bit += 1) {
+      crc = (crc & 1) === 1 ? (crc >>> 1) ^ 0xedb88320 : crc >>> 1;
+    }
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+function createStoredZipArchive(files: Record<string, string>, rootPath: string): Uint8Array {
+  const encoder = new TextEncoder();
+  const localChunks: Uint8Array[] = [];
+  const centralChunks: Uint8Array[] = [];
+  let localOffset = 0;
+  let entryCount = 0;
+
+  for (const [relativePath, content] of Object.entries(files).sort(([left], [right]) => left.localeCompare(right))) {
+    const fileName = encoder.encode(`${rootPath}/${relativePath}`);
+    const body = encoder.encode(content);
+    const checksum = crc32(body);
+
+    const localHeader = new Uint8Array(30 + fileName.length);
+    writeUint32(localHeader, 0, 0x04034b50);
+    writeUint16(localHeader, 4, 20);
+    writeUint16(localHeader, 6, 0x0800);
+    writeUint16(localHeader, 8, 0);
+    writeUint32(localHeader, 14, checksum);
+    writeUint32(localHeader, 18, body.length);
+    writeUint32(localHeader, 22, body.length);
+    writeUint16(localHeader, 26, fileName.length);
+    localHeader.set(fileName, 30);
+
+    const centralHeader = new Uint8Array(46 + fileName.length);
+    writeUint32(centralHeader, 0, 0x02014b50);
+    writeUint16(centralHeader, 4, 20);
+    writeUint16(centralHeader, 6, 20);
+    writeUint16(centralHeader, 8, 0x0800);
+    writeUint16(centralHeader, 10, 0);
+    writeUint32(centralHeader, 16, checksum);
+    writeUint32(centralHeader, 20, body.length);
+    writeUint32(centralHeader, 24, body.length);
+    writeUint16(centralHeader, 28, fileName.length);
+    writeUint32(centralHeader, 42, localOffset);
+    centralHeader.set(fileName, 46);
+
+    localChunks.push(localHeader, body);
+    centralChunks.push(centralHeader);
+    localOffset += localHeader.length + body.length;
+    entryCount += 1;
+  }
+
+  const centralDirectoryLength = centralChunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const archive = new Uint8Array(
+    localChunks.reduce((sum, chunk) => sum + chunk.length, 0) + centralDirectoryLength + 22,
+  );
+  let offset = 0;
+  for (const chunk of localChunks) {
+    archive.set(chunk, offset);
+    offset += chunk.length;
+  }
+  const centralDirectoryOffset = offset;
+  for (const chunk of centralChunks) {
+    archive.set(chunk, offset);
+    offset += chunk.length;
+  }
+  writeUint32(archive, offset, 0x06054b50);
+  writeUint16(archive, offset + 8, entryCount);
+  writeUint16(archive, offset + 10, entryCount);
+  writeUint32(archive, offset + 12, centralDirectoryLength);
+  writeUint32(archive, offset + 16, centralDirectoryOffset);
+  return archive;
+}

cli/src/commands/client/issue.ts

@@ -1,8 +1,10 @@
 import { Command } from "commander";
+import { writeFile } from "node:fs/promises";
 import {
   addIssueCommentSchema,
   checkoutIssueSchema,
   createIssueSchema,
+  type FeedbackTrace,
   updateIssueSchema,
   type Issue,
   type IssueComment,
@@ -15,6 +17,11 @@ import {
   resolveCommandContext,
   type BaseClientOptions,
 } from "./common.js";
+import {
+  buildFeedbackTraceQuery,
+  normalizeFeedbackTraceExportFormat,
+  serializeFeedbackTraces,
+} from "./feedback.js";
 
 interface IssueBaseOptions extends BaseClientOptions {
   status?: string;
@@ -61,6 +68,18 @@ interface IssueCheckoutOptions extends BaseClientOptions {
   expectedStatuses?: string;
 }
 
+interface IssueFeedbackOptions extends BaseClientOptions {
+  targetType?: string;
+  vote?: string;
+  status?: string;
+  from?: string;
+  to?: string;
+  sharedOnly?: boolean;
+  includePayload?: boolean;
+  out?: string;
+  format?: string;
+}
+
 export function registerIssueCommands(program: Command): void {
   const issue = program.command("issue").description("Issue operations");
 
@@ -237,6 +256,85 @@ export function registerIssueCommands(program: Command): void {
       }),
   );
 
+  addCommonClientOptions(
+    issue
+      .command("feedback:list")
+      .description("List feedback traces for an issue")
+      .argument("<issueId>", "Issue ID")
+      .option("--target-type <type>", "Filter by target type")
+      .option("--vote <vote>", "Filter by vote value")
+      .option("--status <status>", "Filter by trace status")
+      .option("--from <iso8601>", "Only include traces created at or after this timestamp")
+      .option("--to <iso8601>", "Only include traces created at or before this timestamp")
+      .option("--shared-only", "Only include traces eligible for sharing/export")
+      .option("--include-payload", "Include stored payload snapshots in the response")
+      .action(async (issueId: string, opts: IssueFeedbackOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const traces = (await ctx.api.get<FeedbackTrace[]>(
+            `/api/issues/${issueId}/feedback-traces${buildFeedbackTraceQuery(opts)}`,
+          )) ?? [];
+          if (ctx.json) {
+            printOutput(traces, { json: true });
+            return;
+          }
+          printOutput(
+            traces.map((trace) => ({
+              id: trace.id,
+              issue: trace.issueIdentifier ?? trace.issueId,
+              vote: trace.vote,
+              status: trace.status,
+              targetType: trace.targetType,
+              target: trace.targetSummary.label,
+            })),
+            { json: false },
+          );
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  addCommonClientOptions(
+    issue
+      .command("feedback:export")
+      .description("Export feedback traces for an issue")
+      .argument("<issueId>", "Issue ID")
+      .option("--target-type <type>", "Filter by target type")
+      .option("--vote <vote>", "Filter by vote value")
+      .option("--status <status>", "Filter by trace status")
+      .option("--from <iso8601>", "Only include traces created at or after this timestamp")
+      .option("--to <iso8601>", "Only include traces created at or before this timestamp")
+      .option("--shared-only", "Only include traces eligible for sharing/export")
+      .option("--include-payload", "Include stored payload snapshots in the export")
+      .option("--out <path>", "Write export to a file path instead of stdout")
+      .option("--format <format>", "Export format: json or ndjson", "ndjson")
+      .action(async (issueId: string, opts: IssueFeedbackOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const traces = (await ctx.api.get<FeedbackTrace[]>(
+            `/api/issues/${issueId}/feedback-traces${buildFeedbackTraceQuery(opts, opts.includePayload ?? true)}`,
+          )) ?? [];
+            const serialized = serializeFeedbackTraces(traces, opts.format);
+            if (opts.out?.trim()) {
+              await writeFile(opts.out, serialized, "utf8");
+              if (ctx.json) {
+                printOutput(
+                  { out: opts.out, count: traces.length, format: normalizeFeedbackTraceExportFormat(opts.format) },
+                  { json: true },
+                );
+                return;
+              }
+              console.log(`Wrote ${traces.length} feedback trace(s) to ${opts.out}`);
+            return;
+          }
+          process.stdout.write(`${serialized}${serialized.endsWith("\n") ? "" : "\n"}`);
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
   addCommonClientOptions(
     issue
       .command("checkout")

cli/src/commands/client/plugin.ts

@@ -0,0 +1,374 @@
+import path from "node:path";
+import { Command } from "commander";
+import pc from "picocolors";
+import {
+  addCommonClientOptions,
+  handleCommandError,
+  printOutput,
+  resolveCommandContext,
+  type BaseClientOptions,
+} from "./common.js";
+
+// ---------------------------------------------------------------------------
+// Types mirroring server-side shapes
+// ---------------------------------------------------------------------------
+
+interface PluginRecord {
+  id: string;
+  pluginKey: string;
+  packageName: string;
+  version: string;
+  status: string;
+  displayName?: string;
+  lastError?: string | null;
+  installedAt: string;
+  updatedAt: string;
+}
+
+
+// ---------------------------------------------------------------------------
+// Option types
+// ---------------------------------------------------------------------------
+
+interface PluginListOptions extends BaseClientOptions {
+  status?: string;
+}
+
+interface PluginInstallOptions extends BaseClientOptions {
+  local?: boolean;
+  version?: string;
+}
+
+interface PluginUninstallOptions extends BaseClientOptions {
+  force?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a local path argument to an absolute path so the server can find the
+ * plugin on disk regardless of where the user ran the CLI.
+ */
+function resolvePackageArg(packageArg: string, isLocal: boolean): string {
+  if (!isLocal) return packageArg;
+  // Already absolute
+  if (path.isAbsolute(packageArg)) return packageArg;
+  // Expand leading ~ to home directory
+  if (packageArg.startsWith("~")) {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    return path.resolve(home, packageArg.slice(1).replace(/^[\\/]/, ""));
+  }
+  return path.resolve(process.cwd(), packageArg);
+}
+
+function formatPlugin(p: PluginRecord): string {
+  const statusColor =
+    p.status === "ready"
+      ? pc.green(p.status)
+      : p.status === "error"
+        ? pc.red(p.status)
+        : p.status === "disabled"
+          ? pc.dim(p.status)
+          : pc.yellow(p.status);
+
+  const parts = [
+    `key=${pc.bold(p.pluginKey)}`,
+    `status=${statusColor}`,
+    `version=${p.version}`,
+    `id=${pc.dim(p.id)}`,
+  ];
+
+  if (p.lastError) {
+    parts.push(`error=${pc.red(p.lastError.slice(0, 80))}`);
+  }
+
+  return parts.join("  ");
+}
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
+export function registerPluginCommands(program: Command): void {
+  const plugin = program.command("plugin").description("Plugin lifecycle management");
+
+  // -------------------------------------------------------------------------
+  // plugin list
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("list")
+      .description("List installed plugins")
+      .option("--status <status>", "Filter by status (ready, error, disabled, installed, upgrade_pending)")
+      .action(async (opts: PluginListOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const qs = opts.status ? `?status=${encodeURIComponent(opts.status)}` : "";
+          const plugins = await ctx.api.get<PluginRecord[]>(`/api/plugins${qs}`);
+
+          if (ctx.json) {
+            printOutput(plugins, { json: true });
+            return;
+          }
+
+          const rows = plugins ?? [];
+          if (rows.length === 0) {
+            console.log(pc.dim("No plugins installed."));
+            return;
+          }
+
+          for (const p of rows) {
+            console.log(formatPlugin(p));
+          }
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  // -------------------------------------------------------------------------
+  // plugin install <package-or-path>
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("install <package>")
+      .description(
+        "Install a plugin from a local path or npm package.\n" +
+          "  Examples:\n" +
+          "    paperclipai plugin install ./my-plugin              # local path\n" +
+          "    paperclipai plugin install @acme/plugin-linear      # npm package\n" +
+          "    paperclipai plugin install @acme/plugin-linear@1.2  # pinned version",
+      )
+      .option("-l, --local", "Treat <package> as a local filesystem path", false)
+      .option("--version <version>", "Specific npm version to install (npm packages only)")
+      .action(async (packageArg: string, opts: PluginInstallOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+
+          // Auto-detect local paths: starts with . or / or ~ or is an absolute path
+          const isLocal =
+            opts.local ||
+            packageArg.startsWith("./") ||
+            packageArg.startsWith("../") ||
+            packageArg.startsWith("/") ||
+            packageArg.startsWith("~");
+
+          const resolvedPackage = resolvePackageArg(packageArg, isLocal);
+
+          if (!ctx.json) {
+            console.log(
+              pc.dim(
+                isLocal
+                  ? `Installing plugin from local path: ${resolvedPackage}`
+                  : `Installing plugin: ${resolvedPackage}${opts.version ? `@${opts.version}` : ""}`,
+              ),
+            );
+          }
+
+          const installedPlugin = await ctx.api.post<PluginRecord>("/api/plugins/install", {
+            packageName: resolvedPackage,
+            version: opts.version,
+            isLocalPath: isLocal,
+          });
+
+          if (ctx.json) {
+            printOutput(installedPlugin, { json: true });
+            return;
+          }
+
+          if (!installedPlugin) {
+            console.log(pc.dim("Install returned no plugin record."));
+            return;
+          }
+
+          console.log(
+            pc.green(
+              `✓ Installed ${pc.bold(installedPlugin.pluginKey)} v${installedPlugin.version} (${installedPlugin.status})`,
+            ),
+          );
+
+          if (installedPlugin.lastError) {
+            console.log(pc.red(`  Warning: ${installedPlugin.lastError}`));
+          }
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  // -------------------------------------------------------------------------
+  // plugin uninstall <plugin-key-or-id>
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("uninstall <pluginKey>")
+      .description(
+        "Uninstall a plugin by its plugin key or database ID.\n" +
+          "  Use --force to hard-purge all state and config.",
+      )
+      .option("--force", "Purge all plugin state and config (hard delete)", false)
+      .action(async (pluginKey: string, opts: PluginUninstallOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const purge = opts.force === true;
+          const qs = purge ? "?purge=true" : "";
+
+          if (!ctx.json) {
+            console.log(
+              pc.dim(
+                purge
+                  ? `Uninstalling and purging plugin: ${pluginKey}`
+                  : `Uninstalling plugin: ${pluginKey}`,
+              ),
+            );
+          }
+
+          const result = await ctx.api.delete<PluginRecord | null>(
+            `/api/plugins/${encodeURIComponent(pluginKey)}${qs}`,
+          );
+
+          if (ctx.json) {
+            printOutput(result, { json: true });
+            return;
+          }
+
+          console.log(pc.green(`✓ Uninstalled ${pc.bold(pluginKey)}${purge ? " (purged)" : ""}`));
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  // -------------------------------------------------------------------------
+  // plugin enable <plugin-key-or-id>
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("enable <pluginKey>")
+      .description("Enable a disabled or errored plugin")
+      .action(async (pluginKey: string, opts: BaseClientOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const result = await ctx.api.post<PluginRecord>(
+            `/api/plugins/${encodeURIComponent(pluginKey)}/enable`,
+          );
+
+          if (ctx.json) {
+            printOutput(result, { json: true });
+            return;
+          }
+
+          console.log(pc.green(`✓ Enabled ${pc.bold(pluginKey)} — status: ${result?.status ?? "unknown"}`));
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  // -------------------------------------------------------------------------
+  // plugin disable <plugin-key-or-id>
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("disable <pluginKey>")
+      .description("Disable a running plugin without uninstalling it")
+      .action(async (pluginKey: string, opts: BaseClientOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const result = await ctx.api.post<PluginRecord>(
+            `/api/plugins/${encodeURIComponent(pluginKey)}/disable`,
+          );
+
+          if (ctx.json) {
+            printOutput(result, { json: true });
+            return;
+          }
+
+          console.log(pc.dim(`Disabled ${pc.bold(pluginKey)} — status: ${result?.status ?? "unknown"}`));
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  // -------------------------------------------------------------------------
+  // plugin inspect <plugin-key-or-id>
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("inspect <pluginKey>")
+      .description("Show full details for an installed plugin")
+      .action(async (pluginKey: string, opts: BaseClientOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const result = await ctx.api.get<PluginRecord>(
+            `/api/plugins/${encodeURIComponent(pluginKey)}`,
+          );
+
+          if (ctx.json) {
+            printOutput(result, { json: true });
+            return;
+          }
+
+          if (!result) {
+            console.log(pc.red(`Plugin not found: ${pluginKey}`));
+            process.exit(1);
+          }
+
+          console.log(formatPlugin(result));
+          if (result.lastError) {
+            console.log(`\n${pc.red("Last error:")}\n${result.lastError}`);
+          }
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  // -------------------------------------------------------------------------
+  // plugin examples
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("examples")
+      .description("List bundled example plugins available for local install")
+      .action(async (opts: BaseClientOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const examples = await ctx.api.get<
+            Array<{
+              packageName: string;
+              pluginKey: string;
+              displayName: string;
+              description: string;
+              localPath: string;
+              tag: string;
+            }>
+          >("/api/plugins/examples");
+
+          if (ctx.json) {
+            printOutput(examples, { json: true });
+            return;
+          }
+
+          const rows = examples ?? [];
+          if (rows.length === 0) {
+            console.log(pc.dim("No bundled examples available."));
+            return;
+          }
+
+          for (const ex of rows) {
+            console.log(
+              `${pc.bold(ex.displayName)}  ${pc.dim(ex.pluginKey)}\n` +
+                `  ${ex.description}\n` +
+                `  ${pc.cyan(`paperclipai plugin install ${ex.localPath}`)}`,
+            );
+          }
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+}

cli/src/commands/client/zip.ts

@@ -0,0 +1,129 @@
+import { inflateRawSync } from "node:zlib";
+import path from "node:path";
+import type { CompanyPortabilityFileEntry } from "@paperclipai/shared";
+
+const textDecoder = new TextDecoder();
+
+export const binaryContentTypeByExtension: Record<string, string> = {
+  ".gif": "image/gif",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+};
+
+function normalizeArchivePath(pathValue: string) {
+  return pathValue
+    .replace(/\\/g, "/")
+    .split("/")
+    .filter(Boolean)
+    .join("/");
+}
+
+function readUint16(source: Uint8Array, offset: number) {
+  return source[offset]! | (source[offset + 1]! << 8);
+}
+
+function readUint32(source: Uint8Array, offset: number) {
+  return (
+    source[offset]! |
+    (source[offset + 1]! << 8) |
+    (source[offset + 2]! << 16) |
+    (source[offset + 3]! << 24)
+  ) >>> 0;
+}
+
+function sharedArchiveRoot(paths: string[]) {
+  if (paths.length === 0) return null;
+  const firstSegments = paths
+    .map((entry) => normalizeArchivePath(entry).split("/").filter(Boolean))
+    .filter((parts) => parts.length > 0);
+  if (firstSegments.length === 0) return null;
+  const candidate = firstSegments[0]![0]!;
+  return firstSegments.every((parts) => parts.length > 1 && parts[0] === candidate)
+    ? candidate
+    : null;
+}
+
+function bytesToPortableFileEntry(pathValue: string, bytes: Uint8Array): CompanyPortabilityFileEntry {
+  const contentType = binaryContentTypeByExtension[path.extname(pathValue).toLowerCase()];
+  if (!contentType) return textDecoder.decode(bytes);
+  return {
+    encoding: "base64",
+    data: Buffer.from(bytes).toString("base64"),
+    contentType,
+  };
+}
+
+async function inflateZipEntry(compressionMethod: number, bytes: Uint8Array) {
+  if (compressionMethod === 0) return bytes;
+  if (compressionMethod !== 8) {
+    throw new Error("Unsupported zip archive: only STORE and DEFLATE entries are supported.");
+  }
+  return new Uint8Array(inflateRawSync(bytes));
+}
+
+export async function readZipArchive(source: ArrayBuffer | Uint8Array): Promise<{
+  rootPath: string | null;
+  files: Record<string, CompanyPortabilityFileEntry>;
+}> {
+  const bytes = source instanceof Uint8Array ? source : new Uint8Array(source);
+  const entries: Array<{ path: string; body: CompanyPortabilityFileEntry }> = [];
+  let offset = 0;
+
+  while (offset + 4 <= bytes.length) {
+    const signature = readUint32(bytes, offset);
+    if (signature === 0x02014b50 || signature === 0x06054b50) break;
+    if (signature !== 0x04034b50) {
+      throw new Error("Invalid zip archive: unsupported local file header.");
+    }
+
+    if (offset + 30 > bytes.length) {
+      throw new Error("Invalid zip archive: truncated local file header.");
+    }
+
+    const generalPurposeFlag = readUint16(bytes, offset + 6);
+    const compressionMethod = readUint16(bytes, offset + 8);
+    const compressedSize = readUint32(bytes, offset + 18);
+    const fileNameLength = readUint16(bytes, offset + 26);
+    const extraFieldLength = readUint16(bytes, offset + 28);
+
+    if ((generalPurposeFlag & 0x0008) !== 0) {
+      throw new Error("Unsupported zip archive: data descriptors are not supported.");
+    }
+
+    const nameOffset = offset + 30;
+    const bodyOffset = nameOffset + fileNameLength + extraFieldLength;
+    const bodyEnd = bodyOffset + compressedSize;
+    if (bodyEnd > bytes.length) {
+      throw new Error("Invalid zip archive: truncated file contents.");
+    }
+
+    const rawArchivePath = textDecoder.decode(bytes.slice(nameOffset, nameOffset + fileNameLength));
+    const archivePath = normalizeArchivePath(rawArchivePath);
+    const isDirectoryEntry = /\/$/.test(rawArchivePath.replace(/\\/g, "/"));
+    if (archivePath && !isDirectoryEntry) {
+      const entryBytes = await inflateZipEntry(compressionMethod, bytes.slice(bodyOffset, bodyEnd));
+      entries.push({
+        path: archivePath,
+        body: bytesToPortableFileEntry(archivePath, entryBytes),
+      });
+    }
+
+    offset = bodyEnd;
+  }
+
+  const rootPath = sharedArchiveRoot(entries.map((entry) => entry.path));
+  const files: Record<string, CompanyPortabilityFileEntry> = {};
+  for (const entry of entries) {
+    const normalizedPath =
+      rootPath && entry.path.startsWith(`${rootPath}/`)
+        ? entry.path.slice(rootPath.length + 1)
+        : entry.path;
+    if (!normalizedPath) continue;
+    files[normalizedPath] = entry.body;
+  }
+
+  return { rootPath, files };
+}

cli/src/commands/configure.ts

@@ -10,6 +10,7 @@ import { defaultSecretsConfig, promptSecrets } from "../prompts/secrets.js";
 import { defaultStorageConfig, promptStorage } from "../prompts/storage.js";
 import { promptServer } from "../prompts/server.js";
 import {
+  resolveDefaultBackupDir,
   resolveDefaultEmbeddedPostgresDir,
   resolveDefaultLogsDir,
   resolvePaperclipInstanceId,
@@ -39,6 +40,12 @@ function defaultConfig(): PaperclipConfig {
       mode: "embedded-postgres",
       embeddedPostgresDataDir: resolveDefaultEmbeddedPostgresDir(instanceId),
       embeddedPostgresPort: 54329,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: resolveDefaultBackupDir(instanceId),
+      },
     },
     logging: {
       mode: "file",
@@ -47,6 +54,7 @@ function defaultConfig(): PaperclipConfig {
     server: {
       deploymentMode: "local_trusted",
       exposure: "private",
+      bind: "loopback",
       host: "127.0.0.1",
       port: 3100,
       allowedHostnames: [],
@@ -54,6 +62,10 @@ function defaultConfig(): PaperclipConfig {
     },
     auth: {
       baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+    telemetry: {
+      enabled: true,
     },
     storage: defaultStorageConfig(),
     secrets: defaultSecretsConfig(),
@@ -118,7 +130,7 @@ export async function configure(opts: {
 
     switch (section) {
       case "database":
-        config.database = await promptDatabase();
+        config.database = await promptDatabase(config.database);
         break;
       case "llm": {
         const llm = await promptLlm();

cli/src/commands/db-backup.ts

@@ -0,0 +1,102 @@
+import path from "node:path";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+import { formatDatabaseBackupResult, runDatabaseBackup } from "@paperclipai/db";
+import {
+  expandHomePrefix,
+  resolveDefaultBackupDir,
+  resolvePaperclipInstanceId,
+} from "../config/home.js";
+import { readConfig, resolveConfigPath } from "../config/store.js";
+import { printPaperclipCliBanner } from "../utils/banner.js";
+
+type DbBackupOptions = {
+  config?: string;
+  dir?: string;
+  retentionDays?: number;
+  filenamePrefix?: string;
+  json?: boolean;
+};
+
+function resolveConnectionString(configPath?: string): { value: string; source: string } {
+  const envUrl = process.env.DATABASE_URL?.trim();
+  if (envUrl) return { value: envUrl, source: "DATABASE_URL" };
+
+  const config = readConfig(configPath);
+  if (config?.database.mode === "postgres" && config.database.connectionString?.trim()) {
+    return { value: config.database.connectionString.trim(), source: "config.database.connectionString" };
+  }
+
+  const port = config?.database.embeddedPostgresPort ?? 54329;
+  return {
+    value: `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`,
+    source: `embedded-postgres@${port}`,
+  };
+}
+
+function normalizeRetentionDays(value: number | undefined, fallback: number): number {
+  const candidate = value ?? fallback;
+  if (!Number.isInteger(candidate) || candidate < 1) {
+    throw new Error(`Invalid retention days '${String(candidate)}'. Use a positive integer.`);
+  }
+  return candidate;
+}
+
+function resolveBackupDir(raw: string): string {
+  return path.resolve(expandHomePrefix(raw.trim()));
+}
+
+export async function dbBackupCommand(opts: DbBackupOptions): Promise<void> {
+  printPaperclipCliBanner();
+  p.intro(pc.bgCyan(pc.black(" paperclip db:backup ")));
+
+  const configPath = resolveConfigPath(opts.config);
+  const config = readConfig(opts.config);
+  const connection = resolveConnectionString(opts.config);
+  const defaultDir = resolveDefaultBackupDir(resolvePaperclipInstanceId());
+  const configuredDir = opts.dir?.trim() || config?.database.backup.dir || defaultDir;
+  const backupDir = resolveBackupDir(configuredDir);
+  const retentionDays = normalizeRetentionDays(
+    opts.retentionDays,
+    config?.database.backup.retentionDays ?? 30,
+  );
+  const filenamePrefix = opts.filenamePrefix?.trim() || "paperclip";
+
+  p.log.message(pc.dim(`Config: ${configPath}`));
+  p.log.message(pc.dim(`Connection source: ${connection.source}`));
+  p.log.message(pc.dim(`Backup dir: ${backupDir}`));
+  p.log.message(pc.dim(`Retention: ${retentionDays} day(s)`));
+
+  const spinner = p.spinner();
+  spinner.start("Creating database backup...");
+  try {
+    const result = await runDatabaseBackup({
+      connectionString: connection.value,
+      backupDir,
+      retention: { dailyDays: retentionDays, weeklyWeeks: 4, monthlyMonths: 1 },
+      filenamePrefix,
+    });
+    spinner.stop(`Backup saved: ${formatDatabaseBackupResult(result)}`);
+
+    if (opts.json) {
+      console.log(
+        JSON.stringify(
+          {
+            backupFile: result.backupFile,
+            sizeBytes: result.sizeBytes,
+            prunedCount: result.prunedCount,
+            backupDir,
+            retentionDays,
+            connectionSource: connection.source,
+          },
+          null,
+          2,
+        ),
+      );
+    }
+    p.outro(pc.green("Backup completed."));
+  } catch (err) {
+    spinner.stop(pc.red("Backup failed."));
+    throw err;
+  }
+}

cli/src/commands/doctor.ts

@@ -14,6 +14,7 @@ import {
   storageCheck,
   type CheckResult,
 } from "../checks/index.js";
+import { loadPaperclipEnvFile } from "../config/env.js";
 import { printPaperclipCliBanner } from "../utils/banner.js";
 
 const STATUS_ICON = {
@@ -31,6 +32,7 @@ export async function doctor(opts: {
   p.intro(pc.bgCyan(pc.black(" paperclip doctor ")));
 
   const configPath = resolveConfigPath(opts.config);
+  loadPaperclipEnvFile(configPath);
   const results: CheckResult[] = [];
 
   // 1. Config check (must pass before others)
@@ -64,28 +66,40 @@ export async function doctor(opts: {
   printResult(deploymentAuthResult);
 
   // 3. Agent JWT check
-  const jwtResult = agentJwtSecretCheck(opts.config);
-  results.push(jwtResult);
-  printResult(jwtResult);
-  await maybeRepair(jwtResult, opts);
+  results.push(
+    await runRepairableCheck({
+      run: () => agentJwtSecretCheck(opts.config),
+      configPath,
+      opts,
+    }),
+  );
 
   // 4. Secrets adapter check
-  const secretsResult = secretsCheck(config, configPath);
-  results.push(secretsResult);
-  printResult(secretsResult);
-  await maybeRepair(secretsResult, opts);
+  results.push(
+    await runRepairableCheck({
+      run: () => secretsCheck(config, configPath),
+      configPath,
+      opts,
+    }),
+  );
 
   // 5. Storage check
-  const storageResult = storageCheck(config, configPath);
-  results.push(storageResult);
-  printResult(storageResult);
-  await maybeRepair(storageResult, opts);
+  results.push(
+    await runRepairableCheck({
+      run: () => storageCheck(config, configPath),
+      configPath,
+      opts,
+    }),
+  );
 
   // 6. Database check
-  const dbResult = await databaseCheck(config, configPath);
-  results.push(dbResult);
-  printResult(dbResult);
-  await maybeRepair(dbResult, opts);
+  results.push(
+    await runRepairableCheck({
+      run: () => databaseCheck(config, configPath),
+      configPath,
+      opts,
+    }),
+  );
 
   // 7. LLM check
   const llmResult = await llmCheck(config);
@@ -93,10 +107,13 @@ export async function doctor(opts: {
   printResult(llmResult);
 
   // 8. Log directory check
-  const logResult = logCheck(config, configPath);
-  results.push(logResult);
-  printResult(logResult);
-  await maybeRepair(logResult, opts);
+  results.push(
+    await runRepairableCheck({
+      run: () => logCheck(config, configPath),
+      configPath,
+      opts,
+    }),
+  );
 
   // 9. Port check
   const portResult = await portCheck(config);
@@ -118,9 +135,9 @@ function printResult(result: CheckResult): void {
 async function maybeRepair(
   result: CheckResult,
   opts: { repair?: boolean; yes?: boolean },
-): Promise<void> {
-  if (result.status === "pass" || !result.canRepair || !result.repair) return;
-  if (!opts.repair) return;
+): Promise<boolean> {
+  if (result.status === "pass" || !result.canRepair || !result.repair) return false;
+  if (!opts.repair) return false;
 
   let shouldRepair = opts.yes;
   if (!shouldRepair) {
@@ -128,7 +145,7 @@ async function maybeRepair(
       message: `Repair "${result.name}"?`,
       initialValue: true,
     });
-    if (p.isCancel(answer)) return;
+    if (p.isCancel(answer)) return false;
     shouldRepair = answer;
   }
 
@@ -136,10 +153,30 @@ async function maybeRepair(
     try {
       await result.repair();
       p.log.success(`Repaired: ${result.name}`);
+      return true;
     } catch (err) {
       p.log.error(`Repair failed: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
+  return false;
+}
+
+async function runRepairableCheck(input: {
+  run: () => CheckResult | Promise<CheckResult>;
+  configPath: string;
+  opts: { repair?: boolean; yes?: boolean };
+}): Promise<CheckResult> {
+  let result = await input.run();
+  printResult(result);
+
+  const repaired = await maybeRepair(result, input.opts);
+  if (!repaired) return result;
+
+  // Repairs may create/update the adjacent .env file or other local resources.
+  loadPaperclipEnvFile(input.configPath);
+  result = await input.run();
+  printResult(result);
+  return result;
 }
 
 function printSummary(results: CheckResult[]): { passed: number; warned: number; failed: number } {

cli/src/commands/env.ts

@@ -118,6 +118,29 @@ function collectDeploymentEnvRows(config: PaperclipConfig | null, configPath: st
   const dbUrl = process.env.DATABASE_URL ?? config?.database?.connectionString ?? "";
   const databaseMode = config?.database?.mode ?? "embedded-postgres";
   const dbUrlSource: EnvSource = process.env.DATABASE_URL ? "env" : config?.database?.connectionString ? "config" : "missing";
+  const publicUrl =
+    process.env.PAPERCLIP_PUBLIC_URL ??
+    process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL ??
+    process.env.BETTER_AUTH_URL ??
+    process.env.BETTER_AUTH_BASE_URL ??
+    config?.auth?.publicBaseUrl ??
+    "";
+  const publicUrlSource: EnvSource =
+    process.env.PAPERCLIP_PUBLIC_URL
+      ? "env"
+      : process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL || process.env.BETTER_AUTH_URL || process.env.BETTER_AUTH_BASE_URL
+        ? "env"
+        : config?.auth?.publicBaseUrl
+          ? "config"
+          : "missing";
+  let trustedOriginsDefault = "";
+  if (publicUrl) {
+    try {
+      trustedOriginsDefault = new URL(publicUrl).origin;
+    } catch {
+      trustedOriginsDefault = "";
+    }
+  }
 
   const heartbeatInterval = process.env.HEARTBEAT_SCHEDULER_INTERVAL_MS ?? DEFAULT_HEARTBEAT_SCHEDULER_INTERVAL_MS;
   const heartbeatEnabled = process.env.HEARTBEAT_SCHEDULER_ENABLED ?? "true";
@@ -192,6 +215,24 @@ function collectDeploymentEnvRows(config: PaperclipConfig | null, configPath: st
       required: false,
       note: "HTTP listen port",
     },
+    {
+      key: "PAPERCLIP_PUBLIC_URL",
+      value: publicUrl,
+      source: publicUrlSource,
+      required: false,
+      note: "Canonical public URL for auth/callback/invite origin wiring",
+    },
+    {
+      key: "BETTER_AUTH_TRUSTED_ORIGINS",
+      value: process.env.BETTER_AUTH_TRUSTED_ORIGINS ?? trustedOriginsDefault,
+      source: process.env.BETTER_AUTH_TRUSTED_ORIGINS
+        ? "env"
+        : trustedOriginsDefault
+          ? "default"
+          : "missing",
+      required: false,
+      note: "Comma-separated auth origin allowlist (auto-derived from PAPERCLIP_PUBLIC_URL when possible)",
+    },
     {
       key: "PAPERCLIP_AGENT_JWT_TTL_SECONDS",
       value: process.env.PAPERCLIP_AGENT_JWT_TTL_SECONDS ?? DEFAULT_AGENT_JWT_TTL_SECONDS,

cli/src/commands/onboard.ts

@@ -1,5 +1,22 @@
 import * as p from "@clack/prompts";
+import path from "node:path";
 import pc from "picocolors";
+import {
+  AUTH_BASE_URL_MODES,
+  BIND_MODES,
+  DEPLOYMENT_EXPOSURES,
+  DEPLOYMENT_MODES,
+  SECRET_PROVIDERS,
+  STORAGE_PROVIDERS,
+  inferBindModeFromHost,
+  resolveRuntimeBind,
+  type BindMode,
+  type AuthBaseUrlMode,
+  type DeploymentExposure,
+  type DeploymentMode,
+  type SecretProvider,
+  type StorageProvider,
+} from "@paperclipai/shared";
 import { configExists, readConfig, resolveConfigPath, writeConfig } from "../config/store.js";
 import type { PaperclipConfig } from "../config/schema.js";
 import { ensureAgentJwtSecret, resolveAgentJwtEnvFile } from "../config/env.js";
@@ -10,14 +27,22 @@ import { promptLogging } from "../prompts/logging.js";
 import { defaultSecretsConfig } from "../prompts/secrets.js";
 import { defaultStorageConfig, promptStorage } from "../prompts/storage.js";
 import { promptServer } from "../prompts/server.js";
+import { buildPresetServerConfig } from "../config/server-bind.js";
 import {
   describeLocalInstancePaths,
+  expandHomePrefix,
+  resolveDefaultBackupDir,
   resolveDefaultEmbeddedPostgresDir,
   resolveDefaultLogsDir,
   resolvePaperclipInstanceId,
 } from "../config/home.js";
 import { bootstrapCeoInvite } from "./auth-bootstrap-ceo.js";
 import { printPaperclipCliBanner } from "../utils/banner.js";
+import {
+  getTelemetryClient,
+  trackInstallStarted,
+  trackInstallCompleted,
+} from "../telemetry.js";
 
 type SetupMode = "quickstart" | "advanced";
 
@@ -26,37 +51,282 @@ type OnboardOptions = {
   run?: boolean;
   yes?: boolean;
   invokedByRun?: boolean;
+  bind?: BindMode;
 };
 
-function quickstartDefaults(): Pick<PaperclipConfig, "database" | "logging" | "server" | "auth" | "storage" | "secrets"> {
+type OnboardDefaults = Pick<PaperclipConfig, "database" | "logging" | "server" | "auth" | "storage" | "secrets">;
+
+const TAILNET_BIND_WARNING =
+  "No Tailscale address was detected during setup. The saved config will stay on loopback until Tailscale is available or PAPERCLIP_TAILNET_BIND_HOST is set.";
+
+const ONBOARD_ENV_KEYS = [
+  "PAPERCLIP_PUBLIC_URL",
+  "DATABASE_URL",
+  "PAPERCLIP_DB_BACKUP_ENABLED",
+  "PAPERCLIP_DB_BACKUP_INTERVAL_MINUTES",
+  "PAPERCLIP_DB_BACKUP_RETENTION_DAYS",
+  "PAPERCLIP_DB_BACKUP_DIR",
+  "PAPERCLIP_DEPLOYMENT_MODE",
+  "PAPERCLIP_DEPLOYMENT_EXPOSURE",
+  "PAPERCLIP_BIND",
+  "PAPERCLIP_BIND_HOST",
+  "PAPERCLIP_TAILNET_BIND_HOST",
+  "HOST",
+  "PORT",
+  "SERVE_UI",
+  "PAPERCLIP_ALLOWED_HOSTNAMES",
+  "PAPERCLIP_AUTH_BASE_URL_MODE",
+  "PAPERCLIP_AUTH_PUBLIC_BASE_URL",
+  "BETTER_AUTH_URL",
+  "BETTER_AUTH_BASE_URL",
+  "PAPERCLIP_STORAGE_PROVIDER",
+  "PAPERCLIP_STORAGE_LOCAL_DIR",
+  "PAPERCLIP_STORAGE_S3_BUCKET",
+  "PAPERCLIP_STORAGE_S3_REGION",
+  "PAPERCLIP_STORAGE_S3_ENDPOINT",
+  "PAPERCLIP_STORAGE_S3_PREFIX",
+  "PAPERCLIP_STORAGE_S3_FORCE_PATH_STYLE",
+  "PAPERCLIP_SECRETS_PROVIDER",
+  "PAPERCLIP_SECRETS_STRICT_MODE",
+  "PAPERCLIP_SECRETS_MASTER_KEY_FILE",
+] as const;
+
+function parseBooleanFromEnv(rawValue: string | undefined): boolean | null {
+  if (rawValue === undefined) return null;
+  const lower = rawValue.trim().toLowerCase();
+  if (lower === "true" || lower === "1" || lower === "yes") return true;
+  if (lower === "false" || lower === "0" || lower === "no") return false;
+  return null;
+}
+
+function parseNumberFromEnv(rawValue: string | undefined): number | null {
+  if (!rawValue) return null;
+  const parsed = Number(rawValue);
+  if (!Number.isFinite(parsed)) return null;
+  return parsed;
+}
+
+function parseEnumFromEnv<T extends string>(rawValue: string | undefined, allowedValues: readonly T[]): T | null {
+  if (!rawValue) return null;
+  return allowedValues.includes(rawValue as T) ? (rawValue as T) : null;
+}
+
+function resolvePathFromEnv(rawValue: string | undefined): string | null {
+  if (!rawValue || rawValue.trim().length === 0) return null;
+  return path.resolve(expandHomePrefix(rawValue.trim()));
+}
+
+function describeServerBinding(server: Pick<PaperclipConfig["server"], "bind" | "customBindHost" | "host" | "port">): string {
+  const bind = server.bind ?? inferBindModeFromHost(server.host);
+  const detail =
+    bind === "custom"
+      ? server.customBindHost ?? server.host
+      : bind === "tailnet"
+        ? "detected tailscale address"
+        : server.host;
+  return `${bind}${detail ? ` (${detail})` : ""}:${server.port}`;
+}
+
+function quickstartDefaultsFromEnv(opts?: { preferTrustedLocal?: boolean }): {
+  defaults: OnboardDefaults;
+  usedEnvKeys: string[];
+  ignoredEnvKeys: Array<{ key: string; reason: string }>;
+} {
+  const preferTrustedLocal = opts?.preferTrustedLocal ?? false;
   const instanceId = resolvePaperclipInstanceId();
-  return {
+  const defaultStorage = defaultStorageConfig();
+  const defaultSecrets = defaultSecretsConfig();
+  const databaseUrl = process.env.DATABASE_URL?.trim() || undefined;
+  const publicUrl = preferTrustedLocal
+    ? undefined
+    : (
+      process.env.PAPERCLIP_PUBLIC_URL?.trim() ||
+      process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL?.trim() ||
+      process.env.BETTER_AUTH_URL?.trim() ||
+      process.env.BETTER_AUTH_BASE_URL?.trim() ||
+      undefined
+    );
+  const deploymentMode = preferTrustedLocal
+    ? "local_trusted"
+    : (parseEnumFromEnv<DeploymentMode>(process.env.PAPERCLIP_DEPLOYMENT_MODE, DEPLOYMENT_MODES) ?? "local_trusted");
+  const deploymentExposureFromEnv = parseEnumFromEnv<DeploymentExposure>(
+    process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE,
+    DEPLOYMENT_EXPOSURES,
+  );
+  const deploymentExposure =
+    deploymentMode === "local_trusted" ? "private" : (deploymentExposureFromEnv ?? "private");
+  const bindFromEnv = parseEnumFromEnv<BindMode>(process.env.PAPERCLIP_BIND, BIND_MODES);
+  const customBindHostFromEnv = process.env.PAPERCLIP_BIND_HOST?.trim() || undefined;
+  const hostFromEnv = process.env.HOST?.trim() || undefined;
+  const configuredBindHost = customBindHostFromEnv ?? hostFromEnv;
+  const bind = preferTrustedLocal
+    ? "loopback"
+    : (
+      deploymentMode === "local_trusted"
+        ? "loopback"
+        : (bindFromEnv ?? (configuredBindHost ? inferBindModeFromHost(configuredBindHost) : "lan"))
+    );
+  const resolvedBind = resolveRuntimeBind({
+    bind,
+    host: hostFromEnv ?? (bind === "loopback" ? "127.0.0.1" : "0.0.0.0"),
+    customBindHost: customBindHostFromEnv,
+    tailnetBindHost: process.env.PAPERCLIP_TAILNET_BIND_HOST?.trim(),
+  });
+  const authPublicBaseUrl = publicUrl;
+  const authBaseUrlModeFromEnv = parseEnumFromEnv<AuthBaseUrlMode>(
+    process.env.PAPERCLIP_AUTH_BASE_URL_MODE,
+    AUTH_BASE_URL_MODES,
+  );
+  const authBaseUrlMode = authBaseUrlModeFromEnv ?? (authPublicBaseUrl ? "explicit" : "auto");
+  const allowedHostnamesFromEnv = process.env.PAPERCLIP_ALLOWED_HOSTNAMES
+    ? process.env.PAPERCLIP_ALLOWED_HOSTNAMES
+      .split(",")
+      .map((value) => value.trim().toLowerCase())
+      .filter((value) => value.length > 0)
+    : [];
+  const hostnameFromPublicUrl = publicUrl
+    ? (() => {
+      try {
+        return new URL(publicUrl).hostname.trim().toLowerCase();
+      } catch {
+        return null;
+      }
+    })()
+    : null;
+  const storageProvider =
+    parseEnumFromEnv<StorageProvider>(process.env.PAPERCLIP_STORAGE_PROVIDER, STORAGE_PROVIDERS) ??
+    defaultStorage.provider;
+  const secretsProvider =
+    parseEnumFromEnv<SecretProvider>(process.env.PAPERCLIP_SECRETS_PROVIDER, SECRET_PROVIDERS) ??
+    defaultSecrets.provider;
+  const databaseBackupEnabled = parseBooleanFromEnv(process.env.PAPERCLIP_DB_BACKUP_ENABLED) ?? true;
+  const databaseBackupIntervalMinutes = Math.max(
+    1,
+    parseNumberFromEnv(process.env.PAPERCLIP_DB_BACKUP_INTERVAL_MINUTES) ?? 60,
+  );
+  const databaseBackupRetentionDays = Math.max(
+    1,
+    parseNumberFromEnv(process.env.PAPERCLIP_DB_BACKUP_RETENTION_DAYS) ?? 30,
+  );
+  const defaults: OnboardDefaults = {
     database: {
-      mode: "embedded-postgres",
+      mode: databaseUrl ? "postgres" : "embedded-postgres",
+      ...(databaseUrl ? { connectionString: databaseUrl } : {}),
       embeddedPostgresDataDir: resolveDefaultEmbeddedPostgresDir(instanceId),
       embeddedPostgresPort: 54329,
+      backup: {
+        enabled: databaseBackupEnabled,
+        intervalMinutes: databaseBackupIntervalMinutes,
+        retentionDays: databaseBackupRetentionDays,
+        dir: resolvePathFromEnv(process.env.PAPERCLIP_DB_BACKUP_DIR) ?? resolveDefaultBackupDir(instanceId),
+      },
     },
     logging: {
       mode: "file",
       logDir: resolveDefaultLogsDir(instanceId),
     },
     server: {
-      deploymentMode: "local_trusted",
-      exposure: "private",
-      host: "127.0.0.1",
-      port: 3100,
-      allowedHostnames: [],
-      serveUi: true,
+      deploymentMode,
+      exposure: deploymentExposure,
+      bind: resolvedBind.bind,
+      ...(resolvedBind.customBindHost ? { customBindHost: resolvedBind.customBindHost } : {}),
+      host: resolvedBind.host,
+      port: Number(process.env.PORT) || 3100,
+      allowedHostnames: Array.from(new Set([...allowedHostnamesFromEnv, ...(hostnameFromPublicUrl ? [hostnameFromPublicUrl] : [])])),
+      serveUi: parseBooleanFromEnv(process.env.SERVE_UI) ?? true,
     },
     auth: {
-      baseUrlMode: "auto",
+      baseUrlMode: authBaseUrlMode,
+      disableSignUp: false,
+      ...(authPublicBaseUrl ? { publicBaseUrl: authPublicBaseUrl } : {}),
+    },
+    storage: {
+      provider: storageProvider,
+      localDisk: {
+        baseDir:
+          resolvePathFromEnv(process.env.PAPERCLIP_STORAGE_LOCAL_DIR) ?? defaultStorage.localDisk.baseDir,
+      },
+      s3: {
+        bucket: process.env.PAPERCLIP_STORAGE_S3_BUCKET ?? defaultStorage.s3.bucket,
+        region: process.env.PAPERCLIP_STORAGE_S3_REGION ?? defaultStorage.s3.region,
+        endpoint: process.env.PAPERCLIP_STORAGE_S3_ENDPOINT ?? defaultStorage.s3.endpoint,
+        prefix: process.env.PAPERCLIP_STORAGE_S3_PREFIX ?? defaultStorage.s3.prefix,
+        forcePathStyle:
+          parseBooleanFromEnv(process.env.PAPERCLIP_STORAGE_S3_FORCE_PATH_STYLE) ??
+          defaultStorage.s3.forcePathStyle,
+      },
+    },
+    secrets: {
+      provider: secretsProvider,
+      strictMode: parseBooleanFromEnv(process.env.PAPERCLIP_SECRETS_STRICT_MODE) ?? defaultSecrets.strictMode,
+      localEncrypted: {
+        keyFilePath:
+          resolvePathFromEnv(process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE) ??
+          defaultSecrets.localEncrypted.keyFilePath,
+      },
     },
-    storage: defaultStorageConfig(),
-    secrets: defaultSecretsConfig(),
   };
+  const ignoredEnvKeys: Array<{ key: string; reason: string }> = [];
+  if (preferTrustedLocal) {
+    const forcedLocalReason = "Ignored because --yes quickstart forces trusted local loopback defaults";
+    for (const key of [
+      "PAPERCLIP_DEPLOYMENT_MODE",
+      "PAPERCLIP_DEPLOYMENT_EXPOSURE",
+      "PAPERCLIP_BIND",
+      "PAPERCLIP_BIND_HOST",
+      "HOST",
+      "PAPERCLIP_AUTH_BASE_URL_MODE",
+      "PAPERCLIP_AUTH_PUBLIC_BASE_URL",
+      "PAPERCLIP_PUBLIC_URL",
+      "BETTER_AUTH_URL",
+      "BETTER_AUTH_BASE_URL",
+    ] as const) {
+      if (process.env[key] !== undefined) {
+        ignoredEnvKeys.push({ key, reason: forcedLocalReason });
+      }
+    }
+  }
+  if (deploymentMode === "local_trusted" && process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE !== undefined) {
+    ignoredEnvKeys.push({
+      key: "PAPERCLIP_DEPLOYMENT_EXPOSURE",
+      reason: "Ignored because deployment mode local_trusted always forces private exposure",
+    });
+  }
+  if (deploymentMode === "local_trusted" && process.env.PAPERCLIP_BIND !== undefined) {
+    ignoredEnvKeys.push({
+      key: "PAPERCLIP_BIND",
+      reason: "Ignored because deployment mode local_trusted always uses loopback reachability",
+    });
+  }
+  if (deploymentMode === "local_trusted" && process.env.PAPERCLIP_BIND_HOST !== undefined) {
+    ignoredEnvKeys.push({
+      key: "PAPERCLIP_BIND_HOST",
+      reason: "Ignored because deployment mode local_trusted always uses loopback reachability",
+    });
+  }
+  if (deploymentMode === "local_trusted" && process.env.HOST !== undefined) {
+    ignoredEnvKeys.push({
+      key: "HOST",
+      reason: "Ignored because deployment mode local_trusted always uses loopback reachability",
+    });
+  }
+
+  const ignoredKeySet = new Set(ignoredEnvKeys.map((entry) => entry.key));
+  const usedEnvKeys = ONBOARD_ENV_KEYS.filter(
+    (key) => process.env[key] !== undefined && !ignoredKeySet.has(key),
+  );
+  return { defaults, usedEnvKeys, ignoredEnvKeys };
+}
+
+function canCreateBootstrapInviteImmediately(config: Pick<PaperclipConfig, "database" | "server">): boolean {
+  return config.server.deploymentMode === "authenticated" && config.database.mode !== "embedded-postgres";
 }
 
 export async function onboard(opts: OnboardOptions): Promise<void> {
+  if (opts.bind && !["loopback", "lan", "tailnet"].includes(opts.bind)) {
+    throw new Error(`Unsupported bind preset for onboard: ${opts.bind}. Use loopback, lan, or tailnet.`);
+  }
+
   printPaperclipCliBanner();
   p.intro(pc.bgCyan(pc.black(" paperclipai onboard ")));
   const configPath = resolveConfigPath(opts.config);
@@ -67,11 +337,12 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     ),
   );
 
+  let existingConfig: PaperclipConfig | null = null;
   if (configExists(opts.config)) {
-    p.log.message(pc.dim(`${configPath} exists, updating config`));
+    p.log.message(pc.dim(`${configPath} exists`));
 
     try {
-      readConfig(opts.config);
+      existingConfig = readConfig(opts.config);
     } catch (err) {
       p.log.message(
         pc.yellow(
@@ -81,9 +352,85 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     }
   }
 
+  if (existingConfig) {
+    p.log.message(
+      pc.dim("Existing Paperclip install detected; keeping the current configuration unchanged."),
+    );
+    p.log.message(pc.dim(`Use ${pc.cyan("paperclipai configure")} if you want to change settings.`));
+
+    const jwtSecret = ensureAgentJwtSecret(configPath);
+    const envFilePath = resolveAgentJwtEnvFile(configPath);
+    if (jwtSecret.created) {
+      p.log.success(`Created ${pc.cyan("PAPERCLIP_AGENT_JWT_SECRET")} in ${pc.dim(envFilePath)}`);
+    } else if (process.env.PAPERCLIP_AGENT_JWT_SECRET?.trim()) {
+      p.log.info(`Using existing ${pc.cyan("PAPERCLIP_AGENT_JWT_SECRET")} from environment`);
+    } else {
+      p.log.info(`Using existing ${pc.cyan("PAPERCLIP_AGENT_JWT_SECRET")} in ${pc.dim(envFilePath)}`);
+    }
+
+    const keyResult = ensureLocalSecretsKeyFile(existingConfig, configPath);
+    if (keyResult.status === "created") {
+      p.log.success(`Created local secrets key file at ${pc.dim(keyResult.path)}`);
+    } else if (keyResult.status === "existing") {
+      p.log.message(pc.dim(`Using existing local secrets key file at ${keyResult.path}`));
+    }
+
+    p.note(
+      [
+        "Existing config preserved",
+        `Database: ${existingConfig.database.mode}`,
+        existingConfig.llm ? `LLM: ${existingConfig.llm.provider}` : "LLM: not configured",
+        `Logging: ${existingConfig.logging.mode} -> ${existingConfig.logging.logDir}`,
+        `Server: ${existingConfig.server.deploymentMode}/${existingConfig.server.exposure} @ ${describeServerBinding(existingConfig.server)}`,
+        `Allowed hosts: ${existingConfig.server.allowedHostnames.length > 0 ? existingConfig.server.allowedHostnames.join(", ") : "(loopback only)"}`,
+        `Auth URL mode: ${existingConfig.auth.baseUrlMode}${existingConfig.auth.publicBaseUrl ? ` (${existingConfig.auth.publicBaseUrl})` : ""}`,
+        `Storage: ${existingConfig.storage.provider}`,
+        `Secrets: ${existingConfig.secrets.provider} (strict mode ${existingConfig.secrets.strictMode ? "on" : "off"})`,
+        "Agent auth: PAPERCLIP_AGENT_JWT_SECRET configured",
+      ].join("\n"),
+      "Configuration ready",
+    );
+
+    p.note(
+      [
+        `Run: ${pc.cyan("paperclipai run")}`,
+        `Reconfigure later: ${pc.cyan("paperclipai configure")}`,
+        `Diagnose setup: ${pc.cyan("paperclipai doctor")}`,
+      ].join("\n"),
+      "Next commands",
+    );
+
+    let shouldRunNow = opts.run === true || opts.yes === true;
+    if (!shouldRunNow && !opts.invokedByRun && process.stdin.isTTY && process.stdout.isTTY) {
+      const answer = await p.confirm({
+        message: "Start Paperclip now?",
+        initialValue: true,
+      });
+      if (!p.isCancel(answer)) {
+        shouldRunNow = answer;
+      }
+    }
+
+    if (shouldRunNow && !opts.invokedByRun) {
+      process.env.PAPERCLIP_OPEN_ON_LISTEN = "true";
+      const { runCommand } = await import("./run.js");
+      await runCommand({ config: configPath, repair: true, yes: true });
+      return;
+    }
+
+    p.outro("Existing Paperclip setup is ready.");
+    return;
+  }
+
   let setupMode: SetupMode = "quickstart";
   if (opts.yes) {
-    p.log.message(pc.dim("`--yes` enabled: using Quickstart defaults."));
+    p.log.message(
+      pc.dim(
+        opts.bind
+          ? `\`--yes\` enabled: using Quickstart defaults with bind=${opts.bind}.`
+          : "`--yes` enabled: using Quickstart defaults.",
+      ),
+    );
   } else {
     const setupModeChoice = await p.select({
       message: "Choose setup path",
@@ -108,7 +455,13 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     setupMode = setupModeChoice as SetupMode;
   }
 
+  const tc = getTelemetryClient();
+  if (tc) trackInstallStarted(tc);
+
   let llm: PaperclipConfig["llm"] | undefined;
+  const { defaults: derivedDefaults, usedEnvKeys, ignoredEnvKeys } = quickstartDefaultsFromEnv({
+    preferTrustedLocal: opts.yes === true && !opts.bind,
+  });
   let {
     database,
     logging,
@@ -116,11 +469,24 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     auth,
     storage,
     secrets,
-  } = quickstartDefaults();
+  } = derivedDefaults;
+
+  if (opts.bind === "loopback" || opts.bind === "lan" || opts.bind === "tailnet") {
+    const preset = buildPresetServerConfig(opts.bind, {
+      port: server.port,
+      allowedHostnames: server.allowedHostnames,
+      serveUi: server.serveUi,
+    });
+    server = preset.server;
+    auth = preset.auth;
+    if (opts.bind === "tailnet" && server.host === "127.0.0.1") {
+      p.log.warn(TAILNET_BIND_WARNING);
+    }
+  }
 
   if (setupMode === "advanced") {
     p.log.step(pc.bold("Database"));
-    database = await promptDatabase();
+    database = await promptDatabase(database);
 
     if (database.mode === "postgres" && database.connectionString) {
       const s = p.spinner();
@@ -184,13 +550,20 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     logging = await promptLogging();
 
     p.log.step(pc.bold("Server"));
-    ({ server, auth } = await promptServer());
+    ({ server, auth } = await promptServer({ currentServer: server, currentAuth: auth }));
 
     p.log.step(pc.bold("Storage"));
-    storage = await promptStorage(defaultStorageConfig());
+    storage = await promptStorage(storage);
 
     p.log.step(pc.bold("Secrets"));
-    secrets = defaultSecretsConfig();
+    const secretsDefaults = defaultSecretsConfig();
+    secrets = {
+      provider: secrets.provider ?? secretsDefaults.provider,
+      strictMode: secrets.strictMode ?? secretsDefaults.strictMode,
+      localEncrypted: {
+        keyFilePath: secrets.localEncrypted?.keyFilePath ?? secretsDefaults.localEncrypted.keyFilePath,
+      },
+    };
     p.log.message(
       pc.dim(
         `Using defaults: provider=${secrets.provider}, strictMode=${secrets.strictMode}, keyFile=${secrets.localEncrypted.keyFilePath}`,
@@ -199,8 +572,22 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
   } else {
     p.log.step(pc.bold("Quickstart"));
     p.log.message(
-      pc.dim("Using local defaults: embedded database, no LLM provider, file storage, and local encrypted secrets."),
+      pc.dim(
+        opts.bind
+          ? `Using quickstart defaults with bind=${opts.bind}.`
+          : `Using quickstart defaults: ${server.deploymentMode}/${server.exposure} @ ${describeServerBinding(server)}.`,
+      ),
     );
+    if (usedEnvKeys.length > 0) {
+      p.log.message(pc.dim(`Environment-aware defaults active (${usedEnvKeys.length} env var(s) detected).`));
+    } else {
+      p.log.message(
+        pc.dim("No environment overrides detected: embedded database, file storage, local encrypted secrets."),
+      );
+    }
+    for (const ignored of ignoredEnvKeys) {
+      p.log.message(pc.dim(`Ignored ${ignored.key}: ${ignored.reason}`));
+    }
   }
 
   const jwtSecret = ensureAgentJwtSecret(configPath);
@@ -224,6 +611,9 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     logging,
     server,
     auth,
+    telemetry: {
+      enabled: true,
+    },
     storage,
     secrets,
   };
@@ -237,12 +627,16 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
 
   writeConfig(config, opts.config);
 
+  if (tc) trackInstallCompleted(tc, {
+    adapterType: server.deploymentMode,
+  });
+
   p.note(
     [
       `Database: ${database.mode}`,
       llm ? `LLM: ${llm.provider}` : "LLM: not configured",
       `Logging: ${logging.mode} -> ${logging.logDir}`,
-      `Server: ${server.deploymentMode}/${server.exposure} @ ${server.host}:${server.port}`,
+      `Server: ${server.deploymentMode}/${server.exposure} @ ${describeServerBinding(server)}`,
       `Allowed hosts: ${server.allowedHostnames.length > 0 ? server.allowedHostnames.join(", ") : "(loopback only)"}`,
       `Auth URL mode: ${auth.baseUrlMode}${auth.publicBaseUrl ? ` (${auth.publicBaseUrl})` : ""}`,
       `Storage: ${storage.provider}`,
@@ -261,7 +655,7 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     "Next commands",
   );
 
-  if (server.deploymentMode === "authenticated") {
+  if (canCreateBootstrapInviteImmediately({ database, server })) {
     p.log.step("Generating bootstrap CEO invite");
     await bootstrapCeoInvite({ config: configPath });
   }
@@ -284,5 +678,15 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     return;
   }
 
+  if (server.deploymentMode === "authenticated" && database.mode === "embedded-postgres") {
+    p.log.info(
+      [
+        "Bootstrap CEO invite will be created after the server starts.",
+        `Next: ${pc.cyan("paperclipai run")}`,
+        `Then: ${pc.cyan("paperclipai auth bootstrap-ceo")}`,
+      ].join("\n"),
+    );
+  }
+
   p.outro("You're all set!");
 }

cli/src/commands/routines.ts

@@ -0,0 +1,352 @@
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { Command } from "commander";
+import pc from "picocolors";
+import {
+  applyPendingMigrations,
+  createDb,
+  createEmbeddedPostgresLogBuffer,
+  ensurePostgresDatabase,
+  formatEmbeddedPostgresError,
+  routines,
+} from "@paperclipai/db";
+import { eq, inArray } from "drizzle-orm";
+import { loadPaperclipEnvFile } from "../config/env.js";
+import { readConfig, resolveConfigPath } from "../config/store.js";
+
+type RoutinesDisableAllOptions = {
+  config?: string;
+  dataDir?: string;
+  companyId?: string;
+  json?: boolean;
+};
+
+type DisableAllRoutinesResult = {
+  companyId: string;
+  totalRoutines: number;
+  pausedCount: number;
+  alreadyPausedCount: number;
+  archivedCount: number;
+};
+
+type EmbeddedPostgresInstance = {
+  initialise(): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+};
+
+type EmbeddedPostgresCtor = new (opts: {
+  databaseDir: string;
+  user: string;
+  password: string;
+  port: number;
+  persistent: boolean;
+  initdbFlags?: string[];
+  onLog?: (message: unknown) => void;
+  onError?: (message: unknown) => void;
+}) => EmbeddedPostgresInstance;
+
+type EmbeddedPostgresHandle = {
+  port: number;
+  startedByThisProcess: boolean;
+  stop: () => Promise<void>;
+};
+
+type ClosableDb = ReturnType<typeof createDb> & {
+  $client?: {
+    end?: (options?: { timeout?: number }) => Promise<void>;
+  };
+};
+
+function nonEmpty(value: string | null | undefined): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+async function isPortAvailable(port: number): Promise<boolean> {
+  return await new Promise<boolean>((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", () => resolve(false));
+    server.listen(port, "127.0.0.1", () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+async function findAvailablePort(preferredPort: number): Promise<number> {
+  let port = Math.max(1, Math.trunc(preferredPort));
+  while (!(await isPortAvailable(port))) {
+    port += 1;
+  }
+  return port;
+}
+
+function readPidFilePort(postmasterPidFile: string): number | null {
+  if (!fs.existsSync(postmasterPidFile)) return null;
+  try {
+    const lines = fs.readFileSync(postmasterPidFile, "utf8").split("\n");
+    const port = Number(lines[3]?.trim());
+    return Number.isInteger(port) && port > 0 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+function readRunningPostmasterPid(postmasterPidFile: string): number | null {
+  if (!fs.existsSync(postmasterPidFile)) return null;
+  try {
+    const pid = Number(fs.readFileSync(postmasterPidFile, "utf8").split("\n")[0]?.trim());
+    if (!Number.isInteger(pid) || pid <= 0) return null;
+    process.kill(pid, 0);
+    return pid;
+  } catch {
+    return null;
+  }
+}
+
+async function ensureEmbeddedPostgres(dataDir: string, preferredPort: number): Promise<EmbeddedPostgresHandle> {
+  const moduleName = "embedded-postgres";
+  let EmbeddedPostgres: EmbeddedPostgresCtor;
+  try {
+    const mod = await import(moduleName);
+    EmbeddedPostgres = mod.default as EmbeddedPostgresCtor;
+  } catch {
+    throw new Error(
+      "Embedded PostgreSQL support requires dependency `embedded-postgres`. Reinstall dependencies and try again.",
+    );
+  }
+
+  const postmasterPidFile = path.resolve(dataDir, "postmaster.pid");
+  const runningPid = readRunningPostmasterPid(postmasterPidFile);
+  if (runningPid) {
+    return {
+      port: readPidFilePort(postmasterPidFile) ?? preferredPort,
+      startedByThisProcess: false,
+      stop: async () => {},
+    };
+  }
+
+  const port = await findAvailablePort(preferredPort);
+  const logBuffer = createEmbeddedPostgresLogBuffer();
+  const instance = new EmbeddedPostgres({
+    databaseDir: dataDir,
+    user: "paperclip",
+    password: "paperclip",
+    port,
+    persistent: true,
+    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
+    onLog: logBuffer.append,
+    onError: logBuffer.append,
+  });
+
+  if (!fs.existsSync(path.resolve(dataDir, "PG_VERSION"))) {
+    try {
+      await instance.initialise();
+    } catch (error) {
+      throw formatEmbeddedPostgresError(error, {
+        fallbackMessage: `Failed to initialize embedded PostgreSQL cluster in ${dataDir} on port ${port}`,
+        recentLogs: logBuffer.getRecentLogs(),
+      });
+    }
+  }
+
+  if (fs.existsSync(postmasterPidFile)) {
+    fs.rmSync(postmasterPidFile, { force: true });
+  }
+
+  try {
+    await instance.start();
+  } catch (error) {
+    throw formatEmbeddedPostgresError(error, {
+      fallbackMessage: `Failed to start embedded PostgreSQL on port ${port}`,
+      recentLogs: logBuffer.getRecentLogs(),
+    });
+  }
+
+  return {
+    port,
+    startedByThisProcess: true,
+    stop: async () => {
+      await instance.stop();
+    },
+  };
+}
+
+async function closeDb(db: ClosableDb): Promise<void> {
+  await db.$client?.end?.({ timeout: 5 }).catch(() => undefined);
+}
+
+async function openConfiguredDb(configPath: string): Promise<{
+  db: ClosableDb;
+  stop: () => Promise<void>;
+}> {
+  const config = readConfig(configPath);
+  if (!config) {
+    throw new Error(`Config not found at ${configPath}.`);
+  }
+
+  let embeddedHandle: EmbeddedPostgresHandle | null = null;
+  try {
+    if (config.database.mode === "embedded-postgres") {
+      embeddedHandle = await ensureEmbeddedPostgres(
+        config.database.embeddedPostgresDataDir,
+        config.database.embeddedPostgresPort,
+      );
+      const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${embeddedHandle.port}/postgres`;
+      await ensurePostgresDatabase(adminConnectionString, "paperclip");
+      const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${embeddedHandle.port}/paperclip`;
+      await applyPendingMigrations(connectionString);
+      const db = createDb(connectionString) as ClosableDb;
+      return {
+        db,
+        stop: async () => {
+          await closeDb(db);
+          if (embeddedHandle?.startedByThisProcess) {
+            await embeddedHandle.stop().catch(() => undefined);
+          }
+        },
+      };
+    }
+
+    const connectionString = nonEmpty(config.database.connectionString);
+    if (!connectionString) {
+      throw new Error(`Config at ${configPath} does not define a database connection string.`);
+    }
+
+    await applyPendingMigrations(connectionString);
+    const db = createDb(connectionString) as ClosableDb;
+    return {
+      db,
+      stop: async () => {
+        await closeDb(db);
+      },
+    };
+  } catch (error) {
+    if (embeddedHandle?.startedByThisProcess) {
+      await embeddedHandle.stop().catch(() => undefined);
+    }
+    throw error;
+  }
+}
+
+export async function disableAllRoutinesInConfig(
+  options: Pick<RoutinesDisableAllOptions, "config" | "companyId">,
+): Promise<DisableAllRoutinesResult> {
+  const configPath = resolveConfigPath(options.config);
+  loadPaperclipEnvFile(configPath);
+  const companyId =
+    nonEmpty(options.companyId)
+    ?? nonEmpty(process.env.PAPERCLIP_COMPANY_ID)
+    ?? null;
+  if (!companyId) {
+    throw new Error("Company ID is required. Pass --company-id or set PAPERCLIP_COMPANY_ID.");
+  }
+
+  const config = readConfig(configPath);
+  if (!config) {
+    throw new Error(`Config not found at ${configPath}.`);
+  }
+
+  let embeddedHandle: EmbeddedPostgresHandle | null = null;
+  let db: ClosableDb | null = null;
+  try {
+    if (config.database.mode === "embedded-postgres") {
+      embeddedHandle = await ensureEmbeddedPostgres(
+        config.database.embeddedPostgresDataDir,
+        config.database.embeddedPostgresPort,
+      );
+      const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${embeddedHandle.port}/postgres`;
+      await ensurePostgresDatabase(adminConnectionString, "paperclip");
+      const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${embeddedHandle.port}/paperclip`;
+      await applyPendingMigrations(connectionString);
+      db = createDb(connectionString) as ClosableDb;
+    } else {
+      const connectionString = nonEmpty(config.database.connectionString);
+      if (!connectionString) {
+        throw new Error(`Config at ${configPath} does not define a database connection string.`);
+      }
+      await applyPendingMigrations(connectionString);
+      db = createDb(connectionString) as ClosableDb;
+    }
+
+    const existing = await db
+      .select({
+        id: routines.id,
+        status: routines.status,
+      })
+      .from(routines)
+      .where(eq(routines.companyId, companyId));
+
+    const alreadyPausedCount = existing.filter((routine) => routine.status === "paused").length;
+    const archivedCount = existing.filter((routine) => routine.status === "archived").length;
+    const idsToPause = existing
+      .filter((routine) => routine.status !== "paused" && routine.status !== "archived")
+      .map((routine) => routine.id);
+
+    if (idsToPause.length > 0) {
+      await db
+        .update(routines)
+        .set({
+          status: "paused",
+          updatedAt: new Date(),
+        })
+        .where(inArray(routines.id, idsToPause));
+    }
+
+    return {
+      companyId,
+      totalRoutines: existing.length,
+      pausedCount: idsToPause.length,
+      alreadyPausedCount,
+      archivedCount,
+    };
+  } finally {
+    if (db) {
+      await closeDb(db);
+    }
+    if (embeddedHandle?.startedByThisProcess) {
+      await embeddedHandle.stop().catch(() => undefined);
+    }
+  }
+}
+
+export async function disableAllRoutinesCommand(options: RoutinesDisableAllOptions): Promise<void> {
+  const result = await disableAllRoutinesInConfig(options);
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (result.totalRoutines === 0) {
+    console.log(pc.dim(`No routines found for company ${result.companyId}.`));
+    return;
+  }
+
+  console.log(
+    `Paused ${result.pausedCount} routine(s) for company ${result.companyId} ` +
+      `(${result.alreadyPausedCount} already paused, ${result.archivedCount} archived).`,
+  );
+}
+
+export function registerRoutineCommands(program: Command): void {
+  const routinesCommand = program.command("routines").description("Local routine maintenance commands");
+
+  routinesCommand
+    .command("disable-all")
+    .description("Pause all non-archived routines in the configured local instance for one company")
+    .option("-c, --config <path>", "Path to config file")
+    .option("-d, --data-dir <path>", "Paperclip data directory root (isolates state from ~/.paperclip)")
+    .option("-C, --company-id <id>", "Company ID")
+    .option("--json", "Output raw JSON")
+    .action(async (opts: RoutinesDisableAllOptions) => {
+      try {
+        await disableAllRoutinesCommand(opts);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(pc.red(message));
+        process.exit(1);
+      }
+    });
+}

cli/src/commands/run.ts

@@ -1,11 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
+import { bootstrapCeoInvite } from "./auth-bootstrap-ceo.js";
 import { onboard } from "./onboard.js";
 import { doctor } from "./doctor.js";
+import { loadPaperclipEnvFile } from "../config/env.js";
 import { configExists, resolveConfigPath } from "../config/store.js";
+import type { PaperclipConfig } from "../config/schema.js";
+import { readConfig } from "../config/store.js";
 import {
   describeLocalInstancePaths,
   resolvePaperclipHomeDir,
@@ -17,6 +22,14 @@ interface RunOptions {
   instance?: string;
   repair?: boolean;
   yes?: boolean;
+  bind?: "loopback" | "lan" | "tailnet";
+}
+
+interface StartedServer {
+  apiUrl: string;
+  databaseUrl: string;
+  host: string;
+  listenPort: number;
 }
 
 export async function runCommand(opts: RunOptions): Promise<void> {
@@ -31,6 +44,7 @@ export async function runCommand(opts: RunOptions): Promise<void> {
 
   const configPath = resolveConfigPath(opts.config);
   process.env.PAPERCLIP_CONFIG = configPath;
+  loadPaperclipEnvFile(configPath);
 
   p.intro(pc.bgCyan(pc.black(" paperclipai run ")));
   p.log.message(pc.dim(`Home: ${paths.homeDir}`));
@@ -45,7 +59,7 @@ export async function runCommand(opts: RunOptions): Promise<void> {
     }
 
     p.log.step("No config found. Starting onboarding...");
-    await onboard({ config: configPath, invokedByRun: true });
+    await onboard({ config: configPath, invokedByRun: true, bind: opts.bind });
   }
 
   p.log.step("Running doctor checks...");
@@ -60,8 +74,41 @@ export async function runCommand(opts: RunOptions): Promise<void> {
     process.exit(1);
   }
 
+  const config = readConfig(configPath);
+  if (!config) {
+    p.log.error(`No config found at ${configPath}.`);
+    process.exit(1);
+  }
+
   p.log.step("Starting Paperclip server...");
-  await importServerEntry();
+  const startedServer = await importServerEntry();
+
+  if (shouldGenerateBootstrapInviteAfterStart(config)) {
+    p.log.step("Generating bootstrap CEO invite");
+    await bootstrapCeoInvite({
+      config: configPath,
+      dbUrl: startedServer.databaseUrl,
+      baseUrl: resolveBootstrapInviteBaseUrl(config, startedServer),
+    });
+  }
+}
+
+function resolveBootstrapInviteBaseUrl(
+  config: PaperclipConfig,
+  startedServer: StartedServer,
+): string {
+  const explicitBaseUrl =
+    process.env.PAPERCLIP_PUBLIC_URL ??
+    process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL ??
+    process.env.BETTER_AUTH_URL ??
+    process.env.BETTER_AUTH_BASE_URL ??
+    (config.auth.baseUrlMode === "explicit" ? config.auth.publicBaseUrl : undefined);
+
+  if (typeof explicitBaseUrl === "string" && explicitBaseUrl.trim().length > 0) {
+    return explicitBaseUrl.trim().replace(/\/+$/, "");
+  }
+
+  return startedServer.apiUrl.replace(/\/api$/, "");
 }
 
 function formatError(err: unknown): string {
@@ -101,19 +148,44 @@ function maybeEnableUiDevMiddleware(entrypoint: string): void {
   }
 }
 
-async function importServerEntry(): Promise<void> {
+function ensureDevWorkspaceBuildDeps(projectRoot: string): void {
+  const buildScript = path.resolve(projectRoot, "scripts/ensure-plugin-build-deps.mjs");
+  if (!fs.existsSync(buildScript)) return;
+
+  const result = spawnSync(process.execPath, [buildScript], {
+    cwd: projectRoot,
+    stdio: "inherit",
+    timeout: 120_000,
+  });
+
+  if (result.error) {
+    throw new Error(
+      `Failed to prepare workspace build artifacts before starting the Paperclip dev server.\n${formatError(result.error)}`,
+    );
+  }
+
+  if ((result.status ?? 1) !== 0) {
+    throw new Error(
+      "Failed to prepare workspace build artifacts before starting the Paperclip dev server.",
+    );
+  }
+}
+
+async function importServerEntry(): Promise<StartedServer> {
   // Dev mode: try local workspace path (monorepo with tsx)
   const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
   const devEntry = path.resolve(projectRoot, "server/src/index.ts");
   if (fs.existsSync(devEntry)) {
+    ensureDevWorkspaceBuildDeps(projectRoot);
     maybeEnableUiDevMiddleware(devEntry);
-    await import(pathToFileURL(devEntry).href);
-    return;
+    const mod = await import(pathToFileURL(devEntry).href);
+    return await startServerFromModule(mod, devEntry);
   }
 
   // Production mode: import the published @paperclipai/server package
   try {
-    await import("@paperclipai/server");
+    const mod = await import("@paperclipai/server");
+    return await startServerFromModule(mod, "@paperclipai/server");
   } catch (err) {
     const missingSpecifier = getMissingModuleSpecifier(err);
     const missingServerEntrypoint = !missingSpecifier || missingSpecifier === "@paperclipai/server";
@@ -130,3 +202,15 @@ async function importServerEntry(): Promise<void> {
     );
   }
 }
+
+function shouldGenerateBootstrapInviteAfterStart(config: PaperclipConfig): boolean {
+  return config.server.deploymentMode === "authenticated" && config.database.mode === "embedded-postgres";
+}
+
+async function startServerFromModule(mod: unknown, label: string): Promise<StartedServer> {
+  const startServer = (mod as { startServer?: () => Promise<StartedServer> }).startServer;
+  if (typeof startServer !== "function") {
+    throw new Error(`Paperclip server entrypoint did not export startServer(): ${label}`);
+  }
+  return await startServer();
+}

cli/src/commands/worktree-lib.ts

@@ -0,0 +1,279 @@
+import { randomInt } from "node:crypto";
+import path from "node:path";
+import type { PaperclipConfig } from "../config/schema.js";
+import { expandHomePrefix } from "../config/home.js";
+
+export const DEFAULT_WORKTREE_HOME = "~/.paperclip-worktrees";
+export const WORKTREE_SEED_MODES = ["minimal", "full"] as const;
+
+export type WorktreeSeedMode = (typeof WORKTREE_SEED_MODES)[number];
+
+export type WorktreeSeedPlan = {
+  mode: WorktreeSeedMode;
+  excludedTables: string[];
+  nullifyColumns: Record<string, string[]>;
+};
+
+const MINIMAL_WORKTREE_EXCLUDED_TABLES = [
+  "activity_log",
+  "agent_runtime_state",
+  "agent_task_sessions",
+  "agent_wakeup_requests",
+  "cost_events",
+  "heartbeat_run_events",
+  "heartbeat_runs",
+  "workspace_runtime_services",
+];
+
+const MINIMAL_WORKTREE_NULLIFIED_COLUMNS: Record<string, string[]> = {
+  issues: ["checkout_run_id", "execution_run_id"],
+};
+
+export type WorktreeLocalPaths = {
+  cwd: string;
+  repoConfigDir: string;
+  configPath: string;
+  envPath: string;
+  homeDir: string;
+  instanceId: string;
+  instanceRoot: string;
+  contextPath: string;
+  embeddedPostgresDataDir: string;
+  backupDir: string;
+  logDir: string;
+  secretsKeyFilePath: string;
+  storageDir: string;
+};
+
+export type WorktreeUiBranding = {
+  name: string;
+  color: string;
+};
+
+export function isWorktreeSeedMode(value: string): value is WorktreeSeedMode {
+  return (WORKTREE_SEED_MODES as readonly string[]).includes(value);
+}
+
+export function resolveWorktreeSeedPlan(mode: WorktreeSeedMode): WorktreeSeedPlan {
+  if (mode === "full") {
+    return {
+      mode,
+      excludedTables: [],
+      nullifyColumns: {},
+    };
+  }
+  return {
+    mode,
+    excludedTables: [...MINIMAL_WORKTREE_EXCLUDED_TABLES],
+    nullifyColumns: {
+      ...MINIMAL_WORKTREE_NULLIFIED_COLUMNS,
+    },
+  };
+}
+
+function nonEmpty(value: string | null | undefined): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  const value = hostname.trim().toLowerCase();
+  return value === "127.0.0.1" || value === "localhost" || value === "::1";
+}
+
+export function sanitizeWorktreeInstanceId(rawValue: string): string {
+  const trimmed = rawValue.trim().toLowerCase();
+  const normalized = trimmed
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[-_]+|[-_]+$/g, "");
+  return normalized || "worktree";
+}
+
+export function resolveSuggestedWorktreeName(cwd: string, explicitName?: string): string {
+  return nonEmpty(explicitName) ?? path.basename(path.resolve(cwd));
+}
+
+function hslComponentToHex(n: number): string {
+  return Math.round(Math.max(0, Math.min(255, n)))
+    .toString(16)
+    .padStart(2, "0");
+}
+
+function hslToHex(hue: number, saturation: number, lightness: number): string {
+  const s = Math.max(0, Math.min(100, saturation)) / 100;
+  const l = Math.max(0, Math.min(100, lightness)) / 100;
+  const c = (1 - Math.abs((2 * l) - 1)) * s;
+  const h = ((hue % 360) + 360) % 360;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - (c / 2);
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+
+  if (h < 60) {
+    r = c;
+    g = x;
+  } else if (h < 120) {
+    r = x;
+    g = c;
+  } else if (h < 180) {
+    g = c;
+    b = x;
+  } else if (h < 240) {
+    g = x;
+    b = c;
+  } else if (h < 300) {
+    r = x;
+    b = c;
+  } else {
+    r = c;
+    b = x;
+  }
+
+  return `#${hslComponentToHex((r + m) * 255)}${hslComponentToHex((g + m) * 255)}${hslComponentToHex((b + m) * 255)}`;
+}
+
+export function generateWorktreeColor(): string {
+  return hslToHex(randomInt(0, 360), 68, 56);
+}
+
+export function resolveWorktreeLocalPaths(opts: {
+  cwd: string;
+  homeDir?: string;
+  instanceId: string;
+}): WorktreeLocalPaths {
+  const cwd = path.resolve(opts.cwd);
+  const homeDir = path.resolve(expandHomePrefix(opts.homeDir ?? DEFAULT_WORKTREE_HOME));
+  const instanceRoot = path.resolve(homeDir, "instances", opts.instanceId);
+  const repoConfigDir = path.resolve(cwd, ".paperclip");
+  return {
+    cwd,
+    repoConfigDir,
+    configPath: path.resolve(repoConfigDir, "config.json"),
+    envPath: path.resolve(repoConfigDir, ".env"),
+    homeDir,
+    instanceId: opts.instanceId,
+    instanceRoot,
+    contextPath: path.resolve(homeDir, "context.json"),
+    embeddedPostgresDataDir: path.resolve(instanceRoot, "db"),
+    backupDir: path.resolve(instanceRoot, "data", "backups"),
+    logDir: path.resolve(instanceRoot, "logs"),
+    secretsKeyFilePath: path.resolve(instanceRoot, "secrets", "master.key"),
+    storageDir: path.resolve(instanceRoot, "data", "storage"),
+  };
+}
+
+export function rewriteLocalUrlPort(rawUrl: string | undefined, port: number): string | undefined {
+  if (!rawUrl) return undefined;
+  try {
+    const parsed = new URL(rawUrl);
+    if (!isLoopbackHost(parsed.hostname)) return rawUrl;
+    parsed.port = String(port);
+    return parsed.toString();
+  } catch {
+    return rawUrl;
+  }
+}
+
+export function buildWorktreeConfig(input: {
+  sourceConfig: PaperclipConfig | null;
+  paths: WorktreeLocalPaths;
+  serverPort: number;
+  databasePort: number;
+  now?: Date;
+}): PaperclipConfig {
+  const { sourceConfig, paths, serverPort, databasePort } = input;
+  const nowIso = (input.now ?? new Date()).toISOString();
+
+  const source = sourceConfig;
+  const authPublicBaseUrl = rewriteLocalUrlPort(source?.auth.publicBaseUrl, serverPort);
+
+  return {
+    $meta: {
+      version: 1,
+      updatedAt: nowIso,
+      source: "configure",
+    },
+    ...(source?.llm ? { llm: source.llm } : {}),
+    database: {
+      mode: "embedded-postgres",
+      embeddedPostgresDataDir: paths.embeddedPostgresDataDir,
+      embeddedPostgresPort: databasePort,
+      backup: {
+        enabled: source?.database.backup.enabled ?? true,
+        intervalMinutes: source?.database.backup.intervalMinutes ?? 60,
+        retentionDays: source?.database.backup.retentionDays ?? 30,
+        dir: paths.backupDir,
+      },
+    },
+    logging: {
+      mode: source?.logging.mode ?? "file",
+      logDir: paths.logDir,
+    },
+    server: {
+      deploymentMode: source?.server.deploymentMode ?? "local_trusted",
+      exposure: source?.server.exposure ?? "private",
+      ...(source?.server.bind ? { bind: source.server.bind } : {}),
+      ...(source?.server.customBindHost ? { customBindHost: source.server.customBindHost } : {}),
+      host: source?.server.host ?? "127.0.0.1",
+      port: serverPort,
+      allowedHostnames: source?.server.allowedHostnames ?? [],
+      serveUi: source?.server.serveUi ?? true,
+    },
+    auth: {
+      baseUrlMode: source?.auth.baseUrlMode ?? "auto",
+      ...(authPublicBaseUrl ? { publicBaseUrl: authPublicBaseUrl } : {}),
+      disableSignUp: source?.auth.disableSignUp ?? false,
+    },
+    telemetry: {
+      enabled: source?.telemetry?.enabled ?? true,
+    },
+    storage: {
+      provider: source?.storage.provider ?? "local_disk",
+      localDisk: {
+        baseDir: paths.storageDir,
+      },
+      s3: {
+        bucket: source?.storage.s3.bucket ?? "paperclip",
+        region: source?.storage.s3.region ?? "us-east-1",
+        endpoint: source?.storage.s3.endpoint,
+        prefix: source?.storage.s3.prefix ?? "",
+        forcePathStyle: source?.storage.s3.forcePathStyle ?? false,
+      },
+    },
+    secrets: {
+      provider: source?.secrets.provider ?? "local_encrypted",
+      strictMode: source?.secrets.strictMode ?? false,
+      localEncrypted: {
+        keyFilePath: paths.secretsKeyFilePath,
+      },
+    },
+  };
+}
+
+export function buildWorktreeEnvEntries(
+  paths: WorktreeLocalPaths,
+  branding?: WorktreeUiBranding,
+): Record<string, string> {
+  return {
+    PAPERCLIP_HOME: paths.homeDir,
+    PAPERCLIP_INSTANCE_ID: paths.instanceId,
+    PAPERCLIP_CONFIG: paths.configPath,
+    PAPERCLIP_CONTEXT: paths.contextPath,
+    PAPERCLIP_IN_WORKTREE: "true",
+    ...(branding?.name ? { PAPERCLIP_WORKTREE_NAME: branding.name } : {}),
+    ...(branding?.color ? { PAPERCLIP_WORKTREE_COLOR: branding.color } : {}),
+  };
+}
+
+function shellEscape(value: string): string {
+  return `'${value.replaceAll("'", `'\"'\"'`)}'`;
+}
+
+export function formatShellExports(entries: Record<string, string>): string {
+  return Object.entries(entries)
+    .filter(([, value]) => typeof value === "string" && value.trim().length > 0)
+    .map(([key, value]) => `export ${key}=${shellEscape(value)}`)
+    .join("\n");
+}

cli/src/commands/worktree-merge-history-lib.ts

@@ -0,0 +1,764 @@
+import {
+  agents,
+  assets,
+  documentRevisions,
+  goals,
+  issueAttachments,
+  issueComments,
+  issueDocuments,
+  issues,
+  projects,
+  projectWorkspaces,
+} from "@paperclipai/db";
+
+type IssueRow = typeof issues.$inferSelect;
+type CommentRow = typeof issueComments.$inferSelect;
+type AgentRow = typeof agents.$inferSelect;
+type ProjectRow = typeof projects.$inferSelect;
+type ProjectWorkspaceRow = typeof projectWorkspaces.$inferSelect;
+type GoalRow = typeof goals.$inferSelect;
+type IssueDocumentLinkRow = typeof issueDocuments.$inferSelect;
+type DocumentRevisionTableRow = typeof documentRevisions.$inferSelect;
+type IssueAttachmentTableRow = typeof issueAttachments.$inferSelect;
+type AssetRow = typeof assets.$inferSelect;
+
+export const WORKTREE_MERGE_SCOPES = ["issues", "comments"] as const;
+export type WorktreeMergeScope = (typeof WORKTREE_MERGE_SCOPES)[number];
+
+export type ImportAdjustment =
+  | "clear_assignee_agent"
+  | "clear_project"
+  | "clear_project_workspace"
+  | "clear_goal"
+  | "clear_author_agent"
+  | "coerce_in_progress_to_todo"
+  | "clear_document_agent"
+  | "clear_document_revision_agent"
+  | "clear_attachment_agent";
+
+export type IssueMergeAction = "skip_existing" | "insert";
+export type CommentMergeAction = "skip_existing" | "skip_missing_parent" | "insert";
+
+export type PlannedIssueInsert = {
+  source: IssueRow;
+  action: "insert";
+  previewIssueNumber: number;
+  previewIdentifier: string;
+  targetStatus: string;
+  targetAssigneeAgentId: string | null;
+  targetCreatedByAgentId: string | null;
+  targetProjectId: string | null;
+  targetProjectWorkspaceId: string | null;
+  targetGoalId: string | null;
+  projectResolution: "preserved" | "cleared" | "mapped" | "imported";
+  mappedProjectName: string | null;
+  adjustments: ImportAdjustment[];
+};
+
+export type PlannedIssueSkip = {
+  source: IssueRow;
+  action: "skip_existing";
+  driftKeys: string[];
+};
+
+export type PlannedCommentInsert = {
+  source: CommentRow;
+  action: "insert";
+  targetAuthorAgentId: string | null;
+  adjustments: ImportAdjustment[];
+};
+
+export type PlannedCommentSkip = {
+  source: CommentRow;
+  action: "skip_existing" | "skip_missing_parent";
+};
+
+export type IssueDocumentRow = {
+  id: IssueDocumentLinkRow["id"];
+  companyId: IssueDocumentLinkRow["companyId"];
+  issueId: IssueDocumentLinkRow["issueId"];
+  documentId: IssueDocumentLinkRow["documentId"];
+  key: IssueDocumentLinkRow["key"];
+  linkCreatedAt: IssueDocumentLinkRow["createdAt"];
+  linkUpdatedAt: IssueDocumentLinkRow["updatedAt"];
+  title: string | null;
+  format: string;
+  latestBody: string;
+  latestRevisionId: string | null;
+  latestRevisionNumber: number;
+  createdByAgentId: string | null;
+  createdByUserId: string | null;
+  updatedByAgentId: string | null;
+  updatedByUserId: string | null;
+  documentCreatedAt: Date;
+  documentUpdatedAt: Date;
+};
+
+export type DocumentRevisionRow = {
+  id: DocumentRevisionTableRow["id"];
+  companyId: DocumentRevisionTableRow["companyId"];
+  documentId: DocumentRevisionTableRow["documentId"];
+  revisionNumber: DocumentRevisionTableRow["revisionNumber"];
+  body: DocumentRevisionTableRow["body"];
+  changeSummary: DocumentRevisionTableRow["changeSummary"];
+  createdByAgentId: string | null;
+  createdByUserId: string | null;
+  createdAt: Date;
+};
+
+export type IssueAttachmentRow = {
+  id: IssueAttachmentTableRow["id"];
+  companyId: IssueAttachmentTableRow["companyId"];
+  issueId: IssueAttachmentTableRow["issueId"];
+  issueCommentId: IssueAttachmentTableRow["issueCommentId"];
+  assetId: IssueAttachmentTableRow["assetId"];
+  provider: AssetRow["provider"];
+  objectKey: AssetRow["objectKey"];
+  contentType: AssetRow["contentType"];
+  byteSize: AssetRow["byteSize"];
+  sha256: AssetRow["sha256"];
+  originalFilename: AssetRow["originalFilename"];
+  createdByAgentId: string | null;
+  createdByUserId: string | null;
+  assetCreatedAt: Date;
+  assetUpdatedAt: Date;
+  attachmentCreatedAt: Date;
+  attachmentUpdatedAt: Date;
+};
+
+export type PlannedDocumentRevisionInsert = {
+  source: DocumentRevisionRow;
+  targetRevisionNumber: number;
+  targetCreatedByAgentId: string | null;
+  adjustments: ImportAdjustment[];
+};
+
+export type PlannedIssueDocumentInsert = {
+  source: IssueDocumentRow;
+  action: "insert";
+  targetCreatedByAgentId: string | null;
+  targetUpdatedByAgentId: string | null;
+  latestRevisionId: string | null;
+  latestRevisionNumber: number;
+  revisionsToInsert: PlannedDocumentRevisionInsert[];
+  adjustments: ImportAdjustment[];
+};
+
+export type PlannedIssueDocumentMerge = {
+  source: IssueDocumentRow;
+  action: "merge_existing";
+  targetCreatedByAgentId: string | null;
+  targetUpdatedByAgentId: string | null;
+  latestRevisionId: string | null;
+  latestRevisionNumber: number;
+  revisionsToInsert: PlannedDocumentRevisionInsert[];
+  adjustments: ImportAdjustment[];
+};
+
+export type PlannedIssueDocumentSkip = {
+  source: IssueDocumentRow;
+  action: "skip_existing" | "skip_missing_parent" | "skip_conflicting_key";
+};
+
+export type PlannedAttachmentInsert = {
+  source: IssueAttachmentRow;
+  action: "insert";
+  targetIssueCommentId: string | null;
+  targetCreatedByAgentId: string | null;
+  adjustments: ImportAdjustment[];
+};
+
+export type PlannedAttachmentSkip = {
+  source: IssueAttachmentRow;
+  action: "skip_existing" | "skip_missing_parent";
+};
+
+export type PlannedProjectImport = {
+  source: ProjectRow;
+  targetLeadAgentId: string | null;
+  targetGoalId: string | null;
+  workspaces: ProjectWorkspaceRow[];
+};
+
+export type WorktreeMergePlan = {
+  companyId: string;
+  companyName: string;
+  issuePrefix: string;
+  previewIssueCounterStart: number;
+  scopes: WorktreeMergeScope[];
+  projectImports: PlannedProjectImport[];
+  issuePlans: Array<PlannedIssueInsert | PlannedIssueSkip>;
+  commentPlans: Array<PlannedCommentInsert | PlannedCommentSkip>;
+  documentPlans: Array<PlannedIssueDocumentInsert | PlannedIssueDocumentMerge | PlannedIssueDocumentSkip>;
+  attachmentPlans: Array<PlannedAttachmentInsert | PlannedAttachmentSkip>;
+  counts: {
+    projectsToImport: number;
+    issuesToInsert: number;
+    issuesExisting: number;
+    issueDrift: number;
+    commentsToInsert: number;
+    commentsExisting: number;
+    commentsMissingParent: number;
+    documentsToInsert: number;
+    documentsToMerge: number;
+    documentsExisting: number;
+    documentsConflictingKey: number;
+    documentsMissingParent: number;
+    documentRevisionsToInsert: number;
+    attachmentsToInsert: number;
+    attachmentsExisting: number;
+    attachmentsMissingParent: number;
+  };
+  adjustments: Record<ImportAdjustment, number>;
+};
+
+function compareIssueCoreFields(source: IssueRow, target: IssueRow): string[] {
+  const driftKeys: string[] = [];
+  if (source.title !== target.title) driftKeys.push("title");
+  if ((source.description ?? null) !== (target.description ?? null)) driftKeys.push("description");
+  if (source.status !== target.status) driftKeys.push("status");
+  if (source.priority !== target.priority) driftKeys.push("priority");
+  if ((source.parentId ?? null) !== (target.parentId ?? null)) driftKeys.push("parentId");
+  if ((source.projectId ?? null) !== (target.projectId ?? null)) driftKeys.push("projectId");
+  if ((source.projectWorkspaceId ?? null) !== (target.projectWorkspaceId ?? null)) driftKeys.push("projectWorkspaceId");
+  if ((source.goalId ?? null) !== (target.goalId ?? null)) driftKeys.push("goalId");
+  if ((source.assigneeAgentId ?? null) !== (target.assigneeAgentId ?? null)) driftKeys.push("assigneeAgentId");
+  if ((source.assigneeUserId ?? null) !== (target.assigneeUserId ?? null)) driftKeys.push("assigneeUserId");
+  return driftKeys;
+}
+
+function incrementAdjustment(
+  counts: Record<ImportAdjustment, number>,
+  adjustment: ImportAdjustment,
+): void {
+  counts[adjustment] += 1;
+}
+
+function groupBy<T>(rows: T[], keyFor: (row: T) => string): Map<string, T[]> {
+  const out = new Map<string, T[]>();
+  for (const row of rows) {
+    const key = keyFor(row);
+    const existing = out.get(key);
+    if (existing) {
+      existing.push(row);
+    } else {
+      out.set(key, [row]);
+    }
+  }
+  return out;
+}
+
+function sameDate(left: Date, right: Date): boolean {
+  return left.getTime() === right.getTime();
+}
+
+function sortDocumentRows(rows: IssueDocumentRow[]): IssueDocumentRow[] {
+  return [...rows].sort((left, right) => {
+    const createdDelta = left.documentCreatedAt.getTime() - right.documentCreatedAt.getTime();
+    if (createdDelta !== 0) return createdDelta;
+    const linkDelta = left.linkCreatedAt.getTime() - right.linkCreatedAt.getTime();
+    if (linkDelta !== 0) return linkDelta;
+    return left.documentId.localeCompare(right.documentId);
+  });
+}
+
+function sortDocumentRevisions(rows: DocumentRevisionRow[]): DocumentRevisionRow[] {
+  return [...rows].sort((left, right) => {
+    const revisionDelta = left.revisionNumber - right.revisionNumber;
+    if (revisionDelta !== 0) return revisionDelta;
+    const createdDelta = left.createdAt.getTime() - right.createdAt.getTime();
+    if (createdDelta !== 0) return createdDelta;
+    return left.id.localeCompare(right.id);
+  });
+}
+
+function sortAttachments(rows: IssueAttachmentRow[]): IssueAttachmentRow[] {
+  return [...rows].sort((left, right) => {
+    const createdDelta = left.attachmentCreatedAt.getTime() - right.attachmentCreatedAt.getTime();
+    if (createdDelta !== 0) return createdDelta;
+    return left.id.localeCompare(right.id);
+  });
+}
+
+function sortIssuesForImport(sourceIssues: IssueRow[]): IssueRow[] {
+  const byId = new Map(sourceIssues.map((issue) => [issue.id, issue]));
+  const memoDepth = new Map<string, number>();
+
+  const depthFor = (issue: IssueRow, stack = new Set<string>()): number => {
+    const memoized = memoDepth.get(issue.id);
+    if (memoized !== undefined) return memoized;
+    if (!issue.parentId) {
+      memoDepth.set(issue.id, 0);
+      return 0;
+    }
+    if (stack.has(issue.id)) {
+      memoDepth.set(issue.id, 0);
+      return 0;
+    }
+    const parent = byId.get(issue.parentId);
+    if (!parent) {
+      memoDepth.set(issue.id, 0);
+      return 0;
+    }
+    stack.add(issue.id);
+    const depth = depthFor(parent, stack) + 1;
+    stack.delete(issue.id);
+    memoDepth.set(issue.id, depth);
+    return depth;
+  };
+
+  return [...sourceIssues].sort((left, right) => {
+    const depthDelta = depthFor(left) - depthFor(right);
+    if (depthDelta !== 0) return depthDelta;
+    const createdDelta = left.createdAt.getTime() - right.createdAt.getTime();
+    if (createdDelta !== 0) return createdDelta;
+    return left.id.localeCompare(right.id);
+  });
+}
+
+export function parseWorktreeMergeScopes(rawValue: string | undefined): WorktreeMergeScope[] {
+  if (!rawValue || rawValue.trim().length === 0) {
+    return ["issues", "comments"];
+  }
+
+  const parsed = rawValue
+    .split(",")
+    .map((value) => value.trim().toLowerCase())
+    .filter((value): value is WorktreeMergeScope =>
+      (WORKTREE_MERGE_SCOPES as readonly string[]).includes(value),
+    );
+
+  if (parsed.length === 0) {
+    throw new Error(
+      `Invalid scope "${rawValue}". Expected a comma-separated list of: ${WORKTREE_MERGE_SCOPES.join(", ")}.`,
+    );
+  }
+
+  return [...new Set(parsed)];
+}
+
+export function buildWorktreeMergePlan(input: {
+  companyId: string;
+  companyName: string;
+  issuePrefix: string;
+  previewIssueCounterStart: number;
+  scopes: WorktreeMergeScope[];
+  sourceIssues: IssueRow[];
+  targetIssues: IssueRow[];
+  sourceComments: CommentRow[];
+  targetComments: CommentRow[];
+  sourceProjects?: ProjectRow[];
+  sourceProjectWorkspaces?: ProjectWorkspaceRow[];
+  sourceDocuments?: IssueDocumentRow[];
+  targetDocuments?: IssueDocumentRow[];
+  sourceDocumentRevisions?: DocumentRevisionRow[];
+  targetDocumentRevisions?: DocumentRevisionRow[];
+  sourceAttachments?: IssueAttachmentRow[];
+  targetAttachments?: IssueAttachmentRow[];
+  targetAgents: AgentRow[];
+  targetProjects: ProjectRow[];
+  targetProjectWorkspaces: ProjectWorkspaceRow[];
+  targetGoals: GoalRow[];
+  importProjectIds?: Iterable<string>;
+  projectIdOverrides?: Record<string, string | null | undefined>;
+}): WorktreeMergePlan {
+  const targetIssuesById = new Map(input.targetIssues.map((issue) => [issue.id, issue]));
+  const targetCommentIds = new Set(input.targetComments.map((comment) => comment.id));
+  const targetAgentIds = new Set(input.targetAgents.map((agent) => agent.id));
+  const targetProjectIds = new Set(input.targetProjects.map((project) => project.id));
+  const targetProjectsById = new Map(input.targetProjects.map((project) => [project.id, project]));
+  const targetProjectWorkspaceIds = new Set(input.targetProjectWorkspaces.map((workspace) => workspace.id));
+  const targetGoalIds = new Set(input.targetGoals.map((goal) => goal.id));
+  const sourceProjectsById = new Map((input.sourceProjects ?? []).map((project) => [project.id, project]));
+  const sourceProjectWorkspaces = input.sourceProjectWorkspaces ?? [];
+  const sourceProjectWorkspacesByProjectId = groupBy(sourceProjectWorkspaces, (workspace) => workspace.projectId);
+  const importProjectIds = new Set(input.importProjectIds ?? []);
+  const scopes = new Set(input.scopes);
+
+  const adjustmentCounts: Record<ImportAdjustment, number> = {
+    clear_assignee_agent: 0,
+    clear_project: 0,
+    clear_project_workspace: 0,
+    clear_goal: 0,
+    clear_author_agent: 0,
+    coerce_in_progress_to_todo: 0,
+    clear_document_agent: 0,
+    clear_document_revision_agent: 0,
+    clear_attachment_agent: 0,
+  };
+
+  const projectImports: PlannedProjectImport[] = [];
+  for (const projectId of importProjectIds) {
+    if (targetProjectIds.has(projectId)) continue;
+    const sourceProject = sourceProjectsById.get(projectId);
+    if (!sourceProject) continue;
+    projectImports.push({
+      source: sourceProject,
+      targetLeadAgentId:
+        sourceProject.leadAgentId && targetAgentIds.has(sourceProject.leadAgentId)
+          ? sourceProject.leadAgentId
+          : null,
+      targetGoalId:
+        sourceProject.goalId && targetGoalIds.has(sourceProject.goalId)
+          ? sourceProject.goalId
+          : null,
+      workspaces: [...(sourceProjectWorkspacesByProjectId.get(projectId) ?? [])].sort((left, right) => {
+        const primaryDelta = Number(right.isPrimary) - Number(left.isPrimary);
+        if (primaryDelta !== 0) return primaryDelta;
+        const createdDelta = left.createdAt.getTime() - right.createdAt.getTime();
+        if (createdDelta !== 0) return createdDelta;
+        return left.id.localeCompare(right.id);
+      }),
+    });
+  }
+  const importedProjectWorkspaceIds = new Set(
+    projectImports.flatMap((project) => project.workspaces.map((workspace) => workspace.id)),
+  );
+
+  const issuePlans: Array<PlannedIssueInsert | PlannedIssueSkip> = [];
+  let nextPreviewIssueNumber = input.previewIssueCounterStart;
+  for (const issue of sortIssuesForImport(input.sourceIssues)) {
+    const existing = targetIssuesById.get(issue.id);
+    if (existing) {
+      issuePlans.push({
+        source: issue,
+        action: "skip_existing",
+        driftKeys: compareIssueCoreFields(issue, existing),
+      });
+      continue;
+    }
+
+    nextPreviewIssueNumber += 1;
+    const adjustments: ImportAdjustment[] = [];
+    const targetAssigneeAgentId =
+      issue.assigneeAgentId && targetAgentIds.has(issue.assigneeAgentId) ? issue.assigneeAgentId : null;
+    if (issue.assigneeAgentId && !targetAssigneeAgentId) {
+      adjustments.push("clear_assignee_agent");
+      incrementAdjustment(adjustmentCounts, "clear_assignee_agent");
+    }
+
+    const targetCreatedByAgentId =
+      issue.createdByAgentId && targetAgentIds.has(issue.createdByAgentId) ? issue.createdByAgentId : null;
+
+    let targetProjectId =
+      issue.projectId && targetProjectIds.has(issue.projectId) ? issue.projectId : null;
+    let projectResolution: PlannedIssueInsert["projectResolution"] = targetProjectId ? "preserved" : "cleared";
+    let mappedProjectName: string | null = null;
+    const overrideProjectId =
+      issue.projectId && input.projectIdOverrides
+        ? input.projectIdOverrides[issue.projectId] ?? null
+        : null;
+    if (!targetProjectId && overrideProjectId && targetProjectIds.has(overrideProjectId)) {
+      targetProjectId = overrideProjectId;
+      projectResolution = "mapped";
+      mappedProjectName = targetProjectsById.get(overrideProjectId)?.name ?? null;
+    }
+    if (!targetProjectId && issue.projectId && importProjectIds.has(issue.projectId)) {
+      const sourceProject = sourceProjectsById.get(issue.projectId);
+      if (sourceProject) {
+        targetProjectId = sourceProject.id;
+        projectResolution = "imported";
+        mappedProjectName = sourceProject.name;
+      }
+    }
+    if (issue.projectId && !targetProjectId) {
+      adjustments.push("clear_project");
+      incrementAdjustment(adjustmentCounts, "clear_project");
+    }
+
+    const targetProjectWorkspaceId =
+      targetProjectId
+      && targetProjectId === issue.projectId
+      && issue.projectWorkspaceId
+      && (targetProjectWorkspaceIds.has(issue.projectWorkspaceId)
+        || importedProjectWorkspaceIds.has(issue.projectWorkspaceId))
+        ? issue.projectWorkspaceId
+        : null;
+    if (issue.projectWorkspaceId && !targetProjectWorkspaceId) {
+      adjustments.push("clear_project_workspace");
+      incrementAdjustment(adjustmentCounts, "clear_project_workspace");
+    }
+
+    const targetGoalId =
+      issue.goalId && targetGoalIds.has(issue.goalId) ? issue.goalId : null;
+    if (issue.goalId && !targetGoalId) {
+      adjustments.push("clear_goal");
+      incrementAdjustment(adjustmentCounts, "clear_goal");
+    }
+
+    let targetStatus = issue.status;
+    if (
+      targetStatus === "in_progress"
+      && !targetAssigneeAgentId
+      && !(issue.assigneeUserId && issue.assigneeUserId.trim().length > 0)
+    ) {
+      targetStatus = "todo";
+      adjustments.push("coerce_in_progress_to_todo");
+      incrementAdjustment(adjustmentCounts, "coerce_in_progress_to_todo");
+    }
+
+    issuePlans.push({
+      source: issue,
+      action: "insert",
+      previewIssueNumber: nextPreviewIssueNumber,
+      previewIdentifier: `${input.issuePrefix}-${nextPreviewIssueNumber}`,
+      targetStatus,
+      targetAssigneeAgentId,
+      targetCreatedByAgentId,
+      targetProjectId,
+      targetProjectWorkspaceId,
+      targetGoalId,
+      projectResolution,
+      mappedProjectName,
+      adjustments,
+    });
+  }
+
+  const issueIdsAvailableAfterImport = new Set<string>([
+    ...input.targetIssues.map((issue) => issue.id),
+    ...issuePlans.filter((plan): plan is PlannedIssueInsert => plan.action === "insert").map((plan) => plan.source.id),
+  ]);
+
+  const commentPlans: Array<PlannedCommentInsert | PlannedCommentSkip> = [];
+  if (scopes.has("comments")) {
+    const sortedComments = [...input.sourceComments].sort((left, right) => {
+      const createdDelta = left.createdAt.getTime() - right.createdAt.getTime();
+      if (createdDelta !== 0) return createdDelta;
+      return left.id.localeCompare(right.id);
+    });
+
+    for (const comment of sortedComments) {
+      if (targetCommentIds.has(comment.id)) {
+        commentPlans.push({ source: comment, action: "skip_existing" });
+        continue;
+      }
+      if (!issueIdsAvailableAfterImport.has(comment.issueId)) {
+        commentPlans.push({ source: comment, action: "skip_missing_parent" });
+        continue;
+      }
+
+      const adjustments: ImportAdjustment[] = [];
+      const targetAuthorAgentId =
+        comment.authorAgentId && targetAgentIds.has(comment.authorAgentId) ? comment.authorAgentId : null;
+      if (comment.authorAgentId && !targetAuthorAgentId) {
+        adjustments.push("clear_author_agent");
+        incrementAdjustment(adjustmentCounts, "clear_author_agent");
+      }
+
+      commentPlans.push({
+        source: comment,
+        action: "insert",
+        targetAuthorAgentId,
+        adjustments,
+      });
+    }
+  }
+
+  const sourceDocuments = input.sourceDocuments ?? [];
+  const targetDocuments = input.targetDocuments ?? [];
+  const sourceDocumentRevisions = input.sourceDocumentRevisions ?? [];
+  const targetDocumentRevisions = input.targetDocumentRevisions ?? [];
+
+  const targetDocumentsById = new Map(targetDocuments.map((document) => [document.documentId, document]));
+  const targetDocumentsByIssueKey = new Map(targetDocuments.map((document) => [`${document.issueId}:${document.key}`, document]));
+  const sourceRevisionsByDocumentId = groupBy(sourceDocumentRevisions, (revision) => revision.documentId);
+  const targetRevisionsByDocumentId = groupBy(targetDocumentRevisions, (revision) => revision.documentId);
+  const commentIdsAvailableAfterImport = new Set<string>([
+    ...input.targetComments.map((comment) => comment.id),
+    ...commentPlans.filter((plan): plan is PlannedCommentInsert => plan.action === "insert").map((plan) => plan.source.id),
+  ]);
+
+  const documentPlans: Array<PlannedIssueDocumentInsert | PlannedIssueDocumentMerge | PlannedIssueDocumentSkip> = [];
+  for (const document of sortDocumentRows(sourceDocuments)) {
+    if (!issueIdsAvailableAfterImport.has(document.issueId)) {
+      documentPlans.push({ source: document, action: "skip_missing_parent" });
+      continue;
+    }
+
+    const existingDocument = targetDocumentsById.get(document.documentId);
+    const conflictingIssueKeyDocument = targetDocumentsByIssueKey.get(`${document.issueId}:${document.key}`);
+    if (!existingDocument && conflictingIssueKeyDocument && conflictingIssueKeyDocument.documentId !== document.documentId) {
+      documentPlans.push({ source: document, action: "skip_conflicting_key" });
+      continue;
+    }
+
+    const adjustments: ImportAdjustment[] = [];
+    const targetCreatedByAgentId =
+      document.createdByAgentId && targetAgentIds.has(document.createdByAgentId) ? document.createdByAgentId : null;
+    const targetUpdatedByAgentId =
+      document.updatedByAgentId && targetAgentIds.has(document.updatedByAgentId) ? document.updatedByAgentId : null;
+    if (
+      (document.createdByAgentId && !targetCreatedByAgentId)
+      || (document.updatedByAgentId && !targetUpdatedByAgentId)
+    ) {
+      adjustments.push("clear_document_agent");
+      incrementAdjustment(adjustmentCounts, "clear_document_agent");
+    }
+
+    const sourceRevisions = sortDocumentRevisions(sourceRevisionsByDocumentId.get(document.documentId) ?? []);
+    const targetRevisions = sortDocumentRevisions(targetRevisionsByDocumentId.get(document.documentId) ?? []);
+    const existingRevisionIds = new Set(targetRevisions.map((revision) => revision.id));
+    const usedRevisionNumbers = new Set(targetRevisions.map((revision) => revision.revisionNumber));
+    let nextRevisionNumber = targetRevisions.reduce(
+      (maxValue, revision) => Math.max(maxValue, revision.revisionNumber),
+      0,
+    ) + 1;
+
+    const targetRevisionNumberById = new Map<string, number>(
+      targetRevisions.map((revision) => [revision.id, revision.revisionNumber]),
+    );
+    const revisionsToInsert: PlannedDocumentRevisionInsert[] = [];
+
+    for (const revision of sourceRevisions) {
+      if (existingRevisionIds.has(revision.id)) continue;
+      let targetRevisionNumber = revision.revisionNumber;
+      if (usedRevisionNumbers.has(targetRevisionNumber)) {
+        while (usedRevisionNumbers.has(nextRevisionNumber)) {
+          nextRevisionNumber += 1;
+        }
+        targetRevisionNumber = nextRevisionNumber;
+        nextRevisionNumber += 1;
+      }
+      usedRevisionNumbers.add(targetRevisionNumber);
+      targetRevisionNumberById.set(revision.id, targetRevisionNumber);
+
+      const revisionAdjustments: ImportAdjustment[] = [];
+      const targetCreatedByAgentId =
+        revision.createdByAgentId && targetAgentIds.has(revision.createdByAgentId) ? revision.createdByAgentId : null;
+      if (revision.createdByAgentId && !targetCreatedByAgentId) {
+        revisionAdjustments.push("clear_document_revision_agent");
+        incrementAdjustment(adjustmentCounts, "clear_document_revision_agent");
+      }
+
+      revisionsToInsert.push({
+        source: revision,
+        targetRevisionNumber,
+        targetCreatedByAgentId,
+        adjustments: revisionAdjustments,
+      });
+    }
+
+    const latestRevisionId = document.latestRevisionId ?? existingDocument?.latestRevisionId ?? null;
+    const latestRevisionNumber =
+      (latestRevisionId ? targetRevisionNumberById.get(latestRevisionId) : undefined)
+      ?? document.latestRevisionNumber
+      ?? existingDocument?.latestRevisionNumber
+      ?? 0;
+
+    if (!existingDocument) {
+      documentPlans.push({
+        source: document,
+        action: "insert",
+        targetCreatedByAgentId,
+        targetUpdatedByAgentId,
+        latestRevisionId,
+        latestRevisionNumber,
+        revisionsToInsert,
+        adjustments,
+      });
+      continue;
+    }
+
+    const documentAlreadyMatches =
+      existingDocument.key === document.key
+      && existingDocument.title === document.title
+      && existingDocument.format === document.format
+      && existingDocument.latestBody === document.latestBody
+      && (existingDocument.latestRevisionId ?? null) === latestRevisionId
+      && existingDocument.latestRevisionNumber === latestRevisionNumber
+      && (existingDocument.updatedByAgentId ?? null) === targetUpdatedByAgentId
+      && (existingDocument.updatedByUserId ?? null) === (document.updatedByUserId ?? null)
+      && sameDate(existingDocument.documentUpdatedAt, document.documentUpdatedAt)
+      && sameDate(existingDocument.linkUpdatedAt, document.linkUpdatedAt)
+      && revisionsToInsert.length === 0;
+
+    if (documentAlreadyMatches) {
+      documentPlans.push({ source: document, action: "skip_existing" });
+      continue;
+    }
+
+    documentPlans.push({
+      source: document,
+      action: "merge_existing",
+      targetCreatedByAgentId,
+      targetUpdatedByAgentId,
+      latestRevisionId,
+      latestRevisionNumber,
+      revisionsToInsert,
+      adjustments,
+    });
+  }
+
+  const sourceAttachments = input.sourceAttachments ?? [];
+  const targetAttachmentIds = new Set((input.targetAttachments ?? []).map((attachment) => attachment.id));
+  const attachmentPlans: Array<PlannedAttachmentInsert | PlannedAttachmentSkip> = [];
+  for (const attachment of sortAttachments(sourceAttachments)) {
+    if (targetAttachmentIds.has(attachment.id)) {
+      attachmentPlans.push({ source: attachment, action: "skip_existing" });
+      continue;
+    }
+    if (!issueIdsAvailableAfterImport.has(attachment.issueId)) {
+      attachmentPlans.push({ source: attachment, action: "skip_missing_parent" });
+      continue;
+    }
+
+    const adjustments: ImportAdjustment[] = [];
+    const targetCreatedByAgentId =
+      attachment.createdByAgentId && targetAgentIds.has(attachment.createdByAgentId)
+        ? attachment.createdByAgentId
+        : null;
+    if (attachment.createdByAgentId && !targetCreatedByAgentId) {
+      adjustments.push("clear_attachment_agent");
+      incrementAdjustment(adjustmentCounts, "clear_attachment_agent");
+    }
+
+    attachmentPlans.push({
+      source: attachment,
+      action: "insert",
+      targetIssueCommentId:
+        attachment.issueCommentId && commentIdsAvailableAfterImport.has(attachment.issueCommentId)
+          ? attachment.issueCommentId
+          : null,
+      targetCreatedByAgentId,
+      adjustments,
+    });
+  }
+
+  const counts = {
+    projectsToImport: projectImports.length,
+    issuesToInsert: issuePlans.filter((plan) => plan.action === "insert").length,
+    issuesExisting: issuePlans.filter((plan) => plan.action === "skip_existing").length,
+    issueDrift: issuePlans.filter((plan) => plan.action === "skip_existing" && plan.driftKeys.length > 0).length,
+    commentsToInsert: commentPlans.filter((plan) => plan.action === "insert").length,
+    commentsExisting: commentPlans.filter((plan) => plan.action === "skip_existing").length,
+    commentsMissingParent: commentPlans.filter((plan) => plan.action === "skip_missing_parent").length,
+    documentsToInsert: documentPlans.filter((plan) => plan.action === "insert").length,
+    documentsToMerge: documentPlans.filter((plan) => plan.action === "merge_existing").length,
+    documentsExisting: documentPlans.filter((plan) => plan.action === "skip_existing").length,
+    documentsConflictingKey: documentPlans.filter((plan) => plan.action === "skip_conflicting_key").length,
+    documentsMissingParent: documentPlans.filter((plan) => plan.action === "skip_missing_parent").length,
+    documentRevisionsToInsert: documentPlans.reduce(
+      (sum, plan) =>
+        sum + (plan.action === "insert" || plan.action === "merge_existing" ? plan.revisionsToInsert.length : 0),
+      0,
+    ),
+    attachmentsToInsert: attachmentPlans.filter((plan) => plan.action === "insert").length,
+    attachmentsExisting: attachmentPlans.filter((plan) => plan.action === "skip_existing").length,
+    attachmentsMissingParent: attachmentPlans.filter((plan) => plan.action === "skip_missing_parent").length,
+  };
+
+  return {
+    companyId: input.companyId,
+    companyName: input.companyName,
+    issuePrefix: input.issuePrefix,
+    previewIssueCounterStart: input.previewIssueCounterStart,
+    scopes: input.scopes,
+    projectImports,
+    issuePlans,
+    commentPlans,
+    documentPlans,
+    attachmentPlans,
+    counts,
+    adjustments: adjustmentCounts,
+  };
+}

cli/src/config/env.ts

@@ -22,20 +22,35 @@ function parseEnvFile(contents: string) {
   }
 }
 
+function formatEnvValue(value: string): string {
+  if (/^[A-Za-z0-9_./:@-]+$/.test(value)) {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+
 function renderEnvFile(entries: Record<string, string>) {
   const lines = [
     "# Paperclip environment variables",
-    "# Generated by `paperclipai onboard`",
-    ...Object.entries(entries).map(([key, value]) => `${key}=${value}`),
+    "# Generated by Paperclip CLI commands",
+    ...Object.entries(entries).map(([key, value]) => `${key}=${formatEnvValue(value)}`),
     "",
   ];
   return lines.join("\n");
 }
 
+export function resolvePaperclipEnvFile(configPath?: string): string {
+  return resolveEnvFilePath(configPath);
+}
+
 export function resolveAgentJwtEnvFile(configPath?: string): string {
   return resolveEnvFilePath(configPath);
 }
 
+export function loadPaperclipEnvFile(configPath?: string): void {
+  loadAgentJwtEnvFile(resolveEnvFilePath(configPath));
+}
+
 export function loadAgentJwtEnvFile(filePath = resolveEnvFilePath()): void {
   if (loadedEnvFiles.has(filePath)) return;
 
@@ -78,13 +93,33 @@ export function ensureAgentJwtSecret(configPath?: string): { secret: string; cre
 }
 
 export function writeAgentJwtEnv(secret: string, filePath = resolveEnvFilePath()): void {
+  mergePaperclipEnvEntries({ [JWT_SECRET_ENV_KEY]: secret }, filePath);
+}
+
+export function readPaperclipEnvEntries(filePath = resolveEnvFilePath()): Record<string, string> {
+  if (!fs.existsSync(filePath)) return {};
+  return parseEnvFile(fs.readFileSync(filePath, "utf-8"));
+}
+
+export function writePaperclipEnvEntries(entries: Record<string, string>, filePath = resolveEnvFilePath()): void {
   const dir = path.dirname(filePath);
   fs.mkdirSync(dir, { recursive: true });
-
-  const current = fs.existsSync(filePath) ? parseEnvFile(fs.readFileSync(filePath, "utf-8")) : {};
-  current[JWT_SECRET_ENV_KEY] = secret;
-
-  fs.writeFileSync(filePath, renderEnvFile(current), {
+  fs.writeFileSync(filePath, renderEnvFile(entries), {
     mode: 0o600,
   });
 }
+
+export function mergePaperclipEnvEntries(
+  entries: Record<string, string>,
+  filePath = resolveEnvFilePath(),
+): Record<string, string> {
+  const current = readPaperclipEnvEntries(filePath);
+  const next = {
+    ...current,
+    ...Object.fromEntries(
+      Object.entries(entries).filter(([, value]) => typeof value === "string" && value.trim().length > 0),
+    ),
+  };
+  writePaperclipEnvEntries(next, filePath);
+  return next;
+}

cli/src/config/home.ts

@@ -33,6 +33,10 @@ export function resolveDefaultContextPath(): string {
   return path.resolve(resolvePaperclipHomeDir(), "context.json");
 }
 
+export function resolveDefaultCliAuthPath(): string {
+  return path.resolve(resolvePaperclipHomeDir(), "auth.json");
+}
+
 export function resolveDefaultEmbeddedPostgresDir(instanceId?: string): string {
   return path.resolve(resolvePaperclipInstanceRoot(instanceId), "db");
 }
@@ -49,6 +53,10 @@ export function resolveDefaultStorageDir(instanceId?: string): string {
   return path.resolve(resolvePaperclipInstanceRoot(instanceId), "data", "storage");
 }
 
+export function resolveDefaultBackupDir(instanceId?: string): string {
+  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "data", "backups");
+}
+
 export function expandHomePrefix(value: string): string {
   if (value === "~") return os.homedir();
   if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
@@ -64,6 +72,7 @@ export function describeLocalInstancePaths(instanceId?: string) {
     instanceRoot,
     configPath: resolveDefaultConfigPath(resolvedInstanceId),
     embeddedPostgresDataDir: resolveDefaultEmbeddedPostgresDir(resolvedInstanceId),
+    backupDir: resolveDefaultBackupDir(resolvedInstanceId),
     logDir: resolveDefaultLogsDir(resolvedInstanceId),
     secretsKeyFilePath: resolveDefaultSecretsKeyFilePath(resolvedInstanceId),
     storageDir: resolveDefaultStorageDir(resolvedInstanceId),

cli/src/config/schema.ts

@@ -2,10 +2,12 @@ export {
   paperclipConfigSchema,
   configMetaSchema,
   llmConfigSchema,
+  databaseBackupConfigSchema,
   databaseConfigSchema,
   loggingConfigSchema,
   serverConfigSchema,
   authConfigSchema,
+  telemetryConfigSchema,
   storageConfigSchema,
   storageLocalDiskConfigSchema,
   storageS3ConfigSchema,
@@ -13,14 +15,16 @@ export {
   secretsLocalEncryptedConfigSchema,
   type PaperclipConfig,
   type LlmConfig,
+  type DatabaseBackupConfig,
   type DatabaseConfig,
   type LoggingConfig,
   type ServerConfig,
   type AuthConfig,
+  type TelemetryConfig,
   type StorageConfig,
   type StorageLocalDiskConfig,
   type StorageS3Config,
   type SecretsConfig,
   type SecretsLocalEncryptedConfig,
   type ConfigMeta,
-} from "@paperclipai/shared";
+} from "../../../packages/shared/src/config-schema.js";

cli/src/config/server-bind.ts

@@ -0,0 +1,183 @@
+import { execFileSync } from "node:child_process";
+import {
+  ALL_INTERFACES_BIND_HOST,
+  LOOPBACK_BIND_HOST,
+  inferBindModeFromHost,
+  isAllInterfacesHost,
+  isLoopbackHost,
+  type BindMode,
+  type DeploymentExposure,
+  type DeploymentMode,
+} from "@paperclipai/shared";
+import type { AuthConfig, ServerConfig } from "./schema.js";
+
+const TAILSCALE_DETECT_TIMEOUT_MS = 3000;
+
+type BaseServerInput = {
+  port: number;
+  allowedHostnames: string[];
+  serveUi: boolean;
+};
+
+export function inferConfiguredBind(server?: Partial<ServerConfig>): BindMode {
+  if (server?.bind) return server.bind;
+  return inferBindModeFromHost(server?.customBindHost ?? server?.host);
+}
+
+export function detectTailnetBindHost(): string | undefined {
+  const explicit = process.env.PAPERCLIP_TAILNET_BIND_HOST?.trim();
+  if (explicit) return explicit;
+
+  try {
+    const stdout = execFileSync("tailscale", ["ip", "-4"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: TAILSCALE_DETECT_TIMEOUT_MS,
+    });
+    return stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find(Boolean);
+  } catch {
+    return undefined;
+  }
+}
+
+export function buildPresetServerConfig(
+  bind: Exclude<BindMode, "custom">,
+  input: BaseServerInput,
+): { server: ServerConfig; auth: AuthConfig } {
+  const host =
+    bind === "loopback"
+      ? LOOPBACK_BIND_HOST
+      : bind === "tailnet"
+        ? (detectTailnetBindHost() ?? LOOPBACK_BIND_HOST)
+        : ALL_INTERFACES_BIND_HOST;
+
+  return {
+    server: {
+      deploymentMode: bind === "loopback" ? "local_trusted" : "authenticated",
+      exposure: "private",
+      bind,
+      customBindHost: undefined,
+      host,
+      port: input.port,
+      allowedHostnames: input.allowedHostnames,
+      serveUi: input.serveUi,
+    },
+    auth: {
+      baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+  };
+}
+
+export function buildCustomServerConfig(input: BaseServerInput & {
+  deploymentMode: DeploymentMode;
+  exposure: DeploymentExposure;
+  host: string;
+  publicBaseUrl?: string;
+}): { server: ServerConfig; auth: AuthConfig } {
+  const normalizedHost = input.host.trim();
+  const bind = isLoopbackHost(normalizedHost)
+    ? "loopback"
+    : isAllInterfacesHost(normalizedHost)
+      ? "lan"
+      : "custom";
+
+  return {
+    server: {
+      deploymentMode: input.deploymentMode,
+      exposure: input.deploymentMode === "local_trusted" ? "private" : input.exposure,
+      bind,
+      customBindHost: bind === "custom" ? normalizedHost : undefined,
+      host: normalizedHost,
+      port: input.port,
+      allowedHostnames: input.allowedHostnames,
+      serveUi: input.serveUi,
+    },
+    auth:
+      input.deploymentMode === "authenticated" && input.exposure === "public"
+        ? {
+          baseUrlMode: "explicit",
+          disableSignUp: false,
+          publicBaseUrl: input.publicBaseUrl,
+        }
+        : {
+          baseUrlMode: "auto",
+          disableSignUp: false,
+        },
+  };
+}
+
+export function resolveQuickstartServerConfig(input: {
+  bind?: BindMode | null;
+  deploymentMode?: DeploymentMode | null;
+  exposure?: DeploymentExposure | null;
+  host?: string | null;
+  port: number;
+  allowedHostnames: string[];
+  serveUi: boolean;
+  publicBaseUrl?: string;
+}): { server: ServerConfig; auth: AuthConfig } {
+  const trimmedHost = input.host?.trim();
+  const explicitBind = input.bind ?? null;
+
+  if (explicitBind === "loopback" || explicitBind === "lan" || explicitBind === "tailnet") {
+    return buildPresetServerConfig(explicitBind, {
+      port: input.port,
+      allowedHostnames: input.allowedHostnames,
+      serveUi: input.serveUi,
+    });
+  }
+
+  if (explicitBind === "custom") {
+    return buildCustomServerConfig({
+      deploymentMode: input.deploymentMode ?? "authenticated",
+      exposure: input.exposure ?? "private",
+      host: trimmedHost || LOOPBACK_BIND_HOST,
+      port: input.port,
+      allowedHostnames: input.allowedHostnames,
+      serveUi: input.serveUi,
+      publicBaseUrl: input.publicBaseUrl,
+    });
+  }
+
+  if (trimmedHost) {
+    return buildCustomServerConfig({
+      deploymentMode: input.deploymentMode ?? (isLoopbackHost(trimmedHost) ? "local_trusted" : "authenticated"),
+      exposure: input.exposure ?? "private",
+      host: trimmedHost,
+      port: input.port,
+      allowedHostnames: input.allowedHostnames,
+      serveUi: input.serveUi,
+      publicBaseUrl: input.publicBaseUrl,
+    });
+  }
+
+  if (input.deploymentMode === "authenticated") {
+    if (input.exposure === "public") {
+      return buildCustomServerConfig({
+        deploymentMode: "authenticated",
+        exposure: "public",
+        host: ALL_INTERFACES_BIND_HOST,
+        port: input.port,
+        allowedHostnames: input.allowedHostnames,
+        serveUi: input.serveUi,
+        publicBaseUrl: input.publicBaseUrl,
+      });
+    }
+
+    return buildPresetServerConfig("lan", {
+      port: input.port,
+      allowedHostnames: input.allowedHostnames,
+      serveUi: input.serveUi,
+    });
+  }
+
+  return buildPresetServerConfig("loopback", {
+    port: input.port,
+    allowedHostnames: input.allowedHostnames,
+    serveUi: input.serveUi,
+  });
+}

cli/src/index.ts

@@ -7,6 +7,7 @@ import { addAllowedHostname } from "./commands/allowed-hostname.js";
 import { heartbeatRun } from "./commands/heartbeat-run.js";
 import { runCommand } from "./commands/run.js";
 import { bootstrapCeoInvite } from "./commands/auth-bootstrap-ceo.js";
+import { dbBackupCommand } from "./commands/db-backup.js";
 import { registerContextCommands } from "./commands/client/context.js";
 import { registerCompanyCommands } from "./commands/client/company.js";
 import { registerIssueCommands } from "./commands/client/issue.js";
@@ -14,7 +15,15 @@ import { registerAgentCommands } from "./commands/client/agent.js";
 import { registerApprovalCommands } from "./commands/client/approval.js";
 import { registerActivityCommands } from "./commands/client/activity.js";
 import { registerDashboardCommands } from "./commands/client/dashboard.js";
+import { registerRoutineCommands } from "./commands/routines.js";
+import { registerFeedbackCommands } from "./commands/client/feedback.js";
 import { applyDataDirOverride, type DataDirOptionLike } from "./config/data-dir.js";
+import { loadPaperclipEnvFile } from "./config/env.js";
+import { initTelemetryFromConfigFile, flushTelemetry } from "./telemetry.js";
+import { registerWorktreeCommands } from "./commands/worktree.js";
+import { registerPluginCommands } from "./commands/client/plugin.js";
+import { registerClientAuthCommands } from "./commands/client/auth.js";
+import { cliVersion } from "./version.js";
 
 const program = new Command();
 const DATA_DIR_OPTION_HELP =
@@ -23,7 +32,7 @@ const DATA_DIR_OPTION_HELP =
 program
   .name("paperclipai")
   .description("Paperclip CLI — setup, diagnose, and configure your instance")
-  .version("0.2.6");
+  .version(cliVersion);
 
 program.hook("preAction", (_thisCommand, actionCommand) => {
   const options = actionCommand.optsWithGlobals() as DataDirOptionLike;
@@ -32,6 +41,8 @@ program.hook("preAction", (_thisCommand, actionCommand) => {
     hasConfigOption: optionNames.has("config"),
     hasContextOption: optionNames.has("context"),
   });
+  loadPaperclipEnvFile(options.config);
+  initTelemetryFromConfigFile(options.config);
 });
 
 program
@@ -39,7 +50,8 @@ program
   .description("Interactive first-run setup wizard")
   .option("-c, --config <path>", "Path to config file")
   .option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP)
-  .option("-y, --yes", "Accept defaults (quickstart + start immediately)", false)
+  .option("--bind <mode>", "Quickstart reachability preset (loopback, lan, tailnet)")
+  .option("-y, --yes", "Accept quickstart defaults (trusted local loopback unless --bind is set) and start immediately", false)
   .option("--run", "Start Paperclip immediately after saving config", false)
   .action(onboard);
 
@@ -70,6 +82,19 @@ program
   .option("-s, --section <section>", "Section to configure (llm, database, logging, server, storage, secrets)")
   .action(configure);
 
+program
+  .command("db:backup")
+  .description("Create a one-off database backup using current config")
+  .option("-c, --config <path>", "Path to config file")
+  .option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP)
+  .option("--dir <path>", "Backup output directory (overrides config)")
+  .option("--retention-days <days>", "Retention window used for pruning", (value) => Number(value))
+  .option("--filename-prefix <prefix>", "Backup filename prefix", "paperclip")
+  .option("--json", "Print backup metadata as JSON")
+  .action(async (opts) => {
+    await dbBackupCommand(opts);
+  });
+
 program
   .command("allowed-hostname")
   .description("Allow a hostname for authenticated/private mode access")
@@ -84,6 +109,7 @@ program
   .option("-c, --config <path>", "Path to config file")
   .option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP)
   .option("-i, --instance <id>", "Local instance id (default: default)")
+  .option("--bind <mode>", "On first run, use onboarding reachability preset (loopback, lan, tailnet)")
   .option("--repair", "Attempt automatic repairs during doctor", true)
   .option("--no-repair", "Disable automatic repairs during doctor")
   .action(runCommand);
@@ -118,6 +144,10 @@ registerAgentCommands(program);
 registerApprovalCommands(program);
 registerActivityCommands(program);
 registerDashboardCommands(program);
+registerRoutineCommands(program);
+registerFeedbackCommands(program);
+registerWorktreeCommands(program);
+registerPluginCommands(program);
 
 const auth = program.command("auth").description("Authentication and bootstrap utilities");
 
@@ -131,7 +161,22 @@ auth
   .option("--base-url <url>", "Public base URL used to print invite link")
   .action(bootstrapCeoInvite);
 
-program.parseAsync().catch((err) => {
-  console.error(err instanceof Error ? err.message : String(err));
-  process.exit(1);
-});
+registerClientAuthCommands(auth);
+
+async function main(): Promise<void> {
+  let failed = false;
+  try {
+    await program.parseAsync();
+  } catch (err) {
+    failed = true;
+    console.error(err instanceof Error ? err.message : String(err));
+  } finally {
+    await flushTelemetry();
+  }
+
+  if (failed) {
+    process.exit(1);
+  }
+}
+
+void main();

cli/src/prompts/database.ts

@@ -1,9 +1,26 @@
 import * as p from "@clack/prompts";
 import type { DatabaseConfig } from "../config/schema.js";
-import { resolveDefaultEmbeddedPostgresDir, resolvePaperclipInstanceId } from "../config/home.js";
+import {
+  resolveDefaultBackupDir,
+  resolveDefaultEmbeddedPostgresDir,
+  resolvePaperclipInstanceId,
+} from "../config/home.js";
 
-export async function promptDatabase(): Promise<DatabaseConfig> {
-  const defaultEmbeddedDir = resolveDefaultEmbeddedPostgresDir(resolvePaperclipInstanceId());
+export async function promptDatabase(current?: DatabaseConfig): Promise<DatabaseConfig> {
+  const instanceId = resolvePaperclipInstanceId();
+  const defaultEmbeddedDir = resolveDefaultEmbeddedPostgresDir(instanceId);
+  const defaultBackupDir = resolveDefaultBackupDir(instanceId);
+  const base: DatabaseConfig = current ?? {
+    mode: "embedded-postgres",
+    embeddedPostgresDataDir: defaultEmbeddedDir,
+    embeddedPostgresPort: 54329,
+    backup: {
+      enabled: true,
+      intervalMinutes: 60,
+      retentionDays: 30,
+      dir: defaultBackupDir,
+    },
+  };
 
   const mode = await p.select({
     message: "Database mode",
@@ -11,6 +28,7 @@ export async function promptDatabase(): Promise<DatabaseConfig> {
       { value: "embedded-postgres" as const, label: "Embedded PostgreSQL (managed locally)", hint: "recommended" },
       { value: "postgres" as const, label: "PostgreSQL (external server)" },
     ],
+    initialValue: base.mode,
   });
 
   if (p.isCancel(mode)) {
@@ -18,9 +36,14 @@ export async function promptDatabase(): Promise<DatabaseConfig> {
     process.exit(0);
   }
 
+  let connectionString: string | undefined = base.connectionString;
+  let embeddedPostgresDataDir = base.embeddedPostgresDataDir || defaultEmbeddedDir;
+  let embeddedPostgresPort = base.embeddedPostgresPort || 54329;
+
   if (mode === "postgres") {
-    const connectionString = await p.text({
+    const value = await p.text({
       message: "PostgreSQL connection string",
+      defaultValue: base.connectionString ?? "",
       placeholder: "postgres://user:pass@localhost:5432/paperclip",
       validate: (val) => {
         if (!val) return "Connection string is required for PostgreSQL mode";
@@ -28,48 +51,107 @@ export async function promptDatabase(): Promise<DatabaseConfig> {
       },
     });
 
-    if (p.isCancel(connectionString)) {
+    if (p.isCancel(value)) {
       p.cancel("Setup cancelled.");
       process.exit(0);
     }
 
-    return {
-      mode: "postgres",
-      connectionString,
-      embeddedPostgresDataDir: defaultEmbeddedDir,
-      embeddedPostgresPort: 54329,
-    };
+    connectionString = value;
+  } else {
+    const dataDir = await p.text({
+      message: "Embedded PostgreSQL data directory",
+      defaultValue: base.embeddedPostgresDataDir || defaultEmbeddedDir,
+      placeholder: defaultEmbeddedDir,
+    });
+
+    if (p.isCancel(dataDir)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+
+    embeddedPostgresDataDir = dataDir || defaultEmbeddedDir;
+
+    const portValue = await p.text({
+      message: "Embedded PostgreSQL port",
+      defaultValue: String(base.embeddedPostgresPort || 54329),
+      placeholder: "54329",
+      validate: (val) => {
+        const n = Number(val);
+        if (!Number.isInteger(n) || n < 1 || n > 65535) return "Port must be an integer between 1 and 65535";
+      },
+    });
+
+    if (p.isCancel(portValue)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+
+    embeddedPostgresPort = Number(portValue || "54329");
+    connectionString = undefined;
   }
 
-  const embeddedPostgresDataDir = await p.text({
-    message: "Embedded PostgreSQL data directory",
-    defaultValue: defaultEmbeddedDir,
-    placeholder: defaultEmbeddedDir,
+  const backupEnabled = await p.confirm({
+    message: "Enable automatic database backups?",
+    initialValue: base.backup.enabled,
   });
-
-  if (p.isCancel(embeddedPostgresDataDir)) {
+  if (p.isCancel(backupEnabled)) {
     p.cancel("Setup cancelled.");
     process.exit(0);
   }
 
-  const embeddedPostgresPort = await p.text({
-    message: "Embedded PostgreSQL port",
-    defaultValue: "54329",
-    placeholder: "54329",
+  const backupDirInput = await p.text({
+    message: "Backup directory",
+    defaultValue: base.backup.dir || defaultBackupDir,
+    placeholder: defaultBackupDir,
+    validate: (val) => (!val || val.trim().length === 0 ? "Backup directory is required" : undefined),
+  });
+  if (p.isCancel(backupDirInput)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
+
+  const backupIntervalInput = await p.text({
+    message: "Backup interval (minutes)",
+    defaultValue: String(base.backup.intervalMinutes || 60),
+    placeholder: "60",
     validate: (val) => {
       const n = Number(val);
-      if (!Number.isInteger(n) || n < 1 || n > 65535) return "Port must be an integer between 1 and 65535";
+      if (!Number.isInteger(n) || n < 1) return "Interval must be a positive integer";
+      if (n > 10080) return "Interval must be 10080 minutes (7 days) or less";
+      return undefined;
     },
   });
+  if (p.isCancel(backupIntervalInput)) {
+    p.cancel("Setup cancelled.");
+    process.exit(0);
+  }
 
-  if (p.isCancel(embeddedPostgresPort)) {
+  const backupRetentionInput = await p.text({
+    message: "Backup retention (days)",
+    defaultValue: String(base.backup.retentionDays || 30),
+    placeholder: "30",
+    validate: (val) => {
+      const n = Number(val);
+      if (!Number.isInteger(n) || n < 1) return "Retention must be a positive integer";
+      if (n > 3650) return "Retention must be 3650 days or less";
+      return undefined;
+    },
+  });
+  if (p.isCancel(backupRetentionInput)) {
     p.cancel("Setup cancelled.");
     process.exit(0);
   }
 
   return {
-    mode: "embedded-postgres",
-    embeddedPostgresDataDir: embeddedPostgresDataDir || defaultEmbeddedDir,
-    embeddedPostgresPort: Number(embeddedPostgresPort || "54329"),
+    mode,
+    connectionString,
+    embeddedPostgresDataDir,
+    embeddedPostgresPort,
+    backup: {
+      enabled: backupEnabled,
+      intervalMinutes: Number(backupIntervalInput || "60"),
+      retentionDays: Number(backupRetentionInput || "30"),
+      dir: backupDirInput || defaultBackupDir,
+    },
   };
 }

cli/src/prompts/server.ts

@@ -1,6 +1,16 @@
 import * as p from "@clack/prompts";
+import { isLoopbackHost, type BindMode } from "@paperclipai/shared";
 import type { AuthConfig, ServerConfig } from "../config/schema.js";
 import { parseHostnameCsv } from "../config/hostnames.js";
+import { buildCustomServerConfig, buildPresetServerConfig, inferConfiguredBind } from "../config/server-bind.js";
+
+const TAILNET_BIND_WARNING =
+  "No Tailscale address was detected during setup. The saved config will stay on loopback until Tailscale is available or PAPERCLIP_TAILNET_BIND_HOST is set.";
+
+function cancelled(): never {
+  p.cancel("Setup cancelled.");
+  process.exit(0);
+}
 
 export async function promptServer(opts?: {
   currentServer?: Partial<ServerConfig>;
@@ -8,69 +18,37 @@ export async function promptServer(opts?: {
 }): Promise<{ server: ServerConfig; auth: AuthConfig }> {
   const currentServer = opts?.currentServer;
   const currentAuth = opts?.currentAuth;
+  const currentBind = inferConfiguredBind(currentServer);
 
-  const deploymentModeSelection = await p.select({
-    message: "Deployment mode",
+  const bindSelection = await p.select({
+    message: "Reachability",
     options: [
       {
-        value: "local_trusted",
-        label: "Local trusted",
-        hint: "Easiest for local setup (no login, localhost-only)",
+        value: "loopback" as const,
+        label: "Trusted local",
+        hint: "Recommended for first run: localhost only, no login friction",
       },
       {
-        value: "authenticated",
-        label: "Authenticated",
-        hint: "Login required; use for private network or public hosting",
+        value: "lan" as const,
+        label: "Private network",
+        hint: "Broad private bind for LAN, VPN, or legacy --tailscale-auth style access",
+      },
+      {
+        value: "tailnet" as const,
+        label: "Tailnet",
+        hint: "Private authenticated access using the machine's detected Tailscale address",
+      },
+      {
+        value: "custom" as const,
+        label: "Custom",
+        hint: "Choose exact auth mode, exposure, and host manually",
       },
     ],
-    initialValue: currentServer?.deploymentMode ?? "local_trusted",
+    initialValue: currentBind,
   });
 
-  if (p.isCancel(deploymentModeSelection)) {
-    p.cancel("Setup cancelled.");
-    process.exit(0);
-  }
-  const deploymentMode = deploymentModeSelection as ServerConfig["deploymentMode"];
-
-  let exposure: ServerConfig["exposure"] = "private";
-  if (deploymentMode === "authenticated") {
-    const exposureSelection = await p.select({
-      message: "Exposure profile",
-      options: [
-        {
-          value: "private",
-          label: "Private network",
-          hint: "Private access (for example Tailscale), lower setup friction",
-        },
-        {
-          value: "public",
-          label: "Public internet",
-          hint: "Internet-facing deployment with stricter requirements",
-        },
-      ],
-      initialValue: currentServer?.exposure ?? "private",
-    });
-    if (p.isCancel(exposureSelection)) {
-      p.cancel("Setup cancelled.");
-      process.exit(0);
-    }
-    exposure = exposureSelection as ServerConfig["exposure"];
-  }
-
-  const hostDefault = deploymentMode === "local_trusted" ? "127.0.0.1" : "0.0.0.0";
-  const hostStr = await p.text({
-    message: "Bind host",
-    defaultValue: currentServer?.host ?? hostDefault,
-    placeholder: hostDefault,
-    validate: (val) => {
-      if (!val.trim()) return "Host is required";
-    },
-  });
-
-  if (p.isCancel(hostStr)) {
-    p.cancel("Setup cancelled.");
-    process.exit(0);
-  }
+  if (p.isCancel(bindSelection)) cancelled();
+  const bind = bindSelection as BindMode;
 
   const portStr = await p.text({
     message: "Server port",
@@ -84,15 +62,113 @@ export async function promptServer(opts?: {
     },
   });
 
-  if (p.isCancel(portStr)) {
-    p.cancel("Setup cancelled.");
-    process.exit(0);
+  if (p.isCancel(portStr)) cancelled();
+  const port = Number(portStr) || 3100;
+  const serveUi = currentServer?.serveUi ?? true;
+
+  if (bind === "loopback") {
+    return buildPresetServerConfig("loopback", {
+      port,
+      allowedHostnames: [],
+      serveUi,
+    });
   }
 
+  if (bind === "lan" || bind === "tailnet") {
+    const allowedHostnamesInput = await p.text({
+      message: "Allowed private hostnames (comma-separated, optional)",
+      defaultValue: (currentServer?.allowedHostnames ?? []).join(", "),
+      placeholder:
+        bind === "tailnet"
+          ? "your-machine.tailnet.ts.net"
+          : "dotta-macbook-pro, host.docker.internal",
+      validate: (val) => {
+        try {
+          parseHostnameCsv(val);
+          return;
+        } catch (err) {
+          return err instanceof Error ? err.message : "Invalid hostname list";
+        }
+      },
+    });
+
+    if (p.isCancel(allowedHostnamesInput)) cancelled();
+
+    const preset = buildPresetServerConfig(bind, {
+      port,
+      allowedHostnames: parseHostnameCsv(allowedHostnamesInput),
+      serveUi,
+    });
+    if (bind === "tailnet" && isLoopbackHost(preset.server.host)) {
+      p.log.warn(TAILNET_BIND_WARNING);
+    }
+    return preset;
+  }
+
+  const deploymentModeSelection = await p.select({
+    message: "Auth mode",
+    options: [
+      {
+        value: "local_trusted",
+        label: "Local trusted",
+        hint: "No login required; only safe with loopback-only or similarly trusted access",
+      },
+      {
+        value: "authenticated",
+        label: "Authenticated",
+        hint: "Login required; supports both private-network and public deployments",
+      },
+    ],
+    initialValue: currentServer?.deploymentMode ?? "authenticated",
+  });
+
+  if (p.isCancel(deploymentModeSelection)) cancelled();
+  const deploymentMode = deploymentModeSelection as ServerConfig["deploymentMode"];
+
+  let exposure: ServerConfig["exposure"] = "private";
+  if (deploymentMode === "authenticated") {
+    const exposureSelection = await p.select({
+      message: "Exposure profile",
+      options: [
+        {
+          value: "private",
+          label: "Private network",
+          hint: "Private access only, with automatic URL handling",
+        },
+        {
+          value: "public",
+          label: "Public internet",
+          hint: "Internet-facing deployment with explicit public URL requirements",
+        },
+      ],
+      initialValue: currentServer?.exposure ?? "private",
+    });
+    if (p.isCancel(exposureSelection)) cancelled();
+    exposure = exposureSelection as ServerConfig["exposure"];
+  }
+
+  const defaultHost =
+    currentServer?.customBindHost ??
+    currentServer?.host ??
+    (deploymentMode === "local_trusted" ? "127.0.0.1" : "0.0.0.0");
+  const host = await p.text({
+    message: "Bind host",
+    defaultValue: defaultHost,
+    placeholder: defaultHost,
+    validate: (val) => {
+      if (!val.trim()) return "Host is required";
+      if (deploymentMode === "local_trusted" && !isLoopbackHost(val.trim())) {
+        return "Local trusted mode requires a loopback host such as 127.0.0.1";
+      }
+    },
+  });
+
+  if (p.isCancel(host)) cancelled();
+
   let allowedHostnames: string[] = [];
   if (deploymentMode === "authenticated" && exposure === "private") {
     const allowedHostnamesInput = await p.text({
-      message: "Allowed hostnames (comma-separated, optional)",
+      message: "Allowed private hostnames (comma-separated, optional)",
       defaultValue: (currentServer?.allowedHostnames ?? []).join(", "),
       placeholder: "dotta-macbook-pro, your-host.tailnet.ts.net",
       validate: (val) => {
@@ -105,15 +181,11 @@ export async function promptServer(opts?: {
       },
     });
 
-    if (p.isCancel(allowedHostnamesInput)) {
-      p.cancel("Setup cancelled.");
-      process.exit(0);
-    }
+    if (p.isCancel(allowedHostnamesInput)) cancelled();
     allowedHostnames = parseHostnameCsv(allowedHostnamesInput);
   }
 
-  const port = Number(portStr) || 3100;
-  let auth: AuthConfig = { baseUrlMode: "auto" };
+  let publicBaseUrl: string | undefined;
   if (deploymentMode === "authenticated" && exposure === "public") {
     const urlInput = await p.text({
       message: "Public base URL",
@@ -133,24 +205,17 @@ export async function promptServer(opts?: {
         }
       },
     });
-    if (p.isCancel(urlInput)) {
-      p.cancel("Setup cancelled.");
-      process.exit(0);
-    }
-    auth = {
-      baseUrlMode: "explicit",
-      publicBaseUrl: urlInput.trim().replace(/\/+$/, ""),
-    };
-  } else if (currentAuth?.baseUrlMode === "explicit" && currentAuth.publicBaseUrl) {
-    auth = {
-      baseUrlMode: "explicit",
-      publicBaseUrl: currentAuth.publicBaseUrl,
-    };
+    if (p.isCancel(urlInput)) cancelled();
+    publicBaseUrl = urlInput.trim().replace(/\/+$/, "");
   }
 
-  return {
-    server: { deploymentMode, exposure, host: hostStr.trim(), port, allowedHostnames, serveUi: true },
-    auth,
-  };
+  return buildCustomServerConfig({
+    deploymentMode,
+    exposure,
+    host: host.trim(),
+    port,
+    allowedHostnames,
+    serveUi,
+    publicBaseUrl,
+  });
 }
-

cli/src/telemetry.ts

@@ -0,0 +1,49 @@
+import path from "node:path";
+import {
+  TelemetryClient,
+  resolveTelemetryConfig,
+  loadOrCreateState,
+  trackInstallStarted,
+  trackInstallCompleted,
+  trackCompanyImported,
+} from "../../packages/shared/src/telemetry/index.js";
+import { resolvePaperclipInstanceRoot } from "./config/home.js";
+import { readConfig } from "./config/store.js";
+import { cliVersion } from "./version.js";
+
+let client: TelemetryClient | null = null;
+
+export function initTelemetry(fileConfig?: { enabled?: boolean }): TelemetryClient | null {
+  if (client) return client;
+
+  const config = resolveTelemetryConfig(fileConfig);
+  if (!config.enabled) return null;
+
+  const stateDir = path.join(resolvePaperclipInstanceRoot(), "telemetry");
+  client = new TelemetryClient(config, () => loadOrCreateState(stateDir, cliVersion), cliVersion);
+  return client;
+}
+
+export function initTelemetryFromConfigFile(configPath?: string): TelemetryClient | null {
+  try {
+    return initTelemetry(readConfig(configPath)?.telemetry);
+  } catch {
+    return initTelemetry();
+  }
+}
+
+export function getTelemetryClient(): TelemetryClient | null {
+  return client;
+}
+
+export async function flushTelemetry(): Promise<void> {
+  if (client) {
+    await client.flush();
+  }
+}
+
+export {
+  trackInstallStarted,
+  trackInstallCompleted,
+  trackCompanyImported,
+};

cli/src/version.ts

@@ -0,0 +1,10 @@
+import { createRequire } from "node:module";
+
+type PackageJson = {
+  version?: string;
+};
+
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json") as PackageJson;
+
+export const cliVersion = pkg.version ?? "0.0.0";

cli/tsconfig.json

@@ -1,8 +1,8 @@
 {
-  "extends": "../tsconfig.json",
+  "extends": "../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src"
+    "rootDir": ".."
   },
-  "include": ["src"]
+  "include": ["src", "../packages/shared/src"]
 }

doc/AGENTCOMPANIES_SPEC_INVENTORY.md

@@ -0,0 +1,115 @@
+# Agent Companies Spec Inventory
+
+This document indexes every part of the Paperclip codebase that touches the [Agent Companies Specification](docs/companies/companies-spec.md) (`agentcompanies/v1-draft`).
+
+Use it when you need to:
+
+1. **Update the spec** — know which implementation code must change in lockstep.
+2. **Change code that involves the spec** — find all related files quickly.
+3. **Keep things aligned** — audit whether implementation matches the spec.
+
+---
+
+## 1. Specification & Design Documents
+
+| File | Role |
+|---|---|
+| `docs/companies/companies-spec.md` | **Normative spec** — defines the markdown-first package format (COMPANY.md, TEAM.md, AGENTS.md, PROJECT.md, TASK.md, SKILL.md), reserved files, frontmatter schemas, and vendor extension conventions (`.paperclip.yaml`). |
+| `doc/plans/2026-03-13-company-import-export-v2.md` | Implementation plan for the markdown-first package model cutover — phases, API changes, UI plan, and rollout strategy. |
+| `doc/SPEC-implementation.md` | V1 implementation contract; references the portability system and `.paperclip.yaml` sidecar format. |
+| `docs/specs/cliphub-plan.md` | Earlier blueprint bundle plan; partially superseded by the markdown-first spec (noted in the v2 plan). |
+| `doc/plans/2026-02-16-module-system.md` | Module system plan; JSON-only company template sections superseded by the markdown-first model. |
+| `doc/plans/2026-03-14-skills-ui-product-plan.md` | Skills UI plan; references portable skill files and `.paperclip.yaml`. |
+| `doc/plans/2026-03-14-adapter-skill-sync-rollout.md` | Adapter skill sync rollout; companion to the v2 import/export plan. |
+
+## 2. Shared Types & Validators
+
+These define the contract between server, CLI, and UI.
+
+| File | What it defines |
+|---|---|
+| `packages/shared/src/types/company-portability.ts` | TypeScript interfaces: `CompanyPortabilityManifest`, `CompanyPortabilityFileEntry`, `CompanyPortabilityEnvInput`, export/import/preview request and result types, manifest entry types for agents, skills, projects, issues, recurring routines, companies. |
+| `packages/shared/src/validators/company-portability.ts` | Zod schemas for all portability request/response shapes — used by both server routes and CLI. |
+| `packages/shared/src/types/index.ts` | Re-exports portability types. |
+| `packages/shared/src/validators/index.ts` | Re-exports portability validators. |
+
+## 3. Server — Services
+
+| File | Responsibility |
+|---|---|
+| `server/src/services/company-portability.ts` | **Core portability service.** Export (manifest generation, markdown file emission, `.paperclip.yaml` sidecars), import (graph resolution, collision handling, entity creation), preview (planned-action summary). Handles skill key derivation, recurring task <-> routine mapping, legacy recurrence migration, and package README generation. References `agentcompanies/v1` version string. |
+| `server/src/services/routines.ts` | Paperclip routine runtime service. Portability now exports routines as recurring `TASK.md` entries and imports recurring tasks back through this service. |
+| `server/src/services/company-export-readme.ts` | Generates `README.md` and Mermaid org-chart for exported company packages. |
+| `server/src/services/index.ts` | Re-exports `companyPortabilityService`. |
+
+## 4. Server — Routes
+
+| File | Endpoints |
+|---|---|
+| `server/src/routes/companies.ts` | `POST /api/companies/:companyId/export` — legacy export bundle<br>`POST /api/companies/:companyId/exports/preview` — export preview<br>`POST /api/companies/:companyId/exports` — export package<br>`POST /api/companies/import/preview` — import preview<br>`POST /api/companies/import` — perform import |
+
+Route registration lives in `server/src/app.ts` via `companyRoutes(db, storage)`.
+
+## 5. Server — Tests
+
+| File | Coverage |
+|---|---|
+| `server/src/__tests__/company-portability.test.ts` | Unit tests for the portability service (export, import, preview, manifest shape, `agentcompanies/v1` version). |
+| `server/src/__tests__/company-portability-routes.test.ts` | Integration tests for the portability HTTP endpoints. |
+
+## 6. CLI
+
+| File | Commands |
+|---|---|
+| `cli/src/commands/client/company.ts` | `company export` — exports a company package to disk (flags: `--out`, `--include`, `--projects`, `--issues`, `--projectIssues`).<br>`company import <fromPathOrUrl>` — imports a company package from a file or folder (flags: positional source path/URL or GitHub shorthand, `--include`, `--target`, `--companyId`, `--newCompanyName`, `--agents`, `--collision`, `--ref`, `--dryRun`).<br>Reads/writes portable file entries and handles `.paperclip.yaml` filtering. |
+
+## 7. UI — Pages
+
+| File | Role |
+|---|---|
+| `ui/src/pages/CompanyExport.tsx` | Export UI: preview, manifest display, file tree visualization, ZIP archive creation and download. Filters `.paperclip.yaml` based on selection. Shows manifest and README in editor. |
+| `ui/src/pages/CompanyImport.tsx` | Import UI: source input (upload/folder/GitHub URL/generic URL), ZIP reading, preview pane with dependency tree, entity selection checkboxes, trust/licensing warnings, secrets requirements, collision strategy, adapter config. |
+
+## 8. UI — Components
+
+| File | Role |
+|---|---|
+| `ui/src/components/PackageFileTree.tsx` | Reusable file tree component for both import and export. Builds tree from `CompanyPortabilityFileEntry` items, parses frontmatter, shows action indicators (create/update/skip), and maps frontmatter field labels. |
+
+## 9. UI — Libraries
+
+| File | Role |
+|---|---|
+| `ui/src/lib/portable-files.ts` | Helpers for portable file entries: `getPortableFileText`, `getPortableFileDataUrl`, `getPortableFileContentType`, `isPortableImageFile`. |
+| `ui/src/lib/zip.ts` | ZIP archive creation (`createZipArchive`) and reading (`readZipArchive`) — implements ZIP format from scratch for company packages. CRC32, DOS date/time encoding. |
+| `ui/src/lib/zip.test.ts` | Tests for ZIP utilities; exercises round-trip with portability file entries and `.paperclip.yaml` content. |
+
+## 10. UI — API Client
+
+| File | Functions |
+|---|---|
+| `ui/src/api/companies.ts` | `companiesApi.exportBundle`, `companiesApi.exportPreview`, `companiesApi.exportPackage`, `companiesApi.importPreview`, `companiesApi.importBundle` — typed fetch wrappers for the portability endpoints. |
+
+## 11. Skills & Agent Instructions
+
+| File | Relevance |
+|---|---|
+| `skills/paperclip/references/company-skills.md` | Reference doc for company skill library workflow — install, inspect, update, assign. Skill packages are a subset of the agent companies spec. |
+| `server/src/services/company-skills.ts` | Company skill management service — handles SKILL.md-based imports and company-level skill library. |
+| `server/src/services/agent-instructions.ts` | Agent instructions service — resolves AGENTS.md paths for agent instruction loading. |
+
+## 12. Quick Cross-Reference by Spec Concept
+
+| Spec concept | Primary implementation files |
+|---|---|
+| `COMPANY.md` frontmatter & body | `company-portability.ts` (export emitter + import parser) |
+| `AGENTS.md` frontmatter & body | `company-portability.ts`, `agent-instructions.ts` |
+| `PROJECT.md` frontmatter & body | `company-portability.ts` |
+| `TASK.md` frontmatter & body | `company-portability.ts` |
+| `SKILL.md` packages | `company-portability.ts`, `company-skills.ts` |
+| `.paperclip.yaml` vendor sidecar | `company-portability.ts`, `routines.ts`, `CompanyExport.tsx`, `company.ts` (CLI) |
+| `manifest.json` | `company-portability.ts` (generation), shared types (schema) |
+| ZIP package format | `zip.ts` (UI), `company.ts` (CLI file I/O) |
+| Collision resolution | `company-portability.ts` (server), `CompanyImport.tsx` (UI) |
+| Env/secrets declarations | shared types (`CompanyPortabilityEnvInput`), `CompanyImport.tsx` (UI) |
+| README + org chart | `company-export-readme.ts` |

doc/CLI.md

@@ -32,10 +32,12 @@ Mode taxonomy and design intent are documented in `doc/DEPLOYMENT-MODES.md`.
 Current CLI behavior:
 
 - `paperclipai onboard` and `paperclipai configure --section server` set deployment mode in config
+- server onboarding/configure ask for reachability intent and write `server.bind`
+- `paperclipai run --bind <loopback|lan|tailnet>` passes a quickstart bind preset into first-run onboarding when config is missing
 - runtime can override mode with `PAPERCLIP_DEPLOYMENT_MODE`
-- `paperclipai run` and `paperclipai doctor` do not yet expose a direct `--mode` flag
+- `paperclipai run` and `paperclipai doctor` still do not expose a direct low-level `--mode` flag
 
-Target behavior (planned) is documented in `doc/DEPLOYMENT-MODES.md` section 5.
+Canonical behavior is documented in `doc/DEPLOYMENT-MODES.md`.
 
 Allow an authenticated/private hostname (for example custom Tailscale DNS):
 
@@ -116,6 +118,20 @@ pnpm paperclipai issue release <issue-id>
 ```sh
 pnpm paperclipai agent list --company-id <company-id>
 pnpm paperclipai agent get <agent-id>
+pnpm paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>
+```
+
+`agent local-cli` is the quickest way to run local Claude/Codex manually as a Paperclip agent:
+
+- creates a new long-lived agent API key
+- installs missing Paperclip skills into `~/.codex/skills` and `~/.claude/skills`
+- prints `export ...` lines for `PAPERCLIP_API_URL`, `PAPERCLIP_COMPANY_ID`, `PAPERCLIP_AGENT_ID`, and `PAPERCLIP_API_KEY`
+
+Example for shortname-based local setup:
+
+```sh
+pnpm paperclipai agent local-cli codexcoder --company-id <company-id>
+pnpm paperclipai agent local-cli claudecoder --company-id <company-id>
 ```
 
 ## Approval Commands

doc/DATABASE.md

@@ -19,6 +19,14 @@ That's it. On first start the server:
 
 Data persists across restarts in `~/.paperclip/instances/default/db/`. To reset local dev data, delete that directory.
 
+If you need to apply pending migrations manually, run:
+
+```sh
+pnpm db:migrate
+```
+
+When `DATABASE_URL` is unset, this command targets the current embedded PostgreSQL instance for your active Paperclip config/instance.
+
 This mode is ideal for local development and one-command installs.
 
 Docker note: the Docker quickstart image also uses embedded PostgreSQL by default. Persist `/paperclip` to keep DB state across container restarts (see `doc/DOCKER.md`).
@@ -86,6 +94,16 @@ Set `DATABASE_URL` in your `.env`:
 DATABASE_URL=postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres
 ```
 
+For hosted deployments that use a pooled runtime URL, set
+`DATABASE_MIGRATION_URL` to the direct connection URL. Paperclip uses it for
+startup schema checks/migrations and plugin namespace migrations, while the app
+continues to use `DATABASE_URL` for runtime queries:
+
+```sh
+DATABASE_URL=postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres
+DATABASE_MIGRATION_URL=postgres://postgres.[PROJECT-REF]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:5432/postgres
+```
+
 If using connection pooling (port 6543), the `postgres` client must disable prepared statements. Update `packages/db/src/client.ts`:
 
 ```ts

doc/DEPLOYMENT-MODES.md

@@ -17,6 +17,11 @@ Paperclip supports two runtime modes:
 
 This keeps one authenticated auth stack while still separating low-friction private-network defaults from internet-facing hardening requirements.
 
+Paperclip now treats **bind** as a separate concern from auth:
+
+- auth model: `local_trusted` vs `authenticated`, plus `private/public`
+- reachability model: `server.bind = loopback | lan | tailnet | custom`
+
 ## 2. Canonical Model
 
 | Runtime Mode | Exposure | Human auth | Primary use |
@@ -25,6 +30,15 @@ This keeps one authenticated auth stack while still separating low-friction priv
 | `authenticated` | `private` | Login required | Private-network access (for example Tailscale/VPN/LAN) |
 | `authenticated` | `public` | Login required | Internet-facing/cloud deployment |
 
+## Reachability Model
+
+| Bind | Meaning | Typical use |
+|---|---|---|
+| `loopback` | Listen on localhost only | default local usage, reverse-proxy deployments |
+| `lan` | Listen on all interfaces (`0.0.0.0`) | LAN/VPN/private-network access |
+| `tailnet` | Listen on a detected Tailscale IP | Tailscale-only access |
+| `custom` | Listen on an explicit host/IP | advanced interface-specific setups |
+
 ## 3. Security Policy
 
 ## `local_trusted`
@@ -38,12 +52,14 @@ This keeps one authenticated auth stack while still separating low-friction priv
 - login required
 - low-friction URL handling (`auto` base URL mode)
 - private-host trust policy required
+- bind can be `loopback`, `lan`, `tailnet`, or `custom`
 
 ## `authenticated + public`
 
 - login required
 - explicit public URL required
 - stricter deployment checks and failures in doctor
+- recommended bind is `loopback` behind a reverse proxy; direct `lan/custom` is advanced
 
 ## 4. Onboarding UX Contract
 
@@ -55,14 +71,22 @@ pnpm paperclipai onboard
 
 Server prompt behavior:
 
-1. ask mode, default `local_trusted`
-2. option copy:
-- `local_trusted`: "Easiest for local setup (no login, localhost-only)"
-- `authenticated`: "Login required; use for private network or public hosting"
-3. if `authenticated`, ask exposure:
-- `private`: "Private network access (for example Tailscale), lower setup friction"
-- `public`: "Internet-facing deployment, stricter security requirements"
-4. ask explicit public URL only for `authenticated + public`
+1. quickstart `--yes` defaults to `server.bind=loopback` and therefore `local_trusted/private`
+2. advanced server setup asks reachability first:
+- `Trusted local` → `bind=loopback`, `local_trusted/private`
+- `Private network` → `bind=lan`, `authenticated/private`
+- `Tailnet` → `bind=tailnet`, `authenticated/private`
+- `Custom` → manual mode/exposure/host entry
+3. raw host entry is only required for the `Custom` path
+4. explicit public URL is only required for `authenticated + public`
+
+Examples:
+
+```sh
+pnpm paperclipai onboard --yes
+pnpm paperclipai onboard --yes --bind lan
+pnpm paperclipai run --bind tailnet
+```
 
 `configure --section server` follows the same interactive behavior.
 
@@ -118,3 +142,4 @@ This prevents lockout when a user migrates from long-running local trusted usage
 - implementation plan: `doc/plans/deployment-auth-mode-consolidation.md`
 - V1 contract: `doc/SPEC-implementation.md`
 - operator workflows: `doc/DEVELOPING.md` and `doc/CLI.md`
+- invite/join state map: `doc/spec/invite-flow.md`