# Universal Company OS packs

Company OS packs are portable operating-system packages for a company. A pack
describes memory, workflows, document profiles, policies, connectors,
automations, onboarding, and tests. It is not a prompt dump and it is not an
authority boundary.

## Runtime resolution

```text
authenticated principal + active company
        ↓
company profile, role, locale, and host policy
        ↓
active installed packs
        ↓
deterministic company / industry / task / locale / role matching
        ↓
exact connector and data-scope intersection
        ↓
digest-addressed governed context bundle
        ↓
AI proposes an answer or action
        ↓
existing Company OS effect + approval gateway
        ↓
evidence, decision, commitment, exception, and audit ledgers
```

The pack resolver does not use semantic similarity to decide authorization.
Semantic retrieval can help find relevant content after admission, but tenant
identity, role permissions, connector bindings, policy, approval, and ledger
authority remain host-owned.

## Contract

The machine-readable manifest is
[`schemas/company_os_pack_manifest.v1.json`](../../schemas/company_os_pack_manifest.v1.json)
and the Rust wire type is `hsm_api_contract::PackManifest`.

```json
{
  "schema": "hsm.company_os.pack_manifest.v1",
  "kind": "company-os-pack",
  "id": "example.property-management",
  "version": "1.0.0",
  "publisher": "example",
  "name": "Example Property Management",
  "industries": ["property-management"],
  "locales": ["fr-CA", "en-CA"],
  "supportedTasks": ["prepare_board_minutes"],
  "requiredApprovals": ["board_document_distribution"],
  "connectors": ["document-storage", "calendar"],
  "requires": ["document-storage", "calendar"],
  "dataScopes": ["company.profile", "meetings.read"],
  "riskLevels": {"prepare_board_minutes": "medium"},
  "conflictsWith": [],
  "compatibleCompanyOs": ">=1.0.0",
  "tests": ["tests/board-minutes-fr-ca.json"],
  "retention": {"meeting_records": "7y"}
}
```

Unknown fields are rejected. In particular, a pack cannot add `permissions`,
`grants`, credentials, bearer tokens, or secret values to the manifest. The
`connectors`, `requires`, and `dataScopes` fields are requests only.

Each compiled bundle records pack/version digests, policy digests, source
provenance, requested versus granted scopes, permissions actually used,
omitted sections, missing-information warnings, a sensitivity ceiling, byte
and token limits, and an expiry timestamp. The AI receives that bounded
artifact rather than the full company memory.

## Embedding surfaces

The implementation is intentionally provider-neutral:

- Rust runtime: `company_os_core::pack::{resolve_packs, compile_context_bundle}`
- JSON/YAML offline CLI: `company-os pack validate|preview|test|export`
- API boundary: `hsm-api-contract::PackManifest` and `PackContextBundle`
- Durable registry: `GET|POST /api/company/companies/{company_id}/packs`
- Task resolution: `GET /api/company/companies/{company_id}/packs/resolve?task=...`
- existing Company OS extension contracts for connector execution and effects
- existing policy/approval gateway for consequential actions

An SDK or React/web-component embedder should call the host context compiler
and render the returned bundle/proposal state. It must not construct grants or
execute connectors directly. This keeps local, server, cloud, and hosted
embeddings on the same authority model.

The authenticated registry accepts a manifest plus optional declared UTF-8
content files. Manifest versions are immutable; activation and precedence live
in a separate binding. The host validates content paths, rejects secret-looking
files/markers, derives connector availability from configured company
connectors, and records the installation receipt. Reinstalling the same
`company_id + pack_id + version` with different bytes is refused.

## Gestion Velora reference implementation

The first pack is at
[`packs/gestion-velora-property-management`](../../packs/gestion-velora-property-management/).
It preserves the established Gestion Velora document system while making the
adaptation explicit:

- `Velora Core` for invoices, contracts, board documents, and procès-verbaux;
- `Modern Editorial` for offerings, presentations, and proposals;
- `Premium Property` for property and board presentations;
- `Operations Grid` for verification packs and operating reports.

The pack references the existing Velora brand profile instead of copying
private building, customer, banking, or connector data. When another company
installs the universal pack, Company OS keeps the structural format and
replaces the identity, logo, language, legal profile, connectors, scopes, and
approval policy only after the company setup flow confirms them.

## CLI truthfulness

```bash
bash scripts/company-os pack validate packs/gestion-velora-property-management
bash scripts/company-os pack preview packs/gestion-velora-property-management \
  --task prepare_board_minutes --scope company.profile
bash scripts/company-os pack test packs/gestion-velora-property-management
bash scripts/company-os pack export packs/gestion-velora-property-management \
  --redact --out /tmp/pack-export.json
```

The offline CLI does not silently mutate a server. Install/deploy should use
the authenticated registry route with a transport bearer and a separate
principal token; the pack still cannot grant either credential or activate its
own permissions. A future CLI transport adapter can call that route, but
validation/preview/test/export remain safe without server credentials.