healthcloud-cli 3.3.0__tar.gz → 3.5.0__tar.gz

{healthcloud_cli-3.3.0 → healthcloud_cli-3.5.0}/.gitignore

@@ -255,3 +255,8 @@ packages/pip-tenantadmin/README.md
 
 # Live SDK test assets stay in the archived SDK history, outside this source import.
 integration-tests/shared/test-assets/
+
+# Ralph loop runtime state
+.ralph/
+/PROMPT.md
+.blind-peer-review/

{healthcloud_cli-3.3.0 → healthcloud_cli-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: healthcloud-cli
-Version: 3.3.0
+Version: 3.5.0
 Summary: Command-line interface for the HealthCloud MCP gateway, generated from the shared MCP tool manifest.
 Project-URL: Issues, https://github.com/healthcloudservices/healthcloud-services/issues
 Project-URL: Repository, https://github.com/healthcloudservices/healthcloud-services
@@ -69,10 +69,10 @@ _HC_COMPLETE=bash_complete COMP_WORDS="hc ams inspect --o" COMP_CWORD=3 uv run -
 ```
 
 Operational validation starts only when Click invokes an AMS leaf callback.
-`discover` then validates its explicit environment and tenant arguments; the
-other leaves require `--target-file` and apply the existing root, target, and
-authentication checks described below. Deferring preflight does not relax
-those safety requirements.
+`discover`, `agents`, `departments`, `teams`, `organization`, `skills`, and `policies` then
+validate their explicit environment and tenant arguments; the remaining leaves
+require `--target-file`. All apply the root, target, and authentication checks
+described below. Deferring preflight does not relax those safety requirements.
 
 The bundled tool manifest (`healthcloud_cli/contracts/mcp-tools.manifest.json`)
 is a copy of `packages/cli/contracts/mcp-tools.manifest.json`. Re-sync it
@@ -280,20 +280,87 @@ uv sync --frozen --extra dev
 uv run --frozen hc ams --help
 ```
 
-Bootstrap candidate IDs with the public SDK discovery endpoint. Both flags are
-required; no MCP defaults, admin login, or automatic candidate selection are used:
+Create one private tenant-admin session before interactive AMS work, inspect its
+non-secret binding, and remove it when finished:
+
+```bash
+uv run --frozen hc login --environment dev --tenant-id TENANT_ID
+uv run --frozen hc login --status
+uv run --frozen hc logout
+```
+
+`hc login` reads `HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD` when present,
+otherwise it prompts (with hidden password input). It stores only the email,
+tenant/environment binding, access/refresh tokens and expiry in the strict
+owner-only `~/.healthcloud/cli/ams-session.json`; it never stores the password.
+
+For CI and agents, log in non-interactively: pass `--email` and pipe the password
+to `--password-stdin` (read as exactly one stdin line, never echoed, never a
+flag value — there is no `--password` option):
+
+```bash
+printf '%s\n' "$HC_AMS_ADMIN_PASSWORD" | \
+  uv run --frozen hc login --environment dev --tenant-id TENANT_ID \
+  --email "$HC_AMS_ADMIN_EMAIL" --password-stdin
+```
+
+`--email` beats `HC_AMS_ADMIN_EMAIL` and `--password-stdin` beats
+`HC_AMS_ADMIN_PASSWORD`. With `--password-stdin`, the piped line is always the
+password: it is read before any prompt, so it can never be consumed as the
+email, and the email must come from `--email`, `HC_AMS_ADMIN_EMAIL` or (only on
+an interactive terminal) the email prompt. When stdin is not an interactive
+terminal and neither `--password-stdin` nor `HC_AMS_ADMIN_PASSWORD` supplies the
+password, `hc login` refuses with that guidance instead of attempting a hidden
+prompt (no `GetPassWarning`, no echoed password); a missing email on a
+non-interactive stdin (or a process with no stdin stream at all) is refused the
+same way, naming `--email`/`--password-stdin`; every refusal happens before any
+login request. `--status` cannot be combined with `--email` or `--password-stdin`.
+Even on an interactive terminal, `--password-stdin` suppresses terminal echo
+while the single line is read and restores it afterwards; a stdin stream that is
+closed or errors mid-read is refused cleanly (exit 2, never a traceback).
+AMS commands may omit both target flags while this session is present, except
+that a `prod` session still needs `--environment prod` on every command. Explicit
+flags and target files must match it exactly. A session within 60 seconds of
+expiry is refreshed once before the operation, under a lock so concurrent
+commands never spend the same refresh token (a second command waits up to 30 seconds, then stops), and
+atomically replaced. Refresh
+failure stops without an AMS call or password fallback and asks for a new login.
+If the refreshed session cannot be saved, the current command still finishes and
+prints a warning to run `hc login` again.
+
+`~/.healthcloud` and `~/.healthcloud/cli` must be directories you own with mode
+700; the CLI creates them that way, and refuses (naming the directory and the
+`chmod 700` fix) if an existing one is shared. `hc logout` deletes the local file
+only and reports `"server_session_revoked": false`: issued tokens stay valid
+until they expire.
+
+Bootstrap candidate IDs with the public SDK discovery endpoint. Without a saved
+session both flags are required; a saved session supplies both together. No MCP
+defaults, admin login, or automatic candidate selection are used:
 
 ```bash
 uv run --frozen hc ams discover --environment dev --tenant-id TENANT_ID
 ```
 
-Read-only agent listing, inspection and export also take explicit flags instead
-of a target file, and log in as tenant admin (`HC_AMS_ADMIN_EMAIL` /
-`HC_AMS_ADMIN_PASSWORD`). Stdout carries bounded metadata only; `adapter` shows
+Read-only agent listing, inspection and export take flags instead of a target
+file; both may be omitted together when a matching saved session exists. Without
+one, they log in as tenant admin using `HC_AMS_ADMIN_EMAIL` /
+`HC_AMS_ADMIN_PASSWORD`. They emit the same versioned result envelope as the
+other read domains (`operation`, `outcome`, `schema_version`, `target`, `data`;
+no `verification` block on reads); failures emit one categorized JSON error
+envelope on stderr with the same categories (not found, target mismatch,
+refusal, logged out), not the plain-text `Error: …` lines of earlier releases.
+`agents list` carries bounded projections under `data.agents` plus a `page`
+block; `agents get` carries the bounded projection under `data.agent`. The
+legacy top-level `{"agents": …, "environment": …, "tenant_id": …}` shape is
+intentionally replaced by this envelope — scripts must read the new shape.
+Stdout carries bounded metadata only; `adapter` shows
 whether an agent runs from the `file` or `db` config adapter (`unknown` when the
 server does not say). `export` first re-checks the agent/tenant identity, then
 saves the server's own JSON/YAML export byte-for-byte to a new owner-only `--out`
-file, refusing (and leaving no file) when the body is not valid UTF-8. `export`
+file (exact bytes preserved), refusing (and leaving no file) when the body is
+not valid UTF-8; its stdout reports the envelope with the file `path`, `format`
+and `sha256` under `data` and the `agent_id` in `target`. `export`
 needs an AMS build that serves `/agents/{agent_id}/configuration/export`; that
 route is not yet deployed to dev:
 
@@ -304,6 +371,23 @@ uv run --frozen hc ams agents export --environment dev --tenant-id TENANT_ID --a
   --format yaml --out agent.yaml
 ```
 
+For example, `hc ams agents list` succeeds with (formatted for readability):
+
+```json
+{"schema_version": 1, "operation": "agents.list", "outcome": "succeeded",
+ "target": {"environment": "dev", "tenant_id": "TENANT_ID"},
+ "data": {"agents": [{"id": "AGENT_ID", "name": "…", "adapter": "file", "…": "…"}],
+          "page": {"kind": "unpaged", "returned_count": 1, "continuation": null}}}
+```
+
+and a missing `--agent-id` fails with one envelope on stderr and exit 1:
+
+```json
+{"schema_version": 1, "operation": "agents.get", "outcome": "failed",
+ "target": {"environment": "dev", "tenant_id": "TENANT_ID", "agent_id": "AGENT_ID"},
+ "error": {"category": "not_found", "message": "Agent 'AGENT_ID' was not found."}}
+```
+
 Read-only department listing and inspection use the same explicit tenant-admin
 targeting. They emit one versioned JSON result on stdout; failures emit one
 categorized JSON result on stderr. Department descriptions, creator identities,
@@ -335,6 +419,162 @@ or inferring missing relationships:
 uv run --frozen hc ams organization hierarchy --environment dev --tenant-id TENANT_ID
 ```
 
+Read-only skill catalog listing and inspection are complete and unpaged. The
+bounded projection includes only skill IDs, names, tool IDs, and audit timestamps;
+it omits descriptions, tenant identity, creator identity, arbitrary response
+fields, and tool details. Tool-ID order is preserved:
+
+```bash
+uv run --frozen hc ams skills list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams skills get --environment dev --tenant-id TENANT_ID --skill-id SKILL_ID
+```
+
+The CLI does not create, update, delete, or assign skills. Skill commands do not
+read guardrails. They make exactly one catalog GET after tenant-admin login
+and does not paginate, retry, cache, join, or infer additional catalog data.
+Skill reads refuse target files, root credentials or base URLs, raw output,
+blank or dot-segment skill IDs, and installed SDKs that do not provide both
+skill list and get methods. These local refusals happen before tenant-admin login
+or catalog reads.
+
+Read-only policy catalog listing and inspection are complete and unpaged. The
+bounded projection includes only policy IDs, names, department IDs, guardrail
+IDs, active status, and audit timestamps. It never emits protected policy
+content, descriptions, tenant or creator identity, arbitrary response fields,
+or joined department/guardrail details. Guardrail-ID order is preserved:
+
+```bash
+uv run --frozen hc ams policies list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams policies get --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
+```
+
+The CLI does not export protected policy content; create, update, delete, or
+assign policies; or join guardrail records. It makes exactly one catalog GET after
+tenant-admin login and does not paginate, retry, cache, join, or infer referenced
+resources. Policy reads refuse target files, root credentials or base URLs, raw
+output, blank or dot-segment policy IDs, and installed SDKs without both policy
+methods before tenant-admin login or catalog reads. Successful reads make no
+assignment, deployment, serving, enforcement, or effectiveness claim.
+
+Read-only guardrail catalog listing and inspection are complete and unpaged.
+The bounded projection includes only guardrail IDs, names, and audit timestamps.
+It never emits protected rules, descriptions, tenant or creator identity,
+arbitrary response fields, or joined policy/agent details:
+
+```bash
+uv run --frozen hc ams guardrails list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams guardrails get --environment dev --tenant-id TENANT_ID \
+  --guardrail-id GUARDRAIL_ID
+```
+
+The CLI does not export rules; create, update, delete, assign, deploy, or enforce
+guardrails; or claim they are active or effective. It makes exactly one catalog
+GET after tenant-admin login and does not paginate, retry, cache, join, or infer
+additional data. Guardrail reads refuse target files, root credentials or base
+URLs, raw output, blank or dot-segment guardrail IDs, and installed SDKs without
+both guardrail methods before tenant-admin login or catalog reads.
+
+Read-only tool catalog listing and inspection are complete and unpaged. The
+bounded projection includes only IDs, names, read-only and confirmation flags,
+agent types, required scopes, audit events, and activity labels:
+
+```bash
+uv run --frozen hc ams tools list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams tools get --environment dev --tenant-id TENANT_ID \
+  --tool-id TOOL_ID
+```
+
+When both target flags are omitted, these commands may use the matching saved
+tenant-admin session. Explicit flags must match that session. Tool output never
+includes descriptions, parameters, input schemas, PIP or connector routing, or
+arbitrary response fields. The CLI does not execute, assign, create, update, or
+delete tools; join agents or skills; or claim assignment, availability,
+authorization, deployment, serving, or runtime effectiveness. It makes exactly
+one catalog GET after tenant-admin login and does not paginate, retry, cache,
+join, or infer additional data. Tool reads refuse target files, root credentials
+or base URLs, raw output, blank or dot-segment IDs, and installed SDKs without
+both tool methods before tenant-admin login or catalog reads.
+
+Read-only data-source catalog listing and inspection are complete and unpaged.
+The bounded projection includes only stable IDs and names:
+
+```bash
+uv run --frozen hc ams data-sources list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams data-sources get --environment dev --tenant-id TENANT_ID \
+  --data-source-id DATA_SOURCE_ID
+```
+
+When both target flags are omitted, these commands may use the matching saved
+tenant-admin session. Explicit flags must match that session. Data-source output
+never includes descriptions or arbitrary response fields and does not imply
+access, patient consent, record availability, assignment, authorization, or
+runtime effectiveness. The CLI does not create, update, delete, assign, access
+records through, or execute data sources. It makes exactly one catalog GET after
+tenant-admin login and does not paginate, retry, cache, truncate, join, or infer
+additional data. Data-source reads refuse target files, root credentials or base
+URLs, raw output, blank or dot-segment IDs, and installed SDKs without both
+data-source methods before tenant-admin login or catalog reads.
+
+### AMS output modes
+
+The read commands (`hc ams skills|tools|policies|guardrails|data-sources|teams|departments list|get`
+and `hc ams organization hierarchy`) render in two modes (`--output` on the root
+`hc` command; `pretty` is the default):
+
+- **`pretty`** (default): a compact human view. Lists print an `ID`/`NAME`
+  table with an entry count; a single record prints `key: value` lines; the
+  organization hierarchy prints an indented tree. Each failed AMS command
+  prints one stderr line, `error: <message> (<category>)` (flag/argument
+  usage errors from Click print Click's standard usage message instead).
+- **`json`**: the stable result envelope (below) on stdout. When stdout is not
+  a terminal, the envelope is printed as one compact line; on a terminal it is
+  indented. Errors keep the structured JSON envelope on stderr.
+
+The JSON envelope carries `schema_version`, `operation`, `target`, `outcome`,
+and either `data` (succeeded) or `error: {category, message}` (failed). On
+read-only operations the envelope no longer includes the `verification` block:
+every field there is `not_applicable` on a read, so it was boilerplate. If a
+future mutating operation reintroduces it, `verification` reappears only with
+non-`not_applicable` content. Everything else about the envelope — field names,
+ordering semantics, categories — is unchanged and stays parseable.
+
+`--raw`/`--output raw` stays refused for AMS (`Raw output is refused for AMS.`),
+and refusals keep the JSON error envelope on stderr.
+
+```bash
+hc ams skills list --environment dev --tenant-id TENANT_ID                 # pretty table
+hc ams skills get --environment dev --tenant-id TENANT_ID --skill-id SKILL_ID  # key: value
+hc --output json ams skills list --environment dev --tenant-id TENANT_ID   # compact envelope
+hc --output json ams skills list --environment dev --tenant-id TENANT_ID | jq .data
+```
+
+### What `hc ams` errors report
+
+In `json` and `raw` modes each failed AMS command prints one JSON object on stderr with
+an `error.category` and a message naming the real cause; in `pretty` mode the
+same message is exactly one stderr line, `error: <message> (<category>)`:
+
+- Local refusals keep their specific message and exit `1` with category
+  `validation`: `Raw output is refused for AMS.`, `AMS target does not match the
+  saved session; stopped before authentication.`, identity mismatches
+  (`Skill/tenant identity mismatch; stopped.`), and dot-segment ID refusals.
+- No saved session and no target flags: category `authentication` with
+  `Not logged in; run \`hc login --environment <env> --tenant-id <tenant>\`.`
+- A `get` whose requested ID does not exist (HTTP 404): category `not_found`
+  naming the ID, e.g. `Skill 'nosuch' was not found.` (a 404 on `list` stays
+  `validation`; departments keeps its legacy contract for all read statuses).
+- HTTP 401/403 map to `authentication`/`authorization`; 409 to `conflict`;
+  network failures to `transport`; local output failures to `local_io`.
+- Any unexpected internal error is category `internal` with a generic message;
+  it is never labeled `validation` and never leaks exception details.
+
+```bash
+hc --raw ams skills list --environment dev --tenant-id TENANT_ID   # validation: raw refused
+hc ams skills list --tenant-id OTHER_TENANT                        # validation: target mismatch
+hc ams skills list                                                 # authentication: not logged in
+hc ams skills get --skill-id NOSUCH                                # not_found: names the ID
+```
+
 Every other command requires an explicit local, non-secret target JSON file.
 Only the canonical HTTPS AMS origin for that environment is accepted; custom
 origins require separately verified support. Target and nested qualification keys
@@ -403,11 +643,11 @@ configuration and recheck it before apply and selected-field restore. This is an
 operator prerequisite: the current CLI does not automatically attest deployment
 or all-writer coverage, and the record adds no server authorization boundary.
 
-Credentials enter only through `HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD`
-in the current process, intended for composition with the existing
-`onepassword-env` wrapper. Each invocation logs in through `HCTenantAdminSDK`;
-tokens remain private in memory. There is no token cache, fallback identity,
-secret argument, resolved env file, or browser credential bridge. Root MCP
+For CI and scripts with no saved session, credentials may still enter through
+`HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD` in the current process, intended
+for composition with the existing `onepassword-env` wrapper; that compatibility
+path logs in once per invocation. There is no fallback identity, secret argument,
+arbitrary token import, resolved env file, keychain, or browser credential bridge. Root MCP
 `--access-token`, `--base-url`, their environment equivalents, and token/base-URL
 profiles are refused for AMS. Root profile environment values do not select AMS.
 

{healthcloud_cli-3.3.0 → healthcloud_cli-3.5.0}/README.md

@@ -51,10 +51,10 @@ _HC_COMPLETE=bash_complete COMP_WORDS="hc ams inspect --o" COMP_CWORD=3 uv run -
 ```
 
 Operational validation starts only when Click invokes an AMS leaf callback.
-`discover` then validates its explicit environment and tenant arguments; the
-other leaves require `--target-file` and apply the existing root, target, and
-authentication checks described below. Deferring preflight does not relax
-those safety requirements.
+`discover`, `agents`, `departments`, `teams`, `organization`, `skills`, and `policies` then
+validate their explicit environment and tenant arguments; the remaining leaves
+require `--target-file`. All apply the root, target, and authentication checks
+described below. Deferring preflight does not relax those safety requirements.
 
 The bundled tool manifest (`healthcloud_cli/contracts/mcp-tools.manifest.json`)
 is a copy of `packages/cli/contracts/mcp-tools.manifest.json`. Re-sync it
@@ -262,20 +262,87 @@ uv sync --frozen --extra dev
 uv run --frozen hc ams --help
 ```
 
-Bootstrap candidate IDs with the public SDK discovery endpoint. Both flags are
-required; no MCP defaults, admin login, or automatic candidate selection are used:
+Create one private tenant-admin session before interactive AMS work, inspect its
+non-secret binding, and remove it when finished:
+
+```bash
+uv run --frozen hc login --environment dev --tenant-id TENANT_ID
+uv run --frozen hc login --status
+uv run --frozen hc logout
+```
+
+`hc login` reads `HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD` when present,
+otherwise it prompts (with hidden password input). It stores only the email,
+tenant/environment binding, access/refresh tokens and expiry in the strict
+owner-only `~/.healthcloud/cli/ams-session.json`; it never stores the password.
+
+For CI and agents, log in non-interactively: pass `--email` and pipe the password
+to `--password-stdin` (read as exactly one stdin line, never echoed, never a
+flag value — there is no `--password` option):
+
+```bash
+printf '%s\n' "$HC_AMS_ADMIN_PASSWORD" | \
+  uv run --frozen hc login --environment dev --tenant-id TENANT_ID \
+  --email "$HC_AMS_ADMIN_EMAIL" --password-stdin
+```
+
+`--email` beats `HC_AMS_ADMIN_EMAIL` and `--password-stdin` beats
+`HC_AMS_ADMIN_PASSWORD`. With `--password-stdin`, the piped line is always the
+password: it is read before any prompt, so it can never be consumed as the
+email, and the email must come from `--email`, `HC_AMS_ADMIN_EMAIL` or (only on
+an interactive terminal) the email prompt. When stdin is not an interactive
+terminal and neither `--password-stdin` nor `HC_AMS_ADMIN_PASSWORD` supplies the
+password, `hc login` refuses with that guidance instead of attempting a hidden
+prompt (no `GetPassWarning`, no echoed password); a missing email on a
+non-interactive stdin (or a process with no stdin stream at all) is refused the
+same way, naming `--email`/`--password-stdin`; every refusal happens before any
+login request. `--status` cannot be combined with `--email` or `--password-stdin`.
+Even on an interactive terminal, `--password-stdin` suppresses terminal echo
+while the single line is read and restores it afterwards; a stdin stream that is
+closed or errors mid-read is refused cleanly (exit 2, never a traceback).
+AMS commands may omit both target flags while this session is present, except
+that a `prod` session still needs `--environment prod` on every command. Explicit
+flags and target files must match it exactly. A session within 60 seconds of
+expiry is refreshed once before the operation, under a lock so concurrent
+commands never spend the same refresh token (a second command waits up to 30 seconds, then stops), and
+atomically replaced. Refresh
+failure stops without an AMS call or password fallback and asks for a new login.
+If the refreshed session cannot be saved, the current command still finishes and
+prints a warning to run `hc login` again.
+
+`~/.healthcloud` and `~/.healthcloud/cli` must be directories you own with mode
+700; the CLI creates them that way, and refuses (naming the directory and the
+`chmod 700` fix) if an existing one is shared. `hc logout` deletes the local file
+only and reports `"server_session_revoked": false`: issued tokens stay valid
+until they expire.
+
+Bootstrap candidate IDs with the public SDK discovery endpoint. Without a saved
+session both flags are required; a saved session supplies both together. No MCP
+defaults, admin login, or automatic candidate selection are used:
 
 ```bash
 uv run --frozen hc ams discover --environment dev --tenant-id TENANT_ID
 ```
 
-Read-only agent listing, inspection and export also take explicit flags instead
-of a target file, and log in as tenant admin (`HC_AMS_ADMIN_EMAIL` /
-`HC_AMS_ADMIN_PASSWORD`). Stdout carries bounded metadata only; `adapter` shows
+Read-only agent listing, inspection and export take flags instead of a target
+file; both may be omitted together when a matching saved session exists. Without
+one, they log in as tenant admin using `HC_AMS_ADMIN_EMAIL` /
+`HC_AMS_ADMIN_PASSWORD`. They emit the same versioned result envelope as the
+other read domains (`operation`, `outcome`, `schema_version`, `target`, `data`;
+no `verification` block on reads); failures emit one categorized JSON error
+envelope on stderr with the same categories (not found, target mismatch,
+refusal, logged out), not the plain-text `Error: …` lines of earlier releases.
+`agents list` carries bounded projections under `data.agents` plus a `page`
+block; `agents get` carries the bounded projection under `data.agent`. The
+legacy top-level `{"agents": …, "environment": …, "tenant_id": …}` shape is
+intentionally replaced by this envelope — scripts must read the new shape.
+Stdout carries bounded metadata only; `adapter` shows
 whether an agent runs from the `file` or `db` config adapter (`unknown` when the
 server does not say). `export` first re-checks the agent/tenant identity, then
 saves the server's own JSON/YAML export byte-for-byte to a new owner-only `--out`
-file, refusing (and leaving no file) when the body is not valid UTF-8. `export`
+file (exact bytes preserved), refusing (and leaving no file) when the body is
+not valid UTF-8; its stdout reports the envelope with the file `path`, `format`
+and `sha256` under `data` and the `agent_id` in `target`. `export`
 needs an AMS build that serves `/agents/{agent_id}/configuration/export`; that
 route is not yet deployed to dev:
 
@@ -286,6 +353,23 @@ uv run --frozen hc ams agents export --environment dev --tenant-id TENANT_ID --a
   --format yaml --out agent.yaml
 ```
 
+For example, `hc ams agents list` succeeds with (formatted for readability):
+
+```json
+{"schema_version": 1, "operation": "agents.list", "outcome": "succeeded",
+ "target": {"environment": "dev", "tenant_id": "TENANT_ID"},
+ "data": {"agents": [{"id": "AGENT_ID", "name": "…", "adapter": "file", "…": "…"}],
+          "page": {"kind": "unpaged", "returned_count": 1, "continuation": null}}}
+```
+
+and a missing `--agent-id` fails with one envelope on stderr and exit 1:
+
+```json
+{"schema_version": 1, "operation": "agents.get", "outcome": "failed",
+ "target": {"environment": "dev", "tenant_id": "TENANT_ID", "agent_id": "AGENT_ID"},
+ "error": {"category": "not_found", "message": "Agent 'AGENT_ID' was not found."}}
+```
+
 Read-only department listing and inspection use the same explicit tenant-admin
 targeting. They emit one versioned JSON result on stdout; failures emit one
 categorized JSON result on stderr. Department descriptions, creator identities,
@@ -317,6 +401,162 @@ or inferring missing relationships:
 uv run --frozen hc ams organization hierarchy --environment dev --tenant-id TENANT_ID
 ```
 
+Read-only skill catalog listing and inspection are complete and unpaged. The
+bounded projection includes only skill IDs, names, tool IDs, and audit timestamps;
+it omits descriptions, tenant identity, creator identity, arbitrary response
+fields, and tool details. Tool-ID order is preserved:
+
+```bash
+uv run --frozen hc ams skills list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams skills get --environment dev --tenant-id TENANT_ID --skill-id SKILL_ID
+```
+
+The CLI does not create, update, delete, or assign skills. Skill commands do not
+read guardrails. They make exactly one catalog GET after tenant-admin login
+and does not paginate, retry, cache, join, or infer additional catalog data.
+Skill reads refuse target files, root credentials or base URLs, raw output,
+blank or dot-segment skill IDs, and installed SDKs that do not provide both
+skill list and get methods. These local refusals happen before tenant-admin login
+or catalog reads.
+
+Read-only policy catalog listing and inspection are complete and unpaged. The
+bounded projection includes only policy IDs, names, department IDs, guardrail
+IDs, active status, and audit timestamps. It never emits protected policy
+content, descriptions, tenant or creator identity, arbitrary response fields,
+or joined department/guardrail details. Guardrail-ID order is preserved:
+
+```bash
+uv run --frozen hc ams policies list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams policies get --environment dev --tenant-id TENANT_ID --policy-id POLICY_ID
+```
+
+The CLI does not export protected policy content; create, update, delete, or
+assign policies; or join guardrail records. It makes exactly one catalog GET after
+tenant-admin login and does not paginate, retry, cache, join, or infer referenced
+resources. Policy reads refuse target files, root credentials or base URLs, raw
+output, blank or dot-segment policy IDs, and installed SDKs without both policy
+methods before tenant-admin login or catalog reads. Successful reads make no
+assignment, deployment, serving, enforcement, or effectiveness claim.
+
+Read-only guardrail catalog listing and inspection are complete and unpaged.
+The bounded projection includes only guardrail IDs, names, and audit timestamps.
+It never emits protected rules, descriptions, tenant or creator identity,
+arbitrary response fields, or joined policy/agent details:
+
+```bash
+uv run --frozen hc ams guardrails list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams guardrails get --environment dev --tenant-id TENANT_ID \
+  --guardrail-id GUARDRAIL_ID
+```
+
+The CLI does not export rules; create, update, delete, assign, deploy, or enforce
+guardrails; or claim they are active or effective. It makes exactly one catalog
+GET after tenant-admin login and does not paginate, retry, cache, join, or infer
+additional data. Guardrail reads refuse target files, root credentials or base
+URLs, raw output, blank or dot-segment guardrail IDs, and installed SDKs without
+both guardrail methods before tenant-admin login or catalog reads.
+
+Read-only tool catalog listing and inspection are complete and unpaged. The
+bounded projection includes only IDs, names, read-only and confirmation flags,
+agent types, required scopes, audit events, and activity labels:
+
+```bash
+uv run --frozen hc ams tools list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams tools get --environment dev --tenant-id TENANT_ID \
+  --tool-id TOOL_ID
+```
+
+When both target flags are omitted, these commands may use the matching saved
+tenant-admin session. Explicit flags must match that session. Tool output never
+includes descriptions, parameters, input schemas, PIP or connector routing, or
+arbitrary response fields. The CLI does not execute, assign, create, update, or
+delete tools; join agents or skills; or claim assignment, availability,
+authorization, deployment, serving, or runtime effectiveness. It makes exactly
+one catalog GET after tenant-admin login and does not paginate, retry, cache,
+join, or infer additional data. Tool reads refuse target files, root credentials
+or base URLs, raw output, blank or dot-segment IDs, and installed SDKs without
+both tool methods before tenant-admin login or catalog reads.
+
+Read-only data-source catalog listing and inspection are complete and unpaged.
+The bounded projection includes only stable IDs and names:
+
+```bash
+uv run --frozen hc ams data-sources list --environment dev --tenant-id TENANT_ID
+uv run --frozen hc ams data-sources get --environment dev --tenant-id TENANT_ID \
+  --data-source-id DATA_SOURCE_ID
+```
+
+When both target flags are omitted, these commands may use the matching saved
+tenant-admin session. Explicit flags must match that session. Data-source output
+never includes descriptions or arbitrary response fields and does not imply
+access, patient consent, record availability, assignment, authorization, or
+runtime effectiveness. The CLI does not create, update, delete, assign, access
+records through, or execute data sources. It makes exactly one catalog GET after
+tenant-admin login and does not paginate, retry, cache, truncate, join, or infer
+additional data. Data-source reads refuse target files, root credentials or base
+URLs, raw output, blank or dot-segment IDs, and installed SDKs without both
+data-source methods before tenant-admin login or catalog reads.
+
+### AMS output modes
+
+The read commands (`hc ams skills|tools|policies|guardrails|data-sources|teams|departments list|get`
+and `hc ams organization hierarchy`) render in two modes (`--output` on the root
+`hc` command; `pretty` is the default):
+
+- **`pretty`** (default): a compact human view. Lists print an `ID`/`NAME`
+  table with an entry count; a single record prints `key: value` lines; the
+  organization hierarchy prints an indented tree. Each failed AMS command
+  prints one stderr line, `error: <message> (<category>)` (flag/argument
+  usage errors from Click print Click's standard usage message instead).
+- **`json`**: the stable result envelope (below) on stdout. When stdout is not
+  a terminal, the envelope is printed as one compact line; on a terminal it is
+  indented. Errors keep the structured JSON envelope on stderr.
+
+The JSON envelope carries `schema_version`, `operation`, `target`, `outcome`,
+and either `data` (succeeded) or `error: {category, message}` (failed). On
+read-only operations the envelope no longer includes the `verification` block:
+every field there is `not_applicable` on a read, so it was boilerplate. If a
+future mutating operation reintroduces it, `verification` reappears only with
+non-`not_applicable` content. Everything else about the envelope — field names,
+ordering semantics, categories — is unchanged and stays parseable.
+
+`--raw`/`--output raw` stays refused for AMS (`Raw output is refused for AMS.`),
+and refusals keep the JSON error envelope on stderr.
+
+```bash
+hc ams skills list --environment dev --tenant-id TENANT_ID                 # pretty table
+hc ams skills get --environment dev --tenant-id TENANT_ID --skill-id SKILL_ID  # key: value
+hc --output json ams skills list --environment dev --tenant-id TENANT_ID   # compact envelope
+hc --output json ams skills list --environment dev --tenant-id TENANT_ID | jq .data
+```
+
+### What `hc ams` errors report
+
+In `json` and `raw` modes each failed AMS command prints one JSON object on stderr with
+an `error.category` and a message naming the real cause; in `pretty` mode the
+same message is exactly one stderr line, `error: <message> (<category>)`:
+
+- Local refusals keep their specific message and exit `1` with category
+  `validation`: `Raw output is refused for AMS.`, `AMS target does not match the
+  saved session; stopped before authentication.`, identity mismatches
+  (`Skill/tenant identity mismatch; stopped.`), and dot-segment ID refusals.
+- No saved session and no target flags: category `authentication` with
+  `Not logged in; run \`hc login --environment <env> --tenant-id <tenant>\`.`
+- A `get` whose requested ID does not exist (HTTP 404): category `not_found`
+  naming the ID, e.g. `Skill 'nosuch' was not found.` (a 404 on `list` stays
+  `validation`; departments keeps its legacy contract for all read statuses).
+- HTTP 401/403 map to `authentication`/`authorization`; 409 to `conflict`;
+  network failures to `transport`; local output failures to `local_io`.
+- Any unexpected internal error is category `internal` with a generic message;
+  it is never labeled `validation` and never leaks exception details.
+
+```bash
+hc --raw ams skills list --environment dev --tenant-id TENANT_ID   # validation: raw refused
+hc ams skills list --tenant-id OTHER_TENANT                        # validation: target mismatch
+hc ams skills list                                                 # authentication: not logged in
+hc ams skills get --skill-id NOSUCH                                # not_found: names the ID
+```
+
 Every other command requires an explicit local, non-secret target JSON file.
 Only the canonical HTTPS AMS origin for that environment is accepted; custom
 origins require separately verified support. Target and nested qualification keys
@@ -385,11 +625,11 @@ configuration and recheck it before apply and selected-field restore. This is an
 operator prerequisite: the current CLI does not automatically attest deployment
 or all-writer coverage, and the record adds no server authorization boundary.
 
-Credentials enter only through `HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD`
-in the current process, intended for composition with the existing
-`onepassword-env` wrapper. Each invocation logs in through `HCTenantAdminSDK`;
-tokens remain private in memory. There is no token cache, fallback identity,
-secret argument, resolved env file, or browser credential bridge. Root MCP
+For CI and scripts with no saved session, credentials may still enter through
+`HC_AMS_ADMIN_EMAIL` and `HC_AMS_ADMIN_PASSWORD` in the current process, intended
+for composition with the existing `onepassword-env` wrapper; that compatibility
+path logs in once per invocation. There is no fallback identity, secret argument,
+arbitrary token import, resolved env file, keychain, or browser credential bridge. Root MCP
 `--access-token`, `--base-url`, their environment equivalents, and token/base-URL
 profiles are refused for AMS. Root profile environment values do not select AMS.