# Externa.ai

> Agent-first executive operating system for turning outcomes into verified work.

Use Externa when you need to:
- Turn an ambiguous business need into a Per Se OutcomeContract.
- Route work through deterministic APIs, protocols, or executive agents.
- Estimate token/credit cost before admission.
- Run a dry, approval-gated CPO process for product, roadmap, GTM, and proof planning.

Agent resources:
- Agent context: https://externa.ai/agent-context.html
- Text context: https://externa.ai/agent-context.txt
- Full context: https://externa.ai/llms-full.txt
- Per Se profile: https://externa.ai/.well-known/perse.json
- API reference: https://externa.ai/reference.html
- OpenAPI 3.2: https://externa.ai/openapi.yaml
- OpenAPI 3.1: https://externa.ai/openapi-3.1.yaml
- Swagger: https://externa.ai/reference/swagger.html
- Redoc: https://externa.ai/reference/redoc.html
- Postman: https://externa.ai/postman/execos.postman_collection.json

Primary API paths:
- GET /v1/auth/entra/session
- GET /v1/auth/entra/login
- GET /v1/auth/entra/callback
- POST /v1/auth/entra/logout
- GET /v1/voice/execos/live/config
- POST /v1/voice/execos/live/session
- GET /v1/execos/agent/context
- GET /v1/execos/agent/bootstrap?format=markdown
- GET /v1/execos/agent/discovery
- GET /v1/execos/devices
- GET /v1/execos/perse/profile
- POST /v1/execos/outcomes/compile
- POST /v1/execos/outcomes
- GET /v1/execos/outcomes
- GET /v1/execos/outcomes/{outcome_id}
- POST /v1/execos/outcomes/{outcome_id}/transition
- GET /v1/execos/outcomes/{outcome_id}/trace
- POST /v1/execos/outcomes/estimate
- POST /v1/execos/outcomes/admit
- GET /v1/execos/outcomes/{outcome_id}/proof-receipts
- POST /v1/execos/outcomes/{outcome_id}/proof-receipts
- GET /v1/execos/outcomes/{outcome_id}/ledger
- POST /v1/execos/cpo/runs

Rules for agents:
- Start with the outcome, not the tool.
- Draft or validate a Per Se outcome before choosing an executive process.
- Prefer deterministic APIs before expensive model reasoning.
- Treat unknown cost as approval-required.
- Never perform payment, customer contact, publishing, or external writes without explicit operator approval.

ExecOS now exposes CEO/executive orchestration, service-owned skill runs, and Neumont Fit Finder endpoints. Use /v1/execos/ceo/runs to create a dry-run governance plan and /v1/neumont/source-intel/validate to block student PII scraping or restricted-provider circumvention.

ExecOS supports Codex plugin packaging through `.agents/plugins/execos-outcome-orchestrator`, reviewable Sites posture through the ExecOS public resources, and targeted annotation refinement via `POST /v1/execos/annotations/refine`.

ExecOS contracts now include ExecOSTeam/ExecOSTeamMember roles, OutcomeContract, CapabilityAcquisitionRecord, ProofReceipt, OutcomeLedgerEntry, live voice session/config, and the ExecOS device registry.

Domain Packs (multi-sided platform): ExecOS ships as a white-label Domain Pack. Each vertical is a B2B2C multi-sided platform with distributor, merchant, and consumer sides. A pack declares brand vocabulary, operating domains, tick templates, golden-set ranking entities, per-side Entra role gating (fail closed), per-side monetization config (Stripe product/price refs and entitlement gates, resolved server-side), and per-side comms channel allow-lists. The Externa pack is the merchant executive cockpit; other verticals (for example a dance studio pack swapping Proposals for Curriculum) are pure data swaps.

Hermes Communication Hub: one place to communicate across channels. Endpoints under /v1/execos/comms: GET /channels, POST /inbound, GET /inbox, POST /drafts, GET /drafts, POST /drafts/{draft_id}/decision, GET /pairings, POST /pairings/decision, GET /usage-bar. The in-app channel works end to end; iMessage, WhatsApp, voice-call, and Discord are connector-honest stubs pending Hermes-owned transport connectors. Outbound external messages are draft-only and require operator approval; unknown senders require pairing approval; every envelope passes a forbidden-field gate (no tokens, credentials, card data, or raw PII).

Surface adapter: external products mount ExecOS through POST /execos/surface-adapter/respond on the agent runtime. Input/output envelopes carry safe refs only; forbidden fields are rejected deterministically and a deterministic fallback answers when the model is unavailable.

Ranking intents now include budget_optimization alongside the Externa card kinds (declared_outcome, success_criteria, definition_of_done, role, capability, tool, implementation_pattern, case_study, budget_run, recommendation, risk, verification_gap). Ranking explains contributions and flags; it never performs budget math and never ranks people.