Bring the docs up to what is actually merged

Audited every markdown file against everything that landed today, including the
work that was not mine.

`docs/coworkers.md` still told people to point `MANAGED_AGENT_AG_UI_URL` at
`4200`. #33 made `agent-langgraph` on `4201` the default precisely because the
proof-of-concept hand-writes the protocol and leaves the tool loop to whatever is
watching, so following that page produced the shape the change moved away from.

Three environment variables the server reads were in `.env.example` and nowhere
in the configuration reference: `AGENT_STALL_TIMEOUT_MS` from #19, which is the
only thing that notices a Bot's stream going silent; `AGENT_TOOL_TOKEN` from #34,
without which no framework Bot may call a granted tool back; and `APP_DIST_DIR`,
which the container sets so one process serves both halves.

Both documentation indexes had fallen behind their own directory and listed
neither `deployment.md` nor `releasing.md`.

`docs/development.md` gains the migration workflow the checks in #64 now enforce:
never hand-edit a generated migration, write a data step with `--custom`, and
what to do when `drizzle-kit migrate` hangs and exits non-zero with nothing
printed, which is the journal naming a file a rebase renamed. `drizzle-kit check`
calls that state fine, because it compares schemas rather than asking whether the
journal and the directory agree.

The README keeps its shape: what this is, how to run it, how to deploy it, and
where to read the rest.

Author: davidmckayv

README.md

@@ -315,6 +315,8 @@ Use `bash scripts/start.sh` for the whole stack. Use `bun run dev` only when you
 - [docs/configuration.md](docs/configuration.md)
 - [docs/development.md](docs/development.md)
 - [docs/coworkers.md](docs/coworkers.md)
+- [docs/deployment.md](docs/deployment.md)
+- [docs/releasing.md](docs/releasing.md)
 
 ## Contributing
 

docs/README.md

@@ -6,5 +6,7 @@ Start with the root [README](../README.md), then use these references:
 - [Configuration](configuration.md): environment variables and tenant package YAML.
 - [Development](development.md): local setup, migrations, ports, and quality checks.
 - [Coworkers](coworkers.md): durable Bot profiles, channels, visibility, deletion, and external AG-UI registration.
+- [Deployment](deployment.md): the container, what is in the image, minimum sizes, and the platform notes.
+- [Releasing](releasing.md): how a release is proposed, reviewed and published.
 
 Do not include credential values, customer data, transcripts, or local-only notes in public docs.

docs/configuration.md

@@ -46,6 +46,20 @@ All four Intelligence values are required together. Missing any of them stops se
 | `GOOGLE_GENERATIVE_AI_BASE_URL` | unset                   | Google-compatible endpoint that key is spent against.               |
 | `BOT_MODEL`          | provider default from Bot code/env | Model used by the shipped Bots.                                     |
 | `BOT_RESPONSES_API`  | `false`                            | Makes `agent-langgraph` use the OpenAI Responses API.               |
+| `AGENT_STALL_TIMEOUT_MS` | unset (off)                    | How long a Bot's stream may produce nothing before the turn is ended for it. |
+| `AGENT_TOOL_TOKEN`   | unset                              | The secret a framework Bot presents when it calls a granted tool back through this server. |
+| `APP_DIST_DIR`       | unset                              | Where the built app is, when this process serves it. Set inside the container image; unset in development, where Vite serves the app. |
+
+**`AGENT_STALL_TIMEOUT_MS`** watches for the failure a Bot has that nothing else in the trail can
+show: a stream that stops producing anything. Every other audit row is something that happened, and
+this one is the absence of anything happening, which leaves no trace of its own. Ending the turn
+writes `agent.stream_stalled`. Unset or `0` switches it off and nothing is watched. `.env.example`
+ships `60000`, so a new clone has it on and an upgraded deployment does not acquire it unasked.
+
+**`AGENT_TOOL_TOKEN`** exists because a framework Bot runs its own loop in its own process and still
+may not reach a vendor directly. It calls the deployment that granted the tool, which is where the
+grant, the policy and the audit row live. Absent, no Bot may call tools back, and it is told so
+rather than quietly allowed.
 
 ## OpenAI-compatible endpoints
 

docs/coworkers.md

@@ -54,9 +54,13 @@ Hiding is personal roster state. It removes the coworker from one user's list wi
 Product-created coworkers use:
 
 ```dotenv
-MANAGED_AGENT_AG_UI_URL=http://localhost:4200/ag-ui
+MANAGED_AGENT_AG_UI_URL=http://localhost:4201/ag-ui
 ```
 
+That is `agent-langgraph`, which runs a real framework and its own tool loop. The proof-of-concept on
+`4200` hand-writes the protocol and leaves the loop to whatever is watching, so it is a reference
+rather than something to build a deployment on.
+
 The server requires this setting at startup. Package-provided agents use their own `agents.yaml` configuration.
 
 ## Register an external AG-UI agent

docs/development.md

@@ -56,6 +56,30 @@ bun run --filter server db:migrate
 
 Review generated migration files before sharing them. `start.sh` applies existing migrations when it starts the stack.
 
+**Do not hand-edit a generated migration.** It leaves a file that no longer matches what the
+generator produced. If the generated SQL will not work — `ADD COLUMN ... NOT NULL` fails on a table
+that already has rows — split it instead: generate the column nullable, add the data step, then
+generate the constraint.
+
+**A data step is its own migration**, created with the flag that exists for it:
+
+```sh
+bun run --filter server db:generate -- --custom --name=backfill_something
+```
+
+A generator diffs schema against schema, so a rule like "the rows whose provider is Google get
+Google's issuer" can never come out of one: it is not in the schema. `--custom` writes an empty file
+registered in the journal, and it is the only migration anybody should be writing by hand.
+
+CI enforces two things about this: `drizzle-kit check` for collisions and gaps between migrations,
+and a generate-and-fail-if-dirty probe that refuses a schema change with no migration written for it.
+
+**If `drizzle-kit migrate` hangs and then exits non-zero with no error**, the journal names a
+migration file that is not there. A rebase does this: `meta/_journal.json` is a checked-in file, so
+restoring it can reinstate entries for migrations that were renamed. `drizzle-kit check` reports
+"Everything's fine" in that state, because it compares schemas rather than checking that the journal
+and the directory agree. Compare `meta/_journal.json` against `ls server/drizzle/*.sql`.
+
 ## Quality checks
 
 Run these before opening a pull request: