amadan
docs: carlos proof in the CLI page (H6, needs Paul's copy review)
TestCLICommandsAreDocumented requires a heading for every dispatched command, and proof had none. The section sits after release-keygen, in the usage order, with one example each for keygen, get and put. User-facing copy: not to merge before Paul's copy review.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 file changed,
+39
−0
docs/site/cli.md+39 −0
diff --git a/docs/site/cli.md b/docs/site/cli.md| index f1c082b36..285e67361 100644 |
| --- a/docs/site/cli.md |
| +++ b/docs/site/cli.md |
| @@ -1584,6 +1584,45 @@ a grant. The grant carries no secret material but has to travel with the key, |
| because a scoped key on its own signs pointers nothing will accept. Only the |
| root key can mint a grant, which is what stops a scoped key widening itself. |
| +### carlos proof |
| + |
| +Makes and carries the proofs a box can require before it adopts a build. A |
| +proof is signed by a proving deployment (dev, usually) and says it ran these |
| +exact bytes healthily. A box whose proof policy lists an app adopts a new |
| +build of it only with a proof, or when it has run those bytes well itself. |
| + |
| +```sh |
| +carlos proof keygen |
| +``` |
| + |
| +`keygen` runs as root on the proving box. It writes a fresh signing key to |
| +`/etc/carlos/proving.key`, readable by root only (`--out` puts it somewhere |
| +else), and prints the public half. That public half goes into the `require` |
| +entry of each requiring box's `/etc/carlos/proof-policy.json`. It never |
| +overwrites a key that is already there. |
| + |
| +```sh |
| +carlos proof get --app console --sha256 <sha256> > proof.json |
| +``` |
| + |
| +`get` reads a build's proof from the proving deployment's bucket and prints |
| +it. `--sha256` is the build's artifact hash. `--prover` picks whose proof, |
| +when there is more than one. When there is no proof yet, it says how long the |
| +build has been live on the proving box, if it has been seen there. |
| + |
| +```sh |
| +carlos proof put --app console proof.json |
| +``` |
| + |
| +`put` writes that proof into the requiring deployment's bucket, where its |
| +boxes look for it. It checks the proof's shape but not its signature. The |
| +requiring box checks that against the key in its policy. Putting the same |
| +proof twice is fine. A different proof for the same build and prover is |
| +refused. |
| + |
| +`get` and `put` work only with `CARLOS_DEPLOYMENT_BUCKET` or |
| +`CARLOS_DEPLOYMENT_DIR` set, because a proof lives only in a bucket. |
| + |
| ### carlos economics |
| Records one month's AWS bill so the console's economics dashboard has a real |