diff --git a/CLAUDE.md b/CLAUDE.md
index 996b8b7b7..577380262 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -12,13 +12,6 @@ review or action. A repository is an optional input to a workflow, not the point
of the product. A forge is one of many inputs or outputs; core code never
assumes one.
- The goal until 1 December is a
-production-ready archie-core, including the features the maintainer is still
-adding. Speak up when a request competes with something more urgent: a bug that
-loses work, a failure that shows nothing, a security gap, a broken setup path.
-Give the trade-off in a sentence or two and suggest whether the request belongs
-in the backlog. Don't hold work back on your own judgement.
-
## Services and layout
Each service is a gRPC contract in `proto//v1`, generated into
@@ -27,13 +20,17 @@ and calls its composition root in `internal/app/`.
| Binary | Serves | Dials |
| --- | --- | --- |
-| `archie-state-store` | State Store and Control Plane contracts; owns the task and control-plane PostgreSQL tables | PostgreSQL |
-| `archie-gateway` | Chat, conversation state, task tools | State Store |
-| `archied` | Scheduling, workflow runs, task containers, Daemon contract | State Store, Gateway, Messaging |
-| `archie-messaging` | External channel frontends | Gateway |
-| `archie-ui` | Dashboard HTTP API (`internal/webui`) and the embedded SPA | State Store, Gateway, daemon |
+| `archie-state-store` | State Store and Control Plane contracts; owns the task and control-plane tables | PostgreSQL |
+| `archie-gateway` | Chat contract; owns the conversation tables | State Store, PostgreSQL |
+| `archied` | Daemon contract; scheduling, workflow runs, task containers | State Store, Gateway, Messaging, NATS |
+| `archie-messaging` | Messaging contract; external channel frontends | State Store, Gateway |
+| `archie-ui` | Dashboard HTTP API (`internal/webui`) and the embedded SPA | State Store, Gateway, Daemon, Messaging |
| `archie-agent` | The worker inside each task container | NATS |
+Forge, channel and secret-engine contracts are extension boundaries, not
+services: a core binary starts the extension as a plugin process and dials it.
+`archied` also runs the State Store's backup and restore during a host update.
+
`internal/domain` holds behaviour and interfaces; `internal/infrastructure`
implements them. Every instruction sent to a model is a file in
`internal/prompts`, read through that package; never inline a prompt in code.
@@ -67,13 +64,13 @@ When sources disagree, the higher one wins:
## How to decide
-- **Broken beats new.** A bug that blocks work gets fixed now, with the smallest
- change that unblocks it. No design docs and no new mechanism.
-- **Cheapest option first.** Before building, name the smallest change that
- solves the problem, including changing configuration or deleting something. If
- your plan adds a new mechanism (RPC, process, binary, abstraction, config
- field, tool) or grows past about 100 lines, stop and assess whether you're
- taking the path of least resistance.
+- **Broken comes first.** A bug that blocks or loses work goes ahead of new
+ features. Fix the cause. When that's a bigger job, unblock with a small change
+ first and file the proper fix rather than stopping there.
+- **Cheapest option first.** Before building, consider the smallest change that
+ solves the problem, including changing configuration or deleting something.
+ A new mechanism (RPC, process, binary, abstraction, config field, tool) is
+ fine when it's the right design; say why the smaller option wasn't enough.
- **Delete before adding.** Unused code, dead paths, fallbacks nobody takes and
features nobody runs get removed, not maintained. Solo project, single user:
breaking changes need no compatibility shims.