@tinkerlandai/indiana-cli 0.0.0-stage → 0.3.11

package/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+## 0.3.11 — 2026-10-23
+
+- Preserve the full capability catalog during npm release verification, with an explicit failure when command output exceeds its bound.
+- Finish configuration writes successfully when a competing process recovers the released empty lock directory, preserving any new owner's lock.
+
+## 0.3.10 — 2026-10-23
+
+- Publish stable npm releases through the package-specific GitHub Actions trusted publisher.
+
+## 0.3.9 — 2026-10-23
+
+- Distribute the CLI as `@tinkerlandai/indiana-cli` on npm, with independent `cli-vX.Y.Z` release tags.
+- npm installations check and install updates from the canonical npm package, verify SHA-512 integrity and preserve the global installation prefix. Existing website-managed installations retain their own update channel.
+
+## 0.3.8 — 2026-10-23
+
+- Connect `growth experiments bandit-history list`, `growth metrics event-suggestions list` and `snapshots dimensions` through the management catalog. They and `growth experiments time-series` request `platform.read` plus `analytics.read` in the same environment. Requires the matching Admin deployment.
+- Report Screen preview shares and the App Manifest preview as `BROWSER_ONLY`; they stay in the browser. App Manifest and consent operations remain unavailable until delegated access is connected.
+
+## 0.3.7 — 2026-10-22
+
+- Expose Customer Invoice listing as `customers invoices list <id>` while preserving `customers invoices get <id> <invoiceId>` for details. Request exact `billing.read` and `customers.read` grants; Invoice commands retain their original financial authorization dependencies.
+- Native Invoice list and read-only SDK configuration proposal support require the matching native SQL repair. Configuration proposals require an exact `platform.read` grant and current Owner/Admin membership; publication retains its separate write authorization and exact-content approval.
+
+## 0.3.6 — 2026-10-22
+
+- Follow same-origin Better Auth discovery and Code + PKCE on the native Cloud SQL Admin; reject credentials from a different issuer or environment. Requires the matching native Admin deployment.
+
+- Confirm the exact CLI grant and its current native Auth session on logout. Terminate only that session with local scope, retain credentials on incomplete cleanup, and allow same-session termination retry after grant revocation without restoring business access. Requires matching server support.
+
+- Recover configuration and credential locks after a confirmed local owner-process exit. Preserve live, foreign-host and unverifiable legacy locks; provide explicit recovery guidance for old empty lock files. Recovery never relies on lock age or deletes saved credentials.
+
+- Distinguish network timeouts, DNS, refused/interrupted/unreachable connections, TLS and proxy authentication from real HTTP service failures. Include safe host/stage/deadline diagnostics and relevant troubleshooting hints in doctor, management calls and OAuth exchanges; show HTTP status and request IDs in terminal errors.
+- Preserve sanitized diagnostics through OAuth wrappers and bound token response reading by the request deadline. Keep saved credentials on refresh transport failures and require original-operation/session recovery before retrying uncertain writes or token exchanges; no automatic retries or shell configuration changes.
+
+## 0.3.5 — 2026-10-18
+
+- Add dedicated code-reference scanning and saved-report upload, with scoped Keys, static coverage, bounded atomic reports and recovery. Requires the matching server migration and API. Existing versioned downloads remain immutable.
+
+## 0.3.4 — 2026-10-16
+
+- Rebuild the website distribution against the accepted Funnel Action contract. Preserve immutable 0.3.3 archives.
+
+## 0.3.3 — 2026-10-16
+
+- Add `indiana update --check` and `indiana update` with public version metadata, verified downloads, installation-directory preservation and installed-version checks for curl/global npm installations.
+- Check for new versions at most daily after successful interactive commands. Keep JSON/CI/non-interactive runs silent; tolerate offline failures and support `INDIANA_NO_UPDATE_CHECK=1`. Existing 0.3.2 installations bootstrap with curl or npm once.
+
+## 0.3.2 — 2026-10-16
+
+- Use `indiana snapshots list|get|status|run|cancel` as one concise Snapshot command group. `status <id>` and `cancel <id>` accept the Snapshot UUID directly. Remove the old `growth snapshots` command path while preserving existing HTTP operations, payloads and scope checks.
+
+- Add website-hosted macOS/Linux archives with dependencies and a SHA-256-verifying curl installer that never invokes npm. Node.js 22+ remains required. Keep the previously published 0.3.1 npm tarball unchanged.
+
+## 0.3.1 — 2026-10-16
+
+- Distribute the CLI publicly through versioned Indiana website downloads, with release metadata and SHA-256/SHA-512 integrity. Install directly by HTTPS URL without repository access or an npm account.
+- Keep registry publication disabled; website distribution does not change server authorization or the deployment status of individual operations.
+- Separate `growth snapshots status` progress polling from Snapshot `list/get` readers, fixing duplicate command registration that prevented CLI startup.
+
+- Preserve registered management error codes, diagnostic request IDs, safe business reasons, recovery actions and Retry-After timing in JSON output without printing remote response text. Unknown results require original-operation recovery; malformed-response fallback and automatic mutation retries stay conservative.
+
+- Add 28 finite GrowthBook configuration/result readers with paginated list/get commands and exact App/environment authorization.
+- Add Invoice details, refund history, credit statements, Entity/seat reads, Overview and global event queries using the existing user-bound readers.
+- Derive family coverage from connected operations and expose reader-specific effective permission requirements; correct stale production setup guidance.
+
+- Name the tool Indiana CLI and rename the executable and repository script to `indiana`.
+- Rename project configuration to `indiana.config.json`. Rename existing project files explicitly; the JSON format and user credential directory are unchanged.
+
+## 0.3.0 — 2026-10-16
+
+Private business-management candidate; no npm publication or production deployment.
+
+- Add finite `operations list/describe`, registered `call` and resource commands using the existing Console controllers.
+- Connect Customer, Feature/Product and Offering/Paywall/Funnel operations with explicit native resource grants and exact App/environment SQL checks.
+- Extend existing delegation constraints/functions/RLS on Indiana-test without adding tables, columns or token infrastructure.
+- Preserve original user JWTs, five roles, App allowlists, revision/request identities and signed catalog execution.
+- Recheck delegation before existing privileged payment gateway requests; fail closed for pending operation families.
+- Add bounded file/query/envelope input, private non-overwriting output and conflict handling without mutation retries.
+- Add rollback SQL/RLS and real Supabase OAuth-to-CLI-to-business acceptance.
+
+## 0.2.0 — 2026-10-16
+
+Private workspace candidate; no npm publication or production deployment.
+
+- Reuse Supabase Auth token issuance/refresh; add no authentication database, table, field, RPC or migration.
+- Add verified `whoami`; make credential-free logout idempotent and retain credentials if revocation names another grant.
+- Reject empty/oversized device labels before OAuth and ambiguous authorization callbacks before token exchange.
+- Complete Web authorization progress/error/focus/expiry states, permission visibility, revoke confirmation and immediate device-state updates.
+
+- Add local Offering validate/diff using the canonical hierarchy and publication rules.
+- Use the editable Funnel publication validator; stop requiring delivery-snapshot metadata for local drafts.
+- Report retired subscription-discount routes as unavailable and fail before credential/file/network access.
+- Enforce request deadlines through response-body reading; bound and cancel malformed/oversized streams.
+- Preserve HTTP authentication/conflict/rate-limit errors without requiring a JSON error body; mark transient failures retryable without automatically replaying writes.
+- Bind OAuth approval/refresh to the original grant ID and reject inactive/expired grants before saving rotated tokens.
+- Reject invalid/duplicate permission requests before opening OAuth.
+- Derive binary/Web-guide versions from package metadata; support structured JSON version output.
+- Rename the user-directory override to `INDIANA_CLI_CONFIG_DIR`. Update scripts that previously set `GROW_CLI_CONFIG_DIR`; stored config/credential formats stay unchanged.
+- Correct current command coverage, test/production readiness and document-schema guidance.

package/README.md

@@ -1,3 +1,245 @@
-# Temporary Holding Version
+# Indiana CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Indiana CLI **0.3.11**, Node.js 22+. The executable is `indiana`. CLI versions are independent of the Customer SDKs.
+
+Install the public npm package:
+
+```sh
+npm install -g @tinkerlandai/indiana-cli
+indiana --version
+indiana doctor --server https://tinker.cash --json
+indiana login --server https://tinker.cash
+```
+
+For a reproducible installation, use `npm install -g @tinkerlandai/indiana-cli@0.3.11`. Uninstall with `npm uninstall -g @tinkerlandai/indiana-cli`. Node.js 22+ must be on PATH; the package includes the `indiana` command and npm installs its runtime dependencies.
+
+The existing website installation channel remains available on macOS and Linux:
+
+```sh
+curl -fsSL https://tinker.cash/install.sh | sh
+```
+
+That channel uses six platform archives with dependencies included (macOS arm64/x64; Linux arm64/x64 glibc/musl), verifies SHA-256 and installs without npm or sudo. It has its own published version in [the website manifest](https://tinker.cash/downloads/cli/latest.json); an npm release does not deploy a new website archive. Its default executable is `~/.local/bin/indiana`, with releases under `~/.local/share/indiana/releases/`. Absolute `INDIANA_BIN_DIR` and `INDIANA_INSTALL_ROOT` overrides remain supported. Configuration and credentials are retained on upgrade.
+
+## Updates
+
+```sh
+indiana update --check
+indiana update
+indiana --version
+```
+
+Interactive successful commands check for updates at most once every 24 hours, with a 1.5-second deadline. JSON, CI, non-interactive, help and version invocations stay silent; `INDIANA_NO_UPDATE_CHECK=1` disables notices.
+
+Public npm installations read the canonical npm package's `latest` version and verify SHA-512 before installing the exact archive in the same global prefix, with lifecycle scripts disabled. Website-managed curl and legacy URL npm installations retain the website update channel, including its SHA-256/SHA-512 checks and custom directories. Both refuse downgrades and preserve saved configuration and credentials. Checks are anonymous and independent of `--server`.
+
+CLI 0.3.2 and earlier need one bootstrap upgrade using the curl command above or the current npm install command. Once 0.3.3 is installed, update notices and `indiana update` are available.
+
+Contributors can also build and run from the repository:
+
+```sh
+pnpm task cli:build
+pnpm --silent indiana --version --json
+pnpm --silent indiana capabilities --json
+```
+
+## Scope and availability
+
+Local commands manage credential-free configuration and validate/diff current Funnel, Paywall and Offering documents. Remote management commands use browser-approved Console-member OAuth grants. Code-reference CI commands use a dedicated App/environment Key.
+
+Better Auth in the Indiana Admin issues and refreshes CLI tokens through Authorization Code + PKCE. Accounts and native sessions live in Cloud SQL. Each CLI login has an independent native session; exact App/environment/resource grants remain separate and are checked against current membership. Tokens stay in the local credential store. Logout revokes that CLI session without signing out the Console.
+
+Implemented remote command surfaces include `login`, `whoami`, `auth status`, `logout`, `projects list`, and scoped `coupons`, `rewards` and `referral-programs` catalog/code/lifecycle operations. Their execution still requires current server registration, membership, role/App access and explicit resource grants. No local command proves those permissions.
+
+`coupons subscription`, `coupons subscription-state` and `coupons subscription-recover` are unavailable in the current management runtime. They return `CAPABILITY_UNAVAILABLE` (exit 7) before reading files or credentials or making requests. `capabilities` reports these separately; `--only-supported` excludes them. Customer/Feature/Product management and Offering/Paywall/Funnel authoring now have connected scoped operations. Scoped balances, usage, ledger, billing controls, analytics and Sandbox Stripe refunds also use the original Console handlers. Organization governance, GrowthBook administration, profile images and compatible integration configuration use explicit layered grants. Of 110 Console entries, 107 are connected; Apple/Google provider configuration and native Product bindings remain deferred. Inspect the operation catalog for exact availability; it does not certify every provider/business branch.
+
+Production OAuth and the scoped business slice are deployed at `https://tinker.cash`; `https://dev.tinker.cash` remains the separate Indiana-test deployment. Credentials and native OAuth clients are origin-bound and cannot be shared between them. See production acceptance for exact verified coverage and remaining gaps.
+
+## Layered consent
+
+Use `--scope app`, `--scope organization` or `--scope account` for explicit configuration,
+governance or same-user actions. `--scopes-file <path>` requests several exact levels
+in one immutable consent. Environment remains the default and preserves existing grants.
+App configuration covers all App environments; selected-environment analysis still
+requires its separate resource grants. See [layered authorization](../../docs/cli-layered-authorization.md)
+for dependencies, tested scope and release receipts. Invitation creation/resending
+sends no email unless `--send-email` is explicitly supplied.
+
+## Business operations
+
+### Code reference scanning
+
+CLI **0.3.5** adds a CI surface using a dedicated App/environment API Key, independently of personal OAuth management sessions. The target server must have the matching code-reference API and database migration before a repository can report.
+
+In a Feature's **Code references** tab, configure a GitHub repository, target branches, workflow path, included/excluded paths and static function names. Create a Key with exactly `code-references:read` and `code-references:write`, bind it to that repository, and store its secret as `INDIANA_CODE_REFERENCES_KEY` in the merchant repository. The SDK setup dialog has a preset for these two permissions. No private-source access is granted to Indiana.
+
+```sh
+indiana code-references scan --server https://dev.tinker.cash \
+  --app <app-uuid> --env sandbox --repository-id <repository-uuid> \
+  --branch main --workflow .github/workflows/indiana-code-references.yml \
+  --run-number 12 --run-attempt 1 --root . --out /tmp/new-report.json --upload --json
+
+# Recover an uncertain write with the exact saved input, scan ID and run sequence.
+indiana code-references upload --server https://dev.tinker.cash \
+  --app <app-uuid> --env sandbox --file /tmp/new-report.json --json
+```
+
+`--upload` requires `--out` so the exact report is saved before a write. Output files are new, mode 0600, and never overwrite an earlier report. API credentials come only from the selected environment variable (`--key-env` changes its name); they are absent from reports and command output. Redirects and automatic network retries are refused. `--config <saved-config.json>` supports a local scan without credentials or network; `--upload` still needs the explicit server/App/environment and Key.
+
+Only clean, committed, tracked JS/TS sources within the configured paths are scanned. GitHub runs additionally check repository, branch, commit and workflow identity. Literal calls and configured wrapper names produce file/line locations; dynamic calls and known unsupported source files make coverage uncertain. Parsing, path, file, byte or reference limits fail the whole scan. An explicit empty result is emitted for every scanned key; missing keys never mean zero references. No source snippets are uploaded.
+
+The Console provides a workflow with fixed Action revisions and a versioned official CLI installer. A reusable composite Action source also lives at [`.github/actions/code-references`](../../.github/actions/code-references/action.yml). It requires checkout, Node.js 22+, a trusted push/manual branch workflow and a published CLI version with these commands. Merchants install the generated workflow in their own repository. The composite Action source is also provided for teams maintaining their own pinned integration; no scheduler is activated. PR/fork submissions are not an authoritative scan source.
+
+Failed GitHub jobs retain a metadata-only report artifact for seven days when the report was saved. Download it to replay the same input with `upload`. If no saved report is available, rerun the original workflow with a higher attempt; a rerun from an older workflow number cannot replace a later scan.
+
+Scan evidence describes configured static scope only. Clean up old branches, merge and deploy, inspect older clients and business dependencies, then rescan before considering manual archival. No command deletes or archives a Feature.
+
+### Independent screen sources (unreleased source)
+
+The current source adds `indiana code` for Paywall, Popup and Page designs. These commands require a source build and the matching Web management adapter; the scoped public 0.3.5 scanner release does not include them; they remain pending a separate release.
+
+```sh
+indiana code pull paywall/<uuid> --out ./template
+indiana code pull funnel/<uuid>/screen/<screen-id> --out ./popup
+indiana code pull template/<uuid> --out ./private-template
+indiana code check ./template --json
+indiana code diff ./template --json
+indiana code push ./template --json
+```
+
+Use a new output directory. `indiana.source.json` freezes the target, App/environment, revision and baseline; `screen.json` holds the complete structured design and copy. HTML/CSS contents live under `html/<node-id>/<locale>.html` and `html/<node-id>/style.css`, with empty declarations in `screen.json`. Edit these files with your editor or AI agent. Exported JSON bundles from the Web editor are also accepted by check/diff/push. The Web editor imports either a bundle or the source directory, with a review before applying changes.
+
+Check and diff are offline; remote guards still apply when pushing. Pull requires `platform.read`; push requires `platform.write` and the existing native authoring role. Push saves a draft with its original revision, preserving all other Paywall/Funnel configuration. A template target creates a private copy. A revision conflict preserves local files. Successful pushes update the local baseline while retaining working files, including edits made during the request; server sanitization differences remain visible in the next diff. No command publishes, watches files, runs a preview server or stores credentials in a source package.
+
+```sh
+indiana operations list --available --json
+indiana operations describe console.customers.post --json
+indiana login --permissions project.read,customers.write,features.write,plans.write,balances.read,rewards.read,platform.write
+indiana customers list --json
+indiana customers create --file customer-create.json --json
+indiana customers get <customer-uuid> --json
+indiana customers update <customer-uuid> --file customer-update.json --json
+indiana features list --json
+indiana features apply --file feature-operation.json --json
+indiana products apply --file product-operation.json --timeout 30000 --json
+indiana offerings list --json
+indiana paywalls apply --file paywall-operation.json --json
+indiana funnels apply --file funnel-operation.json --json
+```
+
+If a profile already has credentials, logout before requesting a different grant; scopes never expand automatically. Use only the permissions required for your operations. Inspect `requiredPermissions` in `operations describe`: cross-resource reads used for default Products, dependency/history checks and catalog transactions require explicit grants too. Missing dependencies fail before mutation. Existing Owner/Admin authoring rules and Sandbox/Live restrictions still apply.
+
+`customer-create.json` contains `{ "input": { "externalUserId": "user-42", "name": "Alex" } }`. An update contains `{ "requestId": "<new-uuid>", "patch": { "name": "Alex Updated" } }`. Org/App/environment are resolved from the approved selection, and conflicting supplied values are rejected. Domain action files use the same current DTOs as the Console; save/publish actions retain their original revision and request identity checks.
+
+Use `--query key=value` for query fields, repeating it for distinct keys. For example, `indiana features list --query id=<feature-uuid>`. `--file -` reads JSON from stdin. `indiana call <operationId> --input envelope.json` accepts `{ "params": {}, "query": {}, "body": {} }` for one finite operation; it cannot select an arbitrary URL or RPC. Do not combine `--input` with `--file`, `--query` or `--upload`.
+
+`--out <new-file>` saves JSON privately without overwriting existing files. Failed requests remove incomplete output. Pending operations return `CAPABILITY_UNAVAILABLE` (7) before reading input or credentials. `capabilities` separates connected operations from pending inventory. A connected adapter does not certify every underlying business branch or external provider.
+
+## Configuration and authentication
+
+```sh
+indiana config init --server https://your-indiana-test-host.example
+indiana profiles add work --server https://your-indiana-test-host.example
+indiana profiles use work
+indiana context use --org <org-uuid> --app <app-uuid> --env sandbox
+indiana context show --json
+indiana doctor --json
+indiana login --profile work
+indiana whoami --profile work --json
+indiana auth status --profile work --json
+indiana projects list --profile work --json
+indiana logout --profile work
+```
+
+Replace the host and UUIDs with the explicitly configured deployment and your authorized scope. `doctor` reads public metadata only, sends no credentials and refuses redirects. New login requires an available OAuth client, browser Code+PKCE approval and a selected Org/App/environment. The exact loopback callback remains `http://127.0.0.1:43187/callback`; port conflicts fail explicitly.
+
+For resource commands, request only the necessary supported permissions with `login --permissions project.read,rewards.read`. Invalid, empty or duplicate permission entries are rejected before OAuth starts. Approval uses an immutable ordered scope list and does not widen the member's App allowlist or original role grants.
+
+Scope priority is explicit flags → `indiana.config.json` → selected profile. Local selection remains `verified: false`. Profiles and credential storage bind to the exact management origin. Config files reject secrets and unknown fields; initialization never overwrites an existing file.
+
+Rename existing `grow.config.json` files to `indiana.config.json`; the JSON format is unchanged.
+
+The user directory defaults to `.config/indiana` (Windows: `LOCALAPPDATA/Indiana/cli`). Override with **`INDIANA_CLI_CONFIG_DIR`**; 0.2.0 no longer reads `GROW_CLI_CONFIG_DIR`. Existing configuration formats are unchanged. Credentials default to the system keychain, with no implicit file fallback. Explicit `--credential-store file` requires POSIX 0600 files/0700 directories and is unavailable on Windows. Locks and atomic replacement protect writes. New locks record the local owner process and recover automatically only after that process is confirmed stopped. A live PID, an unverifiable owner or another host keeps the lock occupied regardless of age. Older versions left empty `.lock` files without ownership metadata: stop all Indiana CLI commands using that configuration, then remove only the reported `.lock` file and retry; preserve the configuration and credentials. This recovery is unreleased source until a new CLI distribution is published.
+
+Credentials are saved only after the exact requested authorization is active. Refresh preserves user/client/session/grant identity and requires an active, unexpired grant. whoami verifies the current Supabase user/session and active grant without outputting tokens. Logout without a saved credential succeeds without a network call. With a saved credential, logout confirms revocation of the exact Indiana authorization and termination of its own Supabase Auth session (`scope=local`) before removing local credentials. Both results are reported separately. A failed or incomplete response retains credentials for retry; termination can refresh the same native session after the grant is revoked, without enabling business commands. `logout --local` explicitly leaves both server authorization and native session unchanged. Server and CLI support for this logout contract must be released together; older servers cannot confirm native cleanup.
+
+## Local document tools
+
+```sh
+indiana funnels validate --file funnel.json --mode publish --json
+indiana paywalls validate --file paywall.json --mode draft --json
+indiana offerings validate --file offering.json --mode publish --json
+indiana offerings diff --against before.json --file after.json --json
+cat funnel.json | indiana funnels validate --file - --json
+```
+
+Funnel input is the current editable draft; publish mode uses its publication-structure validator rather than the immutable delivery snapshot schema. Paywall input uses its current document schema, including the required published Offering reference for publication. Offering input is exactly `{ lookupKey, displayName, items, metadata }`: Product leaves at levels 1–3, groups at 1–2, at most 20 distinct Products, and empty groups only in draft mode. Offering has no invented schemaVersion or Package wrapper.
+
+All inputs use strict UTF-8/JSON and the existing 1,000,000-byte document budget. Validation reports `validation: local` and `serverChecks: not_run`; Product existence, Offering terms/membership, permissions and publication require the server. Diff emits escaped JSON Pointers and hashes, omits values, and caps displayed changes at 100 while preserving total/truncated counts.
+
+## Output and errors
+
+`--json` emits one JSON result on stdout. Success uses `{ data }`; failure uses `{ error: { code, message, retryable, details? } }`. Login progress goes to stderr. Version output is `{ data: { version } }`. Tokens, OAuth codes and provider response bodies are excluded from diagnostics.
+
+`--timeout` is a 1–60000 ms request deadline (default 10000), covering response headers and body. Responses are size-bounded and success bodies require JSON with the expected schema. HTTP 401/403/409 remain distinct even without JSON bodies; 429/transient service failures are retryable. The CLI does not automatically replay resource writes.
+
+The current source distinguishes transport failures from HTTP responses in `doctor`, management calls and OAuth token exchange. `TIMEOUT` means the request deadline or a connection/read timeout was reached; `NETWORK_ERROR` carries `details.kind` (`dns`, `connection_refused`, `connection_reset`, `unreachable`, `tls`, `proxy` or `unknown`). Safe diagnostics include the request `stage`, target `host`, deadline and a suggested next step. Terminal output also shows HTTP status and diagnostic request ID when available. Raw exception messages, full URLs and proxy credentials are never printed. A network error alone does not establish a server outage.
+
+`doctor` identifies whether management metadata or OAuth discovery failed. Check the hostname/DNS for `dns`, host/port and proxy address for `connection_refused`, routing/VPN/firewall for `unreachable`, and the system clock/certificate trust for `tls`. HTTP 407 indicates proxy authentication; an unclassified proxy tunnel failure can remain `unknown`. If your network requires a proxy, check `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`. On Node.js 22.21+ within 22.x or Node.js 24+, `NODE_USE_ENV_PROXY=1 indiana doctor --json` enables environment proxies for that invocation. This switch does not create a proxy or configure its address, and the CLI never changes shell configuration automatically.
+
+Read-only transport failures use `check_availability`; writes and OAuth token exchanges use `recover_operation` with `retryable: false`, because the remote operation may have completed. Inspect the original operation/session before retrying. A network failure during refresh preserves the saved credential and does not by itself require deleting it or logging in again. Genuine HTTP service failures retain `SERVICE_UNAVAILABLE` with their status and available request ID. These diagnostics are unreleased source until a new CLI distribution is published.
+
+| Exit | Meaning                                                   |
+| ---- | --------------------------------------------------------- |
+| 0    | Success                                                   |
+| 2    | Invalid arguments, configuration, input or document       |
+| 3    | Missing/expired login or authorization/session failure    |
+| 4    | Origin, permission or redirect constraint                 |
+| 5    | Conflict or occupied write lock                           |
+| 6    | Network, response protocol, service or rate-limit failure |
+| 7    | Runtime/capability/authorization not available            |
+
+## Verification and references
+
+`pnpm task cli-package` builds and installs a real tarball in an isolated consumer, tests the binary against local fixtures and removes its temporary dependencies. It does not perform real OAuth, access a database, open a browser or deploy. System keychain loading on one host does not certify Windows/Linux credential behavior.
+
+See [CHANGELOG](CHANGELOG.md), [architecture design](../../docs/cli-management-design.md), and the [installation instructions above](#indiana-cli). Real Auth/RLS, provider operations, browser approval and deployment need their own current evidence.
+
+## Configuration, results and finance reads
+
+The current source adds 28 finite GrowthBook read models to `capabilities.growthReaders`, each with `list` and `get <id>` aliases. For example:
+
+```sh
+indiana growth features list --query limit=25 --json
+indiana growth features get checkout_enabled --json
+indiana growth experiments list --json
+indiana growth metrics fact-metrics list --json
+indiana growth insights reports get <report-uuid> --json
+indiana operations describe console.growth.read.get --query resource=reports --json
+indiana customers invoices list <customer-uuid> --json
+indiana customers invoices get <customer-uuid> <invoice-uuid> --json
+indiana customers invoices refunds get <customer-uuid> <invoice-uuid> --json
+indiana customers credit-statement get <customer-uuid> --query from=2026-10-01T00:00:00Z --query to=2026-10-02T00:00:00Z --json
+indiana customers entities get <customer-uuid> --json
+indiana customers seats get <customer-uuid> --json
+indiana overview list --json
+indiana events list --query name=payment.failed --json
+```
+
+Configuration requires App `platform.read`. Environment results additionally require the exact environment's `platform.read` and `analytics.read`. A write grant implies read only while the original grant remains valid under the current native role. Private objects retain their original ownership/share rules. The finite reader removes configuration analysis summaries and Data Source connection secrets, without expanding direct OAuth table access.
+
+GrowthBook lists return `{resource, rows, ids, nextCursor}`. Pass the unchanged `nextCursor` as `--query after=...`; default page size is 25, maximum 100, and a response-size boundary can end a page earlier. `parentId` filters child collections. The parallel `ids` array supplies the exact identity for each row, including collision-free composite revision/reference identities. Use `ids[n]` with `get` for `rows[n]`. Parent-filtered lists are the normal way to read those collections. Invoice pages keep their `after` cursor. Statement pages require the original `snapshotAt` plus all three cursor fields `afterAt`, `afterId`, `afterPosition`. Event pages require both `before` (timestamp) and `after` (event ID). Overview and event UTC date ranges are bounded to 90 days.
+
+This source expansion requires the matching server/database reader release. Local capability discovery does not assert that an older deployed server contains it. Apple/Google configuration and bindings remain deferred; SDK runtime calls and retired coupon subscription commands are outside this expansion.
+
+## Snapshots
+
+```sh
+indiana snapshots list --query parentId=<experiment-uuid> --json
+indiana snapshots get <snapshot-uuid> --json
+indiana snapshots status <snapshot-uuid> --json
+indiana snapshots run --file snapshot.json --json
+indiana snapshots cancel <snapshot-uuid> --json
+```
+
+`status` reports computation/query progress and accepts `--query sql=1` for authorized query details. `get` reads the stored Snapshot. `snapshot.json` contains `{ "experimentId": "<experiment-uuid>" }` and may include `phase`, `endDate` or `dimension`. Status and cancellation take the Snapshot UUID directly; the former `growth snapshots` command path is removed. Existing operation IDs, HTTP payloads, permissions and App/environment guards are unchanged.