@tarileo/avileo-catalog-cli 0.3.0 → 0.3.2

package/README.md

@@ -1,25 +1,64 @@
 # @tarileo/avileo-catalog-cli
 
-The Avileo tenant-agent command line interface for a registered `tienda` catalog.
+The Avileo tenant-agent command line interface for a registered business with effective catalog-agent access.
 
-For a first-time human connection, use the temporary device authorization link:
+The origin-pinning contract below describes this checkout. A package version in
+`package.json` does not prove npm availability: `0.3.2` has not been published
+by this release closure. Public handoff must wait for the operator's verified
+package version/artifact and an activated destination. Never substitute an older
+CLI that lacks these flags or silently pair with the integrated deployment.
+
+For an authorized local-source session, build the workspace SDK first and run
+the CLI from the repository root:
 
 ```sh
-npx --yes @tarileo/avileo-catalog-cli@0.3.0 auth login --json
+bun run --filter @tarileo/avileo-sdk build
+bun apps/avileo/agent-cli/src/index.ts auth login --base-url <origin> --json
 ```
 
-The CLI prints only the verification URI, user code and status, opens the link
-with a safe executable when available, polls until approval, and stores the new
-Agent Key locally with `0600` permissions. The key is never printed or placed
-in the URL. Use `auth status --json` to inspect the source (`environment` or
-`local`) without revealing the key, and `auth logout --json` to remove only the
-local credential; remote revocation remains an Avileo action.
+Hereafter `avileo` means that same verified CLI command prefix. Pass only the
+explicit API origin supplied by the operator; package source and API destination
+are independent decisions.
+
+The CLI prints only the verification URI, user code, status and pinned
+`baseUrl`, opens the link with a safe executable when available, polls until
+approval, and stores the new Agent Key locally with `0600` permissions. The key
+is never printed or placed in the URL. Use `auth status --json` to inspect the
+source (`environment` or `local`) and the pinned origin without revealing the
+key, and `auth logout --json` to remove only the local credential; remote
+revocation remains an Avileo action.
+
+Origins must use HTTPS, except plain HTTP for local development hosts
+(loopback, private or Tailscale addresses). Without `--base-url` or
+`AVILEO_AGENT_BASE_URL`, the CLI pairs with production
+(`https://avileo.theelena.me`) and pins it. If the pinned origin fails, fix the
+target; the CLI never falls back to another origin on its own.
 
-For CI/CD and automated agents, continue injecting `AVILEO_AGENT_API_KEY`.
+If Avileo has already issued an Agent Key, configure it without putting the
+secret in shell history, process arguments or JSON:
+
+```sh
+avileo auth configure --base-url <origin> --json
+```
+
+The command reads the key without echoing it and stores it locally. For CI/CD
+and automated agents, continue injecting `AVILEO_AGENT_API_KEY`.
 Environment credentials always take priority over the local credential file.
 Never pass an Agent Key through flags, prompts or JSON input.
 
-`AVILEO_AGENT_BASE_URL` remains the development/test endpoint override.
+`--base-url` wins over `AVILEO_AGENT_BASE_URL`, which remains the advanced
+development/test override: set it before `auth login` or `auth configure` so
+the origin is pinned with the credential. Commands reject
+`CLI_ORIGIN_CONFLICT` when the variable points to a different origin than the
+pinned credential — remove the override or re-authenticate with
+`auth login --base-url <origin>`; an existing key is never sent to another
+host. Invalid or unsafe origins fail with `CLI_ORIGIN_UNSUPPORTED`.
+
+Local credentials created before origin pinning must be authorized again with
+`auth login --base-url <origin>`. A stored key without a bound origin fails
+with `CLI_CONFIGURATION_ERROR` before any request; the CLI cannot infer its
+destination safely and does not migrate it to production or an environment
+override.
 
 Use `--from <json-file>` for structured mutation input. Direct mutations validate
 locally by default; pass `--apply` only after reviewing the result. The CLI is
@@ -29,8 +68,16 @@ reference for headers, idempotency, resources and errors.
 
 For operators and AI agents, the recommended sequence is:
 
-1. Run `business show --json`.
-2. Read the exact resource before proposing a change.
-3. Run mutations without `--apply` to review local validation or a diff.
-4. Request explicit approval and repeat with `--apply`.
-5. Use the durable import preview/apply flow for structured supplier lists.
+1. Run `business show --json` to confirm the connected business and actions.
+2. Run `business profile show --json` when evaluating profile completeness.
+3. Read the exact catalog resource before proposing a change.
+4. Run direct mutations without `--apply` to review local validation or a diff.
+5. Add `--apply` to create a proposal; this does not mutate the business.
+6. Ask the human to approve the exact proposal in Avileo, then apply the
+   returned operation or approval ID.
+7. Use the durable import preview/apply flow for structured supplier lists.
+
+Profile updates use a direct JSON object with `business profile update --from
+profile-update.json`. Without `--apply` the command returns a local diff; with
+`--apply` it creates a `business.profile.update` proposal. After approval, run
+`operation apply <id> --json` and re-read the profile.