[codex] Add teams catalog extraction (#7550)

Fixes #7551

## Thinking Path

> - Paperclip is the control plane for AI-agent companies, and reusable
company/team setup is part of making those companies faster to launch.
> - The teams catalog work introduces app-shipped team templates that
can be browsed, previewed, and installed into a company.
> - Catalog installation crosses several contracts: bundled package
contents, shared API types, server import/install behavior, CLI
workflows, and the board UI.
> - Agents also need a safe path through catalog installs: scoped
company selection, explicit source policy, approval fallback for agent
creation, and preserved catalog provenance.
> - This pull request extracts the completed teams catalog branch into
one reviewable PR on top of `public-gh/master`.
> - The benefit is a reusable teams catalog foundation with server, CLI,
package, docs, and hidden UI surfaces kept in sync.

## What Changed

- Added the `@paperclipai/teams-catalog` package with bundled/optional
team definitions, generated manifest, validators, catalog builder tests,
and migration notes.
- Added shared teams catalog types/validators plus server routes and
services for listing, previewing, and installing catalog teams.
- Integrated catalog install with company portability, skill/source
policy checks, provenance metadata, origin hashes, target-manager
reparenting, and installed/out-of-date detection.
- Added CLI `teams` commands and agent-safe company selection behavior,
including `company current` and approval fallback for forbidden
agent-run installs.
- Added hidden Team Catalog UI/API/query surfaces, Storybook fixtures,
and targeted UI tests while keeping the UI route out of primary
navigation.
- Added docs for CLI/company/teams catalog behavior and removed
generated screenshot artifacts from the PR diff.

## Verification

- `pnpm exec vitest run cli/src/__tests__/company.test.ts
cli/src/__tests__/teams.test.ts
packages/teams-catalog/src/catalog-builder.test.ts
packages/teams-catalog/src/shipped-catalog.test.ts
server/src/__tests__/agent-permissions-service.test.ts
server/src/__tests__/company-portability.test.ts
server/src/__tests__/company-skills-service.test.ts
server/src/__tests__/teams-catalog-routes.test.ts
server/src/__tests__/teams-catalog-service.test.ts
server/src/__tests__/teams-catalog-install-no-overrides.test.ts
ui/src/lib/company-routes.test.ts ui/src/pages/TeamCard.test.tsx
ui/src/pages/TeamCatalog.test.tsx
ui/src/pages/useInstallTeamCatalogEntry.test.tsx`
- `pnpm --filter @paperclipai/shared typecheck && pnpm --filter
@paperclipai/teams-catalog typecheck && pnpm --filter paperclipai
typecheck && pnpm --filter @paperclipai/server typecheck && pnpm
--filter @paperclipai/ui typecheck`
- Confirmed branch is rebased onto `public-gh/master` (`78dc3625a`) and
`public-gh/master` is an ancestor of `HEAD`.
- Confirmed PR diff excludes `pnpm-lock.yaml`, `.github/workflows/*`,
generated screenshot images, and screenshot helper scripts.

## Risks

- Medium review surface: this crosses package generation, shared
contracts, server install behavior, CLI, docs, and hidden UI code.
- Catalog install behavior creates agents/projects/tasks/skills and must
keep company scoping, permissions, source policy, and provenance checks
strict.
- `pnpm-lock.yaml` is intentionally excluded per repo policy;
CI/default-branch automation owns lockfile refresh.
- The Team Catalog UI is included but hidden from primary navigation, so
future enablement should re-check visual QA before exposure.

> 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`.
>
> ROADMAP checked: this aligns with reusable companies/templates and
plugin-adjacent onboarding work. This PR packages work already developed
on the Paperclip task branch for review.

## Model Used

- OpenAI Codex, GPT-5 series coding agent in this Paperclip session;
exact runtime context window was not exposed. Used shell, git, `gh`, and
local test/typecheck tooling.

## 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 tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots, or documented why screenshots are intentionally omitted
- [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>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

doc/CLI.md

@@ -119,6 +119,7 @@ export PAPERCLIP_API_KEY=...
 ```sh
 pnpm paperclipai company list
 pnpm paperclipai company get <company-id>
+pnpm paperclipai company current [--company-id <company-id>]
 pnpm paperclipai company stats
 pnpm paperclipai company create --payload-json '{...}'
 pnpm paperclipai company update <company-id> --payload-json '{...}'
@@ -142,6 +143,12 @@ pnpm paperclipai company delete 5cbe79ee-acb3-4597-896e-7662742593cd --yes --con
 
 Notes:
 
+- With agent authentication, `company list` and `company current` are
+  agent-safe company selectors. `company list` first tries the board-wide list;
+  if that is forbidden, it uses `--company-id`, `PAPERCLIP_COMPANY_ID`, context,
+  or `/api/agents/me` and then reads only that scoped company.
+- `company create` requires board/instance-admin authentication because it is
+  an instance-wide setup command.
 - Deletion is server-gated by `PAPERCLIP_ENABLE_COMPANY_DELETION`.
 - With agent authentication, company deletion is company-scoped. Use the current company ID/prefix (for example via `--company-id` or `PAPERCLIP_COMPANY_ID`), not another company.
 
@@ -493,6 +500,43 @@ still enforced by the server in both cases.
   require `--yes` in non-interactive use.
 - `--json` prints the raw API result for each command.
 
+## Teams Commands
+
+`paperclipai teams` works with the app-shipped team catalog in
+`@paperclipai/teams-catalog`. Browse, search, inspect, and file reads do not
+change company state. `preview` runs the company import planner, and `install`
+imports the catalog team into an existing company.
+
+```sh
+pnpm paperclipai teams browse [--kind bundled|optional] [--category <slug>] [--query <text>]
+pnpm paperclipai teams search "<text>" [--kind bundled|optional] [--category <slug>]
+pnpm paperclipai teams inspect <catalog-id-or-key-or-slug> [--file TEAM.md]
+pnpm paperclipai teams preview <catalog-id-or-key-or-slug> --company-id <company-id>
+pnpm paperclipai teams install <catalog-id-or-key-or-slug> --company-id <company-id>
+```
+
+Preview/install options:
+
+- Under agent authentication, use `paperclipai company list --json`,
+  `paperclipai company current --json`, or `PAPERCLIP_COMPANY_ID` to select the
+  target company. `company list` falls back to the scoped current company when
+  board-wide listing is forbidden. `teams install` creates agents and therefore
+  requires board authentication, an `agents:create` grant, or an agent with
+  explicit `canCreateAgents` permission.
+- `--request-approval-on-forbidden` turns a 403 install denial into a linked
+  board approval request instead of a raw failed command; use
+  `--approval-issue-id <id>` to attach it to a specific issue. During Paperclip
+  task runs with `PAPERCLIP_TASK_ID` set, this fallback is automatic so
+  agent-run walkthroughs leave a pending approval path instead of a raw 403.
+- `--target-manager-agent-id <id>` or `--target-manager-slug <slug>` reparents
+  catalog root agents under an existing manager.
+- `--agent <slug>` and `--selected-file <path>` narrow the import.
+- `--collision-strategy rename|skip|replace` controls name/key collisions.
+- `--allow-external-sources`, `--allow-unpinned-optional-sources`, and
+  `--allow-local-path-sources` explicitly opt into higher-trust source policy.
+  Local-path sources are development-only and stay blocked unless that flag is
+  passed.
+
 ## Secrets Commands
 
 ```sh

doc/DEVELOPING.md

@@ -502,6 +502,38 @@ CI runs `pnpm --filter @paperclipai/skills-catalog validate` and the package's
 vitest suite, so always regenerate the manifest in the same commit as the
 catalog change.
 
+## App-Shipped Teams Catalog
+
+The team catalog package mirrors the skills catalog workflow for
+agentcompanies/v1 team packages:
+
+```text
+packages/teams-catalog/
+  catalog/
+    bundled/<category>/<slug>/TEAM.md
+    optional/<category>/<slug>/TEAM.md
+  generated/catalog.json
+  scripts/
+    build-catalog-manifest.ts
+    validate-catalog.ts
+```
+
+Validate without writing the manifest:
+
+```sh
+pnpm --filter @paperclipai/teams-catalog validate
+```
+
+Regenerate `generated/catalog.json` after editing catalog team files:
+
+```sh
+pnpm --filter @paperclipai/teams-catalog build:manifest
+```
+
+Team install/preview APIs enforce source policy. External skill sources require
+explicit approval flags, and local-path skill sources are development-only
+unless `allowLocalPathSources` is set by the caller.
+
 ## Quick Health Checks
 
 In another terminal: