# cairnloop v0.1.0 - Table of Contents

> Host-owned customer support automation for Phoenix apps — governed drafting, retrieval-backed answers, and durable workflow tools.

## Pages

- [Cairnloop 🏔️](readme.md)
- [Changelog](changelog.md)

## 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.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.

- Web
  - [Cairnloop.Web.ArticleSuggestionPresenter](Cairnloop.Web.ArticleSuggestionPresenter.md)
  - [Cairnloop.Web.ConversationLive](Cairnloop.Web.ConversationLive.md)
  - [Cairnloop.Web.GapCandidatePresenter](Cairnloop.Web.GapCandidatePresenter.md)
  - [Cairnloop.Web.InboxLive](Cairnloop.Web.InboxLive.md)
  - [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.SuggestionReview](Cairnloop.Web.KnowledgeBaseLive.SuggestionReview.md)
  - [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.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.ScoriaEngine](Cairnloop.Automation.ScoriaEngine.md): Mock execution engine for Scoria integration.
Generates structured grounded proposals for operator review.

  - [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.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.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.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.Router](Cairnloop.Router.md)
  - [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.ProcessMessage](Cairnloop.Workers.ProcessMessage.md)
  - [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.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)
- [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`.