@capxul/cli 4.20.0-beta.7 → 4.20.0-beta.8

package/README.md

@@ -89,6 +89,14 @@ These commands accept `--email`. Without it, they restore the protected current
 session. Organization reads accept `--org` or its alias `--org-id`. Identical
 repeated IDs are accepted. Different IDs are refused.
 
+A read without `--org` resolves one exact Organization in this order: the saved
+read default, then the recovery handle this machine recorded for the person's
+Organization journey. A recovery handle can also name an Organization whose
+setup lane still runs, which the own-access list does not carry yet; the read
+reports that exact lane, and it applies the usual current-access rule again once
+the Organization reports ready. The read refuses an Organization it cannot
+reach, and it never substitutes another one.
+
 `org use` requires an explicit Organization ID. It checks current access and
 saves a protected per-person read default. The default never grants authority.
 Each read checks current access again. Without an explicit ID or saved default,
@@ -169,8 +177,10 @@ returned view is the authorization-time view of the consent commit
 
 `org create` and `org retry` restore the protected current session and start the
 existing command-scoped browser signer. They never read or write the saved read
-default. Local input checks run before any client, browser, or backend work, and
-they include the confirmation gate:
+default. `org create` writes the person's Organization recovery handle. That
+handle holds the exact business handle and the exact Organization ID, and it
+holds nothing else. Local input checks run before any client, browser, or
+backend work, and they include the confirmation gate:
 
 - A noninteractive or JSON write requires `--confirm`. Without it the command
   refuses with exit 2 before any client, browser, or mutation work.
@@ -211,6 +221,47 @@ failed lane still reports the Organization it is about. The command returns
 success only after an exact `org(O).getLifecycle()` read reports `ready`. It
 never saves a read default and never returns a different ready Organization.
 
+`org create` continues the Organization journey this machine already prepared.
+Before the first durable write it records the exact business handle as the safe
+recovery handle. It adds the first committed Organization ID to that handle
+before it forwards any founder authorization digest, and it keeps that handle
+after a failure, an interruption, or a ready result. A later create therefore
+resolves exactly one Organization:
+
+- The same handle resumes the exact recorded Organization. It calls the SDK
+  recovery owner once per attempt and settles the same lifecycle. It never
+  submits a second bootstrap, and it never creates a second Organization or
+  treasury.
+- A different handle refuses with exit 2 while the recorded Organization is not
+  ready. The refusal names the exact Organization.
+- A different handle creates one Organization only after the recorded
+  Organization reaches ready.
+- A recorded Organization that is already ready, and still in the person's
+  current access, returns unchanged, with no write and no signature. A ready
+  result the person can no longer reach refuses, and the committed recovery
+  handle stays recorded for exact recovery.
+- A create that continues a recorded handle checks current access before it
+  reports success. The committed Organization ID becomes durable first, so a
+  refusal or an interruption keeps the exact recovery handle, and a ready
+  lifecycle line reaches stderr only after the check resolves.
+- A terminal preview reads the recorded Organization's lifecycle only for the
+  handle that continues it. A different handle is a new creation, so an
+  unreachable recorded Organization never blocks it.
+- A handle the backend refuses is refused before any Organization write. The
+  command releases the prepared handle, so the person can correct the handle and
+  create. Every other failure keeps the handle, because its Organization may
+  already exist.
+
+The recovery line names the exact Organization and the safe handle. JSON mode
+writes it as one newline-delimited progress object:
+
+```json
+{ "type": "organization.recovery", "organizationId": "O", "handle": "acme" }
+```
+
+`org retry` stays explicit: `--org` (or its alias `--org-id`) is the one write
+scope, and no read default or recovery handle is consulted.
+
 `org retry` requires an explicit `--org` (or `--org-id`). It validates the ID
 with the public `toOrgId` constructor, reads that exact Organization's lifecycle
 for its terminal preview, resumes that same durable setup lane, then settles the
@@ -234,7 +285,7 @@ subscription and the browser bridge.
 | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
 | `CAPXUL_CLI_HOME`              | Directory for global CLI settings. Defaults to `$XDG_CONFIG_HOME/capxul/cli`, or `$HOME/.config/capxul/cli`. |
 | `CAPXUL_PUBLISHABLE_KEY`       | Optional developer override for the bundled first-party staging key.                                         |
-| `CAPXUL_BOOTSTRAP_URL`         | Bootstrap origin. Defaults to `https://site.preview.abuusama.dev`. Convex Cloud origins are rejected.        |
+| `CAPXUL_BOOTSTRAP_URL`         | Bootstrap origin. Defaults to `https://api.staging.capxul.com`. Convex Cloud origins are rejected.           |
 | `CAPXUL_POSTHOG_HOST`          | Optional development override for the built-in public PostHog ingestion origin.                              |
 | `CAPXUL_POSTHOG_PROJECT_TOKEN` | Optional development override for the built-in public project ingestion token.                               |
 | `CAPXUL_TELEMETRY_DISABLED`    | Set to `true` to disable remote observation regardless of the saved preference.                              |
@@ -348,11 +399,21 @@ stored and tagged as `legacy-native-grant` in status. A profile read asks for an
 explicit new login; it never exchanges the old grant for a broader session.
 Logout forgets and attempts to revoke both credential types for the selected email.
 
-For a human, `capxul auth login` prompts for email and a hidden OTP. `auth signup`
-also prompts for the current Profile fields: display name, two-letter country
-code, and handle. The browser opens only when the shared Core onboarding journey
-needs Openfort wallet readiness. It shows wallet status only. It has no email,
-OTP, Profile, or approval form.
+`capxul auth login` and `capxul auth signup` stay separate commands. On a
+terminal, each command is a wizard. `auth login` asks for the email and a masked
+OTP. It accepts the code as a paste. It retries an invalid code at most three
+times for one request. After sign-in, an incomplete account gets one offer to
+continue setup in the same command. `auth signup` authenticates first, then asks
+for the Profile fields: display name, two-letter country code, and handle. A
+known value is the prompt default, so Enter keeps it.
+
+The browser opens only when the shared Core onboarding journey needs Openfort
+wallet readiness. It shows wallet status only. It has no email, OTP, Profile, or
+approval form.
+
+Ctrl+C or Ctrl+D at a wizard prompt cancels the command. The command prints no
+success result and exits 130. A step that already finished keeps its result: a
+completed sign-in keeps its session.
 
 For an agent, send and verify in separate processes:
 
@@ -360,7 +421,6 @@ For an agent, send and verify in separate processes:
 capxul auth send --email "$TEST_EMAIL" --json
 # Supply the delivered six-digit OTP through stdin, not a command argument.
 capxul auth verify --email "$TEST_EMAIL" --otp-stdin --json
-capxul auth signup --email "$TEST_EMAIL" --display-name "Test Person" --country GH --handle test_person --json
 capxul auth profile --email "$TEST_EMAIL" --json
 # A later process uses the same protected CLI home; no new OTP is required.
 capxul auth profile --email "$TEST_EMAIL" --json
@@ -368,12 +428,13 @@ capxul auth status --email "$TEST_EMAIL" --json
 capxul auth logout --email "$TEST_EMAIL" --json
 ```
 
-`--otp-stdin` reads up to 64 bytes, ending at EOF. Pipe from a secret provider or
-use input redirection from a protected file. OTPs are never accepted in argv,
-persisted in the continuation, or included in output. Non-interactive commands
-without the required input refuse with exit 2 instead of prompting.
+A machine run never prompts. `auth login` with `--otp-stdin` sends the OTP and
+verifies one code from stdin. It returns the tagged result
+`setupState: "setup-required"` when the account needs setup. It does not start
+setup work, so sign-in never becomes signup.
 
-A fresh non-interactive signup can do verification and setup in one command:
+A fresh machine signup does verification and setup in one command. State every
+Profile field; a missing field refuses with exit 2:
 
 ```sh
 # Supply only the delivered OTP through stdin.
@@ -381,6 +442,11 @@ capxul auth signup --email "$TEST_EMAIL" --otp-stdin \
   --display-name "Test Person" --country GH --handle test_person --json
 ```
 
+`--otp-stdin` reads up to 64 bytes, ending at EOF. Pipe from a secret provider or
+use input redirection from a protected file. An invalid value refuses with exit 2. A missing `--otp-stdin` refuses with exit 2 before the command starts client
+work. OTPs are never accepted in argv, persisted in the continuation, or included
+in output.
+
 The local page binds to an OS-selected loopback port. A random launch capability
 is redeemed once and removed from the URL before Openfort starts. The page receives
 only the authenticated wallet token and encryption session in memory. Closing it
@@ -388,6 +454,29 @@ ends the current wallet attempt. Re-run `auth signup` with the same CLI home to
 resume the same Profile and Account without another OTP while the backend session
 remains valid.
 
+`auth signup` returns only two readiness results. `setupState: "ready"` is a
+personal Account that the Account readiness owner reads as ready and deployed,
+and its data carries the public identifiers: the Profile, the public wallet
+address (`smartAccount.signerAddress`), the personal Smart Account address
+(`smartAccount.smartAccountAddress`), the Account ID
+(`lifecycle.accountId`), and the ready status. Any other state returns the typed
+recoverable result `setupState: "setup-required"`, with the lifecycle, its
+failure code, and the command that resumes the journey. A ready Account starts
+no wallet work, so a retry keeps the one Profile, wallet, Smart Account, and
+Account. An interruption keeps the stored session and stores no code, so the
+next command resumes the same setup.
+
+A ready personal Account continues the same journey into Organization creation
+with `capxul org create --name NAME --handle HANDLE --country CC`. The create
+command records the safe recovery handle for that Organization, so an
+interruption or a restart resumes the exact same Organization.
+
+The CLI checks `--display-name`, `--country`, and `--handle` before it opens a
+client, so a malformed value refuses with exit 2 and no code is sent. The handle
+check covers the grammar only: a handle that another person holds, and a reserved
+handle, refuse through the identity owner after sign-in. Both refusals name the
+handle, and neither offers verification-code recovery for a Profile problem.
+
 The version 2 `first-party-session` record stores the opaque provider credential
 in the existing protected plaintext store. Its scope includes the application
 key, issuer, environment, and email. Each process validates restoration with the