PaperClipAI/maps/feature-map/companies.md

navigation

navigation
section sectionOrder order Getting started and access 10 30

Companies and portability

An operator can switch between companies, change their identity and settings, archive them, and preview an import or export. Each company remains a separate scope for work and agents.

Feature ID: companies.

Implementation: companies, settings, import, export.

Agent access: companion.

Sub-features

• selection: companies/selection — create/select a company and keep navigation in its scope.
• identity: companies/identity — update company identity and configured settings.
• decision-models: companies/decision-models — configure and test the company's decision model, then inspect invocation history and recorded usage.
• prompt-injection-prevention: companies/prompt-injection-prevention — opt into a shared OpenRouter classifier for existing tool-result guards, test fixed samples, and recover unavailable selections.
• fast-responses: companies/fast-responses — configure and test the experimental fast-response service, then inspect acknowledgement history, failures, and recorded usage.
• agent-observability: companies/agent-observability — configure one company OTLP destination for Codex and Claude Code, test synthetic delivery, and disable export.
• archive: companies/archive — archive and restore through the available controls without confusing archival with deletion.
• portability: companies/portability — preview a company package and inspect imported agents, projects, skills, and conflicts.

How to get to it (user POV)

company-switcher

Use the company switcher or /companies, then enter company Settings.

package-transfer

Use /company/export and /company/import where enabled, or the corresponding CLI company commands.

company-ai-services

Use Settings → Connections (/company/settings/connections) for Decision model and Prompt Injection Prevention, independent of experimental flags. Fast response appears there only when its experiment is enabled. Open the Decisions and Fast responses tabs in Costs to inspect invocation history.

Driving it with Playwright and the Paperclip CLI

Preconditions: follow the baseline. Use two disposable companies and a small package fixture. Record cloud-managed restrictions and visible settings gates.

company-switcher

Automated: company list and archive UI cover UI behavior with mocks.

Manual: Create or select a company, rename it, and reload. Switch to the second company and back; verify tasks, agents, and settings follow the selection. Archive the disposable company and verify its visibility and offered restoration path.

package-transfer

Automated: portability routes and CLI import/export cover package and command behavior, not every external Git host.

Manual: Export a small company, inspect the package preview, and import into a disposable target. Verify counts, references, conflict choices, and agent configuration. Run one imported task after supplying its required local credentials. Confirm source company data is unchanged.

company-ai-services

Automated: decision settings, decision history, fast-response settings, decision service, and fast-response service cover component and service contracts with simulated providers.

Manual: As an authorized connection manager, select a disposable shared AI connection, save the provider/model and sponsorship options, reload, and run the bounded Test action. Inspect success and failure receipts and their history in Costs. Verify disabled or revoked connections remain clear and that a user without connection-management permission cannot configure or test the service. Use an owned provider fixture for failure states; record any actual provider usage.

Gotchas

• Restore an archived company through /companies → its menu → Unarchive. Archiving pauses eligible agents and cancels active runs; restoration handles agents paused specifically for company archival.

• Package presence does not prove a runnable imported company; credentials and environment bindings need separate verification.

• Company deletion is a distinct gated operation; do not use it as the archive test.

• Settings hidden in a managed deployment should be recorded as unavailable, not bypassed.

• Decision tests and fast responses have different request and execution contracts. A fast-response receipt is an acknowledgement, not completed agent work. History visibility and connection-management authority are separate; task links in history also require access to the underlying task.

Storybook verification

selection

Capability ID: companies/selection.

Scope: ui Storybook: Company list/create/switcher; empty, loading, error, unavailable company and switched navigation. Production: Switch and reload between companies; verify tasks/agents/cache/routes remain scoped and unauthorized company requests fail. Sources: Source: Companies.tsx, CompanySwitcher.tsx, CompanyContext.tsx. Tests: Companies.test.tsx, CompanyContext.test.tsx, companies-route-cross-company-authz.test.ts

archive

Capability ID: companies/archive.

Scope: ui Storybook: Archive confirmation, pending/error and departure navigation; archived list entry and Unarchive action. Production: Archive eligible agents/runs without deleting history; restoration handles archival-specific pause and navigates to correct company. Sources: Source: CompanySettings.tsx, Companies.tsx, companies.ts. Tests: CompanySettingsArchive.test.tsx, Companies.test.tsx, companies-service.test.ts

portability

Capability ID: companies/portability.

Scope: ui Storybook: Import/export preview, conflict choice, warnings, async progress/failure/success and restricted managed deployment. Production: Apply real small package to disposable target; inspect counts/references/conflicts, source immutability and credential exclusions; imported task requires separate runnable-account proof. Sources: Source: CompanyImport.tsx, CompanyExport.tsx, companies.ts. Tests: CompanyImport.test.tsx, CompanyExport.test.tsx, company-portability-routes.test.ts, company-import-export-e2e.test.ts

Documentation scope: Company and instance administration

Core administration/import/export/operator workflows are mapped; cloud/self-hosted differences, migration/restore compatibility, and platform-specific service variants need deeper recipes.

agent-observability

Use Company Settings → General → Agent observability. Select Braintrust or Custom OTLP, save credentials and capture settings, then test the saved destination. Saving is offline; the test originates at the control plane and does not prove remote runner reachability.

Automated: shared validation, encrypted configuration service, receiver tests, runtime projection, and production settings stories cover their respective boundaries. Provider delivery requires a real run.

Manual: configure a disposable company, reload, test, run Codex and Claude Code locally and remotely, inspect their unique markers at the destination, then disable and verify a new marker is absent.

Storybook verification: agent-observability-01-settings, agent-observability-02-states, and agent-observability-03-journey mount production subjects with simulated APIs/providers.

prompt-injection-prevention

Capability ID: companies/prompt-injection-prevention.

Scope: ui, api, runtime Storybook: Production PromptInjectionPreventionSettingsView states under Companies and portability → Prompt Injection Prevention. Provider data is simulated. Automated: settings, service, gateway, guards including redaction that hides content still delivered under the existing return contract. Manual: Open Connections with Fast Responses off, save a shared OpenRouter connection/default model, reload, run both fixed samples, and inspect charges. Verify benign code reaches a gateway caller, malicious instructions are blocked, provider failure records regex fallback, and disabling makes no model call. Root results with concealed instruction text use input_redaction_mismatch fallback without model dispatch.