[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>

server/src/services/catalog-provenance.ts

@@ -0,0 +1,65 @@
+export const PORTABLE_CATALOG_PROVENANCE_STRING_KEYS = [
+  "sourceRef",
+  "originHash",
+  "catalogId",
+  "catalogKey",
+  "catalogKind",
+  "catalogCategory",
+  "catalogPath",
+  "packageName",
+  "packageVersion",
+  "originVersion",
+  "installedHash",
+  "userModifiedAt",
+  "updateHoldReason",
+  "auditVerdict",
+  "auditScannedAt",
+  "auditScanVersion",
+] as const;
+
+function asCatalogString(value: unknown) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function readCatalogStringList(value: unknown) {
+  if (!Array.isArray(value)) return null;
+  const entries = value.map((entry) => asCatalogString(entry)).filter((entry): entry is string => Boolean(entry));
+  return entries.length === value.length ? entries : null;
+}
+
+function isCatalogRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function readPortableCatalogProvenance(
+  metadata: Record<string, unknown> | null,
+  canonicalKey: string | null = null,
+) {
+  const paperclip = isCatalogRecord(metadata?.paperclip) ? metadata.paperclip : null;
+  const catalog = isCatalogRecord(paperclip?.catalog) ? paperclip.catalog : null;
+  if (!catalog) return null;
+
+  const sourceRef = asCatalogString(catalog.sourceRef) ?? asCatalogString(catalog.originHash);
+  const normalized: Record<string, unknown> = {
+    ...(canonicalKey ? { skillKey: canonicalKey } : {}),
+    sourceKind: "catalog",
+  };
+  const catalogSkillKey = asCatalogString(catalog.skillKey);
+  if (!canonicalKey && catalogSkillKey) normalized.skillKey = catalogSkillKey;
+
+  for (const key of PORTABLE_CATALOG_PROVENANCE_STRING_KEYS) {
+    if (key === "sourceRef") continue;
+    const value = asCatalogString(catalog[key]);
+    if (value) normalized[key] = value;
+  }
+  if (sourceRef && !normalized.originHash) normalized.originHash = sourceRef;
+  const auditCodes = readCatalogStringList(catalog.auditCodes);
+  if (auditCodes) normalized.auditCodes = auditCodes;
+
+  return {
+    sourceRef,
+    metadata: normalized,
+  };
+}

server/src/services/company-portability.ts

@@ -70,6 +70,12 @@ import { issueService } from "./issues.js";
 import { projectService } from "./projects.js";
 import { routineService } from "./routines.js";
 import { secretService } from "./secrets.js";
+import {
+  PORTABLE_CATALOG_PROVENANCE_STRING_KEYS,
+  readCatalogStringList,
+  readPortableCatalogProvenance,
+} from "./catalog-provenance.js";
+import { normalizePortablePath } from "./portable-path.js";
 
 /** Build OrgNode tree from manifest agent list (slug + reportsToSlug). */
 function buildOrgTreeFromManifest(agents: CompanyPortabilityManifest["agents"]): OrgNode[] {
@@ -228,6 +234,28 @@ function readSkillSourceKind(skill: CompanySkill) {
   return asString(metadata?.sourceKind);
 }
 
+function buildPortableCatalogProvenance(skill: CompanySkill) {
+  if (skill.sourceType !== "catalog") return null;
+  const metadata = isPlainRecord(skill.metadata) ? skill.metadata : null;
+  const provenance: Record<string, unknown> = {
+    skillKey: skill.key,
+  };
+
+  const sourceRef = asString(skill.sourceRef) ?? asString(metadata?.originHash);
+  if (sourceRef) provenance.sourceRef = sourceRef;
+
+  for (const key of PORTABLE_CATALOG_PROVENANCE_STRING_KEYS) {
+    if (key === "sourceRef") continue;
+    const value = asString(metadata?.[key]);
+    if (value) provenance[key] = value;
+  }
+
+  const auditCodes = readCatalogStringList(metadata?.auditCodes);
+  if (auditCodes) provenance.auditCodes = auditCodes;
+
+  return Object.keys(provenance).length > 1 ? provenance : null;
+}
+
 function deriveLocalExportNamespace(skill: CompanySkill, slug: string) {
   const metadata = isPlainRecord(skill.metadata) ? skill.metadata : null;
   const candidates = [
@@ -1415,20 +1443,6 @@ function normalizeInclude(input?: Partial<CompanyPortabilityInclude>): CompanyPo
   };
 }
 
-function normalizePortablePath(input: string) {
-  const normalized = input.replace(/\\/g, "/").replace(/^\.\/+/, "");
-  const parts: string[] = [];
-  for (const segment of normalized.split("/")) {
-    if (!segment || segment === ".") continue;
-    if (segment === "..") {
-      if (parts.length > 0) parts.pop();
-      continue;
-    }
-    parts.push(segment);
-  }
-  return parts.join("/");
-}
-
 function resolvePortablePath(fromPath: string, targetPath: string) {
   const baseDir = path.posix.dirname(fromPath.replace(/\\/g, "/"));
   return normalizePortablePath(path.posix.join(baseDir, targetPath.replace(/\\/g, "/")));
@@ -2126,12 +2140,14 @@ async function withSkillSourceMetadata(skill: CompanySkill, markdown: string) {
   if (sourceEntry) {
     metadata.sources = [...existingSources, sourceEntry];
   }
+  const catalogProvenance = buildPortableCatalogProvenance(skill);
   metadata.skillKey = skill.key;
   metadata.paperclipSkillKey = skill.key;
   metadata.paperclip = {
     ...(isPlainRecord(metadata.paperclip) ? metadata.paperclip : {}),
     skillKey: skill.key,
     slug: skill.slug,
+    ...(catalogProvenance ? { catalog: catalogProvenance } : {}),
   };
   const frontmatter = {
     ...parsed.frontmatter,
@@ -2668,10 +2684,17 @@ function buildManifestFromPackageFiles(
       normalizedMetadata = {
         sourceKind: "url",
       };
-    } else if (metadata) {
-      normalizedMetadata = {
-        sourceKind: "catalog",
-      };
+    } else {
+      const catalogProvenance = readPortableCatalogProvenance(metadata);
+      if (catalogProvenance) {
+        sourceType = "catalog";
+        sourceRef = catalogProvenance.sourceRef;
+        normalizedMetadata = catalogProvenance.metadata;
+      } else if (metadata) {
+        normalizedMetadata = {
+          sourceKind: "catalog",
+        };
+      }
     }
     const key = deriveManifestSkillKey(frontmatter, slug, normalizedMetadata, sourceType, sourceLocator);
 

server/src/services/portable-path.ts

@@ -0,0 +1,12 @@
+export function normalizePortablePath(input: string) {
+  const parts: string[] = [];
+  for (const segment of input.replace(/\\/g, "/").replace(/^\.\/+/, "").replace(/^\/+/, "").split("/")) {
+    if (!segment || segment === ".") continue;
+    if (segment === "..") {
+      if (parts.length > 0) parts.pop();
+      continue;
+    }
+    parts.push(segment);
+  }
+  return parts.join("/");
+}

server/src/services/skills-catalog.ts

@@ -0,0 +1,201 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  CatalogSkill,
+  CatalogSkillFileDetail,
+  CatalogSkillListQuery,
+} from "@paperclipai/shared";
+import { HttpError, conflict, notFound } from "../errors.js";
+import { normalizePortablePath } from "./portable-path.js";
+
+interface CatalogManifestFile {
+  packageName: string;
+  packageVersion: string;
+  skills: CatalogSkill[];
+}
+
+const serviceDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(serviceDir, "../../..");
+const catalogPackageRoot = path.join(repoRoot, "packages/skills-catalog");
+const catalogManifestPath = path.join(catalogPackageRoot, "generated/catalog.json");
+let cachedCatalogManifest: {
+  manifest: CatalogManifestFile;
+  mtimeMs: number;
+  size: number;
+} | null = null;
+
+function loadCatalogManifest(): CatalogManifestFile {
+  if (!existsSync(catalogManifestPath)) {
+    throw new Error(
+      `Skills catalog manifest not found at ${catalogManifestPath}. Run pnpm --filter @paperclipai/skills-catalog build:manifest.`,
+    );
+  }
+  return JSON.parse(readFileSync(catalogManifestPath, "utf8")) as CatalogManifestFile;
+}
+
+function getCatalogManifest() {
+  if (!existsSync(catalogManifestPath)) {
+    throw new Error(
+      `Skills catalog manifest not found at ${catalogManifestPath}. Run pnpm --filter @paperclipai/skills-catalog build:manifest.`,
+    );
+  }
+  const stats = statSync(catalogManifestPath);
+  if (
+    cachedCatalogManifest &&
+    cachedCatalogManifest.mtimeMs === stats.mtimeMs &&
+    cachedCatalogManifest.size === stats.size
+  ) {
+    return cachedCatalogManifest.manifest;
+  }
+
+  const manifest = loadCatalogManifest();
+  cachedCatalogManifest = {
+    manifest,
+    mtimeMs: stats.mtimeMs,
+    size: stats.size,
+  };
+  return manifest;
+}
+
+function getCatalogSkills() {
+  const catalogManifest = getCatalogManifest();
+  return catalogManifest.skills.map((skill) => ({
+    ...skill,
+    packageName: catalogManifest.packageName,
+    packageVersion: catalogManifest.packageVersion,
+  }));
+}
+
+function isMarkdownPath(filePath: string) {
+  const fileName = path.posix.basename(filePath).toLowerCase();
+  return fileName === "skill.md" || fileName.endsWith(".md");
+}
+
+function inferLanguageFromPath(filePath: string) {
+  const fileName = path.posix.basename(filePath).toLowerCase();
+  if (fileName === "skill.md" || fileName.endsWith(".md")) return "markdown";
+  if (fileName.endsWith(".ts")) return "typescript";
+  if (fileName.endsWith(".tsx")) return "tsx";
+  if (fileName.endsWith(".js")) return "javascript";
+  if (fileName.endsWith(".jsx")) return "jsx";
+  if (fileName.endsWith(".json")) return "json";
+  if (fileName.endsWith(".yml") || fileName.endsWith(".yaml")) return "yaml";
+  if (fileName.endsWith(".sh")) return "bash";
+  if (fileName.endsWith(".py")) return "python";
+  if (fileName.endsWith(".html")) return "html";
+  if (fileName.endsWith(".css")) return "css";
+  return null;
+}
+
+function resolveCatalogPackageRoot() {
+  return catalogPackageRoot;
+}
+
+function searchText(skill: CatalogSkill) {
+  return [
+    skill.id,
+    skill.key,
+    skill.slug,
+    skill.name,
+    skill.description,
+    skill.category,
+    skill.kind,
+    ...skill.recommendedForRoles,
+    ...skill.tags,
+  ].join("\n").toLowerCase();
+}
+
+export function listCatalogSkills(query: CatalogSkillListQuery = {}): CatalogSkill[] {
+  const normalizedQuery = query.q?.trim().toLowerCase() ?? "";
+  return getCatalogSkills()
+    .filter((skill) => !query.kind || skill.kind === query.kind)
+    .filter((skill) => !query.category || skill.category === query.category)
+    .filter((skill) => !normalizedQuery || searchText(skill).includes(normalizedQuery))
+    .sort((left, right) => left.name.localeCompare(right.name) || left.key.localeCompare(right.key));
+}
+
+export function resolveCatalogSkillReference(reference: string): { skill: CatalogSkill | null; ambiguous: boolean } {
+  const trimmed = reference.trim();
+  if (!trimmed) return { skill: null, ambiguous: false };
+  const catalogSkills = getCatalogSkills();
+
+  const exact = catalogSkills.find((skill) => skill.id === trimmed || skill.key === trimmed);
+  if (exact) return { skill: exact, ambiguous: false };
+
+  const slugMatches = catalogSkills.filter((skill) => skill.slug === trimmed);
+  if (slugMatches.length === 1) return { skill: slugMatches[0]!, ambiguous: false };
+  if (slugMatches.length > 1) return { skill: null, ambiguous: true };
+  return { skill: null, ambiguous: false };
+}
+
+export function getCatalogSkillOrThrow(reference: string): CatalogSkill {
+  const result = resolveCatalogSkillReference(reference);
+  if (result.ambiguous) {
+    throw conflict(`Catalog skill slug "${reference}" is ambiguous. Use an id or key.`);
+  }
+  if (!result.skill) {
+    throw notFound("Catalog skill not found");
+  }
+  return result.skill;
+}
+
+export async function readCatalogSkillFile(
+  reference: string,
+  relativePath = "SKILL.md",
+): Promise<CatalogSkillFileDetail> {
+  const skill = getCatalogSkillOrThrow(reference);
+  const normalizedPath = normalizePortablePath(relativePath || "SKILL.md");
+  const fileEntry = skill.files.find((entry) => entry.path === normalizedPath);
+  if (!fileEntry) {
+    throw notFound("Catalog skill file not found");
+  }
+
+  const packageRoot = resolveCatalogPackageRoot();
+  const absolutePath = path.resolve(packageRoot, skill.path, normalizedPath);
+  const skillRoot = path.resolve(packageRoot, skill.path);
+  if (absolutePath !== skillRoot && !absolutePath.startsWith(`${skillRoot}${path.sep}`)) {
+    throw notFound("Catalog skill file not found");
+  }
+
+  if (fileEntry.kind === "asset") {
+    throw new HttpError(415, "Catalog asset previews are not supported.");
+  }
+
+  const content = await fs.readFile(absolutePath, "utf8");
+  return {
+    catalogSkillId: skill.id,
+    path: normalizedPath,
+    kind: fileEntry.kind,
+    content,
+    language: inferLanguageFromPath(normalizedPath),
+    markdown: isMarkdownPath(normalizedPath),
+  };
+}
+
+export async function copyCatalogSkillFile(reference: string, relativePath: string, targetPath: string): Promise<void> {
+  const skill = getCatalogSkillOrThrow(reference);
+  const normalizedPath = normalizePortablePath(relativePath || "SKILL.md");
+  const fileEntry = skill.files.find((entry) => entry.path === normalizedPath);
+  if (!fileEntry) {
+    throw notFound("Catalog skill file not found");
+  }
+
+  const packageRoot = resolveCatalogPackageRoot();
+  const absolutePath = path.resolve(packageRoot, skill.path, normalizedPath);
+  const skillRoot = path.resolve(packageRoot, skill.path);
+  if (absolutePath !== skillRoot && !absolutePath.startsWith(`${skillRoot}${path.sep}`)) {
+    throw notFound("Catalog skill file not found");
+  }
+
+  await fs.copyFile(absolutePath, targetPath);
+}
+
+export function getCatalogPackageMetadata() {
+  const catalogManifest = getCatalogManifest();
+  return {
+    packageName: catalogManifest.packageName,
+    packageVersion: catalogManifest.packageVersion,
+  };
+}

server/src/services/workspace-runtime.ts

@@ -691,6 +691,12 @@ async function isGitCheckout(cwd: string): Promise<boolean> {
 }
 
 async function detectDefaultBranch(repoRoot: string): Promise<string | null> {
+  const originMasterRef = "origin/master";
+  await refreshRemoteTrackingBaseRef(repoRoot, originMasterRef);
+  if (await resolveBaseRefSha(repoRoot, originMasterRef)) {
+    return originMasterRef;
+  }
+
   // Try the explicit remote HEAD first (set by git clone or git remote set-head)
   try {
     const remoteHead = await runGit(