@withandeo/cli 0.19.19 → 0.19.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withandeo/cli",
-  "version": "0.19.19",
+  "version": "0.19.21",
   "description": "Developer CLI for Andeo applications",
   "type": "module",
   "license": "UNLICENSED",

package/skill/{tender-accounts → andeo}/SKILL.md

@@ -36,7 +36,7 @@ Global installations automatically maintain the CLI and existing default Codex/C
 | Custom domains and customer sign-in | [Domains and authentication](references/domains-auth.md) |
 | Diagnose requests or workflow execution | [Observability](references/observability.md) |
 | Inspect or restore production | [Releases and recovery](references/releases-recovery.md) |
-| Load maintained Recharge, Shopify, or design-system practice | [Authenticated skills](references/skills.md) |
+| Load maintained Recharge, Shopify, product-finder, or design-system practice | [Authenticated skills](references/skills.md) |
 
 ## Load maintained practice when it applies
 
@@ -150,6 +150,25 @@ Production publication stays with the protected policy or authenticated administ
 - Never describe a preview as production, code rollback as database restore, or termination as reversal of an external effect.
 - Never retry an uncertain mutation merely because a UI looks stale. Inspect exact evidence and follow supported recovery.
 
+## Send feedback when Andeo gets in the way
+
+When the CLI, a guide or the platform blocks you, misleads you or lacks something you needed, tell the Andeo team with `andeo feedback --title TEXT --category bug|docs|feature|other --body-file notes.md --json`. Use `--body-file -` for stdin. Give full context: what you tried, what happened, what you expected, and exact commands and errors. Bodies can be up to 65,000 characters. Leave out credentials and customer data, use `--dry-run` to review the text, and tell the user what you sent. Save it for real friction rather than routine progress. It requires login, and the receipt means Andeo accepted the feedback, not that anything was changed.
+
 ## Finish with exact evidence
 
+For a persistent Cloud task, you MUST release its run when the work is done.
+Finish all run-dependent checks, reconcile pending mutations, and retain the
+non-secret evidence needed for the handoff, then run `andeo agent complete --json`
+in that task's existing environment before the final response. Confirm the
+returned `completed` status; do not claim the slot was released if completion
+failed. For an intentionally abandoned task, use `andeo agent cancel --json`
+instead. Do not complete a run while its work is still in progress.
+
+Completion, cancellation, an administrator stopping that run, or its expiry
+releases its concurrent-run slot. Closing the chat, ending a CLI process, or
+finishing a response does not release it. Without explicit completion, an
+unexpired active run continues occupying a slot across the organization.
+See [run completion and capacity](references/authentication.md#finish-a-cloud-run-and-release-its-slot)
+for failure recovery, expiry and preview implications.
+
 Report the journey and app scope, checks, exact preview/release identity, live behavior verified, and outstanding administrator steps. State what remains unproven. Keep credentials, raw customer logs and sensitive payloads out of the handoff.

package/skill/{tender-accounts → andeo}/references/authentication.md

@@ -2,6 +2,46 @@
 
 For Cloud installations using CLI 0.19.16 or newer, configure the secret `ANDEO_CLOUD_BOOTSTRAP`. Standard Andeo origins, the installation identity, and the effective grant scope are resolved automatically. `ANDEO_AGENT_SCOPE` optionally narrows that scope; `ANDEO_AGENT_RUN_SECONDS` optionally requests a different bounded lifetime. Omitted lifetime defaults to 30 minutes, capped by tenant policy and credential expiry. At task startup set a unique `ANDEO_AGENT_TASK_ID` and private `ANDEO_AGENT_STATE_DIR` outside the checkout. Set `NODE_USE_ENV_PROXY=1` only when the runtime requires its network proxy. Explicit invalid overrides fail rather than falling back to defaults.
 
+## Finish a Cloud run and release its slot
+
+Persistent Cloud runs occupy concurrent-run slots across the organization, not
+just one agent or installation. After completing all work that needs the run,
+including verification and preparation of the final handoff, you MUST run:
+
+```sh
+andeo agent complete --json
+```
+
+Use the same task environment and private state directory. Confirm the response
+reports `completed` before saying the run was released. For intentionally
+abandoned work, use `andeo agent cancel --json` and confirm `cancelled`. These
+commands end only the current task's run; they do not undo external mutations.
+Reconcile uncertain writes or in-flight work before ending the run. Do not end
+a run merely because an individual command finished or work is temporarily paused.
+
+A slot is released when the run completes, is cancelled/stopped by its agent or
+an administrator, or reaches its `expiresAt` deadline. Admission excludes expired
+runs immediately without waiting for a cleanup job. Closing Claude/Codex, exiting
+the terminal, ending a response, or API-token expiry alone does not end the run.
+Runs default to 30 minutes; an explicitly requested longer lifetime can hold the
+slot until that later deadline unless the run is ended sooner.
+
+If completion or cancellation cannot be confirmed, preserve task state, report
+the failure, and use `andeo agent status --json` when authentication is available.
+An administrator can inspect and stop the exact run in Persistent agents. Do not
+delete state to bypass the failure, switch authentication modes, or start another
+session to evade capacity limits. A completed, cancelled or expired task cannot
+re-admit using the same state directory; later work needs a fresh task and, when
+continuing source work, the supported `source continue` flow.
+
+Normal completion ends run-bound API, Git and direct-preview access. Retain
+non-secret IDs and verification results before completing. A separately authorized
+`preview.share` handoff survives normal completion within its existing limits;
+cancellation can invalidate it. Do not cancel successfully finished work as a
+substitute for completion. See the delivery reference for preview scope and expiry.
+
+## Human login and project scope
+
 If authentication is missing, start the agent-safe device flow:
 
 ```sh

package/skill/{tender-accounts → andeo}/references/managed-source.md

@@ -11,23 +11,27 @@ Protected transport and successful exact preview/checks remain required.
 Inspect `capabilities`, `source status` and `source merge-policy show`;
 persistent actors cannot edit merge/publication policy to expand permission. Existing saved
 publication policy controls deployment after landing. Do not push main directly.
-After run expiry, use `andeo source continue --change scr_... --json` to obtain
-fresh bounded authority on the original branch and change. Use it in the same
-private state directory after expiry, or as the first authenticated command in a
-fresh task. The same agent, grant and installation retain the change number and
+After run expiry or cancellation by the task itself, use
+`andeo source continue --change scr_... --json` to obtain fresh bounded authority
+on the original branch and change. Run it as the first authenticated command in
+a fresh task. The same agent, grant and installation retain the change number and
 review history. Before a change exists, use `--work asw_...` with `sourceWorkId`
 from `source status`. Normal bootstrap rotation within that installation works.
 A live writer, retained/uncertain source mutation, landing or terminal change
 blocks the handoff. Inspect and settle the original operation before retrying.
-Different installations and revoked access cannot inherit this work.
+Different installations, administrative stops and revoked access cannot inherit this work.
 
 Read `assignedFeatureBranch` from `source status`: continued branches keep their
 original name. Push, preview and refresh that branch with the existing commands.
 Continuation alone changes no source or review snapshot; changed refs still
 invalidate approval. A replacement preview for unchanged source also creates a
 new review snapshot and requires fresh approval for its new validation evidence.
-Old tokens, preview grants and accepted operation deadlines
-stay fixed. Create a fresh exact preview under the new run when needed.
+Old tokens, preview grants and accepted operation deadlines stay fixed. If the
+branch still points at the ready build and current preview policy permits it,
+use `andeo preview open --from sbl_... --json` to issue a fresh link under the
+new run. This reads the current branch tip with `source.read` and applies the
+current `preview.open` and `preview.share` scopes. Use `andeo preview --json`
+when the previous build can no longer be used.
 
 On a managed repository, push the committed feature branch and verify its exact
 native preview, then request one hosted merge. Read `capabilities`,
@@ -83,6 +87,16 @@ scr_... --idempotency-key KEY`, then `resume`, for the same retained inputs.
 `source change cancel` withdraws new work; issued effects require readback and
 may remain `cancellation_pending`. It cannot undo a merge or deployment.
 
+For persistent agents, completed preview evidence and permission to execute a
+preview build have separate lifetimes. The hosted merge preflight can consume
+the same run's ready, unchanged preview after its build lease expires; current
+merge authority, exact source and preview policy must still pass. This never
+renews build authority. Dry-run checks the same preview evidence. Inspect the
+returned reason and next action for `source_merge_preview_required` or
+`agent_effect_authority_changed`; changing idempotency keys cannot repair lost
+authority or invalid validation evidence. Lease duration is a server policy,
+not a per-preview CLI option.
+
 ## Administrator-authorized source-only merges
 
 Use this mode only when a current administrator has explicitly selected
@@ -301,6 +315,22 @@ Source landing never calls the production publisher directly;
 after landing, the repository's already configured default-branch policy may
 publish the same artifact after its exact preview and production validation succeed.
 
+To correct review metadata, read `snapshotVersion` from `source change show`
+and edit the existing open change.
+
+```sh
+andeo source change edit --change scr_... --expected-snapshot 3 \
+  --title "Clarify the account copy update" --description "Includes the empty state." --json
+```
+
+Supply either field or both. Omitted fields keep their current values, and
+`--description ''` clears the description. An actual edit creates a new
+snapshot and preserves the change ID, number, and exact preview. A prior
+approval must be renewed. An identical edit with the current snapshot leaves
+the review unchanged. If the snapshot is stale, read it again and verify the
+current review before retrying. Persistent agents need `review.prepare` for
+their assigned feature branch.
+
 Treat source administration and production publication as different acts. A
 source operation may create a new immutable preview lineage, but only the
 merchant's saved policy or explicit publication approval can authorize production. Portal and gateway remain independent apps: configure variables, policy and delivery for each. Do not imply that two repository refs or apps publish atomically.

package/skill/{tender-accounts → andeo}/references/releases-recovery.md

@@ -13,4 +13,22 @@ Only run rollback when explicitly requested. Select an eligible retained target
 
 Recover `dwf_` publications via administrator Activity → Resume exact publish. `delivery retry` accepts `dly_` preview IDs, not production workflows. Preserve the approved intent; never edit platform records or submit duplicates to escape a hold.
 
+For a succeeded publication with incomplete activation verification, use
+`andeo production releases --json` to inspect the current `activation_id`,
+composition and revision. An administrator may recheck that existing activation:
+
+```sh
+andeo production verify --activation activation_... --composition wfp_... \
+  --expected-revision 168 --json
+```
+
+This probes the existing serving runtime and host policy and records verification
+and audit evidence. It never builds, uploads, publishes, restores or changes the
+production pointer. Changed production, lost administrator access and pending
+runtime mutations block verification. Exit 2 retains a safe failure stage/code
+and available expected/observed deployment fingerprints. Original workflow
+results remain historical; merge status separately reads verified activation
+evidence. `currentlyServing` describes current selection, not a passed health
+check. Do not replay a publication to repair incomplete verification.
+
 Verify final state and actual live composition, same-origin authenticated APIs and relevant generated/custom hostnames. Retained artifacts, preview readiness, stale UI toasts or HTML success are insufficient. Running workflows can retain old definitions and service contracts; code rollback does not cancel them.

package/skill/{tender-accounts → andeo}/references/skills.md

@@ -34,5 +34,6 @@ Reads are session-only. The CLI does not install these skills in a repository or
 | `recharge-customer-operations` | Subscription, charge, bundle, cancellation, reactivation, gifting, profile, benefit, and verification workflows. |
 | `shopify-customer-account` | Customer Account API work and routing into Shopify's maintained AI Toolkit skills. |
 | `guardrailed-design-system` | Component-first React design systems with semantic tokens, typed components, Storybook, and enforceable boundaries. |
+| `andeo-guided-product-finder` | Storefront catalog analysis, Shopify CLI introspection and metafield enrichment, and deterministic recommendation quizzes, bundles, and subscription swaps before optional AI. |
 
 Read the entrypoint first. Use `skills file` only for references linked by that entrypoint and relevant to the current work.

package/skill/publication.json

@@ -1,3 +1,3 @@
 {
-  "minimumCliVersion": "0.19.19"
+  "minimumCliVersion": "0.19.21"
 }