[codex] Add skills CLI and catalog management (#6782)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies through
company-scoped control-plane workflows.
> - Agents need reusable, inspectable skills that can be installed,
reset, audited, exported, and assigned without bespoke local setup.
> - The existing skill truth model needed cleanup so bundled skills,
optional catalog skills, runtime skills, and adapter-provided skills
have clear provenance.
> - Operators also need a practical CLI and board UI for discovering and
managing company skills.
> - This pull request adds the skills CLI, packaged skills catalog,
company skills APIs, and catalog-aware board UI.
> - The benefit is a more reusable Paperclip company setup where skills
are portable, auditable, and easier for operators and agents to manage.

## What Changed

- Added `paperclipai skills` CLI commands and coverage for catalog
listing, installing, resetting, and inspecting company skills.
- Added a packaged `@paperclipai/skills-catalog` workspace with bundled
and optional skill content plus validation/build tests.
- Added shared company-skill types and validators used across CLI,
server, and UI contracts.
- Added server catalog APIs/services for company skill catalog
operations, reset semantics, audit behavior, and portability provenance.
- Updated adapter skill handling so runtime/catalog provenance remains
explicit across local adapters.
- Added board UI support for browsing and managing catalog-backed
company skills.
- Updated docs for the skills CLI/catalog flow and the company skills
Paperclip skill reference.
- Rebased the branch onto current `paperclipai/paperclip:master`; no
`pnpm-lock.yaml`, `.github/workflows`, or migration files are included
in the final PR diff.

## Verification

- Passed: `pnpm run preflight:workspace-links && pnpm exec vitest run
cli/src/__tests__/skills.test.ts
packages/skills-catalog/src/catalog-builder.test.ts
packages/skills-catalog/src/shipped-catalog.test.ts
packages/shared/src/validators/company-skill.test.ts
packages/adapter-utils/src/server-utils.test.ts
packages/plugins/create-paperclip-plugin/src/entrypoints.test.ts
server/src/__tests__/company-skills-catalog-service.test.ts
server/src/__tests__/company-skills-routes.test.ts
server/src/__tests__/company-portability.test.ts`.
- Passed: `pnpm exec vitest run
server/src/__tests__/workspace-runtime.test.ts -t "default
branch|origin/master|symbolic-ref"`.
- Attempted: full `server/src/__tests__/workspace-runtime.test.ts`. Four
provisioning tests failed while seeding an isolated worktree database
from the local Paperclip instance because the local plugin schema dump
contains a duplicate-column foreign key
(`plugin_content_machine_18a7bc327b.content_case_signals`). The
default-branch tests touched by the rebase conflict passed in the
focused run above.
- Checked final diff: no `pnpm-lock.yaml`, no `.github/workflows`, and
no migration-file changes relative to `master`.

## Risks

- Medium: this is a broad skills/catalog change touching CLI, server
APIs, shared contracts, adapter skill sync, and UI.
- Catalog validation and reset semantics need careful reviewer attention
because they affect reusable company setup and portability.
- No database migrations are included in this PR, so there is no
migration ordering/idempotency risk in the final diff.
- No lockfile is included by design; dependency resolution will be
handled by the repository lockfile workflow.

## Model Used

- OpenAI Codex coding agent based on GPT-5, running in Paperclip via the
`codex_local` adapter with shell, git, GitHub CLI, and code-editing tool
access. Exact hosted model build/context-window metadata is not exposed
in this runtime.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run targeted tests locally and documented the local
workspace-runtime seed failure above
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, screenshots were intentionally
omitted per PAP-10124 instructions; UI behavior is covered by tests and
reviewer inspection
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

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

@@ -1,6 +1,6 @@
 # 2026-03-14 Adapter Skill Sync Rollout
 
-Status: Proposed
+Status: Implemented for local adapters; gateway remains unsupported
 Date: 2026-03-14
 Audience: Product and engineering
 Related:
@@ -25,8 +25,10 @@ Paperclip currently has these adapters:
 
 - `claude_local`
 - `codex_local`
-- `cursor_local`
+- `cursor`
 - `gemini_local`
+- `grok_local`
+- `acpx_local`
 - `opencode_local`
 - `pi_local`
 - `openclaw_gateway`
@@ -39,12 +41,14 @@ The current skill API supports:
 
 Current implementation state:
 
-- `codex_local`: implemented, `persistent`
+- `codex_local`: implemented, `ephemeral`
 - `claude_local`: implemented, `ephemeral`
-- `cursor_local`: not yet implemented, but technically suited to `persistent`
-- `gemini_local`: not yet implemented, but technically suited to `persistent`
-- `pi_local`: not yet implemented, but technically suited to `persistent`
-- `opencode_local`: not yet implemented; likely `persistent`, but with special handling because it currently injects into Claude’s shared skills home
+- `cursor`: implemented, `persistent`
+- `gemini_local`: implemented, `persistent`
+- `pi_local`: implemented, `persistent`
+- `opencode_local`: implemented, `persistent`, with shared Claude skills home caveats
+- `acpx_local`: implemented, `ephemeral` for Claude/Codex sub-agents and `unsupported` for custom commands
+- `grok_local`: implemented, `ephemeral`
 - `openclaw_gateway`: not yet implemented; blocked on gateway protocol support, so `unsupported` for now
 
 ## 3. Product Principles
@@ -64,8 +68,7 @@ These adapters have a stable local skills directory that Paperclip can read and
 
 Candidates:
 
-- `codex_local`
-- `cursor_local`
+- `cursor`
 - `gemini_local`
 - `pi_local`
 - `opencode_local` with caveats
@@ -84,7 +87,10 @@ These adapters do not have a meaningful Paperclip-owned persistent install state
 
 Current adapter:
 
+- `codex_local`
 - `claude_local`
+- `acpx_local` when configured for Claude or Codex
+- `grok_local`
 
 Expected UX:
 
@@ -99,6 +105,7 @@ These adapters cannot support skill sync without new external capabilities.
 
 Current adapter:
 
+- `acpx_local` when configured for custom commands
 - `openclaw_gateway`
 
 Expected UX:
@@ -114,7 +121,7 @@ Expected UX:
 
 Target mode:
 
-- `persistent`
+- `ephemeral`
 
 Current state:
 
@@ -122,15 +129,15 @@ Current state:
 
 Requirements to finish:
 
-- keep as reference implementation
-- tighten tests around external custom skills and stale removal
-- ensure imported company skills can be attached and synced without manual path work
+- keep runtime-mounted snapshots separate from persistent install snapshots
+- ensure imported company skills can be attached and mounted without manual path work
+- keep `CODEX_HOME/skills` mutation scoped to heartbeat execution, not `skills/sync`
 
 Success criteria:
 
-- list installed managed and external skills
-- sync desired skills into `CODEX_HOME/skills`
-- preserve external user-managed skills
+- desired skills are stored in Paperclip
+- selected skills are linked into the effective `CODEX_HOME/skills` during runs
+- no persistent installed/stale state is reported from `skills/sync`
 
 ### 5.2 Claude Local
 
@@ -162,18 +169,11 @@ Target mode:
 
 Technical basis:
 
-- runtime already injects Paperclip skills into `~/.cursor/skills`
+- Paperclip reconciles desired skills into `~/.cursor/skills`
 
-Implementation work:
+Current state:
 
-1. Add `listSkills` for Cursor.
-2. Add `syncSkills` for Cursor.
-3. Reuse the same managed-symlink pattern as Codex.
-4. Distinguish:
-   - managed Paperclip skills
-   - external skills already present
-   - missing desired skills
-   - stale managed skills
+- implemented
 
 Testing:
 
@@ -194,14 +194,11 @@ Target mode:
 
 Technical basis:
 
-- runtime already injects Paperclip skills into `~/.gemini/skills`
+- Paperclip reconciles desired skills into `~/.gemini/skills`
 
-Implementation work:
+Current state:
 
-1. Add `listSkills` for Gemini.
-2. Add `syncSkills` for Gemini.
-3. Reuse managed-symlink conventions from Codex/Cursor.
-4. Verify auth remains untouched while skills are reconciled.
+- implemented
 
 Potential caveat:
 
@@ -219,14 +216,11 @@ Target mode:
 
 Technical basis:
 
-- runtime already injects Paperclip skills into `~/.pi/agent/skills`
+- Paperclip reconciles desired skills into `~/.pi/agent/skills`
 
-Implementation work:
+Current state:
 
-1. Add `listSkills` for Pi.
-2. Add `syncSkills` for Pi.
-3. Reuse managed-symlink helpers.
-4. Verify session-file behavior remains independent from skill sync.
+- implemented
 
 Success criteria:
 
@@ -250,9 +244,7 @@ This is product-risky because:
 
 Plan:
 
-Phase 1:
-
-- implement `listSkills` and `syncSkills`
+- implemented `listSkills` and `syncSkills`
 - treat it as `persistent`
 - explicitly label the home as shared in UI copy
 - only remove stale managed Paperclip skills that are clearly marked as Paperclip-managed
@@ -290,6 +282,30 @@ Future target:
 - likely a fourth truth model eventually, such as remote-managed persistent state
 - for now, keep the current API and treat gateway as unsupported
 
+### 5.8 ACPX Local
+
+Target mode:
+
+- `ephemeral` for built-in Claude/Codex ACPX sub-agents
+- `unsupported` for custom ACP commands
+
+Success criteria:
+
+- Claude/Codex ACPX snapshots show skills as configured for the next session
+- custom command snapshots keep desired skills tracked only and do not imply runtime sync
+
+### 5.9 Grok Local
+
+Target mode:
+
+- `ephemeral`
+
+Success criteria:
+
+- desired skills are stored in Paperclip
+- selected skills are copied into the execution workspace for the next run
+- no persistent installed/stale state is reported from `skills/sync`
+
 ## 6. API Plan
 
 ## 6.1 Keep the current minimal adapter API
@@ -333,14 +349,13 @@ Additional UI requirement for shared-home adapters:
 
 Ship:
 
-- `cursor_local`
+- `cursor`
 - `gemini_local`
 - `pi_local`
 
-Rationale:
+Status:
 
-- these are the closest to Codex in architecture
-- they already inject into stable local skill homes
+- implemented
 
 ### Phase 2: OpenCode shared-home support
 
@@ -348,10 +363,9 @@ Ship:
 
 - `opencode_local`
 
-Rationale:
+Status:
 
-- technically feasible now
-- needs slightly more careful product language because of the shared Claude skills home
+- implemented with shared Claude skills-home warning
 
 ### Phase 3: Gateway support decision
 
@@ -390,10 +404,10 @@ Adapter-wide skill support is ready when all are true:
 
 The recommended immediate order is:
 
-1. `cursor_local`
+1. `cursor`
 2. `gemini_local`
 3. `pi_local`
 4. `opencode_local`
 5. defer `openclaw_gateway`
 
-That gets Paperclip from “skills work for Codex and Claude” to “skills work for the whole local-adapter family,” which is the meaningful V1 milestone.
+The local-adapter family now has explicit truth models. The remaining V1 boundary is `openclaw_gateway`, which should stay unsupported until the gateway protocol can report real remote skill state.