@@ -8,6 +8,20 @@ Newest first. `Unreleased` is what is on `main` and not yet tagged.
 
 ## Unreleased
 
+### A new deployment starts with two coworkers, not twelve
+
+The example package loaded every coworker in `examples/fintech/agents/`, so a fresh deployment opened
+with General Assistant, Knowledge and ten more at once. The ten now live in `examples/fintech/catalog/`,
+which is not loaded, and a new deployment starts with General Assistant and Knowledge. Risk Analyst
+and the picked harness still register when their endpoints are configured. To keep any of the ten,
+copy its file from `catalog/` into `agents/`.
+
+A deployment that already registered them keeps them. A coworker dropped from the package is not
+retired on the next boot: its row stays, still listed and still refused by delete as protected,
+because only a remote coworker with a blank endpoint is retired automatically. To remove the ten
+from such a deployment, set `deleted_at` on their `agent_profiles` rows after upgrading (see
+[configuration.md](docs/configuration.md#agents)).
+
 ## 0.1.2
 
 ### CopilotKit 1.77 and AG-UI 1.0
 
@@ -46,7 +46,7 @@ your own machine.
 
 An agent platform that runs inside your own infrastructure. Docker Compose brings up every part of it, the data sits in your PostgreSQL, and the model is yours to choose: no model ships in the box, and an administrator supplies the credential, which is encrypted at rest and never logged.
 
-Thirteen coworkers ship in the example package, and they are configuration rather than code: **General Assistant** for everyday work and **Knowledge** for company questions, a **Risk Analyst** reached as an endpoint, and ten in `examples/fintech/agents/` that each do one job — reading an expense claim against the policy as written, turning a meeting note into the follow-ups actually in it, drafting release notes from what shipped, triaging a ticket, answering a new starter from the handbook, writing a brief that names what it could not find, writing up an interview, handing an on-call shift over, assembling what is known before a renewal, and grouping customer feedback into themes it can cite. Add your own by dropping a file in that directory, by editing `agents.yaml`, or from `/agents` in the UI.
+A deployment starts with two coworkers, and they are configuration rather than code: **General Assistant** for everyday work and **Knowledge** for company questions. A **Risk Analyst** joins them once its endpoint is configured, and ten more wait in `examples/fintech/catalog/`, each doing one job — reading an expense claim against the policy as written, turning a meeting note into the follow-ups actually in it, drafting release notes from what shipped, triaging a ticket, answering a new starter from the handbook, writing a brief that names what it could not find, writing up an interview, handing an on-call shift over, assembling what is known before a renewal, and grouping customer feedback into themes it can cite. Copy one into `examples/fintech/agents/` to add it, write your own there or in `agents.yaml`, or make one from `/agents` in the UI.
 
 Anything a Bot does to a computer, a file, an MCP server or a component goes through one gateway that decides and records it. That is the difference between an agent that can use your tools and an agent you can let near them.
 
 
@@ -831,7 +831,8 @@ examples/fintech/
 ├── model.yaml
 ├── knowledge.yaml
 ├── skills.yaml      (optional)
-└── agents/          (optional)
+├── agents/          (optional, one coworker per file)
+└── catalog/         (not loaded: coworkers to copy into agents/)
     └── expense-review.yaml
 ```
 
@@ -913,8 +914,12 @@ message saying which file wanted it, rather than leaving a Bot pointed at an add
 A coworker may also be one file of its own, in an `agents/` directory beside `agents.yaml`. Both are
 read, and a package that keeps every coworker in `agents.yaml` is unchanged.
 
+The shipped package starts with two coworkers, General Assistant and Knowledge, both in `agents.yaml`.
+Its other two entries, Risk Analyst and the picked harness, register only when their endpoints are
+configured. Ten more are in `catalog/`, which is not read. Copy one into `agents/` to add it:
+
 ```yaml
-# examples/fintech/agents/expense-review.yaml
+# examples/fintech/agents/expense-review.yaml, copied from catalog/
 id: expense-review
 name: Expense Review
 title: Finance Operations
@@ -938,6 +943,12 @@ should not depend on what a directory listing happened to return.
 The directory is in the package checksum, so adding, editing or deleting a coworker there is a
 package change like any other and a running deployment notices it on the next boot.
 
+**Deleting a file does not remove the Bot from a deployment that already registered it.** The next
+boot stops declaring it, but its row stays, still owned by the package, so it is still listed and
+still refused by delete as protected. Only a remote coworker whose `endpoint` is blank is retired
+automatically. Retire one that is gone from the package by setting `deleted_at` on its
+`agent_profiles` row, which is what delete does for a Bot somebody made.
+
 ### `channels.yaml`
 
 ```yaml
 
@@ -3,17 +3,7 @@
 A file in here declares one coworker, and the loader reads it alongside `../agents.yaml`. Both work,
 and a package that keeps everything in `agents.yaml` is unchanged.
 
-The point of the directory is that a coworker becomes a thing you can handle: copy one in, delete
-one you do not want, send one to somebody. Nothing here is a grant. A coworker names skills, a skill
-names tools, and what it may actually call is what an administrator has granted it — so a file
-dropped in here adds an instruction and no capability.
-
-These ten are meant to give you somewhere to start rather than to cover a matrix, and they are
-deliberately unlike each other: finance, meetings, releases, support, onboarding, research, hiring,
-reliability, procurement and product feedback. The part worth
-copying is the shape of `role_description`: it says what the job is, what the coworker must not do,
-and what to say when it cannot find something. A one-line description gets you a coworker that
-answers vaguely.
-
-More of them, outside this repository and not inherited by your clone:
-[awesome-openbot-agents](https://github.com/jerelvelarde/awesome-openbot-agents).
+The package starts with two coworkers from `../agents.yaml`, General Assistant and Knowledge, so a
+fresh deployment opens on a short roster rather than a dozen Bots nobody asked for. Its other two
+entries register only when their endpoints are configured. To add one, copy a file in from
+[`../catalog`](../catalog), or write your own in the same shape. To remove one, delete its file.
@@ -0,0 +1,20 @@
+# Coworkers to copy in
+
+Nothing in this directory is loaded. Each file declares one coworker, in the shape `../agents/`
+reads: copy a file into `../agents/` and the next start registers it. They used to load by
+default, which put a dozen Bots in front of every new deployment at once.
+
+The point of one file per coworker is that a coworker becomes a thing you can handle: copy one in,
+delete one you do not want, send one to somebody. Nothing here is a grant. A coworker names skills,
+a skill names tools, and what it may actually call is what an administrator has granted it, so a
+file copied into `../agents/` adds an instruction and no capability.
+
+These ten are meant to give you somewhere to start rather than to cover a matrix, and they are
+deliberately unlike each other: finance, meetings, releases, support, onboarding, research, hiring,
+reliability, procurement and product feedback. The part worth
+copying is the shape of `role_description`: it says what the job is, what the coworker must not do,
+and what to say when it cannot find something. A one-line description gets you a coworker that
+answers vaguely.
+
+More of them, outside this repository and not inherited by your clone:
+[awesome-openbot-agents](https://github.com/jerelvelarde/awesome-openbot-agents).