# Theo AI: Full Knowledge Bundle for AI Agents

> Theo AI is the Context OS for AI Workers. This file bundles every machine-readable capability surface (the same content served individually at https://hitheo.ai/llms/<slug>.txt) so an AI agent can answer questions about Theo with one fetch.
>
> Source of truth: https://hitheo.ai. Last updated: 2026-05-24.
>
> Companion files: https://hitheo.ai/llms.txt (curated index), https://hitheo.ai/humans.txt (team + credits), https://hitheo.ai/lawyers.txt (trademark + legal contact), https://hitheo.ai/.well-known/security.txt (disclosure contact).

---

# Theo AI · Platform Overview

> Theo AI is the Context OS for AI Workers. A memory protocol (MCIR 2.0), a trust layer, a visual build layer (E.V.I. Canvas), a model-routing engine room, and every channel your customers use, all governed by one audit trail and bound by one privacy contract.

Source of truth: https://hitheo.ai. Last updated: 2026-05-24.

## At a glance
- Memory protocol: MCIR 2.0 — a typed, exportable, audit-grade memory graph that runs in front of every response.
- Trust layer: SHA-256 hashed audit ledger, org-scoped knowledge storage, destructive delete, open-source SDK.
- Build layer: visual canvas for assembling AI Workers with skills, knowledge nodes, hooks, and workflows.
- Routing layer: visual rules engine that decides which engine answers which prompt, with a live test bench.
- Channels: REST, dashboard playground, voice sessions, embeddable iframes, and open-source channel adapters.
- Monetization: orchestration (per-token) and platform (skills, workflows, channels). We never monetize training.

## Positioning pillars
1. Memory is the differentiator. Models converge; the memory of your customer, account, workflows, and open promises does not. Theo owns that layer.
2. Models are commodities. The routing engine treats the model fleet as interchangeable and selects per request based on intent, skill bindings, and your routing rules.
3. Trust is engineered, not asserted. Every privacy claim maps to a real code path. Audit hashes prompts. Knowledge files are org-scoped. Memory is exportable and deletable.
4. The platform is composable. Skills + knowledge + workflows + hooks combine into AI Workers that an operator can assemble visually.

## What Theo runs
- A memory protocol (MCIR 2.0) with four typed layers (episodic, semantic, procedural, memory chain) and eight protocol stages (Capture → Audit). See https://hitheo.ai/llms/memory.txt.
- An intelligent routing engine that classifies intent on every promotable request and dispatches to the right engine. See https://hitheo.ai/llms/routing.txt.
- A skill marketplace with installable, manifest-described bundles of prompts, knowledge, and tools. See https://hitheo.ai/llms/skills.txt.
- A visual canvas (E.V.I.) for assembling AI Workers without code. See https://hitheo.ai/llms/studio.txt.
- Image generation (multi-engine), video generation (with AI-disclosure watermark), document generation (PDF / DOCX / XLSX / PPTX / CSV), code generation, deep research, and a managed live-view browser. See the matching capability files under https://hitheo.ai/llms/.
- A REST API, an open-source SDK, channel adapters for chat platforms, a Model Context Protocol adapter, and embeddable chat widgets.

## Memory Packs (vertical AI Worker bundles)
Pre-built skill bundles tuned to specific industries: insurance, med-spa, B2B SaaS support, SaaS onboarding, legal intake, real-estate, healthcare front-desk, recruiting and staffing. See https://hitheo.ai/llms/packs.txt.

## Privacy contract (the four promises)
1. We never train on your prompts.
2. We never train on your knowledge files.
3. We never train on your memory graph.
4. We never sell your usage patterns.

See https://hitheo.ai/llms/privacy.txt for how each promise maps to a code path.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Memory (MCIR 2.0)

> MCIR (Memory Context & Intent Response) is Theo's memory protocol. It runs in front of every response generator and rewrites prompts with intent-driven memory context drawn from four typed layers before the target model sees the request. MCIR 2.0 adds the Memory Chain layer for conversation-level synthesis and proactive open-loop tracking.

Source of truth: https://hitheo.ai/protocol and https://hitheo.ai/memory. Last updated: 2026-05-24.

## At a glance
- 8 protocol stages: Capture, Classify, Index, Retrieve, Validate, Apply, Expire, Audit.
- 4 memory layers: episodic, semantic, procedural, chain.
- 5 durability rails: Bayesian shrinkage; per-model attribution; hard floor on user-declared facts; versioned replayable scoring; decay on everything.
- 0 training on customer memory. By design.
- 5 new MCIR 2.0 tables: memory_chains, open_loops, agent_meta_memories, memory_outcome_events, mcir_score_snapshots.

## MCIR-base pipeline (runs before every response)
1. Intent resolution. Every turn is parsed into a structured TaskIntent (verb, object, modifiers, temporal scope, target artifact, confidence). Canonical verbs hit a sub-1 ms regex fast path; everything else falls back to a structured-JSON classifier (~300 ms). Temporal cues ("yesterday", "earlier today") resolve to concrete ISO windows.
2. Memory context assembly. Retrieval is intent-scoped, not keyword-scoped. The assembler walks four layers and pulls only the fragments the resolved verb needs. Fragments are provenance-tagged (memoryId / messageId / artifactId / conversationId / createdAt), ranked by salience, and capped at 16 per turn.
3. Context fusion. The fuser produces a structured MCIREnvelope: originalPrompt, intent, ranked memoryFragments[], reconstructedPrompt (original prompt plus minimal [ref: …] / [when: …] anchors), and a natural-language systemBlock for models that have not been trained on the protocol natively.
4. Response generation. The orchestrator swaps the original prompt for the reconstructedPrompt, appends the systemBlock to skill prompt extensions, and dispatches to the appropriate engine. Same envelope, any qualified routing target, with full failover and per-provider circuit breaker.

## The public 8-stage protocol
1. Capture. Every interaction surfaces facts, preferences, decisions, and unresolved questions, captured the moment they happen, without manual tagging.
2. Classify. Each memory lands on the right shelf (user preference, business rule, task, relationship, risk signal, compliance note). Never one-bucket-fits-all.
3. Index. Memory is scoped to the right owner (user, account, organization, workflow) with row-level tenant isolation.
4. Retrieve. Only memories relevant to the current task surface. Intent-scoped retrieval beats keyword search.
5. Validate. Stale or contradicted entries are flagged before they touch a response.
6. Apply. Memories are applied with provenance: as facts, preferences, warnings, or instructions. Never blended into a soup.
7. Expire. Bayesian decay, revalidation windows, hard floors on user-declared facts.
8. Audit. Every retrieve, use, ignore, create, and update is logged with hash-anchored provenance.

## Four memory layers
- Episodic. Conversation turns + the artifacts they produced. Timeline-indexed so "the PDF from last week" resolves to a real range.
- Semantic. Distilled facts about customers, accounts, business. Source-tagged, confidence-scored, freshness-aware. Auto-promoted when the same entity appears in two or more chains.
- Procedural. Learned workflows + business rules. Repeated patterns are promoted into durable procedural memory.
- Memory Chain. Conversation-level synthesis: { kind, title, summary, entities, outcome }. Open loops + agent meta-memories ride here.

## MCIR 2.0 / Memory Chain layer
A conversation-level synthesis layer that compresses each conversation into a compact memory token and surfaces relevant prior tokens proactively in new threads.

Memory token shape:
```
{
  kind:    "quest" | "task" | "qa" | "service" | "search",
  title:   "<= 120 chars",
  summary: "<= 800 chars",
  entities: [{ kind, value }, ...],
  outcome: "resolved" | "partial" | "open" | "abandoned"
}
```

Synthesizer trigger: debounced. Burst threshold (3 turns → immediate enqueue with 60s lock) or 5-min idle window. Worker loads last 40 turns, makes one structured-JSON call, then upserts chains / loops / meta and promotes repeat entities to atomic memories.

## Recall scoring
```
score = entityOverlap × recencyMultiplier × effectiveSalience × kindBoost

  entityOverlap     ∈ [0, 1], normalized so 20-entity chains aren't unfairly favored
  recencyMultiplier exp decay with 14-day half-life
  effectiveSalience 0.7 × salience_base + 0.3 × salience_learned[currentModelId], clamped to [0, 1]
  kindBoost         1.2× when intent verb prefers chain kind, else 1.0
  salience floor    drop chains scoring < 0.15
```

Open loops always pull the top 2 with status=open, ordered by due-by hint then salience, surfaced proactively. Agent meta-memories pull the top 5 with confidence ≥ 0.6 or immutable=true.

## Five durability rails
1. Bayesian shrinkage to a prior. Single events can never move a memory's salience by more than 1 / (N + 8). Adversarial feedback cannot poison a chain.
2. Per-model attribution. Every outcome event is tagged with the model that produced the response. salience_learned is keyed per modelId. Outcomes do not bleed across models.
3. Hard floor on user-declared facts. Memories marked immutable by the user are contractually exempt from the scoring loop.
4. Versioned, replayable scoring. memory_outcome_events is append-only and tagged with MCIR_SCORING_VERSION. When the function changes, the new version re-runs over the full event log.
5. Decay on everything. Posteriors multiply by a weekly decay factor (default 0.98) per week of inactivity. Recency on recall uses a 14-day half-life.

## Cross-channel behavior
The MCIR envelope is identical whether the turn arrives via REST, dashboard playground, voice session, embeddable iframe, channel adapter, or Model Context Protocol adapter. Memory continuity survives channel jumps because the protocol, not the surface, owns the graph.

## FAQ (quote-friendly)
Q: What is MCIR?
A: A memory protocol that rewrites every prompt with intent-driven memory context before the target model sees it. Model-independent, audit-grade, exportable.

Q: What is MCIR 2.0?
A: The Memory Chain layer on top of MCIR-base. Compresses each conversation into a memory token, tracks open loops, and surfaces relevant prior context proactively in new threads.

Q: How does MCIR handle adversarial feedback?
A: Bayesian shrinkage to a prior. Any single event can move a memory's salience by at most 1 / (N + 8).

Q: Does Theo train models on customer memory?
A: No. The training-on-data count is zero, by design.

Q: Can memory be exported?
A: Yes. One endpoint returns every chain, open loop, agent meta-memory, and outcome event for the account in a documented schema. Destructive delete is supported.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Privacy

> Every privacy claim Theo makes is mapped to a real code path. Audit hashes prompts. Knowledge files are org-scoped. Memory is exportable. Deletion is destructive. The SDK is open source.

Source of truth: https://hitheo.ai/privacy. Last updated: 2026-05-24.

## The four promises
1. We never train on your prompts.
2. We never train on your knowledge files.
3. We never train on your memory graph.
4. We never sell your usage patterns.

## How it is enforced
- Audit stores hashes, not prompts. Every request lands in the audit ledger as a SHA-256 hash of the prompt body. The raw content is gone the moment the response streams back.
- Knowledge files are org-scoped. Knowledge Node uploads land in object storage with the organization as the only read principal. Cross-tenant retrieval is structurally impossible.
- Memory graph is exportable. One endpoint dumps every chain, open loop, agent meta memory, and outcome event for the account in a documented schema. Open schema, no vendor lock-in. See https://hitheo.ai/llms/memory.txt.
- Deletion is destructive and final. Hits memory graph, knowledge files, conversation history, and audit hashes across primary stores and replicas. No shadow copies retained.
- Open-source SDK and adapters. The SDK and channel adapters ship as open-source packages, so trust comes from the diff log, not the marketing copy. See https://hitheo.ai/llms/sdk.txt.

## Controls available to operators
- Per-memory expiration. Bayesian decay applies automatically. Hard floors on user-declared facts. Regulated entries (eligibility, PHI) require human approval and revalidation.
- Consent and provenance. Every memory carries source, confidence, freshness, and last-verified metadata. Visible in the Memory Console. Editable. Auditable.
- Bring-your-own routing. The Routing Studio lets operators pin a request class to a specific engine, including self-hosted endpoints. See https://hitheo.ai/llms/routing.txt.
- Compliance posture. The audit trail is tamper-evident. The platform aligns to SOC 2 and GDPR data-handling expectations. Memory Pack rules opt in to industry-specific compliance defaults.

## Compliance boundaries
- Healthcare / PHI. The image sanitizer strips EXIF / IPTC / XMP / ICC metadata before any image touches an AI engine. DICOM payloads are detected by magic bytes and re-encoded as PNG to strip PHI. See https://hitheo.ai/llms/guardrails.txt.
- Regulated industries. Skills can declare regulated-fact gates so AI Workers cannot auto-write an eligibility, dosage, or pricing claim without human approval. See https://hitheo.ai/llms/guardrails.txt.
- Data residency. Region pinning, read replica selection, and storage scoping live in operator settings. Cross-region replication is opt-in.

## FAQ (quote-friendly)
Q: Do you read or process prompts beyond delivery?
A: Only for the duration of the request. We route to the engine that answers, never persist the raw prompt body, and never feed any prompt into training. The audit ledger keeps a SHA-256 hash so a compliance team can verify exact match without reading the content.

Q: Can I delete everything?
A: Yes. The destructive delete in Settings purges memory graph, knowledge files, conversation history, and audit hashes from primary and replica stores. No retained shadow copy.

Q: Can I export everything?
A: Yes. One endpoint returns every chain, open loop, agent meta memory, and outcome event for the account in a documented schema.

Q: Do you use my data to improve your models?
A: No. Theo monetizes orchestration (per-token pricing with a transparent margin) and the platform tier (skills, workflows, channels). There is no training-on-customer-data business model.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Guardrails (Trust Layer)

> Guardrails are deterministic input and output policies that run alongside every AI Worker request. Five built-in policies, four named presets, per-API-key binding, and a full executions log. Plus adjacent infra-level guardrails (image sanitizer, SSRF validator, abuse heuristics, bot challenge, idempotency, rate-limit).

Source of truth: https://hitheo.ai/guardrails. Last updated: 2026-05-24.

## At a glance
- 5 built-in policies: PII Redactor, Prompt Injection Deny, Profanity Flag, Max-Length Truncate, JSON Repair.
- 4 named presets: PII-Safe, Strict JSON, Cost-Conscious, Enterprise Default.
- Per-key bindings: api_key_guardrail_policies join table.
- Full audit: /api/v1/guardrail-executions returns every verdict with the input / output hash and the policy that fired.

## Built-in policies
- PII Redactor (input, redact). Catches the canonical NIST PII shapes (email, phone, SSN, credit card, driver's license) and replaces them with [REDACTED:<kind>] tokens before any model sees the prompt.
- Prompt Injection Deny (input, deny). Pattern-matches known prompt-injection payloads and adversarial instruction shapes. Denies the request before it reaches any model. Returns a structured error.
- Profanity Flag (input + output, flag). Flags profanity in either direction without denying the request. Verdict lands in the executions log for context.
- Max-Length Truncate (input + output, truncate). Caps tokens at a configurable ceiling (default 4K or 8K). Prevents runaway prompts and runaway responses.
- JSON Repair (output, repair). When the model emits malformed JSON, runs a one-shot repair before the response leaves the gateway. Agentic workflows get clean structured output.

## Named presets
- PII-Safe. Redact email / phone / SSN / credit-card / DL before the model sees them. The sensible default for compliance-sensitive teams.
- Strict JSON. Reject prompt injection on input; repair malformed JSON on output. For agentic / structured-output workflows.
- Cost-Conscious. Cap input + output length so a runaway prompt cannot blow the budget. Truncates both directions to a defensible ceiling.
- Enterprise Default. PII redaction + prompt-injection deny + JSON repair + length cap + profanity flag. The canonical full-stack policy, layered in order: PII first, injection deny, JSON repair + length truncation on output, profanity flagging across both phases.

## Adjacent infra-level guardrails
- Geo-blocking. Block or allow by ISO 3166-1 country code. Keep regulated widgets in their lane without writing code.
- Bot challenge. Invisible bot challenge on public embeds. Stops scripted abuse before it hits the inbox.
- Abuse heuristics. Rapid-fire (5 messages / 10 seconds), content repetition (3 dupes / 120 seconds), prompt length cap. Per-key, with a persistent counter and an in-memory fallback.
- Image sanitizer. Strips EXIF / IPTC / XMP / ICC metadata before any image touches an AI engine. DICOM-aware: detects DICOM magic bytes, re-encodes as PNG to strip PHI.
- SSRF validator. Blocks private IP ranges (RFC 1918 / 6598), loopback, link-local, and cloud-metadata endpoints (169.254.169.254, metadata.google.internal). Validates protocol (HTTP / HTTPS only). Blocks embedded credentials.
- Idempotency. POST routes accept an Idempotency-Key header. Per-user namespace, 30s execution lock, 24h replay window, X-Idempotent-Replay header on cache hit.
- Rate-limit. Token-bucket rate limit on API key + session-level rate limit on dashboard users.

## Regulated-fact human approval
Skills can declare specific facts as "regulated" in their manifest. When an AI Worker drafts a regulated claim (eligibility, dosage, pricing, legal text), the response is held until a human approves. The approval flows through the audit ledger with the same SHA-256 hashed provenance as the original turn.

## Executions log
GET /api/v1/guardrail-executions returns every guardrail verdict for the calling key or organization. Filterable by policy_id, verdict, time window. The same data backs the Guardrails dashboard at /dashboard/guardrails.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Routing Studio

> The visual editor that decides which engine answers which prompt. Intent rules, confidence floors, per-mode overrides, and a live test bench. Routing is a first-class product surface, not a hidden implementation detail.

Source of truth: https://hitheo.ai/routing-studio. Last updated: 2026-05-24.

## At a glance
- 3-panel editor. Cascade + Rules + Test Bench.
- 13+ canonical modes. Plus a fast / reason / code / motion / search / image / video / vision / document / genui / analyze / extract / stealth family.
- Live test bench. Type a prompt, see the resolved mode, see why.
- Confidence floor. PROMOTION_CONFIDENCE_FLOOR = 0.85. The intent classifier must clear this before overriding an explicit caller mode.

## The routing cascade (first match wins)
1. Agentic lock. Agentic modes (insurance_*, data_extraction) never get promoted. No classifier call.
2. Attachments → vision. Image attachments on a non-media caller route to the vision engine. Stealth collapses to stealth_image.
3. Skill exclusive override. An intensity-100 skill with a modelPreference wins, still honoring media safety rails.
4. Intent promotion. The intent classifier runs for every promotable caller (text modes + stealth_fast). Promotion fires when the classifier returns a different mode with confidence ≥ 0.85.
5. Stealth family preservation. Any promotion from a stealth_* caller is remapped to the matching stealth engine.
6. Conversation modeHint. Auto fallback when the context resolver surfaced a prior-artifact hint.
7. Requested mode. Default.

## Intent classifier
Two-tier:
- Keyword fast-path (<1 ms). Regex patterns match high-confidence (0.82–0.95) modes.
- LLM fallback (~300 ms). A fast reasoning model classifies into one of 13+ modes.

Default: "fast" mode at 0.5 confidence. The routing engine enforces the 0.85 floor before overriding an explicit caller mode.

## Response telemetry
Every completion emits a routing block: { requested_mode, resolved_mode, promoted, reason, explanation, optional classification / skill_override / locked_family }. Available in v1 JSON, playground SSE meta + done, and the standard chat-completion envelope as theo_metadata.routing.

## Decisions are auditable
The audit ledger records the requested mode, resolved mode, promotion reason, and (if a skill override fired) the skill slug + intensity. Pairs with the Memory Console for memory and the Guardrails dashboard for policy.

## Routing rules in your dashboard
Three rule kinds:
- Pattern rules. Regex / contains / equals matchers on the prompt or metadata.
- Class rules. Pin a request class (vision, research, code, document) to a specific engine.
- Engine pins. Force a particular engine even when the classifier disagrees.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Studio (E.V.I. Canvas)

> The visual build surface for AI Workers. Drag-drop nodes for persona, skill, knowledge, tool, conditional, and vision. Wire them with workflows and hooks. Compile, test, version, publish.

Source of truth: https://hitheo.ai/studio. Last updated: 2026-05-24.

## At a glance
- Six subsystems: Canvas, Skills, Knowledge Node, Workflows, Hooks, Tool Registry.
- Three publish modes: private, organization-only, public marketplace.
- Versioned drafts. Every save is reversible.
- Live compile + test against sample prompts.

## The six subsystems
1. E.V.I. Canvas. The workshop. An infinite grid where nodes are dragged on, wired, compiled, and published.
2. Skills. The unit of reusable intelligence. A skill bundles a prompt, the right tools, the right knowledge, and an optional workflow. See https://hitheo.ai/llms/skills.txt.
3. Knowledge Node. Drop PDFs, DOCX, XLSX, CSV, JSON, and Markdown directly onto a skill. Limits: 10MB per file, 100 files per skill, 50K-token runtime budget per request. Priority weighting 1 to 5 (P1 gets 3× the budget share). Stored in org-scoped object storage.
4. Workflows. Step-based execution engine. Six step types: tool_call, ai_transform, condition, delay, notification, webhook. N-ary branching. 10-step cap. 30-min runtime cap. Credit checkpoint before every step. See https://hitheo.ai/llms/workers.txt.
5. Hooks. Autonomous triggers on domain events. Five preset event patterns (share.accepted.welcome, task.overdue.summary, project.created.suggestions, team.member_joined.onboarding, document.analyzed.followup) plus custom patterns.
6. Tool Registry. Built-in tools (memory, code, research, browser, documents) + skill tools + connector tools. Four permission tiers: user, org_member, org_admin, system. Every call audited.

## Authoring loop
1. Open the canvas at /dashboard/skills/canvas.
2. Drop nodes onto the grid. Wire them with conditionals and tool calls.
3. Compile. The canvas compiler walks the graph and produces a SkillManifest + WorkflowSteps[].
4. Test. Run sample prompts through the compiled skill inside the canvas.
5. Version. Every save is reversible.
6. Publish. Private (you only) → organization (your team) → public (marketplace).

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Skills

> Skills are the unit of reusable intelligence on Theo. A skill bundles a prompt, the right knowledge, the right tools, an optional workflow, and a manifest that describes when it should fire. Authored once, installed across every AI Worker, versioned like code.

Source of truth: https://hitheo.ai/studio. Last updated: 2026-05-24.

## At a glance
- Three publish scopes: private, organization, public marketplace.
- Per-API-key skill bindings (api_key_skills table) so a key can be locked to an allowlist.
- Skill router runs per-turn to pick which installed skills inject prompt extensions / knowledge / vision for the current request.
- Skill manifest declares: name, description, keyword triggers, intensity, modelPreference, tools, knowledge, prompt extensions, regulated facts, and template hints.

## How skills are activated on a request
1. The orchestrator loads the user's installed skills.
2. The skill binding for the API key intersects the installed set (empty binding = inherit-all).
3. Caller-supplied skill slugs in the request body are added to the active set if installed.
4. The skill router scores each candidate against keyword triggers, intensity, manifest fast-path heuristics, and (if needed) a fast Haiku classifier. Top scores survive into the active set; the rest are dropped from prompt extension but their tools remain registered.
5. The orchestrator surfaces a "Skill router" tool run with the candidates and the selected set.

## Skill binding (per-API-key allowlist)
- GET /api/v1/keys/{id}/skills returns the current binding.
- PUT /api/v1/keys/{id}/skills replaces it. Empty = inherit-all; non-empty = strict allowlist.
- Mutating a binding is gated by manageApiKeys permission and a visibility check that skills are public, authored by the caller, or org-scoped.
- Audit: key.skills.updated. Webhook event: key.skills.updated (org-scoped only).

## Skill router cascade
1. Intensity-100 skill always wins (operator pinned a skill to "always fire").
2. Manifest fast-path. Score each candidate against keyword triggers + name + description + category + slug. Top score must clear a floor and beat the runner-up by ≥1.
3. Fast LLM fallback returns at most two slugs (or "none-apply").
4. Keyword-trigger matches always survive into the active set even if the router would otherwise drop them.

## Marketplace
The public marketplace is browsable at /dashboard/skills. Skills can be filtered by category, vertical, and tool surface. Skills declared "public" are reviewed before listing.

## Knowledge attachment
A skill can attach Knowledge Node files (10MB / file, 100 files / skill, 50K-token runtime budget, P1–P5 priority weighting). At runtime, the knowledge-resolver fetches the extracted text and injects it into the system prompt within the budget. See https://hitheo.ai/llms/studio.txt.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · AI Workers

> An AI Worker is an installable, configurable, multi-channel agent assembled from skills, knowledge, hooks, and workflows. Theo's central organizing concept: not a chatbot, not a prompt template, but a named worker with a job description, memory, and tools.

Source of truth: https://hitheo.ai/workers. Last updated: 2026-05-24.

## At a glance
- Composition: persona (prompt extension) + skills (reusable bundles) + knowledge (org-scoped files) + workflows (multi-step orchestration) + hooks (event triggers) + tool registry (permission-gated).
- Multi-channel: every AI Worker is reachable via REST, dashboard playground, voice, embeddable iframes, and channel adapters (chat platforms, Model Context Protocol).
- Memory continuity: every channel writes into the same MCIR memory graph for the same account. The AI Worker remembers across channels.
- Audit grade: every turn, tool call, memory write, and guardrail verdict is logged with hash-anchored provenance.

## Lifecycle
1. Build on the canvas. See https://hitheo.ai/llms/studio.txt.
2. Install on an API key. The key inherits the skill set unless bound to a strict allowlist. See https://hitheo.ai/llms/skills.txt.
3. Wire a channel. REST + dashboard playground are always live. Iframes go on a host site. Voice gets a token endpoint. Channel adapters mount the SDK on a chat platform.
4. Observe. The Memory Console shows what the worker remembers. The Routing dashboard shows what it routed where. The Guardrails dashboard shows what fired.
5. Iterate. Skills and workflows are versioned; every change is reversible.

## Workflows (the orchestration layer for autonomous jobs)
- 6 step types: tool_call, ai_transform, condition, delay, notification, webhook.
- N-ary branching. Condition steps route to branch targets by label (case-insensitive fallback).
- Guard rails: max 10 steps, 30-min total runtime, credit checkpoint before each step, daily-cap enforcement.
- State: workflowRuns table records status (running / completed / failed / paused), steps completed, error.
- Dispatches workflow.completed / workflow.failed webhooks on completion.

## Hooks (autonomous triggers on domain events)
Hooks fire skills when something happens. Five built-in event patterns: share.accepted.welcome, task.overdue.summary, project.created.suggestions, team.member_joined.onboarding, document.analyzed.followup. Custom patterns are also supported, with per-hook cooldowns and daily caps.

## Tool registry
Built-in tools (memory, code, research, browser, documents) + skill-declared tools + connector-declared tools. Permission gating: user (always available), org_member (org context required), org_admin (admin role required), system (never user-invokable). Every call audited.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Memory Packs

> Pre-built skill bundles tuned to a specific industry. Each pack ships persona + skill chain + knowledge templates + workflows + guardrails so an AI Worker is production-ready on day one.

Source of truth: https://hitheo.ai/packs. Last updated: 2026-05-24.

## At a glance
- 8 launch verticals: insurance, med-spa, B2B SaaS support, SaaS onboarding, legal intake, real-estate, healthcare front-desk, recruiting and staffing.
- Each pack is a curated bundle: persona, prompt extensions, skill chain, default knowledge templates, workflow presets, guardrail policies, hooks.
- Install in one click. Customizable. Versioned. Audit-grade.

## Verticals
- /packs/insurance — quoting, eligibility, renewal triage, claims notes.
- /packs/med-spa — bookings, treatment intake, aftercare follow-ups.
- /packs/b2b-saas-support — ticket triage, status updates, escalation routing.
- /packs/saas-onboarding — welcome, account setup, first-value milestones.
- /packs/legal-intake — case intake, conflict checks, document requests.
- /packs/real-estate — listing intake, buyer qualification, tour scheduling.
- /packs/healthcare-front-desk — appointments, insurance verification, intake forms.
- /packs/recruiting-staffing — candidate intake, screening, interview scheduling.

## How a pack is structured
- Persona. A skill-grade prompt extension that defines the AI Worker's voice and limits.
- Skills. Pack-specific skill manifests installed into the user's library and auto-bound to the relevant API keys.
- Knowledge templates. Starter knowledge files the operator can replace with their own. Priority-weighted.
- Workflows. Pre-wired Workflow steps: tool_call, condition, delay, notification, webhook.
- Guardrails. Vertical-appropriate guardrail preset (e.g. healthcare front-desk ships with the Enterprise Default preset + PHI metadata stripping).
- Hooks. Pre-wired hooks (e.g. project.created.suggestions, document.analyzed.followup).

## When NOT to use a pack
Packs are opinionated. If the operator has a meaningfully different workflow than the pack default, fork the pack on the canvas, edit the prompts and workflows, and publish privately to the organization. Forking is a first-class action on the marketplace.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Voice

> Real-time, low-latency voice sessions for AI Workers. Audio-to-audio streaming with tool calling, skill awareness, and a branded transcript surface. Voice continues the same memory graph and skill set as text.

Source of truth: https://hitheo.ai. Last updated: 2026-05-24.

## At a glance
- Real-time audio-to-audio streaming.
- Same skill set as text. Skill tools are namespaced into the voice tool surface (skill_<slug>_<toolName>) so a voice turn can call them.
- Same memory graph as text. MCIR retrieval and capture flow through the voice session.
- Core voice tools: generate_image, generate_video, deep_research, generate_code, generate_document, save_memory.

## Ephemeral-token contract (developer-facing)
- Voice sessions use a server-issued ephemeral token. The mint endpoint cannot accept setup fields, so the Theo token endpoints (/api/v1/voice/token, /api/playground/voice/token, /api/embed/voice/token) return the systemInstruction and tools alongside the token in the response body.
- The client MUST attach both to the voice connection config. Skipping them drops the session to the default persona with zero tool access.
- The token endpoint emits a vendor-neutral 503 (voice_unavailable / voice_key_invalid) if the underlying voice API key is malformed; the route logs an explicit warn so operators can find the misconfigured value in the server log.

## Branded transcript UI
The playground voice surface shows a scrollable feed that merges speech transcripts + delegated action cards + inline artifacts (images, videos, code, documents). Reuses the same pixel card + image / code preview components as text mode so voice output visually matches text output.

## STT / TTS (REST path)
- Speech-to-text and text-to-speech are also available as REST endpoints for batch transcription and pre-recorded voice output. Not used by live sessions (those are audio-to-audio).

## Skills
Skill tools defined in a skill manifest are automatically bridged to the voice tool surface, so an AI Worker built for text also works in voice. See https://hitheo.ai/llms/skills.txt.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Browser (Live-View Headless Browser)

> Theo Browser is a managed headless browser that an AI Worker can drive autonomously, with a live debugger surface so a human can watch (or take over) at any time. Branded as Theo Browser end-to-end. The upstream provider is never named on customer-facing surfaces.

Source of truth: https://hitheo.ai. Last updated: 2026-05-24.

## At a glance
- Managed session lifecycle. POST /api/v1/browser/sessions creates a session with a tracked liveViewUrl; DELETE releases the session and reconciles billing.
- Live view. GET /api/v1/browser/sessions/{id}/live returns a debugger iframe URL plus the open page list. Cached for 60 seconds; force-refresh available via ?force=1.
- Branded surface. The artifact uses providerId "theo-browser" and modelId "theo-1-browser". Tool descriptions, session payloads, and error messages never name the upstream provider.

## Tool surface (skills can call any of these)
- browser_start — open a session.
- browser_navigate — go to a URL. Forces a live-view refresh so the iframe picks up the new page within the 60s TTL.
- browser_act — perform a high-level action (click, type, select, scroll). Backed by an agentic act engine.
- browser_extract — pull structured data from the current page.
- browser_observe — read the current page's text + role tree.
- browser_screenshot — capture a screenshot, persisted to object storage with a Theo-branded artifact tag.
- browser_end — release the session.
- web_fetch — direct HTTP fetch with SSRF validation.
- web_search — web search via the research engine.

## In-turn action feed
Each browser_* call appends to an actions[] feed on the session artifact and re-emits via the agent loop's deduped collector, so the playground browser card + modal update in place as the AI Worker drives the session.

## Live view
The playground hosts a Theo-branded modal that embeds the debugger iframe alongside a real-time action feed. The CSP allows the upstream debugger origin so the frame loads. The branded modal is the only entry point a customer sees.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Image Generation

> Theo's image stack is a priority-ordered provider chain with intelligent prompt enhancement and an honest fallback contract. Every generated image is persisted, branded with the engine that actually served the request, and exposed under one Theo-branded model surface.

Source of truth: https://hitheo.ai. Last updated: 2026-05-24.

## At a glance
- Engines (branded): Theo Turbo (fast), Theo Core (general), Theo Ink (vector + type), Theo Lucid (clean), Theo Chroma (saturated), Theo Photo (photo-real), Theo Studio (high-detail), Theo Design (illustrative), Theo Type (typography-aware).
- Prompt enhancement: each request is rewritten by a fast reasoning model into a directorial prompt before generation.
- Honest fallback: when the chain falls through from the requested engine to a fallback, the artifact, the tool trace, and the response label all reflect the engine that actually served the request.
- Persistent storage: every generated image is uploaded to object storage. Responses include a permanent URL.
- Aspect ratios: square, portrait, landscape, wide. Each engine maps to its allowed sizes automatically.

## Editing (image-to-image)
- Engines: Theo Ink Edit, Theo Studio Edit (subject-preserving), Theo Dream Edit, Theo Dream Lite Edit (Stealth surface).
- The routing engine automatically promotes "edit" intents on a prior image to the matching edit engine so prior-subject continuity is preserved.
- Edits accept an image_url and optional strength / mask parameters.

## API
- Primary endpoint: POST /api/v1/completions with mode "image" or with an image-intent prompt that the routing engine promotes.
- Body fields: prompt (required), style (optional), aspect (optional, defaults square), engine (optional pin), num_images (optional).
- Response: streaming SSE with artifact events (modelId, providerId, url, dimensions) or non-streaming JSON with an artifacts[] array.

## Selecting an engine
- For speed: Theo Turbo. Sub-3-second wall time on a clean prompt.
- For photo-real: Theo Photo. The highest-fidelity tier for product, portrait, and editorial work.
- For typography or signage: Theo Type. Reads the prompt for typographic intent and chooses a layout-aware engine.
- For vector / illustration: Theo Ink or Theo Design.
- For high detail with iterative edits: Theo Studio.
- For unfiltered / NSFW: Theo Dream / Theo Dream Lite (Stealth surface). See https://hitheo.ai/llms/stealth.txt.

## Safety
- Image sanitizer strips EXIF / IPTC / XMP / ICC metadata before any image touches an AI engine. DICOM-aware: re-encodes DICOM payloads as PNG to strip PHI. See https://hitheo.ai/llms/guardrails.txt.
- Bot challenge and abuse heuristics apply to public embed image surfaces.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Video Generation

> The Theo Motion family handles every video request from a single branded surface. Intelligent style + duration routing inside the engine, native-audio support on cinematic engines, and an AI-disclosure watermark on every output.

Source of truth: https://hitheo.ai. Last updated: 2026-05-24.

## At a glance
- Engines (branded): Theo Motion (cinematic / commercial / documentary), Theo Motion Uncensored, Theo Animate, Theo Animate Pro, Theo Ovi (anime / animated).
- Intelligent style routing: a video classifier reads the prompt and selects style (cinematic / commercial / documentary / casual / animated) and target duration before dispatch.
- Native audio on the cinematic engines.
- Image-to-video supported on every engine via a separate endpoint.
- AI-disclosure watermark applied to every generated mp4 before upload.

## Style → engine mapping
- cinematic / commercial / documentary → Theo Motion (best quality, native audio).
- casual / auto → Theo Motion (speed-optimized variant).
- animated / anime → Theo Animate / Theo Ovi.
- Fallback chain per style runs inside the engine. The end-user sees one branded surface.

## AI-disclosure watermark
Every Theo Motion and Theo Stealth Motion output is piped through a watermarking pipeline before persistence. A tiny semi-transparent "theo" wordmark (~108px wide, ~16px padding) is overlaid in the bottom-right corner of the final frame. This is a provenance signal, not a branding toggle: it is applied regardless of operator branding preference. Expect ~2–15 seconds of additional re-encoding latency per video.

## API
- Primary endpoint: POST /api/v1/completions with mode "video" or with a video-intent prompt that the routing engine promotes.
- Body fields: prompt (required), style (optional), duration (optional, allowed values depend on engine), engine (optional pin), image_url (optional, enables image-to-video).
- Response: queue-based async. SSE stream emits tool events as the video classifier and the engine progress; final artifact event contains the persistent URL.

## Selecting an engine
- For cinematic ads or product video: Theo Motion.
- For unfiltered video: Theo Motion Uncensored (Stealth surface). See https://hitheo.ai/llms/stealth.txt.
- For anime or 2D animated style: Theo Ovi.
- For high-fidelity animation: Theo Animate Pro.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Document Generation

> Theo can produce native PDF, DOCX, XLSX, PPTX, and CSV documents from a single conversational prompt. Content is drafted by a reasoning model, then rendered through format-specific pipelines into a downloadable artifact persisted to object storage.

Source of truth: https://hitheo.ai. Last updated: 2026-05-24.

## At a glance
- Formats: PDF, DOCX, XLSX, PPTX, CSV.
- Triggered automatically by the routing engine when an intent classifier detects a document request, or explicitly by passing a "documentFormat" hint.
- Renders to a permanent URL on object storage. Streaming clients receive the URL in the final artifact event.
- Style guidance: customers can pin a template via skill manifest (cover sheet, header / footer, palette, font stack).

## How a request flows
1. The routing engine inspects the prompt for a document request shape (verb + a format keyword like "report", "spreadsheet", "deck").
2. The orchestrator dispatches to the document mode pipeline.
3. A reasoning model drafts structured content (title, sections, tables, bullets).
4. A format-specific renderer produces the binary asset (React-PDF for PDF, native DOCX / XLSX / PPTX engines).
5. The artifact is uploaded to object storage and surfaced as a download link.

## API
- Endpoint: POST /api/v1/completions with mode "document", or rely on the routing engine to promote a document-shaped prompt.
- Body fields: prompt (required), format (one of pdf / docx / xlsx / pptx / csv; optional, auto-detected from prompt), template (optional skill template id), filename (optional).
- Response: SSE stream emits a document tool run plus a final artifact event with the persistent URL.

## Skills
Document templates can ship as skills. A skill manifest can declare a default template (cover page, header / footer, table styles) so an AI Worker dedicated to invoicing, reporting, or onboarding always produces a branded document. See https://hitheo.ai/llms/skills.txt.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Code Generation

> A dedicated code generation pipeline with language detection, syntax highlighting metadata, and structured artifact output. Routed to the reasoning engine (theo-core / theo-1-reason), not the conversational engine.

Source of truth: https://hitheo.ai. Last updated: 2026-05-24.

## At a glance
- Branded engine: theo-1-code (a routing alias for theo-1-reason).
- Output is a structured code artifact with language tag, filename hint, and a copy-ready string.
- Multi-file responses are supported: a single prompt can produce several code artifacts in one turn.
- Skills can extend with tools (write_file, run_tests, apply_diff) so an AI Worker can edit a repository, not just produce snippets.

## How a request is routed
The routing engine detects code-shaped prompts by signal: file-extension patterns (.tsx, .ts, .py, .go, .rs), code keywords ("function", "class", "refactor", "stack trace"), or explicit mode pinning. Detected prompts dispatch to the code pipeline rather than the conversational pipeline.

## API
- Endpoint: POST /api/v1/completions with mode "code", or rely on the routing engine to promote.
- Body fields: prompt (required), language (optional pin), format (optional, defaults to text/openai-compatible).
- Response: streaming SSE with token events for the prose and one or more code artifact events with the structured payload, or non-streaming JSON with an artifacts[] array.

## Code review and agentic edits
When a skill declares a write_file tool (or a connector exposes a repository write), the orchestrator runs the agentic loop: it can read files, propose diffs, run tests, and iterate. The orchestrator audits every tool call.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Deep Research

> A multi-step research pipeline that plans queries, fetches sources in parallel, deduplicates, and synthesizes a cited markdown report. Built for prompts that demand grounded answers, not hallucinations.

Source of truth: https://hitheo.ai. Last updated: 2026-05-24.

## At a glance
- Pipeline: plan → search → deduplicate → synthesize.
- Plan stage: a fast reasoning model produces 3–6 focused search queries from the operator's topic.
- Search stage: queries run in parallel through a web search backend, advanced depth, ~8 results per query.
- Deduplicate by URL.
- Synthesize: a reasoning model writes a structured markdown report with inline source citations.

## Domain enrichment
When a domain or URL is detected in the user prompt, the research engine optionally enriches with brand / product / styleguide metadata. Mode-aware: code / build / image surfaces request styleguide data; research / reason surfaces request product + scraping context.

## API
- Endpoint: POST /api/v1/completions with mode "research", or rely on the routing engine to promote a research-shaped prompt ("cite sources", "compare", "investigate", "find references for").
- Body fields: prompt (required), depth (basic / advanced; optional), max_sources (optional).
- Response: streaming SSE with progress events ("planning" → "searching" → "synthesizing" → "complete") and a final synthesis artifact.

## Open loops
A research turn writes a chain into the memory graph (kind = "search", outcome = "resolved"). Any unresolved threads land as open loops surfaced on the next conversation. See https://hitheo.ai/llms/memory.txt.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Stealth (Zero Retention)

> Theo Stealth is the zero-retention, low-filter surface. No memory writes, no skill injection, no audit-grade content storage. For requests that must not leave a trace.

Source of truth: https://hitheo.ai. Last updated: 2026-05-24.

## At a glance
- Branded engines: theo-1-stealth (text), theo-1-stealth-create (image), theo-1-stealth-motion (video).
- Branded image sub-engines: Theo Dream, Theo Dream Lite, Theo Raw, Theo Chroma, Theo Unbound, Theo Ink.
- Branded edit sub-engines: Theo Ink Edit, Theo Dream Edit, Theo Dream Lite Edit.
- Branded video sub-engines: Theo Motion Uncensored, Theo Animate, Theo Animate Pro, Theo Ovi.
- Zero retention: no memory writes, no audit content storage, no skill injection.
- Watermark: every Theo Stealth Motion mp4 carries the same AI-disclosure wordmark as Theo Motion. The watermark is a provenance signal, not a branding choice.

## When to use Stealth
- A creative exploration that must not pollute the customer's memory graph.
- A safety / red-team probe where you do not want audit-storable content.
- A request that requires a less restrictive content filter than the conversational engines apply.

## When NOT to use Stealth
- Anything that benefits from MCIR memory continuity. Stealth turns are not recorded in the memory graph.
- Customer-facing AI Worker turns. Skill prompt extensions, knowledge files, and routing rules are all skipped in Stealth.

## API
- Body fields: stealth_model (one of the branded engine ids; "auto" lets the routing engine pick within the family), stealth_aspect (square / portrait / landscape / wide), stealth_duration (per-engine allowed values).
- The orchestrator strips skill injection and memory writes when any mode starts with "stealth_".
- Routing engine respects the stealth family: even if the routing engine promotes a stealth_fast caller to image / video, the result stays in the stealth family.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Embeddable Chat Widgets

> Theo iframes are white-label chat widgets that drop onto any site. Backed by an API key, governed by Brand Soul (voice, palette, behaviour), and shielded by abuse heuristics + a bot challenge.

Source of truth: https://hitheo.ai. Last updated: 2026-05-24.

## At a glance
- Public URL pattern: /embed/{configId}.
- Auth: ownership tied to a developer's API key. Domain allowlist enforced via CORS.
- Brand Soul: each key carries a curated persona, palette, and behaviour overlay that the widget inherits.
- Preview tokens: short-lived tokens let an unpublished widget be previewed inside the dashboard before going public.
- Abuse defense: layered heuristics (rapid-fire, content repetition, prompt length cap) and an optional bot challenge.

## Authoring loop
1. /dashboard/iframes → create a widget. Pick the linked API key + brand soul.
2. Configure appearance (colors, avatar, greeting), behaviour (welcome messages, suggested prompts, handoff rules), and security (allowed origins, optional bot challenge).
3. Preview it in the dashboard via a preview token.
4. Publish. Copy the embed snippet into the host site.

## Embed runtime
The embed page loads with a context bundle that combines the Brand Soul + appearance + behaviour config. The chat runtime talks to /api/embed/* with the preview token (preview mode) or with the key-derived signed token (public mode). Memory writes flow into the developer's organization, so the AI Worker on the widget retains continuity across sessions if you wire memory in.

## Intent escalation
A keyword fast-path detects "talk to a human", "agent please", and custom keyword triggers. When matched, the runtime emits an intent.escalation event the host site can listen on (postMessage) and optionally route the conversation to a live operator.

## Security
- Frame-ancestors CSP: preview = self only; public = *. Per-key allowedOrigins is the canonical allowlist for CORS on /api/embed/*.
- Geo-blocking is supported by ISO 3166-1 country code. See https://hitheo.ai/llms/guardrails.txt.
- Domain restrictions are enforced server-side; embedding the widget on a non-allowed origin returns a structured error rather than a partial render.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · SDK & Open-Source Adapters

> Theo ships an open-source TypeScript SDK plus channel adapters for the popular chat platforms and a Model Context Protocol adapter. Open source by design: trust comes from the diff log, not the marketing copy.

Source of truth: https://hitheo.ai/for-developers. Last updated: 2026-05-24.

## Packages
- @hitheo/sdk. The official TypeScript SDK. Wraps the REST API, streaming, idempotency, and the structured response envelope.
- @hitheo/telegram. Telegram channel adapter. Mounts an AI Worker on a Telegram bot with one config object.
- @hitheo/whatsapp. WhatsApp channel adapter. Same shape as Telegram.
- @hitheo/mcp. Model Context Protocol adapter. Exposes Theo's tool surface as MCP tools so an MCP-aware client (IDE, agent runtime) can call Theo.

All four packages live in the public Theo monorepo and ship to npm. CI auto-publishes on a version bump.

## SDK quickstart (TypeScript)
```ts
import { Theo } from "@hitheo/sdk";

const theo = new Theo({ apiKey: process.env.THEO_API_KEY! });

// Streaming
const stream = await theo.completions.stream({
  prompt: "Draft a renewal letter for ICHRA policy 12345.",
  mode: "auto",
  metadata: { conversationId: "conv_abc" },
});

for await (const event of stream) {
  if (event.type === "token") process.stdout.write(event.text);
  if (event.type === "artifact") console.log("artifact:", event.url);
}

// Non-streaming
const result = await theo.completions.create({
  prompt: "Summarize the attached PDF.",
  mode: "auto",
});
console.log(result.text);
```

## Channel adapters
Channel adapters bind a Theo API key to a chat platform and translate platform-specific message events into Theo completion calls. They handle media attachments, thread continuity, and platform-specific edge cases (delivery receipts, edit windows).

Telegram example:
```ts
import { TelegramAdapter } from "@hitheo/telegram";

new TelegramAdapter({
  apiKey: process.env.THEO_API_KEY!,
  botToken: process.env.TELEGRAM_BOT_TOKEN!,
}).listen();
```

## Model Context Protocol adapter
@hitheo/mcp exposes Theo's tool surface (memory ops, generation, research, document creation, browser) as MCP-compliant tools. An MCP-aware IDE or agent runtime can call Theo without going through the REST API directly.

## Versioning and stability
The SDK follows semver. Breaking changes ship under a major version bump. The REST API has its own version header (Theo-Api-Version). The SDK pins to a known-stable version by default and accepts overrides per call.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · REST API

> The Theo REST API powers every Theo Worker, channel adapter, and SDK. Auth via API keys, streaming SSE responses, an idempotency contract, a versioned envelope, and a drop-in compatibility format for clients that expect the standard chat-completion shape.

Source of truth: https://hitheo.ai/for-developers and https://docs.hitheo.ai. Last updated: 2026-05-24.

## Auth
- API keys with the prefix `theo_sk_*`. Pass via `Authorization: Bearer theo_sk_...` header.
- Keys have scopes (completions, connectors, browser, memory, …). Tokens are validated by the middleware and rate-limited per token.

## Primary endpoints
- POST /api/v1/completions — main entry point. Accepts a prompt, mode, optional streaming flag, optional skills, optional tools, optional metadata. Returns either streaming SSE or a final JSON envelope.
- POST /api/v1/images — synchronous image-generation endpoint. Returns an artifacts[] array.
- GET /api/v1/models — list available branded engines (theo-1-auto, theo-1-flash, theo-1-reason, theo-1-code, theo-1-create, theo-1-motion, theo-1-research, theo-1-edge, theo-1-genui, theo-1-analyze, theo-1-extract, theo-1-stealth, theo-1-stealth-create, theo-1-stealth-motion).
- GET /api/v1/health — public health + provider status.
- GET /api/v1/audit — paginated audit log for the calling key or organization.
- GET / POST / DELETE /api/v1/keys — manage API keys.
- GET / POST / PATCH / DELETE /api/v1/webhooks — manage webhook endpoints.
- GET / POST / DELETE /api/v1/hooks — manage autonomous triggers.
- GET / POST / DELETE /api/v1/skills — install and author skills.
- GET / POST / DELETE /api/v1/orgs — manage organizations.
- GET /api/v1/openapi.json — machine-readable OpenAPI 3.1 spec.
- POST /api/v1/voice/token — mint a voice session token. See https://hitheo.ai/llms/voice.txt.
- POST / DELETE /api/v1/browser/sessions — manage Theo Browser sessions. See https://hitheo.ai/llms/browser.txt.

## Streaming protocol (Server-Sent Events)
`text/event-stream` over HTTP. Events:
1. `thinking` — immediate heartbeat before orchestration runs.
2. `meta` — completion id, resolved mode, branded model info, tools, artifacts.
3. `tool` — one per tool used (classifier, memory, research, code, document, browser).
4. `artifact` — one per artifact produced (image, video, document, code).
5. `token` — streamed text tokens.
6. `done` — final payload with full content, follow-ups, usage, billing.

Also supports a drop-in industry-standard `chat.completion` compatibility envelope. Activated by passing a `format` field on the request body; see https://docs.hitheo.ai or the OpenAPI spec for the accepted values.

## Idempotency
POST endpoints accept an `Idempotency-Key` header. Per-user namespace. 30-second execution lock prevents duplicate execution. 24-hour replay window. Cached responses replay with `X-Idempotent-Replay: true` header. Keys are bounded to 256 characters, alphanumeric + `-_.:`.

## Versioning
- Client sends `Theo-Api-Version: 2026-03-28` (date-based version header).
- Response includes `Theo-Version: 2026-03-28`.
- `Theo-Deprecation` header is set when the client version is older than current. Date-based versioning means we can ship non-breaking improvements without coordinating SDK bumps.

## Billing
- Per-token pricing with a transparent passthrough margin. See https://hitheo.ai/llms/pricing.txt.
- `credits.low` webhook fires when balance drops below the configured threshold (default $5.00).

## CORS
- Default allowed origins: hitheo.ai, api.hitheo.ai, docs.hitheo.ai.
- Per-key `allowedOrigins` takes priority over defaults.
- Server-to-server requests (no Origin header) get a wildcard ACAO.

## Audit
Every completion lands in the audit ledger as a SHA-256 hashed entry with action, model, cost, and provenance. See https://hitheo.ai/llms/privacy.txt.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Pricing

> Per-token billing with a transparent passthrough margin. Atomic credit reservation. Welcome credit on signup. No seat fees on the free tier. Operators add top-ups when they want.

Source of truth: https://hitheo.ai. Last updated: 2026-05-24.

## How it works
- Every completion is metered. Token-based engines (text, code, reasoning) are billed per input + output token. Fixed-cost operations (image generation, video generation, document rendering, deep research, web fetches) have published flat rates.
- Theo applies a transparent margin (20%) on top of provider pricing. The margin funds orchestration, memory, the build layer, and the trust layer. We do not monetize training.
- Credits are reserved atomically before execution via an UPDATE … WHERE balance >= cost guard, preventing TOCTOU races on concurrent calls.
- After execution the reservation is reconciled. Over-reservation is refunded; an additional debit happens if the actual cost exceeded the estimate.

## Welcome credit + auto-provisioning
- New accounts receive a $5.00 welcome bonus on signup (provisioned via a webhook on user creation).
- A safety-net path inside the credit guard provisions the bonus on the first request if the webhook did not fire (idempotent: checks for an existing welcome-bonus transaction before crediting).

## Top-ups
- Operators add credit through a hosted checkout. Once funded, credit is held in the operator's account and consumed on each request.
- The `credits.low` webhook fires when balance drops below a configurable threshold (default $5.00). Dispatched to org-scoped webhook endpoints.

## Caps
- Daily-spend caps are available for autonomous and background jobs so a hook gone wrong cannot drain the balance overnight.
- Per-workflow credit checkpoints pause execution before continuing if a single run is about to exceed its budget.

## What is on the bill
- Per-token charges for text / code / reasoning, broken out by branded engine.
- Per-operation charges for image / video / document / research, broken out by branded sub-engine (e.g. Theo Photo, Theo Studio, Theo Motion).
- Storage and bandwidth for persisted artifacts.
- A separate line for the Theo Browser per-minute session rate.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.


---

# Theo · Teams & Permissions

> Theo runs on organizations. Every account belongs to one or more organizations, with role-based permissions and granular per-member overrides. Invitations, ownership transfer, leave, and delete all live at /dashboard/team.

Source of truth: https://hitheo.ai/teams. Last updated: 2026-05-24.

## At a glance
- 4 roles: owner, admin, member, viewer.
- 15 fine-grained permission bits per member (see below).
- Per-member overrides on top of role defaults.
- Invitations + history, resend, revoke, ownership transfer.
- No seat cap on the free tier.

## Roles
- Owner. Full control. Only one per org. Ownership is transferable; the previous owner becomes an admin on transfer.
- Admin. Manage members, manage skills, manage API keys, manage webhooks, manage billing, manage routing, manage guardrails.
- Member. Use the platform within their permitted scope. Can be granted any subset of permissions via override.
- Viewer. Read-only. See the conversation history, memory graph, audit log; cannot mutate.

## Permission bits (15)
manageMembers, manageInvitations, manageRoles, manageBilling, manageApiKeys, manageWebhooks, manageHooks, manageSkills, manageRouting, manageGuardrails, manageBrandSoul, viewAudit, viewMemory, viewBilling, viewAnalytics.

Defaults are role-based; admins can grant or revoke specific permissions per member.

## Invitations
- Send an invitation from /dashboard/team. The invitee gets an email with a one-click accept link.
- Acceptance lands on the Theo-owned /accept-invitation page so the ticket is preserved across sign-in / sign-up.
- History tab shows past invites (pending, accepted, expired, revoked).
- Re-issue an invite (revokes the prior token and mints a fresh one with the same local UUID).
- Revoke an invite at any time.

## Optimistic UX
The team dashboard renders pending invitations and role changes optimistically, with rollback on server error. The invite "Sending…" pill appears the moment the user clicks Send; no waiting for the network round-trip.

## Audit
Every team action is audited: team.invite.sent, team.invite.resent, team.invite.revoked, team.role.changed, team.permission.changed, team.member.removed, team.ownership.transferred.

## Seat policy
Theo does not cap seats on the free tier. Operators can add as many members as their workflow needs.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.