amadan
docs: create is the whole storage path once an account is approved
Stage 8 of #381. The CLI reference described a world where every store needed an operator to grant it, one app at a time, forever. That is now the fallback road rather than the only one, and the page said nothing about the road most people will take. The copy here has NOT been through review yet.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AuiZoEUxEooEfFBAs8XPLB
1 file changed,
+41
−9
docs/site/cli.md+41 −9
CI passed — run details
diff --git a/docs/site/cli.md b/docs/site/cli.md| index 9de517f37..354758c07 100644 |
| --- a/docs/site/cli.md |
| +++ b/docs/site/cli.md |
| @@ -405,24 +405,56 @@ narrows to one instance. |
| ### carlos store |
| -Object storage for an app. `create` declares that the app wants a bucket, |
| -which is a request and not a provision — nothing exists in any cloud account |
| -until an operator runs `grant`. `status` shows what is declared, granted and |
| -delivered, including a rotation that stopped half way. |
| +Object storage for an app. An account owner applies once, and a deployment |
| +operator approves the account. After approval, `create` is the whole member |
| +workflow: it declares the store and provisions it when the deployment has an |
| +object-storage backend. Approval allows unlimited stores, with usage metered; |
| +the deployment's cloud account and its cloud provider's soft bucket quota remain |
| +the practical ceiling. |
| ```sh |
| +carlos store apply --account bac --note "backups for the service" |
| +carlos store approvals |
| +carlos store approve --account bac |
| carlos store create --app hello |
| carlos store status --app hello |
| ``` |
| +`apply` is for an account owner. `approvals`, `approve` and `decline` are |
| +deployment-operator commands. `decline` requires a reason: |
| + |
| +```sh |
| +carlos store decline --account bac --reason "storage is not available for this deployment" |
| +``` |
| + |
| +An owner may apply again after a decline. Declining an already approved account |
| +stops new automatic provisioning but does not tear down existing buckets or |
| +credentials. `carlos store grant` remains the per-app operator override for an |
| +unapproved account, for adopting an existing bucket with `--bucket`, and for |
| +repairing a store after approval is withdrawn. |
| + |
| +`status` adds an account line when it has never applied, is pending or has been |
| +declined. An approved account needs no extra line. It then shows the app's |
| +declaration and provisioning state. A human |
| +account member may see the decline reason; the CLI does not print the |
| +application note. Tenant-facing responses withhold the deciding operator's |
| +address. Machine credentials receive state without the note or reason, while |
| +operator views can show the application details they need to decide. |
| + |
| +If provisioning fails after `create` has declared the store, run `create` again |
| +to resume provisioning. A bucket name can remain unavailable for a short time |
| +after the cloud provider destroys it; during that destroy/re-create window, |
| +retry after the provider releases the name. `status` shows an incomplete store |
| +so you can tell this from an undeclared store. |
| + |
| `carlos store rotate` mints a fresh credential and leaves the old one live |
| until you run it again with `--finish`, so the app has a window to pick the |
| new one up. Rotating, declaring and reading status are member verbs and want |
| -nothing but your bearer token. `grant` is the one that spends money in the |
| -deployment's own cloud account, so it also wants an address on |
| -`CARLOS_STORE_OPERATORS`; that check runs after the account gate, so a |
| -stranger still meets the same 404 as everyone else rather than a 403 that |
| -would confirm the app exists. |
| +nothing but your bearer token. `grant` requires membership in the account and a |
| +deployment-operator address on `CARLOS_STORE_OPERATORS`; a non-member still |
| +receives the same 404 as everyone else. `approvals`, `approve` and `decline` |
| +require both the fleet-operator role and that allowlist entry, but the operator |
| +does not need membership in the account being reviewed. |
| ### carlos email |