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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aac-cli
-Version: 0.1.6
+Version: 0.2.0
 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
@@ -60,7 +60,7 @@ 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 `--workspace` and `--workload-path`, and the same `--trust-url` and
+a new `--agent` and `--workload-path`, 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
@@ -97,7 +97,7 @@ aac init --profile stage \
 offers developer tenants. If you need another sign-in provider, contact
 support@cascadeauth.com.
 
-`--trust-url` is required when a workspace is created: it is the public URL
+`--trust-url` is required when an agent is created: it is the public URL
 where your AAC environment serves trust material, and for AAC stage it is
 `https://trust.stage.cascadeauth.dev`. If you leave it out, the command
 stops before creating anything and names the value your tenant already
@@ -108,137 +108,187 @@ registers the tenant, the second starts the tenant-admin session that
 registers the workload. The command says so before the first one.
 
 Progress lines `[1/5]` to `[5/5]` name the five steps: tenant, sign-in,
-hosted trust domain, workload, and material; the configuration files are
-rendered last. Rerunning the
+hosted trust domain, workload, and material; the settings files are
+written last. Rerunning the
 command is safe: it resumes an interrupted setup, reports a complete
-workspace, or names the exact conflict. It never overwrites private
+agent, or names the exact conflict. It never overwrites private
 material. The sign-in you chose with `--idp` is remembered, so a rerun
 never asks you to pick between GitHub and Google again.
 
 ### What it creates, and where
 
-* `~/.aac/workspaces/<workspace>/` is the **workspace** for one workload
-  (default name `starter`). `pki/` holds what the sidecar container mounts:
-  the workload, terminal-attestation and localhost TLS key pairs, this
-  workspace's root-signing key and the outbound CA bundle. `pair/` holds
-  what both containers mount as secrets: the pairing secret and the public
-  development CA certificate. `ca/` holds the development CA private key,
-  kept out of both mounts so no container ever sees the key that mints
-  identities. Beside them sit `sidecar-config.yaml`, `compose.env` and a
-  manifest that lets a rerun resume.
+* `~/.aac/agents/<agent>/` holds the files **one sidecar** needs (default
+  name `starter`), 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
+  pairing secret and the CA certificate. `keep/` stays with you — it holds
+  the development CA private key, out of both mounts, so no container ever
+  sees the key that mints identities; an agent whose certificates your own
+  issuer signed has no `keep/` at all. Beside them sit
+  `sidecar-config.yaml`, `compose.env`, `state/` and `record.json`, which
+  lets a rerun resume.
 * `~/.aac/tenants/<tenant-id>/` is **tenant-level** material shared by every
-  workspace of that tenant: the tenant-admin signing key, the publisher's
-  input directories (`root-keys/` and `spiffe-bundle/`, public halves only)
-  and the rendered `publisher.env`.
-* `~/.aac/credentials/<tenant-id>` is the tenant API key. The rendered
+  agent of that tenant: the tenant-admin signing key, the publisher's input
+  directories (`root-keys/` and `spiffe-bundle/`, public halves only) and
+  the generated `publisher.env`.
+* `~/.aac/credentials/<tenant-id>` is the tenant API key. The generated
   configuration references it by path.
 
-**Everything `aac init` generates is development material.** The
+**By default everything `aac init` generates is development material.** The
 development CA lives seven days and the leaf certificates one day. Nothing
-here qualifies for production, whatever the tenant's domain. Moving to
-production means a tenant-admin key under production custody
-(`aac tenant rotate-admin-key`), a new root key id published by your
-publisher, and certificates from your approved issuer.
+there qualifies for production, whatever the tenant's domain. If your own
+issuer signs your agent's certificates instead, see "Two ways to get your
+agent's certificates" below; moving to production also means a tenant-admin
+key under production custody (`aac tenant rotate-admin-key`) and a root key
+id published by your publisher.
 
-### What a workspace is for, and how to use it
+### What an agent folder is for, and how to use it
 
-A workspace holds everything one workload needs to run beside an AAC
+An agent folder holds everything one workload needs to run beside an AAC
 sidecar, kept apart from every other workload: its identity in your
-tenant's trust domain, its own root signing key and key id, its development
-CA and certificates, the pairing secret its sidecar and agent share, and the
-configuration files rendered for them. It also records how far setup got,
-so rerunning `aac init` resumes where it stopped.
+tenant's trust domain, its own root signing key and key id, its
+certificates, the pairing secret its sidecar and application share, and the
+settings files written for them. It also records how far setup got, so
+rerunning `aac init` resumes where it stopped.
 
-Use one workspace per workload. `aac init --workspace <name>` creates a
-workspace (with `--trust-url`) or resumes it (the default name is
-`starter`), and three commands look after it:
+Use one agent per workload. `aac init --agent <name>` creates an agent
+(with `--trust-url`) or resumes it (the default name is `starter`), and
+three commands look after it:
 
 ```bash
-aac workspace status --workspace starter           # what exists, what is due, and the next step
-aac workspace renew --workspace starter            # fresh certificates and keys
-aac workspace render --workspace starter --force   # rewrite the configuration files
+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 list                     # every agent on this machine
 ```
 
-A second workload is a second workspace with its own workload path:
+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 --workspace worker --workload-path demo/worker \
+aac init --profile stage --agent starter                     # write them again
+aac init --profile stage --agent starter --layout container  # and change the layout
+```
+
+That is how you rebuild a settings file you lost and how you move between
+running the sidecar directly on this machine and running it in a container.
+`--profile` is required because setup picks the profile before it reads the
+agent; `aac agent status` prints the same command with the right profile
+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 \
   --idp github --trust-url https://trust.stage.cascadeauth.dev
 ```
 
-Pass the same `--trust-url` and `--idp` as for your first workspace. Each
-workspace records its own, and the trust URL also goes into the tenant's
-`publisher.env`, which every workspace of the tenant shares. A render never
-changes that file's endpoints, so a workspace created with a different
-trust URL stops at its last step and has to be set up again under a new
-name.
-
-`--workspace` 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 workspaces 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 workspace name is
-permanent, because the root key id is made from it. `aac init` needs the
-profile the workspace was created with; the `aac workspace` commands read it
-from the workspace itself.
-
-### What "render" means
-
-To render is to write the configuration files that follow from what the
-workspace records, without touching any key: `sidecar-config.yaml` and
-`compose.env` in the workspace, and `publisher.env` in the tenant
-directory. They hold endpoints, identifiers, settings and the paths of the
-key files, never key material.
-
-`aac init` renders them as its last step. Render again with
-`aac workspace render --workspace <name> --force` when a configuration file
-is lost or to change the layout; without `--force`, `render` refuses to
-overwrite files that exist. The layout decides the paths written into the
-sidecar configuration: `host` (the default) uses paths on this machine, for
-a sidecar that runs directly on it, and `container` uses the paths where the
-files are mounted inside the containers. `compose.env` always holds the
-paths on this machine that Docker mounts from, and `publisher.env` the
-paths a publisher running on this machine reads.
-
-`publisher.env` belongs to the tenant, and every workspace of the tenant
-renders it. A render rewrites its paths and poll interval for this machine
-(hand edits to those are replaced), but refuses, even with `--force`, to
-change its tenant ID, trust domain or URLs, because that would repoint the
-publisher for every workspace. The refusal names the values that differ.
-If the file is the stale one, for example after you deliberately moved the
-tenant to new endpoints and set up its workspaces again, move it aside
-(`mv publisher.env publisher.env.old` in the tenant directory) and render
-again from a workspace with the intended endpoints. The admin key and the
-published public keys stay where they are.
-
-### How profiles, workspaces and tenant data fit together
+Pass the same `--trust-url` and `--idp` as for your first agent. Each agent
+records its own, and the trust URL also goes into the tenant's
+`publisher.env`, which every agent of the tenant shares. Writing the
+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
+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.
+
+### Two ways to get your agent's certificates
+
+Find your situation here and use the flags it lists. Nothing is inferred:
+which case you are in is decided by whether you pass certificates your own
+issuer signed, and the agent records the answer, so `aac agent status` can
+tell you later and `aac agent renew` behaves accordingly.
+
+<!-- material-cases:start -->
+
+<!-- Generated from aac_cli/material_cases.py. Do not edit by hand. -->
+
+#### The CLI creates a development CA
+
+The laptop case. The CLI creates a certificate authority on this machine and signs the agent's identity, receipt and HTTPS certificates with it.
+
+**Flags.** No flags are needed. To reuse a development CA across agents, pass `--ca-key-file` and `--ca-cert-file` together; neither one alone.
+
+**Keys and signatures.** The CA and the two identity keys are Ed25519; the HTTPS key is EC P-256.
+
+**The CLI** creates a 7-day certificate authority and keeps its private key in the agent's keep/ folder; issues the workload, receipt and HTTPS certificates; publishes the CA certificate as a trust anchor named `<agent>-dev-ca`.
+
+**The CLI does not** ask you for anything from your own certificate authority.
+
+**Renewal.** `aac agent renew --agent <name>` issues fresh certificates from the same CA.
+
+#### 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.
+
+**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 does not** create a certificate authority; issue any certificate; ask for, read or store your CA private key.
+
+**Renewal.** `aac agent renew --agent <name>` cannot reissue what it did not sign: it takes the replacements your issuer produced.
+
+<!-- material-cases:end -->
+
+The settings files, `sidecar-config.yaml` and `compose.env` in the agent
+folder and `publisher.env` in the tenant directory, follow from what the
+agent records, in both cases. They hold endpoints, identifiers, settings and
+the paths of the key files, never key material. `aac init` writes them as
+its last step and writes them again on any later run. The layout decides the
+paths written into the sidecar configuration: `host` (the default) uses
+paths on this machine, for a sidecar that runs directly on it, and
+`container` uses the paths where the files are mounted inside the
+containers.
+
+`publisher.env` belongs to the tenant, and every agent of the tenant writes
+it. A write rewrites its paths and poll interval for this machine (hand
+edits to those are replaced), but refuses to change its tenant ID, trust
+domain or URLs, because that would repoint the publisher for every agent.
+The refusal names the values that differ. If the file is the stale one, for
+example after you deliberately moved the tenant to new endpoints and set up
+its agents again, move it aside (`mv publisher.env publisher.env.old` in the
+tenant directory) and run setup again from an agent with the intended
+endpoints. The admin key and the published public keys stay where they are.
+
+### How profiles, agents and tenant data fit together
 
 ```text
 profile (~/.aac/config) ── bound to ──> tenant
                                           ├── credentials:      ~/.aac/credentials/<tenant-id>
                                           ├── tenant directory: ~/.aac/tenants/<tenant-id>/
-                                          └── workspaces:       ~/.aac/workspaces/<name>/, one per workload
+                                          └── agents:          ~/.aac/agents/<name>/, one per workload
 ```
 
 * A **profile**, in `~/.aac/config`, names the AAC admin and data-plane
   endpoints you use and, once registration or sign-in has bound it, the one
   tenant it acts for. The trust URL and the sign-in choice are recorded in
-  each workspace instead. "Profiles and configuration", further down,
+  each agent instead. "Profiles and configuration", further down,
   covers profiles in full.
-* The **tenant data** is shared by all of a tenant's workspaces on this
+* The **tenant data** is shared by all of a tenant's agents on this
   machine: the tenant API key and the tenant-admin session in
   `~/.aac/credentials/`, and the tenant directory
   `~/.aac/tenants/<tenant-id>/` with the tenant-admin signing key, the public
   keys and certificates the publisher uploads, and `publisher.env`.
-* A **workspace**, in `~/.aac/workspaces/<name>/`, holds one workload's
+* An **agent folder**, in `~/.aac/agents/<name>/`, holds one workload's
   material. It records the profile and the tenant it was created for and
-  keeps them: one tenant can have many workspaces, and a workspace never
+  keeps them: one tenant can have many agents, and an agent never
   moves to another 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. `<workspace>` is the workspace name
+lives and whether to back it up. `<agent>` is the agent name
 (default `starter`) and `<tenant-id>` the tenant id AAC allocated.
 
 <!-- inventory-table:start -->
@@ -247,44 +297,48 @@ lives and whether to back it up. `<workspace>` is the workspace name
 | 1 | tenant_api_key | `~/.aac/credentials/<tenant-id>` | CLI data-plane calls; the sidecar's workload projection | until retired or rotated; `aac tenant reissue-api-key` | **Yes.** save a protected copy in your secret manager; loss needs `aac tenant reissue-api-key` |
 | 2 | tenant_admin_session | `~/.aac/credentials/<tenant-id>.session` | CLI admin calls | hours; `aac sso login` | No. sign in again |
 | 3 | tenant_admin_signing_key | `~/.aac/tenants/<tenant-id>/tenant-admin.pem`, `~/.aac/tenants/<tenant-id>/tenant-admin.pub.pem` | the publisher signs trust-material uploads; the public half is registered with AAC | until rotated; `aac tenant rotate-admin-key` | **Recommended.** recommended for developer tenants (loss needs `aac tenant rotate-admin-key`; a lost public half is derived from the private key); production custody belongs in an HSM/KMS, not a password manager |
-| 4 | root_signing_key | `~/.aac/workspaces/<workspace>/pki/root.pem`, `~/.aac/workspaces/<workspace>/pki/root.pub.pem`, `~/.aac/tenants/<tenant-id>/root-keys/<workspace>-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 workspace name) | No. never restore the private key: a replacement workspace 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/workspaces/<workspace>/ca/dev-ca.key`, `~/.aac/workspaces/<workspace>/pki/dev-ca.crt`, `~/.aac/workspaces/<workspace>/pair/dev-ca.crt`, `~/.aac/tenants/<tenant-id>/spiffe-bundle/<workspace>-dev-ca.ca.pem` | signs the workload, terminal and TLS certificates; peers trust it via the published bundle | 7 days; `aac workspace renew --ca` | No. development only; reissue; a lost copy of the certificate is copied back from `pki/dev-ca.crt` |
-| 6 | workload_svid | `~/.aac/workspaces/<workspace>/pki/workload.key`, `~/.aac/workspaces/<workspace>/pki/workload.crt` | the sidecar's SPIFFE identity: proves on every live request that this workload holds the key behind its certificate | 1 day; `aac workspace renew` | No. development only; reissue |
-| 7 | terminal_attestation | `~/.aac/workspaces/<workspace>/pki/terminal.key`, `~/.aac/workspaces/<workspace>/pki/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 workspace renew` | No. development only; reissue |
-| 8 | localhost_tls | `~/.aac/workspaces/<workspace>/pki/server.key`, `~/.aac/workspaces/<workspace>/pki/server.crt` | the sidecar's HTTPS listener | 1 day; `aac workspace renew` | No. development only; reissue |
-| 9 | outbound_ca_bundle | `~/.aac/workspaces/<workspace>/pki/outbound-ca.pem` | the sidecar verifies TLS to AAC and to itself | rebuilt by renew; `aac workspace renew` | No. derived |
-| 10 | pairing_secret | `~/.aac/workspaces/<workspace>/pair/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 | workspace_manifest | `~/.aac/workspaces/<workspace>/manifest.json` | the workspace's identities and progress; every `workspace` verb reads it first | for the life of the workspace | **Recommended.** cannot be recreated by any command; without it start a new workspace 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 workspaces | for the life of the tenant | **Recommended.** back up with the tenant directory: a replacement workspace 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) |
-| 13 | rendered_files | `~/.aac/workspaces/<workspace>/sidecar-config.yaml`, `~/.aac/workspaces/<workspace>/compose.env`, `~/.aac/tenants/<tenant-id>/publisher.env` | non-secret configuration derived from the manifest | re-rendered on demand; `aac workspace render --force` | No. derived; `aac workspace render --force` recreates them |
+| 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 |
+| 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) |
+| 13 | settings_files | `~/.aac/agents/<agent>/sidecar-config.yaml`, `~/.aac/agents/<agent>/compose.env`, `~/.aac/tenants/<tenant-id>/publisher.env` | non-secret settings derived from the agent's record | written again on demand; `aac init --profile <profile> --agent <agent>` | No. derived; `aac init --profile <profile> --agent <agent>` writes them again |
 <!-- inventory-table:end -->
 
 In short: back up the tenant API key and the whole tenant directory while
 the machine is healthy. Everything else is regenerated.
 
-### Inspect and maintain a workspace
+### Inspect and maintain an agent
 
 ```bash
-aac workspace status --workspace starter --output table   # what exists, expiry, permissions, next command
-aac workspace status --workspace starter --remote         # also: is the public trust material visible?
-aac workspace renew --workspace starter                   # fresh leaf keys and certificates; old ones archived
-aac workspace render --workspace starter --layout container --force   # container path layout
+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 list                                    # every agent on this machine, with its case
+aac init --profile stage --agent starter --layout container   # write the settings again, container paths
 ```
 
 `status` works offline by default and exits with code 3 when material is
 missing, expired or unsafely permissioned. `renew` reissues the one-day
 certificates with fresh keys, and reissues the development CA only when it
 is expired or within a day of expiry (or when `--ca` is given); a new CA is
-published under the next anchor id and needs the publisher restarted.
-`render` never touches keys and refuses to overwrite rendered files unless
-`--force` is given.
+published under the next anchor id and needs the publisher restarted. For an
+agent whose own issuer signed its certificates, `renew` cannot reissue
+anything: it takes the replacements your issuer produced, through the same
+flags `aac init` accepts.
+Re-running `aac init` writes the settings files again and never touches a
+key.
 
 `status` also names one next step, `next_command`. When material is
 missing, it is the fix for the first missing item: restore it from your
-backup, recreate a lost public copy from the file it copies, renew, or
-render. Otherwise it is renewal when a certificate is due. After the step,
+backup, recreate a lost public copy from the file it copies, renew, or run
+setup again. Otherwise it is renewal when a certificate is due. After the step,
 run `status` again. Commands it names that change your tenant carry the
-workspace's own `--tenant-id` and `--admin-url`, so a value left in
+agent's own `--tenant-id` and `--admin-url`, so a value left in
 `AAC_TENANT_ID` or `AAC_ADMIN_URL` cannot aim them at another tenant. The
 file recipes use `openssl`, which must be OpenSSL 1.1.1 or newer: the
 `openssl` that ships with macOS cannot read Ed25519 keys, so install a
@@ -296,32 +350,32 @@ and refuses with the full list if one already exists. `aac init` never
 installs or replaces a tenant-admin key for an existing tenant: the key on
 this machine must already be the tenant's active admin key, and replacing
 it is always the deliberate `aac tenant rotate-admin-key` command, never a
-side effect of setup. A second workspace for the same tenant
-(`--workspace other`) reuses the tenant-admin key and gets its own root key
+side effect of setup. A second agent for the same tenant
+(`--agent other`) reuses the tenant-admin key and gets its own root key
 id.
 
 ### What to do when keys and certificates expire
 
 It is the certificates that expire, and renewing replaces their keys with
-them. `aac workspace status` shows when each certificate runs out and flags
+them. `aac agent status` shows when each certificate runs out and flags
 it before it does: six hours ahead for the one-day certificates, a day
 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 workspace renew --workspace <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 workspace status --workspace <name> --remote` |
+| 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 |
+| 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" |
 
 A simple routine: when you start work, run
-`aac workspace status --workspace <name>`, and when it names renewal, run
-`aac workspace renew --workspace <name>` and restart the sidecar. About once
+`aac agent status --agent <name>`, and when it names renewal, run
+`aac agent renew --agent <name>` and restart the sidecar. About once
 a week that renewal also replaces the development CA (`renew` then reports
 `republication_required: true`): restart the publisher, the sidecar and the
 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 workspace's `archive/` directory, so whatever reads them must
+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
@@ -400,12 +454,12 @@ 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 workspace name**. A developer tenant
+3. Run the guided setup with a **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 --workspace laptop-2 --idp github \
+   aac init --profile stage --agent laptop-2 --idp github \
      --trust-url https://trust.stage.cascadeauth.dev
    ```
 
@@ -415,7 +469,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 --workspace laptop-2 \
+   aac init --profile stage --agent laptop-2 \
      --trust-url https://trust.stage.cascadeauth.dev
    ```
 
@@ -427,18 +481,19 @@ profile; `aac profile show` prints it, and the example below uses
    fresh after the revocations in step 2 holds only the new key, which is
    accepted because no other key is active any more.
 
-### Why the replacement workspace needs a new name
+### Why the replacement agent needs a new name
 
-The workspace name is baked into two identifiers that are published for
-the whole tenant: the root key id `<workspace>-root-v1` and the development
-CA anchor id `<workspace>-dev-ca`. Other parties look up your keys and
+The agent name is baked into two identifiers that are published for
+the whole tenant: the root key id `<agent>-root-v1` and the CA
+anchor id (`<agent>-dev-ca` for a development CA the CLI created,
+`<agent>-ca` for your own issuer's). Other parties look up your keys and
 certificates by those ids. AAC therefore never accepts new key material
 under an id that has already been published: a key id names one key, for
 good. A new machine has to generate new keys, so it has to publish them
-under new ids, which means a new workspace name. The new ids are published
+under new ids, which means a new agent name. The new ids are published
 alongside the old ones until the old ones are retired.
 
-Reusing the old workspace name on the new machine is refused on purpose:
+Reusing the old agent name on the new machine is refused on purpose:
 the restored tenant directory still holds that name's published root key,
 and `init` never generates different key material under an existing key
 id. The development certificates and the pairing secret are regenerated by
@@ -544,7 +599,7 @@ output empty and take no `--output`.
 | `0` | Success. |
 | `1` | AAC or the identity provider rejected the request. |
 | `2` | Usage error: an invalid flag, value or flag combination. |
-| `3` | A local configuration or state problem: profile, credential file, cached session or workspace. |
+| `3` | A local configuration or state problem: profile, credential file, cached session or agent. |
 | `4` | Transport failure: an endpoint could not be reached. |
 
 If AAC asks you to slow down, the command shows the interval to wait. The
@@ -640,7 +695,7 @@ A developer tenant set up with `aac init` keeps its tenant-admin key in its
 tenant directory, where the publisher's configuration points. To replace a
 lost key there, write the new pair in place, readable only by you, sign in,
 register the new public half, and then recreate every publisher container.
-Pass the tenant id and admin URL explicitly, as `aac workspace status`
+Pass the tenant id and admin URL explicitly, as `aac agent status`
 does, so the change cannot land on another tenant. The `openssl` commands
 need OpenSSL 1.1.1 or newer, which macOS does not ship: