aac-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{aac_cli-0.2.0/aac_cli.egg-info → aac_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aac-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: The aac platform CLI — headless operator interface to the AAC control plane (tenant registration, chain audit).
 Author: Agent Authority Cloud Project
 License-Expression: Apache-2.0
@@ -24,6 +24,9 @@ which tenant they belong to and what they were authorised to do. A
 runs beside an AAC sidecar that signs outgoing requests and verifies
 incoming ones against public trust material the tenant publishes.
 
+New to AAC? [What AAC is for](https://cascadeauth.github.io/aac-sidecar-go/#what-aac-is-for)
+explains what delegated authority between agents buys you, and what it does not.
+
 The `aac` command is how a tenant's operator does everything that is not
 done by the sidecar itself: register the tenant, sign in, manage keys,
 workloads and domains, and prepare a runnable local workload. Everything
@@ -60,20 +63,21 @@ Python 3.10 or newer is required.
 registers the agent's identity with AAC and creates the keys, certificates
 and configuration its sidecar needs. The agent itself is yours. The first
 run also creates your profile and registers your tenant; run it again with
-a new `--agent` and `--workload-path`, and the same `--trust-url` and
-`--idp`, for each further agent.
+a new `--agent` and its own `--agent-config` file, and the same `--trust-url`
+and `--idp`, for each further agent.
 
 Along the way it signs you in, registers a developer tenant (or reuses the
 one your profile is already bound to), takes the trust domain AAC assigns to the
-tenant, registers a sample workload, generates development keys and
+tenant, registers your workload, generates development keys and
 certificates, and writes a complete sidecar configuration together with the
 files the trust-anchor publisher and Docker Compose need.
 
 Point it at the endpoints your AAC environment gives you. The example below
-uses the AAC stage environment:
+uses the AAC stage environment. First save the YAML example in “Agent configuration”
+below as `orders.yaml`:
 
 ```bash
-aac init --profile stage \
+aac init --profile stage --agent orders --agent-config orders.yaml \
   --admin-url https://api.stage.cascadeauth.dev \
   --data-plane-url https://api.stage.cascadeauth.dev \
   --trust-url https://trust.stage.cascadeauth.dev \
@@ -85,7 +89,7 @@ tenant, because a tenant is permanent. In a script, where there is no
 terminal to answer the question, pass `--create-tenant`:
 
 ```bash
-aac init --profile stage \
+aac init --profile stage --agent orders --agent-config orders.yaml \
   --admin-url https://api.stage.cascadeauth.dev \
   --data-plane-url https://api.stage.cascadeauth.dev \
   --trust-url https://trust.stage.cascadeauth.dev \
@@ -117,8 +121,7 @@ never asks you to pick between GitHub and Google again.
 
 ### What it creates, and where
 
-* `~/.aac/agents/<agent>/` holds the files **one sidecar** needs (default
-  name `starter`), in folders named for where each file goes. `sidecar/` is
+* `~/.aac/agents/<agent>/` holds the files **one sidecar** needs, in folders named for where each file goes. `sidecar/` is
   what you mount or copy into the sidecar: the workload, receipt and HTTPS
   key pairs, this agent's root-signing key, the CA certificate and the
   outbound CA bundle. `agent/` is what the paired application reads: the
@@ -153,23 +156,27 @@ settings files written for them. It also records how far setup got, so
 rerunning `aac init` resumes where it stopped.
 
 Use one agent per workload. `aac init --agent <name>` creates an agent
-(with `--trust-url`) or resumes it (the default name is `starter`), and
+(with `--agent-config` and `--trust-url`) or resumes it. There is no default agent;
 three commands look after it:
 
 ```bash
-aac agent status --agent starter   # what exists, what is due, and the next step
-aac agent renew --agent starter    # replace the short-lived certificates
+aac agent status --agent orders   # what exists, what is due, and the next step
+aac agent renew --agent orders    # replace the short-lived certificates
 aac agent list                     # every agent on this machine
 ```
 
+`agent list` reports an unreadable or unsupported record in that agent's
+`state` and continues listing the others. `agent status --agent <name>` still
+returns a local-state error for that individual agent.
+
 There is no separate command for the settings files. Running setup again —
 with the profile the agent belongs to — writes `sidecar-config.yaml`,
 `compose.env` and the tenant's `publisher.env` from what the agent already
 records, without touching a single key:
 
 ```bash
-aac init --profile stage --agent starter                     # write them again
-aac init --profile stage --agent starter --layout container  # and change the layout
+aac init --profile stage --agent orders                     # write them again
+aac init --profile stage --agent orders --layout container  # and change the layout
 ```
 
 That is how you rebuild a settings file you lost and how you move between
@@ -181,7 +188,7 @@ whenever it is the next step.
 A second workload is a second agent with its own workload path:
 
 ```bash
-aac init --profile stage --agent worker --workload-path demo/worker \
+aac init --profile stage --agent worker --agent-config worker.yaml \
   --idp github --trust-url https://trust.stage.cascadeauth.dev
 ```
 
@@ -192,14 +199,177 @@ settings files never changes that file's endpoints, so an agent created with
 a different trust URL stops at its last step and has to be set up again
 under a new name.
 
-`--agent` names the local files; `--workload-path` chooses the workload's
-identity, the path at the end of its SPIFFE ID (`demo/agent` unless you
-choose another). Two agents with the same workload path are the same
+`--agent` names the local files and must match the file's `agent_name`.
+The file's required `workload_path` supplies the path at the end of the SPIFFE ID.
+An optional `--workload-path` must match the file or saved identity; omission
+on refresh reuses that identity. Missing or conflicting identities are refused. Two agents with the same workload path are the same
 workload holding different keys: that is what a replacement computer wants,
 and what a second workload does not. The agent name is permanent, because
 the root key id is made from it. `aac init` needs the profile the agent was
 created with; the `aac agent` commands read it from the agent itself.
 
+### Agent configuration
+
+The operator writes one YAML file. `aac init --agent-config PATH` validates and
+explicitly applies it. The profile remains INI; this file describes one agent,
+not its profile or the hosted service. For example, save this as `orders.yaml`:
+
+```yaml
+agent_name: orders
+workload_path: fulfilment/orders
+tls_server_names: [orders.internal.example, localhost, 127.0.0.1]
+sidecar:
+  agent_invoke_url: http://127.0.0.1:8000/invoke
+  external_bind_address: 127.0.0.1
+  telemetry:
+    sink: orders.jsonl
+    central_forward: false
+classes_of_action:
+  fulfil_order:
+    predicates:
+      action: reserve_inventory
+      amount_max: 10000
+      originator_reference: "PO #4143"
+    valid_for: +8m
+destinations: {}
+```
+
+This declares the tenant's permission; AAC does not invent one. The application
+chooses `fulfil_order` when starting a chain and checks that its business action
+matches the authorized context. Units and business meaning belong to the
+application. Empty classes and destinations are allowed for registration before
+peer identities are known. No self destination is added.
+
+**Chain-start boundary:** restrict `/v1/agent/delegations` and
+`/v1/agent/mint-root` to the authorized originating application at the
+network/ingress boundary. Sidecar **v0.4.0 and later** also require the existing
+pair's AAC1-HMAC-SHA256 signature over the exact alias and raw request body.
+Older releases do not authenticate these callers, so sharing a private network
+with peers is insufficient. An authorized separate originator may hold the pair
+secret only inside the same trusted tenant-application boundary; it gains
+callback-signing capability too. Never share secrets across pairs or tenants.
+Pairing freshness is not idempotent chain creation; do not automatically retry
+an uncertain mint. Development certificates do not require `dev_mode`.
+
+Applications using v0.4.0 can supply per-request `obligations` for T1. Equal
+configured/request values combine once; differing values refuse rather than
+override or intersect. Put dynamic limits in the request instead of also
+configuring a different class value. Native request `valid_until` is reserved;
+remove it and use class `valid_for`. For signed correlation, normally supply a
+`task_ref` obligation per request: top-level `task_ref` alone is correlation
+metadata, while a static class predicate deliberately shares one convergence
+key across that class's chains. Omitted/null metadata inherits a configured or
+obligation predicate; an explicit conflicting value refuses before minting.
+
+The following is the complete input schema. Unknown fields, duplicate mapping
+keys, YAML aliases/merge keys, object tags and files over 64 KiB are refused.
+Null is not an omitted value. Strings must be nonempty and have no surrounding
+whitespace or control characters. Lists allow at most 128 unique values; class
+and destination maps allow at most 128 entries each.
+
+| Field | Type and meaning | Default when omitted |
+|---|---|---|
+| `agent_name` | Required local name, 3–15 characters under the same name rules as `--agent`; must match it. | None |
+| `workload_path` | Required concrete SPIFFE path, 3–150 ASCII characters; slash-separated letters/digits/`._~-`, no empty or dot segments, wildcard, query or escaped character. Fixed once the agent exists. | None |
+| `tls_server_names` | Required nonempty list of DNS names/IP addresses callers use for HTTPS, including the originating application. No URLs, wildcards or unspecified bind addresses. | None |
+| `sidecar.dev_mode` | Boolean enabling the runtime's development exceptions; independent of certificate source and replay profile. | `false` |
+| `sidecar.loopback_bind_address` | Must be exactly `127.0.0.1` when `dev_mode: false`; another loopback IP address requires `dev_mode: true`. Non-loopback addresses are not accepted by this input. | `127.0.0.1` |
+| `sidecar.external_bind_address` | IP bind address for the peer listener; choose the reachability your ingress allows. | `127.0.0.1` |
+| `sidecar.loopback_port`, `sidecar.external_port` | Distinct integer ports, 1–65535. | `8080`, `9443` |
+| `sidecar.agent_invoke_url` | Absolute HTTP(S) URL of your application's invoke endpoint. | `http://127.0.0.1:8000/invoke` |
+| `sidecar.log_level` | `debug`, `info`, `warn` or `error`. | `info` |
+| `sidecar.telemetry.sink` | Filename within managed `state/` (letters/digits/`_.-`, starting with a letter/digit), or `stdout` / `none`. `a2a-egress.db` is reserved for managed database state, regardless of case or whether A2A is enabled. Host/container paths are generated. | `telemetry.jsonl` |
+| `sidecar.telemetry.central_forward` | Boolean opt-in for asynchronous metadata-only forwarding. The endpoint and tenant API-key file come from the selected profile/agent binding, never another tenant's file. | `false` |
+| `replay_protection.backend` | `memory` or `valkey`. | `memory` |
+| `replay_protection.deployment_profile` | `basic` with memory; `ha-retained-write-safe` with Valkey. No fallback. | The matching profile |
+| `replay_protection.url` | Required absolute `valkeys://` URL for Valkey, with an optional numeric database path. No query, fragment or embedded credentials. Not valid with memory. | None |
+| `replay_protection.memory_max_entries` | Integer 1–1000000. | `100000` |
+| `replay_protection.connect_timeout_ms` | Integer 1–100. | Runtime default `100` |
+| `replay_protection.operation_timeout_ms` | Integer 1–250. | Runtime default `50` |
+| `replay_protection.max_connections` | Integer 1–4096. | Runtime default `32` |
+| `replay_protection.cold_start_quarantine_seconds` | Integer 120–3600. | Runtime default `120` |
+| `trust_anchors.tenant_ids` | Additional canonical `tnt-<UUID>` tenant IDs whose root signatures you trust. | Empty; own tenant is always included |
+| `spiffe_bundles.trust_domains` | Additional lowercase trust domains whose workload certificates you trust. | Empty; own assigned domain is always included |
+| `https_trust.ca_files` | Paths to public PEM CA certificate files, relative to the input file or absolute; up to 256 KiB each and 1 MiB total. Certificate-only PEM is saved; refresh/renewal do not reread the source files. No private keys. | Empty; own CA is always included |
+| `https_trust.system_roots` | Boolean adding the current machine's system public HTTPS roots, with certifi fallback. With `false`, every outbound TLS service—including the control plane, trust URL, peer and Valkey—must chain to the own CA or a CA listed in `ca_files`. | `true` |
+| `classes_of_action.<name>.predicates` | Mapping of registered predicate names to supported values, described below. The class entry's `<name>` uses letters/digits/`_.-`, starting with a letter/digit, up to 128 characters; predicate names come only from the closed registry. | Empty mapping |
+| `classes_of_action.<name>.valid_for` | Required positive duration, 1 second–24 hours: digits with optional `+`, then `s`, `m`, `h` or `d`. The CLI supplies the registered `audience_self`. | None |
+| `destinations.<name>.url` | Required absolute HTTPS recipient URL, for native receive or A2A. | None |
+| `destinations.<name>.audience_pattern` | Required exact registered SPIFFE identity; no wildcard. | None |
+| `destinations.<name>.predicates`, `.valid_for` | Same value/duration contract as classes. | Empty predicates; duration required |
+| `destinations.<name>.timeout_ms` | Integer 1–2147483647 without A2A; 1–60000 for every destination when A2A is enabled, matching its generated deadline. | `10000` |
+| `a2a.public_base_url`, `a2a.local_handler_url` | Optional A2A block; both required if present. Public URL is HTTPS with no path except optional `/`; the HTTP(S) local handler path must be exactly `/a2a/v1`, with no escaped spelling. Neither URL permits query or fragment markers, even empty ones. Managed A2A state paths and a 60-second deadline are generated. No A2A self-route is added. | A2A disabled |
+
+URL hosts are ASCII DNS names or IP addresses; URL fields reject whitespace,
+backslashes, embedded credentials and fragments. Basic replay history
+is process-local: restarting loses it, and replicas do not share it. Selecting
+Shared durable declares that the operator has qualified the Valkey service; the
+CLI does not establish durability. This configuration interface does not accept
+credential-bearing replay URLs.
+
+The three kinds of trust above are separate checks. Obtain peer tenant IDs,
+assigned trust domains and exact workload identities from their public status
+or registration output. Exchange public CA certificates only. After registering
+both agents, explicitly apply their peer configurations with the same command:
+
+```bash
+aac init --profile stage --agent orders --agent-config orders.yaml
+```
+
+The closed predicate registry accepts `action`, `amount_max`, `amount_min`,
+`amount`, `valid_from`, `beneficiary_account`, `beneficiary_class`, `currency`,
+`data_scope`, `purpose`, `human_authorization_class`, `task_ref`,
+`min_account_age_days`, `max_authority_amount`, `assessed_damage_amount`,
+`assessment_outcome`, `surveyor_findings`, `payout_amount`, `program_reference`,
+`reporting_quarter`, `claim_ref`, `hours`, `quantity_units`, `beneficiary`,
+`unit_price_usd`, `account`, `esg_scope3_co2e_kg`, `conflict_minerals_clear`,
+`originator_reference`, `scope`, `composite_payout_amount`,
+`composite_payout_total`, `composite_units_total`,
+`composite_esg_scope3_co2e_kg_total` and `composite_conflict_minerals_clear`.
+`amount_max`, `amount_min` and `valid_from` accept nonnegative integers or
+canonical decimal strings (`0` or a nonzero digit followed by digits), at most
+9223372036854775807. Enforced numbers are checked before YAML integer conversion:
+spellings such as `010`, `0x10`, `1_000` and `+10` are refused, quoted or unquoted,
+so the loader cannot silently reinterpret a limit. Other values must be strings. Commas are refused because
+they separate wire predicates. The combined mapping has a 7900-byte UTF-8
+budget, leaving room for the generated expiry.
+
+`valid_until` is generated authority data, so it is refused in static input:
+use `valid_for`. Registry membership alone does not give business labels new
+monotonic enforcement. The current HTTP mint route uses the selected class's
+static first limits; it accepts no per-request obligations. Your application
+remains responsible for its policy decision.
+
+Applying a file rewrites the generated configuration; restart the sidecar to
+load it. Ordinary refresh and certificate renewal use the saved accepted values,
+even if the original file is edited, moved or removed. Public CA file changes
+also require explicit reapplication. The source file is never rewritten. Keep
+the agent directory, credentials and keys; the input file is not their backup.
+Generated files are disposable outputs and should not be hand-edited.
+
+HTTPS certificates must authenticate every configured connection name. The CLI
+issues them for those names or checks supplied certificates against them; renewal
+keeps those names. Applying a different name set requires the installed certificate
+to cover it already: supplied issuers can issue a certificate covering both sets
+before the change. A CLI-issued agent needing new names must be created under a
+new name with the intended configuration. No old agent-record format is migrated.
+
+Central forwarding retains the local sink and sends only permitted metadata.
+It is asynchronous and best-effort; a local event does not prove central delivery.
+It excludes business predicates, task references, raw tokens/proofs and receipts.
+`AAC_TELEMETRY_SINK` and `AAC_AGENT_STATE_DIR` in `compose.env` identify the local
+file and mount; `AAC_API_KEY_FILE` identifies this tenant's credential. Mount it
+at `/run/secrets/tenant-api-key` in the container layout. Do not read private
+`record.json` from consumers.
+
+For a CA change: stop the affected sidecar/application; renew or install the
+issuer's replacement certificates; restart the publisher and verify publication
+with `aac agent status --agent <name> --remote`; exchange the new public CA with
+each intended peer and explicitly reapply that peer's configuration; then restart
+the sidecars/applications and verify traffic in both directions. A peer's files
+are never changed implicitly. Old published CA anchors remain until deliberately
+retired. Leaf-only renewal needs a sidecar restart, without changing peer trust.
+
 ### Two ways to get your agent's certificates
 
 Find your situation here and use the flags it lists. Nothing is inferred:
@@ -227,13 +397,13 @@ The laptop case. The CLI creates a certificate authority on this machine and sig
 
 #### I bring my own CA
 
-The production case. Your own issuer has already signed the agent's certificates, and your CA private key never reaches this machine.
+Your own issuer has signed the agent's certificates, and your CA private key never reaches this machine. Certificate source alone does not qualify a production deployment.
 
 **Flags.** All seven together: `--workload-cert-file`, `--terminal-cert-file` and `--tls-cert-file`, each with its key file (`--workload-key-file`, `--terminal-key-file`, `--tls-key-file`), plus `--ca-cert-file`. Never `--ca-key-file`: the CLI does not want your CA key.
 
 **Keys and signatures.** Your CA's key must be Ed25519 or EC P-256, and it must have signed each certificate with Ed25519 or ECDSA-with-SHA-256. The two identity keys may be Ed25519 or EC P-256; the HTTPS key must be EC P-256. RSA is not supported: the sidecar cannot verify against it.
 
-**The CLI** checks each certificate against its key, its issuer and its validity window; registers the workload and writes the settings files and the pairing secret; publishes your CA certificate as a trust anchor named `<agent>-ca`.
+**The CLI** checks each certificate against its key, its issuer and its validity window, and HTTPS certificates against every configured connection name; registers the workload and writes the settings files and the pairing secret; publishes your CA certificate as a trust anchor named `<agent>-ca`.
 
 **The CLI does not** create a certificate authority; issue any certificate; ask for, read or store your CA private key.
 
@@ -288,8 +458,13 @@ profile (~/.aac/config) ── bound to ──> tenant
 ### What each file is for, and what to back up
 
 The table lists every file the CLI creates, what it is for, how long it
-lives and whether to back it up. `<agent>` is the agent name
-(default `starter`) and `<tenant-id>` the tenant id AAC allocated.
+lives and whether to back it up. `<agent>` is your explicitly selected agent
+name and `<tenant-id>` the tenant id AAC allocated.
+
+For what each of these proves, who else ever gets a copy, what never leaves you
+and how the pieces fit together — including when your own certificate authority
+signs instead of this tool — see
+[Keys and certificates](https://cascadeauth.github.io/aac-sidecar-go/keys-and-certificates.html).
 
 <!-- inventory-table:start -->
 | No. | Material | Where | Used for | Lifetime | Back up? |
@@ -300,9 +475,9 @@ lives and whether to back it up. `<agent>` is the agent name
 | 4 | root_signing_key | `~/.aac/agents/<agent>/sidecar/root.pem`, `~/.aac/agents/<agent>/sidecar/root.pub.pem`, `~/.aac/tenants/<tenant-id>/root-keys/<agent>-root-v1.pub.pem` | the sidecar mints authority chains; the public half is published under the key id | until you retire its key id (root key ids are fixed per agent name) | No. never restore the private key: a replacement agent gets a new name and therefore a new key id, published alongside the old one until the old one is retired; its public copies are recreated from it |
 | 5 | development_ca | `~/.aac/agents/<agent>/keep/ca.key`, `~/.aac/agents/<agent>/sidecar/ca.crt`, `~/.aac/agents/<agent>/agent/ca.crt`, `~/.aac/tenants/<tenant-id>/spiffe-bundle/<agent>-dev-ca.ca.pem` | signs the workload, terminal and TLS certificates; peers trust it via the published bundle | 7 days; `aac agent renew --ca` | No. development only; reissue; a lost copy of the certificate is copied back from `sidecar/ca.crt` |
 | 6 | workload_svid | `~/.aac/agents/<agent>/sidecar/workload.key`, `~/.aac/agents/<agent>/sidecar/workload.crt` | the sidecar's SPIFFE identity: proves on every live request that this workload holds the key behind its certificate | 1 day; `aac agent renew` | No. reissue |
-| 7 | terminal_attestation | `~/.aac/agents/<agent>/sidecar/terminal.key`, `~/.aac/agents/<agent>/sidecar/terminal.crt` | signs the receipt (terminal attestation) the sidecar issues when this workload completes a delegated request; auditors verify it offline against your published CA; kept separate from the workload key so neither can forge the other's role | 1 day; `aac agent renew` | No. reissue |
-| 8 | localhost_tls | `~/.aac/agents/<agent>/sidecar/server.key`, `~/.aac/agents/<agent>/sidecar/server.crt` | the sidecar's HTTPS listener | 1 day; `aac agent renew` | No. reissue |
-| 9 | outbound_ca_bundle | `~/.aac/agents/<agent>/sidecar/outbound-ca.pem` | the sidecar verifies TLS to AAC and to itself | rebuilt by renew; `aac agent renew` | No. derived |
+| 7 | terminal_attestation | `~/.aac/agents/<agent>/sidecar/terminal.key`, `~/.aac/agents/<agent>/sidecar/terminal.crt` | signs the receipt (terminal attestation) the sidecar issues when this workload completes a delegated request; auditors verify it offline against your published CA; setup gives it its own key so the two signing jobs stay separate, but a receipt is verified against your published CA and the expected agent identity, which the workload certificate also satisfies — treat both keys as one blast radius | 1 day; `aac agent renew` | No. reissue |
+| 8 | https_tls | `~/.aac/agents/<agent>/sidecar/server.key`, `~/.aac/agents/<agent>/sidecar/server.crt` | the sidecar's HTTPS listener | 1 day; `aac agent renew` | No. reissue |
+| 9 | outbound_ca_bundle | `~/.aac/agents/<agent>/sidecar/outbound-ca.pem` | the sidecar verifies TLS to AAC and configured peers | rebuilt by renew; `aac agent renew` | No. derived |
 | 10 | pairing_secret | `~/.aac/agents/<agent>/agent/pairing.secret` | the sidecar and its agent authenticate each other (same bytes in both) | until regenerated | No. regenerable; both processes must read the same file |
 | 11 | agent_record | `~/.aac/agents/<agent>/record.json` | the agent's identities and progress; every `aac agent` verb reads it first | for the life of the agent | **Recommended.** cannot be recreated by any command; without it start a new agent under a new name (see the new-computer setup procedure) |
 | 12 | published_public_inputs | `~/.aac/tenants/<tenant-id>/root-keys`, `~/.aac/tenants/<tenant-id>/spiffe-bundle` | the publisher's input directories: every root public key and CA certificate this tenant has published, across all agents | for the life of the tenant | **Recommended.** back up with the tenant directory: a replacement agent must publish its new root key alongside a still-ACTIVE previous one (the control plane refuses a root-key set that drops every ACTIVE key at once) |
@@ -315,11 +490,11 @@ the machine is healthy. Everything else is regenerated.
 ### Inspect and maintain an agent
 
 ```bash
-aac agent status --agent starter --output table   # what exists, expiry, permissions, next command
-aac agent status --agent starter --remote         # also: is the public trust material visible?
-aac agent renew --agent starter                   # replace the short-lived certificates; old ones archived
+aac agent status --agent orders --output table   # what exists, expiry, permissions, next command
+aac agent status --agent orders --remote         # also: is the public trust material visible?
+aac agent renew --agent orders                   # replace the short-lived certificates; old ones archived
 aac agent list                                    # every agent on this machine, with its case
-aac init --profile stage --agent starter --layout container   # write the settings again, container paths
+aac init --profile stage --agent orders --layout container   # write the settings again, container paths
 ```
 
 `status` works offline by default and exits with code 3 when material is
@@ -363,7 +538,7 @@ ahead for the development CA.
 
 | Material | Lasts | When it runs out | What to do |
 |---|---|---|---|
-| Workload, terminal-attestation and localhost TLS certificates | 1 day | the sidecar can no longer prove its identity, sign receipts or serve HTTPS | `aac agent renew --agent <name>`, then restart the sidecar so it loads them |
+| Workload, terminal-attestation and HTTPS certificates | 1 day | the sidecar can no longer prove its identity, sign receipts or serve HTTPS | `aac agent renew --agent <name>`, then restart the sidecar so it loads them |
 | Development CA | 7 days | certificates it signed stop being trusted, and no new ones can be issued | `renew` also replaces the CA when it is expired or within a day of expiry, or when `--ca` is given, and then reissues every certificate under it: restart the publisher so the new CA is published, restart the sidecar and anything else that trusted the old CA, and confirm with `aac agent status --agent <name> --remote` |
 | Tenant-admin session | hours | administration commands ask you to sign in again | `aac sso login` |
 | Tenant API key, tenant-admin signing key, root signing key | do not expire | — | replaced only on purpose: see "Keys" and "Setting up aac-cli on a new computer" |
@@ -376,10 +551,9 @@ a week that renewal also replaces the development CA (`renew` then reports
 agent, and anything else that trusted the old CA. Renewing is safe to
 repeat, but it is not a no-op: every run issues fresh keys and moves the old
 files to the agent's `archive/` directory, so whatever reads them must
-reload. With the
-[AAC Compose starter](https://github.com/CascadeAuth/aac-compose-starter),
-`./starter up` recreates the containers so they load the new files; it
-does not renew anything itself.
+reload. Recreate or restart the affected processes with your deployment's
+normal commands after publishing and explicitly refreshing each peer's public
+trust. Restarting a process does not renew its certificates.
 
 All of this is development material. In production, certificates come from
 your own issuer and follow its renewal process.
@@ -454,12 +628,13 @@ profile; `aac profile show` prints it, and the example below uses
    directory the publisher runs from. Then run step 3 with
    `--tenant-admin-key-file tenant-admin.pem` added.
 
-3. Run the guided setup with a **new agent name**. A developer tenant
+3. Prepare `laptop-2.yaml` with the new `agent_name` and the original
+   workload path, deployment and trust choices. Run setup with that **new agent name**. A developer tenant
    passes its sign-in choice, so an expired session is renewed without a
    prompt:
 
    ```bash
-   aac init --profile stage --agent laptop-2 --idp github \
+   aac init --profile stage --agent laptop-2 --agent-config laptop-2.yaml --idp github \
      --trust-url https://trust.stage.cascadeauth.dev
    ```
 
@@ -469,7 +644,7 @@ profile; `aac profile show` prints it, and the example below uses
    the `aac sso login --idp-url …` command from step 1 first:
 
    ```bash
-   aac init --profile stage --agent laptop-2 \
+   aac init --profile stage --agent laptop-2 --agent-config laptop-2.yaml \
      --trust-url https://trust.stage.cascadeauth.dev
    ```
 
@@ -731,10 +906,19 @@ aac tenant reissue-api-key --profile prod
 
 ### Domains and workloads
 
-Every tenant gets a hosted trust domain from AAC; registration saves it in
-the profile, and `aac tenant assign-hosted-domain` assigns one to a tenant
-that has none yet. To use your own DNS domain as a trust domain instead,
-prove control of it with a DNS TXT record, then bind it:
+Every tenant gets an AAC-assigned trust domain: the tenant id plus a suffix
+the control plane selects for its environment,
+`<tenant_id>.tenants.stage.cascadeauth.dev` on stage and
+`<tenant_id>.tenants.cascadeauth.com` on production. No DNS record or proof
+of ownership is needed; the first call allocates the name permanently and
+every later call returns the same one, so use the name the command returns
+rather than building it yourself. Registration saves it in the profile as
+`hosted_trust_domain`. Signing in with `aac sso login` does not write it:
+`aac tenant assign-hosted-domain` requests the same allocation and saves it
+into the profile bound to that tenant, as `aac init` does during setup. To
+use a custom domain you own as a trust domain instead, prove control of it
+with a DNS TXT record, then bind it; a domain you own is recorded on the
+server and never written to the profile:
 
 ```bash
 aac tenant issue-domain-challenge --profile prod --domain example.com