docs consolidation

docs/modules/cli/guides/commands/auth.md

@@ -1,19 +1,85 @@
-# stella auth — Command Guide
+# stella auth - Command Guide
+
+The `stella auth` command group manages Authority-backed authentication and token operations used by other CLI commands.
 
 ## Commands
-- `stella auth login --token <token> [--url <baseUrl>]`
-- `stella auth status`
-- `stella auth logout`
 
-## Flags
-- `--url`: API base URL; defaults to config/env.
-- `--token`: bearer token or OIDC device code (future); stored in config if allowed.
+### auth login
 
-## Behaviour
-- Login writes token to config file or keyring (where supported) with deterministic permissions; never echoes secrets.
-- Status prints current user/tenant scopes if available; uses exit code 3 when unauthenticated.
-- Logout removes stored token and cached session data.
+Acquire and cache an access token using the configured Authority credentials.
+
+```bash
+stella auth login
+stella auth login --force
+```
+
+Notes:
+- `--force` ignores cached tokens and forces re-authentication.
+- Credential sources are configuration-driven (profile/env). This command does not accept raw tokens on the command line.
+
+### auth status / whoami / logout
+
+```bash
+stella auth status
+stella auth whoami
+stella auth logout
+```
+
+Behavior:
+- `status` reports whether a cached token exists and whether it is still valid.
+- `whoami` prints cached token claims (subject, scopes, expiry) for diagnostics.
+- `logout` removes cached tokens for the active credentials.
+
+### auth revoke export / verify
+
+Export or verify Authority revocation bundles.
+
+```bash
+stella auth revoke export --output ./revocation-export
+stella auth revoke verify --bundle ./revocation-bundle.json --signature ./revocation-bundle.json.jws --key ./authority.pub.pem
+```
+
+### auth token mint
+
+Mint a service account token (requires appropriate Authority permissions).
+
+```bash
+stella auth token mint --service-account concelier-jobs \
+  --scope concelier.jobs.trigger --scope advisory:ingest --scope advisory:read \
+  --tenant tenant-default \
+  --reason "scheduled ingestion" \
+  --raw
+```
+
+Flags:
+- `--service-account` / `-s` (required): service account identifier.
+- `--scope` (repeatable): scopes to include in the minted token.
+- `--expires-in` (optional): expiry in seconds.
+- `--tenant` (optional): tenant context.
+- `--reason` (optional): audit reason.
+- `--raw`: output only the token value (automation-friendly).
+
+### auth token delegate
+
+Delegate your current token to another principal.
+
+```bash
+stella auth token delegate --to user@example.org \
+  --scope advisory:read \
+  --tenant tenant-default \
+  --reason "support session" \
+  --raw
+```
+
+Flags:
+- `--to` (required): principal identifier to delegate to.
+- `--scope` (repeatable): delegated scopes (must be a subset of the current token).
+- `--expires-in` (optional): expiry in seconds (defaults to remaining token lifetime).
+- `--tenant` (optional): tenant context.
+- `--reason` (required): audit reason.
+- `--raw`: output only the token value (automation-friendly).
+
+## Offline notes
+- `auth login` and token mint/delegate require connectivity to Authority.
+- `auth revoke verify`, `status`, `whoami`, and `logout` can operate using local cached state.
 
-## Offline/air-gap notes
-- Login requires network; if `--offline` is set, command must fail with exit code 5.
-- Status/logout work offline using cached credentials only.