Story: Add tenant discovery to shell and compass

1. Goal
2. Status
3. Acceptance
4. Tasks
5. Notes

This page documents a story in the product backlog. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

1. Goal

After compass db provision (or any provisioning flow), developers need to identify the tenant they want to target and export its UUID as ORES_TENANT. Today there is no command to do this — the UUID must be obtained by running raw SQL or by inspecting provisioning output.

ores.cli was retired on 2026-09-23, so discovery re-points at ores.shell. The shell already carries a tenants resource whose verbs live in doc/recipes/shell/tenants/ (see tenant.org):

Shell: tenants list — reads the collection of active tenants from the IAM domain over NATS. Its shape is tenants list [--offset <n>] [--limit <n>] [--order <field>] [--desc], addressed at iam.v1.tenants.list.
Compass: compass db tenants — wraps tenants list (driving ./ores.shell) and formats the output with a copy-pasteable export ORES_TENANT=<uuid> hint per row.

Once in place, the standard post-provision developer workflow becomes:

compass db recreate
compass db provision
compass db tenants          # → see codes + UUIDs
export ORES_TENANT=<uuid>   # copy from output

2. Status

Field	Value
State	BACKLOG
Parent sprint	None (product backlog)
Now	Nothing.
Waiting on	Nothing.
Next	Pick up shell task first; compass task depends on it.
Last touched	2026-09-23

3. Acceptance

tenants list (in ores.shell, per doc/recipes/shell/tenants/) lists all active tenants (code, name, tenant_id) from the IAM domain.
compass db tenants drives the shell's tenants list and prints a table of code / name / tenant_id with an export ORES_TENANT=<uuid> hint alongside each row.
A recipe is added: How do I list tenants? (shell and compass variants), or the existing doc/recipes/shell/tenants/ recipes are cross-linked from the story.

4. Tasks

Task	State	Start	End	Description
Add shell tenants list command	BACKLOG			Confirm the shell's tenants list verb (doc/recipes/shell/tenants/) lists active tenants (code, name, tenant_id) for discovery.
Add compass db tenants command	BACKLOG			Wrap the shell's tenants list in a compass db tenants subcommand that drives ./ores.shell and shows code, name, tenant_id with a copy-pasteable export ORES_TENANT=<uuid> hint. Blocked on shell task.

5. Notes

Surfaced during the Commission: country story (sprint 21) while verifying country CLI commands. The --tenant flag requires a UUID; there was no way to discover that UUID without running raw SQL. The Barclays tenant UUID (36d4c3c9-195c-46b5-a4d8-b36cb48c8f46) was discovered via:

SELECT code, name, tenant_id FROM ores_iam_tenants_tbl
WHERE valid_to = ores_utility_infinity_timestamp_fn()
ORDER BY code;

ORES_TENANT is not written to .env by provisioning — it is tenant-specific by design (a developer chooses which tenant to target). The compass command makes this self-service without requiring knowledge of the schema or raw SQL access.

ores.cli was retired on 2026-09-23 (story Decommission ores.cli). This story is re-pointed at ores.shell, whose tenants resource already carries the discovery verbs under doc/recipes/shell/tenants/. The remaining work is the compass db tenants wrapper.