ha-casa-app

# Casa — Home Assistant app

Canonical current-state documentation for AI agents working on this repository.
Code is the source of truth; these files are a map.

## Architecture

- [architecture/agent-taxonomy.md](architecture/agent-taxonomy.md): How an agent is declared, validated and looked up — tiers, required artifacts, and the registry.
- [architecture/background-jobs.md](architecture/background-jobs.md): Plugin-declared background jobs — the casa.jobs declaration, the resident jobs block, start_job, the batch loop and its progress tool, and resuming a job after a restart.
- [architecture/callback-delivery.md](architecture/callback-delivery.md): The authorization-callback delivery half — the mtime-clocked publish-once spool, the per-flow attempt ledger and its ack protocol, the consumer verbs, and redelivery until receipt.
- [architecture/callbacks.md](architecture/callbacks.md): The public authorization-callback ingress — the unauthenticated GET route, declaration-bound consent, reconciliation, and the validated redirect base URL.
- [architecture/concurrency-model.md](architecture/concurrency-model.md): What runs concurrently — bus dequeue vs execution, session-key serialization, the lock inventory, and threaded vs loop work.
- [architecture/config-reconciliation.md](architecture/config-reconciliation.md): How the config tree is reconciled against image defaults — ownership rules, the per-entry merge, `${VAR}` placeholder semantics, and the declaration carried across a rewrite.
- [architecture/configuration.md](architecture/configuration.md): Where configuration comes from, what is version-controlled, what reload can pick up without a restart, and how secrets resolve.
- [architecture/delegation-announcements.md](architecture/delegation-announcements.md): What a finished delegation owes its creator — the delivery-acknowledged announcement, the answer retained for it, the boot replay's re-announcement, and how long the finished row is kept.
- [architecture/delegation.md](architecture/delegation.md): How one agent addresses and launches another — the delegation ACL and aliases, the depth cap, and the agent-spawn cap.
- [architecture/engagement-completion-gate.md](architecture/engagement-completion-gate.md): The completion gate — what a successful completion is refused over, how unread and in-flight differ, and what each driver counts.
- [architecture/engagement-containment.md](architecture/engagement-containment.md): The OS boundary around a claude_code engagement — its never-reused uid, workspace ownership, root's no-follow access, the privilege drop, and the confirmed-down sweep before replay.
- [architecture/engagement-failure-and-restart.md](architecture/engagement-failure-and-restart.md): A launch that does not become a live engagement — which gate refused it, what its rollback removes, which arms answer the caller rather than the topic, and what a restart replays or refuses.
- [architecture/engagement-finalization.md](architecture/engagement-finalization.md): How a durable engagement ends — the single-winner terminal transition, strict creation and terminal persistence, the finalization side effects behind the flip, and topic output ordering.
- [architecture/engagement-inbound-disclosure.md](architecture/engagement-inbound-disclosure.md): What a terminal outcome discloses about inbound messages that died with the engagement — the spool populations it quotes, the evicted message whose notice never sent, and the reservation that carries its message's text.
- [architecture/engagement-launch-detach.md](architecture/engagement-launch-detach.md): How an in_casa launch turn is detached from the tool call that launched it — the two-call launch, the anchored owner that tells the engager every outcome, the stop's drains, and the one engagement-outcome envelope.
- [architecture/engagement-terminal-telling.md](architecture/engagement-terminal-telling.md): What a terminal engagement's topic and its engager are told — the outcome mark withheld until the topic was told, the unconfirmed-post disclosure, and the durable obligation to notify the party that asked.
- [architecture/engagement-turn-admission.md](architecture/engagement-turn-admission.md): How a turn is admitted to a live engagement — the registry decision taken immediately before the hand-off, where each driver places it, and what it does not fence.
- [architecture/engagements.md](architecture/engagements.md): Durable engagements — their records, how one is launched, and the driver protocol.
- [architecture/eval-framework.md](architecture/eval-framework.md): The evaluation scaffolding — and the fact that its registry ships empty.
- [architecture/home-assistant-control.md](architecture/home-assistant-control.md): How an agent reads and changes the state of the house — and why the limits on that live in Home Assistant, not here.
- [architecture/hook-resolution.md](architecture/hook-resolution.md): The hook-resolution path — credential-bound identity, per-executor policy maps and their fail-closed fallbacks, and the claude_code containment floor.
- [architecture/http-surface.md](architecture/http-surface.md): The two HTTP servers, what each exposes, and how an inbound request is authenticated.
- [architecture/inbound-files.md](architecture/inbound-files.md): Files sent in the Telegram DM — the non-text handler, accepted kinds, the /data/agent-inbox folder, the default agent's read grant, list_inbound_files, retention.
- [architecture/jobs-and-delivery.md](architecture/jobs-and-delivery.md): Durable background jobs — execution vs delivery state, restart reconciliation, and what a graceful stop does to a live row.
- [architecture/mcp-and-tools.md](architecture/mcp-and-tools.md): How tools reach an agent, and where authorization for a tool call actually happens.
- [architecture/memory-lifecycle.md](architecture/memory-lifecycle.md): Retention lifecycle — how a conversation becomes long-term memory, how each item is labelled on the way in, how a reset retires it, and how a failed retain is retried durably.
- [architecture/memory-scoping.md](architecture/memory-scoping.md): Which stored facts a given reader gets back — read clearance per channel and sender, the engagement clearance clamp, and the executor-archive epoch scoping.
- [architecture/memory-wipe.md](architecture/memory-wipe.md): The operator-consented wipe — its two doors and the consent each demands, the order the orchestrator works in, the fence every bank writer passes through, and what a wipe deliberately does not cover.
- [architecture/memory.md](architecture/memory.md): Recall — how a stored fact is rendered on the way back out, and what a caller may claim from what comes back.
- [architecture/observability.md](architecture/observability.md): How work is traced across components, what reaches a log, and what the health surfaces actually assert.
- [architecture/output-boundary.md](architecture/output-boundary.md): One place for per-turn output policy — the turn scope, admission of model text at the Telegram transport, the read-before-describe disclosure, and the note a stored payload carries to the turn that sends it.
- [architecture/overview.md](architecture/overview.md): What Casa is made of — supervised services, the three agent tiers, and where configuration enters.
- [architecture/persistent-state.md](architecture/persistent-state.md): What the application writes to disk, how it treats a missing or corrupt file, and what that means for recovery.
- [architecture/persona-lifecycle.md](architecture/persona-lifecycle.md): How a persona arrives, is approved, and leaves — consent-bound install, the approved roots, removal by reference scan, and the operator-run sweep.
- [architecture/personality.md](architecture/personality.md): What an agent is versus how it presents — role artifacts, personas, bindings, and which prompt is actually served.
- [architecture/plugin-authorization.md](architecture/plugin-authorization.md): What a protected plugin tool call needs before it runs — the single-use grant it consumes, the challenge that mints it, who may answer, and what retires an unanswered one.
- [architecture/plugin-erasure.md](architecture/plugin-erasure.md): How an uninstall erases a plugin's data first — the casa.eraseTool and casa.eraseDataOnlyTool fields and their result convention, Casa's question offering the declared erase kinds, the erase episode that runs the chosen eraser, the finishing call that removes only after a complete erasure, and the plugin-env.conf references cleared after Erase everything.
- [architecture/plugin-events.md](architecture/plugin-events.md): Plugin-emitted domain events — casa-minted generations, per-subscriber delivery receipts, and consent-gated headless wakes.
- [architecture/plugin-handoff.md](architecture/plugin-handoff.md): The folder files move through between plugins — /data/handoff, publish and capture (the vendored casa_handoff contract), the sweep, share_inbound_file's handoff side.
- [architecture/plugin-health.md](architecture/plugin-health.md): How a plugin's problems reach the operator — the standing health report, the notice and DM with their dedup marks, and the status tool.
- [architecture/plugin-mutation-tools.md](architecture/plugin-mutation-tools.md): What the plugin and specialist mutation tools guarantee — the commit-then-converge ordering, what an envelope may claim about an integration, and what a committed removal discloses.
- [architecture/plugin-result-contract.md](architecture/plugin-result-contract.md): The plugin result contract and the escrow broker — non-adopters refused before they run, a declared capability deposited with Casa and redeemed by reference.
- [architecture/plugin-runtime.md](architecture/plugin-runtime.md): The environment a plugin's MCP servers need before an agent can use it, plus the env-conf and media side channels.
- [architecture/plugin-secret-exploration.md](architecture/plugin-secret-exploration.md): How a plugin's required secrets are found — the vault exploration a mutation result carries, the configurator's two vault tools, their shared projection of field ids, roles and types (never an operator-typed string), and the classified op failure.
- [architecture/plugin-setup-dispatch-gate.md](architecture/plugin-setup-dispatch-gate.md): The gate a released setup obligation passes through before dispatch — the recomputation of the applied state a reconcile has written, and the overlay reads that fence the bus send.
- [architecture/plugin-setup-turn.md](architecture/plugin-setup-turn.md): The dispatched setup turn — what it evidences, how a courier turn's delegation is correlated, and the operator identity it carries for the role it is addressed to.
- [architecture/plugin-setup.md](architecture/plugin-setup.md): Who runs a plugin's declared setup tool — the single-runner obligation and the consent verdict that releases it.
- [architecture/plugin-triggers.md](architecture/plugin-triggers.md): What a plugin's declared webhook must satisfy before it routes — the overlay, its preconditions, and the operator approval gating them.
- [architecture/plugins.md](architecture/plugins.md): How a plugin becomes usable — registry, content-addressed store, artifact identity, and which tools are protected.
- [architecture/prompt-file-guards.md](architecture/prompt-file-guards.md): The per-agent prompt files a compiled bundle makes dead — response_shape.yaml and prompts/system.md — and the file-tool guards that refuse an edit to them.
- [architecture/reminders.md](architecture/reminders.md): How an agent comes to nudge someone later — entry ownership, the narrow writer, delivery, and the sweep that redeems a past-dated one-shot the process was down for.
- [architecture/scheduled-asks.md](architecture/scheduled-asks.md): A scheduled question as a durable obligation — its record on disk, its terminal delivery back to the session that asked, and its manners in the operator's attention lane.
- [architecture/scheduled-prompt-endings.md](architecture/scheduled-prompt-endings.md): The convention that closes a scheduled prompt — which prompts ask the turn for silence, and how the tools the turn calls decide the question.
- [architecture/sdk-client-pool.md](architecture/sdk-client-pool.md): The life of the warm, conversation-bound client a turn runs on.
- [architecture/specialist-bundle-recovery.md](architecture/specialist-bundle-recovery.md): What a specialist bundle transaction does when it does not succeed — the pre-journal refusals, the sync-phase and sequencer compensations, the boot replay and quarantine pass, the age sweeps that follow it, and the race and failed-rotation refusals.
- [architecture/specialist-bundle-transactions.md](architecture/specialist-bundle-transactions.md): What happens to an installed specialist after its install — the upgrade, rollback and uninstall transactions, the owned-plugin generation each publishes, and the crash journal that makes a bundle transaction recoverable.
- [architecture/specialist-instance-tuples.md](architecture/specialist-instance-tuples.md): The instance tuples a specialist install leaves behind — what a tuple snapshot may hold and the digest derived from it, a pending candidate and the inputs its re-commit takes, and what boot does with a damaged tuple.
- [architecture/specialist-lifecycle.md](architecture/specialist-lifecycle.md): Specialist install — the content-addressed store, install identity, consent receipts and materialization.
- [architecture/telegram-rendering.md](architecture/telegram-rendering.md): How an answer is rendered for Telegram — the markdown grammar and tables, pagination to the platform's budgets, link-destination fallbacks, and the shared UTF-16 measurement.
- [architecture/telegram.md](architecture/telegram.md): How Telegram messages become turns — transports, authentication, the per-topic causal log, and keyboards.
- [architecture/tools-interface.md](architecture/tools-interface.md): The mutation interface — the one tool registry, result envelopes, the question lifecycle, and which failures roll back versus report.
- [architecture/trigger-secrets.md](architecture/trigger-secrets.md): The secrets that authenticate webhook triggers — who mints one and when, the mint receipt and provenance, the per-slot reload report, and what is not retired.
- [architecture/triggers.md](architecture/triggers.md): What makes an agent act without a person speaking — a resident's scheduled and webhook triggers, and who may write the file they live in.
- [architecture/turn-loop.md](architecture/turn-loop.md): How one inbound message becomes one agent turn, and what bounds it.
- [architecture/vault-drop-off.md](architecture/vault-drop-off.md): How a sign-in link reaches the plugin tool that consumes it without a delegation brief — the casa.dropOffs field, the Casa-titled and tagged vault item, and the assistant's vault_drop_off tool that writes only that item and never returns or logs the value.
- [architecture/voice-delivery.md](architecture/voice-delivery.md): The leased claim/acknowledge protocol that gets a deferred voice answer to a device — attempts, leases, per-device ordering, the fixed bounds, and result disclosure.
- [architecture/voice.md](architecture/voice.md): How speech becomes a turn and the answer gets back — transports, auth, turn budget, deferred delivery.

## Reference

- [reference/operator-options.md](reference/operator-options.md): The option-by-option operator contract — key, env var, consumer, default, restart-vs-reload.

## Doctrine

- [doctrine/operating-casa.md](doctrine/operating-casa.md): How an agent running inside Casa should behave, and which property of the system each rule follows from.
- [doctrine/publishing.md](doctrine/publishing.md): The one rule that decides whether a fact may be written down in this repository.
- [doctrine/working-on-casa.md](doctrine/working-on-casa.md): How to change this repository without breaking it, and how to establish that a claim about it is true.

## Contributing

- [contributing/doc-contract.md](contributing/doc-contract.md): The shape a document takes, and which of its rules CI enforces versus a reviewer.