# cairnloop v0.5.1 - API Reference

## Modules

- Governance
  - [Cairnloop.Governance](Cairnloop.Governance.md): Public facade for the governed-tool proposal system (D-30).
  - [Cairnloop.Governance.Policy](Cairnloop.Governance.Policy.md): Approval-mode resolver for governed tool proposals.
  - [Cairnloop.Governance.Preview](Cairnloop.Governance.Preview.md): Total `render/1` function for governed tool proposals — hides the live-vs-fallback
branching behind a single public API.
  - [Cairnloop.Governance.Telemetry](Cairnloop.Governance.Telemetry.md): Bounded telemetry for governed tool proposal events.
  - [Cairnloop.Governance.Telemetry.Traces](Cairnloop.Governance.Telemetry.Traces.md): Optional OpenInference-conformant trace event module for the Cairnloop governed-action
evidence lane (Phase 17, D17-01, D17-03).
  - [Cairnloop.Governance.ToolActionEvent](Cairnloop.Governance.ToolActionEvent.md): Append-only audit event record for governed tool proposals.
  - [Cairnloop.Governance.ToolApproval](Cairnloop.Governance.ToolApproval.md): Durable approval record for a governed tool proposal.
  - [Cairnloop.Governance.ToolProposal](Cairnloop.Governance.ToolProposal.md): Durable proposal record capturing a governed tool invocation intent, propose-time
snapshots, and idempotency key. Mirrors the `ReviewTask` idiom exactly (D-20).
  - [Cairnloop.Tool](Cairnloop.Tool.md): Governed-tool behaviour and compile-time validating `__using__` macro.
  - [Cairnloop.Tool.Spec](Cairnloop.Tool.Spec.md): Pure data struct carrying compile-time governed-tool metadata.
  - [Cairnloop.ToolRegistry](Cairnloop.ToolRegistry.md): Manages registration and advisory filtering of host-injected governed tools.
  - [Cairnloop.Tools.InternalNote](Cairnloop.Tools.InternalNote.md): Example governed-write tool: appends an operator-only internal note to the
host-owned `cairnloop_messages` store.

- Knowledge Base
  - [Cairnloop.KnowledgeAutomation](Cairnloop.KnowledgeAutomation.md)
  - [Cairnloop.KnowledgeAutomation.ArticleSuggestion](Cairnloop.KnowledgeAutomation.ArticleSuggestion.md)
  - [Cairnloop.KnowledgeAutomation.ArticleSuggestionEvidence](Cairnloop.KnowledgeAutomation.ArticleSuggestionEvidence.md)
  - [Cairnloop.KnowledgeAutomation.CandidateBuilder](Cairnloop.KnowledgeAutomation.CandidateBuilder.md)
  - [Cairnloop.KnowledgeAutomation.GapCandidate](Cairnloop.KnowledgeAutomation.GapCandidate.md)
  - [Cairnloop.KnowledgeAutomation.GapCandidateMembership](Cairnloop.KnowledgeAutomation.GapCandidateMembership.md)
  - [Cairnloop.KnowledgeAutomation.ManualHandlingSignal](Cairnloop.KnowledgeAutomation.ManualHandlingSignal.md)
  - [Cairnloop.KnowledgeAutomation.ReviewTask](Cairnloop.KnowledgeAutomation.ReviewTask.md)
  - [Cairnloop.KnowledgeAutomation.ReviewTaskEvent](Cairnloop.KnowledgeAutomation.ReviewTaskEvent.md)
  - [Cairnloop.KnowledgeAutomation.StaleArticleSignal](Cairnloop.KnowledgeAutomation.StaleArticleSignal.md)
  - [Cairnloop.KnowledgeAutomation.Telemetry](Cairnloop.KnowledgeAutomation.Telemetry.md): Stable telemetry helpers for knowledge-maintenance workflow events.
  - [Cairnloop.KnowledgeAutomation.Workers.BackfillGapCandidates](Cairnloop.KnowledgeAutomation.Workers.BackfillGapCandidates.md)
  - [Cairnloop.KnowledgeAutomation.Workers.GenerateArticleSuggestion](Cairnloop.KnowledgeAutomation.Workers.GenerateArticleSuggestion.md)
  - [Cairnloop.KnowledgeAutomation.Workers.RefreshGapCandidates](Cairnloop.KnowledgeAutomation.Workers.RefreshGapCandidates.md)
  - [Cairnloop.KnowledgeBase](Cairnloop.KnowledgeBase.md)
  - [Cairnloop.KnowledgeBase.Article](Cairnloop.KnowledgeBase.Article.md)
  - [Cairnloop.KnowledgeBase.Chunk](Cairnloop.KnowledgeBase.Chunk.md)
  - [Cairnloop.KnowledgeBase.MarkdownParser](Cairnloop.KnowledgeBase.MarkdownParser.md): Parses markdown into chunks for vector embeddings.

  - [Cairnloop.KnowledgeBase.Revision](Cairnloop.KnowledgeBase.Revision.md)
  - [Cairnloop.KnowledgeBase.Workers.ChunkRevision](Cairnloop.KnowledgeBase.Workers.ChunkRevision.md)

- Retrieval
  - [Cairnloop.Retrieval](Cairnloop.Retrieval.md)
  - [Cairnloop.Retrieval.GapEvent](Cairnloop.Retrieval.GapEvent.md)
  - [Cairnloop.Retrieval.GapEventSnapshot](Cairnloop.Retrieval.GapEventSnapshot.md)
  - [Cairnloop.Retrieval.GapRecorder](Cairnloop.Retrieval.GapRecorder.md)
  - [Cairnloop.Retrieval.Providers.KnowledgeBase](Cairnloop.Retrieval.Providers.KnowledgeBase.md)
  - [Cairnloop.Retrieval.Providers.ResolvedCases](Cairnloop.Retrieval.Providers.ResolvedCases.md)
  - [Cairnloop.Retrieval.Ranker](Cairnloop.Retrieval.Ranker.md)
  - [Cairnloop.Retrieval.ResolvedCaseChunk](Cairnloop.Retrieval.ResolvedCaseChunk.md)
  - [Cairnloop.Retrieval.ResolvedCaseEvidence](Cairnloop.Retrieval.ResolvedCaseEvidence.md)
  - [Cairnloop.Retrieval.Result](Cairnloop.Retrieval.Result.md): Normalized retrieval evidence shared across search, grounding, and telemetry summaries.

  - [Cairnloop.Retrieval.Telemetry](Cairnloop.Retrieval.Telemetry.md): Stable Cairnloop-native telemetry helpers for retrieval search and draft grounding.
  - [Cairnloop.Retrieval.Workers.IndexResolvedConversation](Cairnloop.Retrieval.Workers.IndexResolvedConversation.md)
  - [Cairnloop.Retrieval.Workers.PruneGapEvents](Cairnloop.Retrieval.Workers.PruneGapEvents.md)

- MCP
  - [Cairnloop.Web.MCP.AuthPlug](Cairnloop.Web.MCP.AuthPlug.md): Validates Bearer tokens for MCP.
Does NOT halt the connection on failure. Simply assigns `conn.assigns.mcp_token` if valid.

  - [Cairnloop.Web.MCP.Router](Cairnloop.Web.MCP.Router.md): Optional read-only MCP seam for Cairnloop-governed tools.
  - [Cairnloop.Web.MCP.ToolProjector](Cairnloop.Web.MCP.ToolProjector.md): Pure total function transform: `%Cairnloop.Tool.Spec{}` + tool module → MCP tool definition map.
  - [Cairnloop.Web.MCP.WellKnownPlug](Cairnloop.Web.MCP.WellKnownPlug.md): Serves RFC 9728 metadata for MCP authorization.

- Web
  - [Cairnloop.Web.ArticleSuggestionPresenter](Cairnloop.Web.ArticleSuggestionPresenter.md)
  - [Cairnloop.Web.AuditLogLive](Cairnloop.Web.AuditLogLive.md): Operator audit log (AUDIT-01): a searchable, filterable timeline of
`Cairnloop.Auditor` events.
  - [Cairnloop.Web.AuditLogPresenter](Cairnloop.Web.AuditLogPresenter.md): Pure, total presenter for operator audit-log events (AUDIT-01).
  - [Cairnloop.Web.Components](Cairnloop.Web.Components.md): Cairnloop's shared operator-UI component library.
  - [Cairnloop.Web.ConversationLive](Cairnloop.Web.ConversationLive.md)
  - [Cairnloop.Web.GapCandidatePresenter](Cairnloop.Web.GapCandidatePresenter.md)
  - [Cairnloop.Web.HealthPlug](Cairnloop.Web.HealthPlug.md): A plug for liveness checks.
  - [Cairnloop.Web.HomeLive](Cairnloop.Web.HomeLive.md): Cockpit Home — the operator dashboard's task-oriented landing (GDS "start with
user needs"). Instead of dumping the operator into a bare list, it routes each
persona to their job by intent + ONE actionable "needs-you" live count
  - [Cairnloop.Web.InboxLive](Cairnloop.Web.InboxLive.md): Inbox surface — list of conversations + Phase 25 bulk-recovery cockpit.
  - [Cairnloop.Web.KnowledgeBaseLive.Editor](Cairnloop.Web.KnowledgeBaseLive.Editor.md)
  - [Cairnloop.Web.KnowledgeBaseLive.Gaps](Cairnloop.Web.KnowledgeBaseLive.Gaps.md)
  - [Cairnloop.Web.KnowledgeBaseLive.Index](Cairnloop.Web.KnowledgeBaseLive.Index.md)
  - [Cairnloop.Web.KnowledgeBaseLive.NavComponent](Cairnloop.Web.KnowledgeBaseLive.NavComponent.md): Shared editorial nav function component for all four KB LiveViews.
  - [Cairnloop.Web.KnowledgeBaseLive.SuggestionReview](Cairnloop.Web.KnowledgeBaseLive.SuggestionReview.md)
  - [Cairnloop.Web.MetricsPlug](Cairnloop.Web.MetricsPlug.md): A plug for exposing Prometheus metrics.
  - [Cairnloop.Web.Nav](Cairnloop.Web.Nav.md): The single source of truth for the operator dashboard's top-level navigation.
  - [Cairnloop.Web.ReviewTaskPresenter](Cairnloop.Web.ReviewTaskPresenter.md)
  - [Cairnloop.Web.SearchModalComponent](Cairnloop.Web.SearchModalComponent.md)
  - [Cairnloop.Web.SearchResultPresenter](Cairnloop.Web.SearchResultPresenter.md)
  - [Cairnloop.Web.SettingsLive](Cairnloop.Web.SettingsLive.md)
  - [Cairnloop.Web.ToolProposalPresenter](Cairnloop.Web.ToolProposalPresenter.md): Pure, total presenter for `Cairnloop.Governance.ToolProposal` structs.

- Core
  - [Cairnloop](Cairnloop.md): Documentation for `Cairnloop`.

  - [Cairnloop.Auditor](Cairnloop.Auditor.md): Behaviour for providing host application auditing to Cairnloop.
  - [Cairnloop.Auditor.Governance](Cairnloop.Auditor.Governance.md): Default `Cairnloop.Auditor` implementation backed by the governance audit trail.
  - [Cairnloop.Auditor.NoOp](Cairnloop.Auditor.NoOp.md): A default, no-op implementation of the `Cairnloop.Auditor` behaviour.

  - [Cairnloop.Automation](Cairnloop.Automation.md)
  - [Cairnloop.Automation.Draft](Cairnloop.Automation.Draft.md)
  - [Cairnloop.Automation.DraftGenerator](Cairnloop.Automation.DraftGenerator.md): Behaviour for the host-swappable reply-draft engine.
  - [Cairnloop.Automation.DraftGenerator.Anthropic](Cairnloop.Automation.DraftGenerator.Anthropic.md): Reference `Cairnloop.Automation.DraftGenerator` backed by Anthropic's Claude
(Messages API). Composes a customer-support reply **only when grounding is strong**,
using the canonical Knowledge Base evidence the retrieval layer already gathered.
  - [Cairnloop.Automation.ScoriaEngine](Cairnloop.Automation.ScoriaEngine.md): Deterministic, zero-dependency reply-draft engine — the library default
`Cairnloop.Automation.DraftGenerator`.
  - [Cairnloop.Automation.Workers.DraftWorker](Cairnloop.Automation.Workers.DraftWorker.md)
  - [Cairnloop.AutomationPolicy](Cairnloop.AutomationPolicy.md): Behaviour for providing host application AI policy boundaries.
Allows host applications to dictate how AI drafts are handled.

  - [Cairnloop.Channels.WidgetChannel](Cairnloop.Channels.WidgetChannel.md)
  - [Cairnloop.Channels.WidgetSocket](Cairnloop.Channels.WidgetSocket.md)
  - [Cairnloop.Chat](Cairnloop.Chat.md)
  - [Cairnloop.Chimeway.OutboundNotifier](Cairnloop.Chimeway.OutboundNotifier.md)
  - [Cairnloop.Chimeway.SLABreachNotifier](Cairnloop.Chimeway.SLABreachNotifier.md)
  - [Cairnloop.ContextProvider](Cairnloop.ContextProvider.md): Behaviour for providing host application context to Cairnloop.
  - [Cairnloop.Conversation](Cairnloop.Conversation.md)
  - [Cairnloop.Conversations.SLA](Cairnloop.Conversations.SLA.md)
  - [Cairnloop.DefaultAutomationPolicy](Cairnloop.DefaultAutomationPolicy.md): Default implementation of Cairnloop.AutomationPolicy.
Always returns :draft_only to ensure AI generated outputs are treated safely by default.

  - [Cairnloop.DefaultContextProvider](Cairnloop.DefaultContextProvider.md): Default implementation of Cairnloop.ContextProvider.
Returns an empty context `{:ok, %{}}` for any input to ensure a safe default.

  - [Cairnloop.DefaultSLAPolicyProvider](Cairnloop.DefaultSLAPolicyProvider.md): Default, static implementation of `Cairnloop.SLAPolicyProvider`.
  - [Cairnloop.Doctor](Cairnloop.Doctor.md): Diagnoses a host application's Cairnloop wiring and returns calm, reason-forward findings.
  - [Cairnloop.Embedder](Cairnloop.Embedder.md): Behaviour for generating vector embeddings from text chunks.

  - [Cairnloop.Embedder.ExternalApi](Cairnloop.Embedder.ExternalApi.md): Implementation of Embedder behaviour using an external API.
Uses OpenAI's text-embedding-ada-002 as default.

  - [Cairnloop.Ingress.EmailParser](Cairnloop.Ingress.EmailParser.md)
  - [Cairnloop.Ingress.EmailWebhookPlug](Cairnloop.Ingress.EmailWebhookPlug.md)
  - [Cairnloop.MCP](Cairnloop.MCP.md): Public facade for the MCP token management and validation.

  - [Cairnloop.MCP.Token](Cairnloop.MCP.Token.md): Durable token record for MCP OAuth Bearer authentication.
  - [Cairnloop.Message](Cairnloop.Message.md)
  - [Cairnloop.Notifier](Cairnloop.Notifier.md): Behaviour for notifying the host application of important Cairnloop events.

  - [Cairnloop.Notifier.Chimeway](Cairnloop.Notifier.Chimeway.md)
  - [Cairnloop.Outbound](Cairnloop.Outbound.md): Facade for programmatically triggering support lifecycle events (outbound messages).
  - [Cairnloop.Outbound.BulkEnvelope](Cairnloop.Outbound.BulkEnvelope.md): Durable audit envelope for a bulk outbound action (D-13, OBS-02-shaped). Snapshots
template_id, rendered_body, and recipient cohort at confirmation time. Per-recipient
delivery flows through `Outbound.trigger/2` (sealed) carrying the envelope id. Refused
attempts persist with `status: :refused_cap_exceeded`.
  - [Cairnloop.Outbound.Telemetry.Traces](Cairnloop.Outbound.Telemetry.Traces.md): Optional OpenInference-conformant trace event module for the Cairnloop outbound lane
(Phase 26, D-03).
  - [Cairnloop.Router](Cairnloop.Router.md): Host-router macros for mounting Cairnloop's operator surfaces.
  - [Cairnloop.SLAPolicyProvider](Cairnloop.SLAPolicyProvider.md): Behaviour for providing SLA policies.
  - [Cairnloop.Telemetry](Cairnloop.Telemetry.md): Centralizes telemetry event execution and documentation for Cairnloop.
  - [Cairnloop.Workers.ApprovalExpiryWorker](Cairnloop.Workers.ApprovalExpiryWorker.md): Oban worker that performs the scheduled `:pending → :expired` flip for governed tool approvals.
  - [Cairnloop.Workers.ApprovalResumeWorker](Cairnloop.Workers.ApprovalResumeWorker.md): Oban worker that re-validates a governed tool approval before it can proceed to execution.
  - [Cairnloop.Workers.CheckSLA](Cairnloop.Workers.CheckSLA.md)
  - [Cairnloop.Workers.IngestScrypath](Cairnloop.Workers.IngestScrypath.md)
  - [Cairnloop.Workers.NotifyResolvedWorker](Cairnloop.Workers.NotifyResolvedWorker.md)
  - [Cairnloop.Workers.OutboundWorker](Cairnloop.Workers.OutboundWorker.md): Oban worker that performs the per-recipient outbound delivery for a `system_outbound`
message previously inserted by `Cairnloop.Outbound.trigger/2` (sealed, Phase 22/23).
  - [Cairnloop.Workers.ProcessMessage](Cairnloop.Workers.ProcessMessage.md): Oban worker that dispatches inbound messages to the correct handler by channel.
  - [Cairnloop.Workers.SlaCountdownWorker](Cairnloop.Workers.SlaCountdownWorker.md)
  - [Cairnloop.Workers.ToolExecutionWorker](Cairnloop.Workers.ToolExecutionWorker.md): The ONLY place `run/3` is ever called in Cairnloop.

## Mix Tasks

- [mix cairnloop.add_csat_columns](Mix.Tasks.Cairnloop.AddCsatColumns.md)
- [mix cairnloop.add_draft_table](Mix.Tasks.Cairnloop.AddDraftTable.md)
- [mix cairnloop.add_resolved_at_column](Mix.Tasks.Cairnloop.AddResolvedAtColumn.md)
- [mix cairnloop.add_sla_table](Mix.Tasks.Cairnloop.AddSlaTable.md)
- [mix cairnloop.doctor](Mix.Tasks.Cairnloop.Doctor.md): Diagnoses your host application's Cairnloop wiring and prints calm, reason-forward findings.
- [mix cairnloop.gen.notifier](Mix.Tasks.Cairnloop.Gen.Notifier.md): Scaffolds a Cairnloop.Notifier implementation in your host application
and injects the configuration into `config/config.exs`.
- [mix cairnloop.install](Mix.Tasks.Cairnloop.Install.md): Igniter installer for Cairnloop.
- [mix cairnloop.install.parapet](Mix.Tasks.Cairnloop.Install.Parapet.md)
- [mix cairnloop.install.sla_policies](Mix.Tasks.Cairnloop.Install.SlaPolicies.md)
- [mix cairnloop.install.slos](Mix.Tasks.Cairnloop.Install.Slos.md)
- [mix cairnloop.retrieval.rebuild](Mix.Tasks.Cairnloop.Retrieval.Rebuild.md): Rebuild retrieval corpus state through `Cairnloop.Retrieval`.
- [mix cairnloop.retrieval.replay_failed](Mix.Tasks.Cairnloop.Retrieval.ReplayFailed.md): Replay failed retrieval jobs through `Cairnloop.Retrieval`.