paperclip/doc/plans/2026-03-13-company-import-export-v2.md

# 2026-03-13 Company Import / Export V2 Plan

Status: Proposed implementation plan
Date: 2026-03-13
Audience: Product and engineering
Supersedes for package-format direction:
- `doc/plans/2026-02-16-module-system.md` sections that describe company templates as JSON-only
- `docs/specs/cliphub-plan.md` assumptions about blueprint bundle shape where they conflict with the markdown-first package model

## 1. Purpose

This document defines the next-stage plan for Paperclip company import/export.

The core shift is:

- move from a Paperclip-specific JSON-first portability package toward a markdown-first package format
- make GitHub repositories first-class package sources
- treat the company package model as an extension of the existing Agent Skills ecosystem instead of inventing a separate skill format
- support company, team, agent, and skill reuse without requiring a central registry

The normative package format draft lives in:

- `docs/companies/companies-spec.md`

This plan is about implementation and rollout inside Paperclip.

Adapter-wide skill rollout details live in:

- `doc/plans/2026-03-14-adapter-skill-sync-rollout.md`

## 2. Executive Summary

Paperclip already has portability primitives in the repo:

- server import/export/preview APIs
- CLI import/export commands
- shared portability types and validators

Those primitives are being cut over to the new package model rather than extended for backward compatibility.

The new direction is:

1. markdown-first package authoring
2. GitHub repo or local folder as the default source of truth
3. a vendor-neutral base package spec for agent-company runtimes, not just Paperclip
4. the company package model is explicitly an extension of Agent Skills
5. no future dependency on `paperclip.manifest.json`
6. implicit folder discovery by convention for the common case
7. an always-emitted `.paperclip.yaml` sidecar for high-fidelity Paperclip-specific details
8. package graph resolution at import time
9. entity-level import UI with dependency-aware tree selection
10. `skills.sh` compatibility is a V1 requirement for skill packages and skill installation flows
11. adapter-aware skill sync surfaces so Paperclip can read, diff, enable, disable, and reconcile skills where the adapter supports it

## 3. Product Goals

### 3.1 Goals

- A user can point Paperclip at a local folder or GitHub repo and import a company package without any registry.
- A package is readable and writable by humans with normal git workflows.
- A package can contain:
  - company definition
  - org subtree / team definition
  - agent definitions
  - optional starter projects and tasks
  - reusable skills
- V1 skill support is compatible with the existing `skills.sh` / Agent Skills ecosystem.
- A user can import into:
  - a new company
  - an existing company
- Import preview shows:
  - what will be created
  - what will be updated
  - what is skipped
  - what is referenced externally
  - what needs secrets or approvals
- Export preserves attribution, licensing, and pinned upstream references.
- Export produces a clean vendor-neutral package plus a Paperclip sidecar.
- `companies.sh` can later act as a discovery/index layer over repos implementing this format.

### 3.2 Non-Goals

- No central registry is required for package validity.
- This is not full database backup/restore.
- This does not attempt to export runtime state like:
  - heartbeat runs
  - API keys
  - spend totals
  - run sessions
  - transient workspaces
- This does not require a first-class runtime `teams` table before team portability ships.

## 4. Current State In Repo

Current implementation exists here:

- shared types: `packages/shared/src/types/company-portability.ts`
- shared validators: `packages/shared/src/validators/company-portability.ts`
- server routes: `server/src/routes/companies.ts`
- server service: `server/src/services/company-portability.ts`
- CLI commands: `cli/src/commands/client/company.ts`

Current product limitations:

1. Import/export UX still needs deeper tree-selection and skill/package management polish.
2. Adapter-specific skill sync remains uneven across adapters and must degrade cleanly when unsupported.
3. Projects and starter tasks should stay opt-in on export rather than default package content.
4. Import/export still needs stronger coverage around attribution, pin verification, and executable-package warnings.
5. The current markdown frontmatter parser is intentionally lightweight and should stay constrained to the documented shape.

## 5. Canonical Package Direction

### 5.1 Canonical Authoring Format

The canonical authoring format becomes a markdown-first package rooted in one of:

- `COMPANY.md`
- `TEAM.md`
- `AGENTS.md`
- `PROJECT.md`
- `TASK.md`
- `SKILL.md`

The normative draft is:

- `docs/companies/companies-spec.md`

### 5.2 Relationship To Agent Skills

Paperclip must not redefine `SKILL.md`.

Rules:

- `SKILL.md` stays Agent Skills compatible
- the company package model is an extension of Agent Skills
- the base package is vendor-neutral and intended for any agent-company runtime
- Paperclip-specific fidelity lives in `.paperclip.yaml`
- Paperclip may resolve and install `SKILL.md` packages, but it must not require a Paperclip-only skill format
- `skills.sh` compatibility is a V1 requirement, not a future nice-to-have

### 5.3 Agent-To-Skill Association

`AGENTS.md` should associate skills by skill shortname or slug, not by verbose path in the common case.

Preferred example:

- `skills: [review, react-best-practices]`

Resolution model:

- `review` resolves to `skills/review/SKILL.md` by package convention
- if the skill is external or referenced, the skill package owns that complexity
- exporters should prefer shortname-based associations in `AGENTS.md`
- importers should resolve the shortname against local package skills first, then referenced or installed company skills
### 5.4 Base Package Vs Paperclip Extension

The repo format should have two layers:

- base package:
  - minimal, readable, social, vendor-neutral
  - implicit folder discovery by convention
  - no Paperclip-only runtime fields by default
- Paperclip extension:
  - `.paperclip.yaml`
  - adapter/runtime/permissions/budget/workspace fidelity
  - emitted by Paperclip tools as a sidecar while the base package stays readable

### 5.5 Relationship To Current V1 Manifest

`paperclip.manifest.json` is not part of the future package direction.

This should be treated as a hard cutover in product direction.

- markdown-first repo layout is the target
- no new work should deepen investment in the old manifest model
- future portability APIs and UI should target the markdown-first model only

## 6. Package Graph Model

### 6.1 Entity Kinds

Paperclip import/export should support these entity kinds:

- company
- team
- agent
- project
- task
- skill

### 6.2 Team Semantics

`team` is a package concept first, not a database-table requirement.

In Paperclip V2 portability:

- a team is an importable org subtree
- it is rooted at a manager agent
- it can be attached under a target manager in an existing company

This avoids blocking portability on a future runtime `teams` model.

Imported-team tracking should initially be package/provenance-based:

- if a team package was imported, the imported agents should carry enough provenance to reconstruct that grouping
- Paperclip can treat “this set of agents came from team package X” as the imported-team model
- provenance grouping is the intended near- and medium-term team model for import/export
- only add a first-class runtime `teams` table later if product needs move beyond what provenance grouping can express

### 6.3 Dependency Graph

Import should operate on an entity graph, not raw file selection.

Examples:

- selecting an agent auto-selects its required docs and skill refs
- selecting a team auto-selects its subtree
- selecting a company auto-selects all included entities by default
- selecting a project auto-selects its starter tasks

The preview output should reflect graph resolution explicitly.

## 7. External References, Pinning, And Attribution

### 7.1 Why This Matters

Some packages will:

- reference upstream files we do not want to republish
- include third-party work where attribution must remain visible
- need protection from branch hot-swapping

### 7.2 Policy

Paperclip should support source references in package metadata with:

- repo
- path
- commit sha
- optional blob sha
- optional sha256
- attribution
- license
- usage mode

Usage modes:

- `vendored`
- `referenced`
- `mirrored`

Default exporter behavior for third-party content should be:

- prefer `referenced`
- preserve attribution
- do not silently inline third-party content into exports

### 7.3 Trust Model

Imported package content should be classified by trust level:

- markdown-only
- markdown + assets
- markdown + scripts/executables

The UI and CLI should surface this clearly before apply.

## 8. Import Behavior

### 8.1 Supported Sources

- local folder
- local package root file
- GitHub repo URL
- GitHub subtree URL
- direct URL to markdown/package root

Registry-based discovery may be added later, but must remain optional.

### 8.2 Import Targets

- new company
- existing company

For existing company imports, the preview must support:

- collision handling
- attach-point selection for team imports
- selective entity import

### 8.3 Collision Strategy

Current `rename | skip | replace` support remains, but matching should improve over time.

Preferred matching order:

1. prior install provenance
2. stable package entity identity
3. slug
4. human name as weak fallback

Slug-only matching is acceptable only as a transitional strategy.

### 8.4 Required Preview Output

Every import preview should surface:

- target company action
- entity-level create/update/skip plan
- referenced external content
- missing files
- hash mismatch or pinning issues
- env inputs, including required vs optional and default values when present
- unsupported content types
- trust/licensing warnings

### 8.5 Adapter Skill Sync Surface

People want skill management in the UI, but skills are adapter-dependent.

That means portability and UI planning must include an adapter capability model for skills.

Paperclip should define a new adapter surface area around skills:

- list currently enabled skills for an agent
- report how those skills are represented by the adapter
- install or enable a skill
- disable or remove a skill
- report sync state between desired package config and actual adapter state

Examples:

- Claude Code / Codex style adapters may manage skills as local filesystem packages or adapter-owned skill directories
- OpenClaw-style adapters may expose currently enabled skills through an API or a reflected config surface
- some adapters may be read-only and only report what they have

Planned adapter capability shape:

- `supportsSkillRead`
- `supportsSkillWrite`
- `supportsSkillRemove`
- `supportsSkillSync`
- `skillStorageKind` such as `filesystem`, `remote_api`, `inline_config`, or `unknown`

Baseline adapter interface:

- `listSkills(agent)`
- `applySkills(agent, desiredSkills)`
- `removeSkill(agent, skillId)` optional
- `getSkillSyncState(agent, desiredSkills)` optional

Planned Paperclip behavior:

- if an adapter supports read, Paperclip should show current skills in the UI
- if an adapter supports write, Paperclip should let the user enable/disable imported skills
- if an adapter supports sync, Paperclip should compute desired vs actual state and offer reconcile actions
- if an adapter does not support these capabilities, the UI should still show the package-level desired skills but mark them unmanaged

## 9. Export Behavior

### 9.1 Default Export Target

Default export target should become a markdown-first folder structure.

Example:

```text
my-company/
├── COMPANY.md
├── agents/
├── teams/
└── skills/
```

### 9.2 Export Rules

Exports should:

- omit machine-local ids
- omit timestamps and counters unless explicitly needed
- omit secret values
- omit local absolute paths
- omit duplicated inline prompt content from `.paperclip.yaml` when `AGENTS.md` already carries the instructions
- preserve references and attribution
- emit `.paperclip.yaml` alongside the base package
- express adapter env/secrets as portable env input declarations rather than exported secret binding ids
- preserve compatible `SKILL.md` content as-is

Projects and issues should not be exported by default.

They should be opt-in through selectors such as:

- `--projects project-shortname-1,project-shortname-2`
- `--issues PAP-1,PAP-3`
- `--project-issues project-shortname-1,project-shortname-2`

This supports “clean public company package” workflows where a maintainer exports a follower-facing company package without bundling active work items every time.

### 9.3 Export Units

Initial export units:

- company package
- team package
- single agent package

Later optional units:

- skill pack export
- seed projects/tasks bundle

## 10. Storage Model Inside Paperclip

### 10.1 Short-Term

In the first phase, imported entities can continue mapping onto current runtime tables:

- company -> companies
- agent -> agents
- team -> imported agent subtree attachment plus package provenance grouping
- skill -> company-scoped reusable package metadata plus agent-scoped desired-skill attachment state where supported

### 10.2 Medium-Term

Paperclip should add managed package/provenance records so imports are not anonymous one-off copies.

Needed capabilities:

- remember install origin
- support re-import / upgrade
- distinguish local edits from upstream package state
- preserve external refs and package-level metadata
- preserve imported team grouping without requiring a runtime `teams` table immediately
- preserve desired-skill state separately from adapter runtime state
- support both company-scoped reusable skills and agent-scoped skill attachments

Suggested future tables:

- package_installs
- package_install_entities
- package_sources
- agent_skill_desires
- adapter_skill_snapshots

This is not required for phase 1 UI, but it is required for a robust long-term system.

## 11. API Plan

### 11.1 Keep Existing Endpoints Initially

Retain:

- `POST /api/companies/:companyId/export`
- `POST /api/companies/import/preview`
- `POST /api/companies/import`

But evolve payloads toward the markdown-first graph model.

### 11.2 New API Capabilities

Add support for:

- package root resolution from local/GitHub inputs
- graph resolution preview
- source pin and hash verification results
- entity-level selection
- team attach target selection
- provenance-aware collision planning

### 11.3 Parsing Changes

Replace the current ad hoc markdown frontmatter parser with a real parser that can handle:

- nested YAML
- arrays/objects reliably
- consistent round-tripping

This is a prerequisite for the new package model.

## 12. CLI Plan

The CLI should continue to support direct import/export without a registry.

Target commands:

- `paperclipai company export <company-id> --out <path>`
- `paperclipai company import --from <path-or-url> --dry-run`
- `paperclipai company import --from <path-or-url> --target existing -C <company-id>`

Planned additions:

- `--package-kind company|team|agent`
- `--attach-under <agent-id-or-slug>` for team imports
- `--strict-pins`
- `--allow-unpinned`
- `--materialize-references`
- `--sync-skills`

## 13. UI Plan

### 13.1 Company Settings Import / Export

Add a real import/export section to Company Settings.

Export UI:

- export package kind selector
- include options
- local download/export destination guidance
- attribution/reference summary

Import UI:

- source entry:
  - upload/folder where supported
  - GitHub URL
  - generic URL
- preview pane with:
  - resolved package root
  - dependency tree
  - checkboxes by entity
  - trust/licensing warnings
  - secrets requirements
  - collision plan

### 13.2 Team Import UX

If importing a team into an existing company:

- show the subtree structure
- require the user to choose where to attach it
- preview manager/reporting updates before apply
- preserve imported-team provenance so the UI can later say “these agents came from team package X”

### 13.3 Skills UX

See also:

- `doc/plans/2026-03-14-skills-ui-product-plan.md`

If importing skills:

- show whether each skill is local, vendored, or referenced
- show whether it contains scripts/assets
- preserve Agent Skills compatibility in presentation and export
- preserve `skills.sh` compatibility in both import and install flows
- show agent skill attachments by shortname/slug rather than noisy file paths
- treat agent skills as a dedicated agent tab, not just another subsection of configuration
- show current adapter-reported skills when supported
- show desired package skills separately from actual adapter state
- offer reconcile actions when the adapter supports sync

## 14. Rollout Phases

### Phase 1: Stabilize Current V1 Portability

- add tests for current portability flows
- replace the frontmatter parser
- add Company Settings UI for current import/export capabilities
- start cutover work toward the markdown-first package reader

### Phase 2: Markdown-First Package Reader

- support `COMPANY.md` / `TEAM.md` / `AGENTS.md` root detection
- build internal graph from markdown-first packages
- support local folder and GitHub repo inputs natively
- support agent skill references by shortname/slug
- resolve local `skills/<slug>/SKILL.md` packages by convention
- support `skills.sh`-compatible skill repos as V1 package sources

### Phase 3: Graph-Based Import UX And Skill Surfaces

- entity tree preview
- checkbox selection
- team subtree attach flow
- licensing/trust/reference warnings
- company skill library groundwork
- dedicated agent `Skills` tab groundwork
- adapter skill read/sync UI groundwork

### Phase 4: New Export Model

- export markdown-first folder structure by default

### Phase 5: Provenance And Upgrades

- persist install provenance
- support package-aware re-import and upgrades
- improve collision matching beyond slug-only
- add imported-team provenance grouping
- add desired-vs-actual skill sync state

### Phase 6: Optional Seed Content

- goals
- projects
- starter issues/tasks

This phase is intentionally after the structural model is stable.

## 15. Documentation Plan

Primary docs:

- `docs/companies/companies-spec.md` as the package-format draft
- this implementation plan for rollout sequencing

Docs to update later as implementation lands:

- `doc/SPEC-implementation.md`
- `docs/api/companies.md`
- `docs/cli/control-plane-commands.md`
- board operator docs for Company Settings import/export

## 16. Open Questions

1. Should imported skill packages be stored as managed package files in Paperclip storage, or only referenced at import time?
   Decision: managed package files should support both company-scoped reuse and agent-scoped attachment.
2. What is the minimum adapter skill interface needed to make the UI useful across Claude Code, Codex, OpenClaw, and future adapters?
   Decision: use the baseline interface in section 8.5.
3. Should Paperclip support direct local folder selection in the web UI, or keep that CLI-only initially?
4. Do we want optional generated lock files in phase 2, or defer them until provenance work?
5. How strict should pinning be by default for GitHub references:
   - warn on unpinned
   - or block in normal mode
6. Is package-provenance grouping enough for imported teams, or do we expect product requirements soon that would justify a first-class runtime `teams` table?
   Decision: provenance grouping is enough for the import/export product model for now.

## 17. Recommendation

Engineering should treat this as the current plan of record for company import/export beyond the existing V1 portability feature.

Immediate next steps:

1. accept `docs/companies/companies-spec.md` as the package-format draft
2. implement phase 1 stabilization work
3. build phase 2 markdown-first package reader before expanding ClipHub or `companies.sh`
4. treat the old manifest-based format as deprecated and not part of the future surface

This keeps Paperclip aligned with:

- GitHub-native distribution
- Agent Skills compatibility
- a registry-optional ecosystem model