carlos / platform Public

docs: a stamped route gets its config from the root pass; the notice's two new lines

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Paul Campbell pushed by paul@keymail.dev 1 month ago 2e5b50f965d2920219ed74d7c51008d5643926ab parent aa5a2e9

2 files changed, +26 −2

AGENTS.md +5 −0
docs/site/cli.md +21 −2

diff --git a/AGENTS.md b/AGENTS.md

index 5c8935f05..176bd169a 100644

--- a/AGENTS.md

+++ b/AGENTS.md

@@ -288,6 +288,11 @@ anything.

916cd6b+ AND its console row is stamped, the old rule stands: promote →

adopt → `systemctl restart console.service`, and the header overclaims

until the restart. Ordinary unit/exec tenants restart themselves either way.

+ A stamped route also receives its config from the root pass (spec

+ `docs/superpowers/specs/2026-09-07-named-unit-config-delivery-design.md`):

+ the drop-in it writes RESETS the unit's `EnvironmentFile=` list to the

+ rendered bundle, so a hand-built unit's own `EnvironmentFile=` lines stop

+ applying once it is stamped; `Environment=` lines are untouched.

- **`carlos restart -app X`** (#113, merged 916cd6b, live after the same

roll): member-facing process cycle with no version or config change —

console door touches `apps/<acct>/<app>/restart-gen.json` + bumps the

diff --git a/docs/site/cli.md b/docs/site/cli.md

index 6b7b3c38e..8777f1827 100644

--- a/docs/site/cli.md

+++ b/docs/site/cli.md

@@ -419,6 +419,11 @@ carries on with the old values until its own supervisor restarts it. `set` and

`unset` say so, naming the routes it applies to, and say when they could not

work it out rather than staying quiet about it.

+A write that reaches a route no pass delivers to says so ("this write did

+not reach <host>"), with the two ways out: name the unit that runs the

+process on the box, or opt the bundle into file delivery. A stamped route

+the root pass will refuse is reported as blocked with the reason.

### carlos secrets

The same shape as `carlos env`, sealed. `list` prints key names and never

@@ -428,6 +433,11 @@ values.

carlos secrets set --app hello STRIPE_KEY=sk_live_example

```

+A write that reaches a route no pass delivers to says so ("this write did

+not reach <host>"), with the two ways out: name the unit that runs the

+process on the box, or opt the bundle into file delivery. A stamped route

+the root pass will refuse is reported as blocked with the reason.

Sealing uses a public key; the private half lives on the box that decrypts

them and never leaves it, in either mode. `carlos secrets genkey` mints the

pair, and it is always local to your terminal.

@@ -882,8 +892,9 @@ carlos add --app hello --socket /run/hello.sock hello.example.com

`--channel` sets what the route follows, `--kind` picks instance, service or

static, and `--addr` takes a TCP upstream where the app is not a socket

tenant. `--unit console.service` names the systemd unit that owns the route's

-process, which is what lets adoption cycle it; leave it off for an ordinary

-exec child.

+process, which is what lets adoption cycle it and the root pass deliver its

+config; it needs `--addr` and neither `--socket` nor `--hibernate`; leave it

+off for an ordinary exec child.

### carlos remove

@@ -910,6 +921,14 @@ carlos route --host hello.example.com --channel edge

when idle. `--backing` and `--unit` are two answers to one question — who owns

this route's process — so the command will not let you write both.

+Naming a unit also hands its config to the root pass: on every config

+write the pass renders the route's bundle to `/etc/carlos/apps/<host>.env`,

+keeps a drop-in under `/etc/systemd/system/<unit>.d/` that makes that file

+the unit's only `EnvironmentFile=`, reloads systemd and restarts the unit.

+A stamp needs an addr upstream and no hibernation; `--unit` refuses a

+socket or hibernating row, `--hibernate` refuses a stamped one, and

+`--unit -` always clears.

`--replication` picks how often the route's database is copied off the box:

`stream` syncs on every change, about once a second; `batched` at most every

five minutes; `daily` at wake and then once a day. The rung you pick is a