@withandeo/cli 0.11.0 → 0.13.0

package/skill/tender-accounts/SKILL.md

@@ -1,402 +1,74 @@
 ---
 name: andeo
-description: Create, build, validate, and preview merchant-owned Andeo applications with the project-scoped CLI. Use when starting a new customer account, changing a repository that contains tender-accounts.json, implementing a customer-account feature, diagnosing an Andeo preview, or preparing an exact preview for review.
+description: Build, preview, diagnose and operate merchant-owned Andeo apps with the project-scoped CLI. Use for repositories containing tender-accounts.json, app workflows, storage, secrets, service bindings, domains, managed source and exact release recovery.
 ---
 
-# Andeo application delivery
+# Andeo applications
 
-The product name is **Andeo**. In customer-facing copy, describe sign-in, organization membership, app access, and application storage without naming infrastructure providers. Keep exact technical identifiers in executable code and configuration, and name merchant integrations when they explain the feature.
+Use `npx @withandeo/cli` as the merchant platform interface. Keep merchant behavior in merchant source and provider credentials/customer authorization server-side. Use Andeo in customer-facing copy; retain existing technical identifiers and configuration schemas.
 
-Use the `andeo` CLI (`npx @withandeo/cli`) as the only platform interface. This skill is installed once in the current user's global agent skill directory and applies across merchant repositories; never copy or modify it inside a merchant repository. Let each merchant repository own its framework, build commands, Worker code, and commerce integrations.
+## Discover scope before acting
 
-## Start a new application only when requested
+1. Read the closest `AGENTS.md` and `tender-accounts.json`. Identify the independently deployable app: portal, gateway or private service. Do not assume every app uses the starter layout.
+2. Run `andeo doctor --json` in that app directory. Stop on failed configuration, authentication, linking or project-access checks; follow remediation rather than calling internal APIs.
+3. Run `andeo capabilities --json` before introducing a platform capability. Separate platform support, account enablement/quota and caller permission. Unknown information is not permission. Discovery is advisory; deployment authorization remains authoritative.
+4. Read only the relevant references below. Use `andeo docs` to list bundled topics or `andeo docs workflows --json` for version-matched offline guidance. Use `<command> --help` for exact syntax.
 
-When the user asked for a new Shopify customer-account repository and the target is empty, inspect the exact plan and then create the optional starter:
+| Task | Required reference |
+| --- | --- |
+| Sign in, select a profile, link an app | [Authentication](references/authentication.md) |
+| Pull managed source; branch, review or land | [Managed source](references/managed-source.md) |
+| Build, upload, preview, reopen or retry | [Delivery](references/delivery.md) |
+| Define or operate background work | [Workflows](references/workflows.md) |
+| Public configuration or private tokens | [Configuration and secrets](references/configuration-secrets.md) |
+| Declare resources or evolve app-owned state | [Storage](references/storage.md) |
+| Connect private apps or workflow services | [Services](references/services.md) |
+| 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) |
 
-```sh
-npx @withandeo/cli init --name "Merchant customer account" --directory ./merchant-account --dry-run --json
-npx @withandeo/cli init --name "Merchant customer account" --directory ./merchant-account --json
-```
-
-Never run `init` inside an existing application or use it to replace a merchant's architecture. It creates a stable gateway and independently editable `apps/portal`. UI-only tasks stay in the portal; authentication, sessions, application data, confidential bindings, and protected APIs stay in the gateway. The command deliberately does not install dependencies, initialize Git, link projects, or deploy.
-
-## Materialize an existing app before scope discovery
-
-If the user gives an exact `prj_...` but the current workspace is empty, do not
-ask them to open a repository before asking Andeo which managed source belongs
-to that project. Install this skill, authenticate to the exact project, then run:
-
-```sh
-npx @withandeo/cli auth create prj_... --device --project prj_... --json
-# After approval:
-npx @withandeo/cli auth status --profile prj_... --json
-npx @withandeo/cli auth activate prj_... --json
-npx @withandeo/cli source status --project prj_... --json
-npx @withandeo/cli source pull --project prj_... --json
-```
-
-`source pull` uses standard Git. In an empty directory it clones the exact
-connected Andeo-managed repository; in an existing clean matching checkout it
-performs a fast-forward-only pull. It then writes the machine-local project link
-for the configured app. The short-lived repository credential exists only in
-the Git child process and is never stored in the remote URL, repository, CLI
-output, or shell history.
-
-The command refuses non-empty non-Git directories, dirty worktrees, detached
-HEADs, mismatched remotes, paused sources, conflicting project links, and unsafe
-managed working directories. Do not work around those checks with `source
-connect`, a hand-written remote, or a copied token. If the project uses
-merchant-hosted Git instead of Andeo-managed Git, open that exact checkout and
-continue with `link`; Andeo cannot clone a private third-party repository with
-a managed-source credential.
-
-## Start every task with scope discovery
-
-1. After the checkout exists, read the closest `AGENTS.md` files and `tender-accounts.json`. In a generated two-service repository, identify whether the request belongs to `apps/portal` or `apps/gateway` before editing.
-2. Run:
-
-   ```sh
-   npx @withandeo/cli doctor --json
-   ```
-
-3. Stop if configuration, authentication, linking, or project access fails. Report the exact error code and remediation. Never bypass the CLI with direct API calls.
-4. Confirm the linked project is the application the user requested. Use `--cwd apps/portal` or `--cwd apps/gateway` from a generated repository. Do not edit a gateway, service, or portal outside the current repository and credential scope.
-
-If authentication is missing, start the agent-safe device flow:
-
-```sh
-npx @withandeo/cli auth create <merchant-or-work-context> --device --no-open --json
-```
-
-Derive a stable lowercase profile from the merchant or work context; when the exact project ID is known, it is also a safe profile name and should be supplied as the `--project prj_...` authorization hint. Return the exact `verificationUrlComplete` and `userCode` to the user. Do not start another login while this request is pending. After the user approves the organization and exact apps in Andeo, resume the same request with:
-
-```sh
-<the exact profile-aware auth status command returned by auth create>
-```
-
-Then activate that profile from the repository root so it applies to every descendant app:
-
-```sh
-npx @withandeo/cli auth activate <merchant-or-work-context> --json
-```
-
-Multiple merchant profiles and their machine-local directory activations coexist outside the repository. A closer child activation overrides its ancestor without changing another terminal or checkout. Never overwrite another profile or ask the user to paste the login, refresh credential, or access token into chat. `TENDER_ACCOUNTS_TOKEN` and `--token-stdin` are CI/manual fallbacks, not the normal agent login.
-
-Never add `authProfile` to `.tender/link.json` or let repository content select a machine-local identity. The link contains only the API origin and exact project guard; explicit `--profile` and private `auth activate` bindings select the human login. Ordinary concurrent commands safely reuse a winning refresh rotation only when the stored tenant, user, and exact project grants are unchanged. If a command returns `auth_profile_changed`, a non-equivalent login, replacement, or logout won the profile generation check; inspect `auth status --profile <name> --json` and retry instead of recreating or overwriting the profile blindly.
-
-If profile selection is ambiguous, inspect only the non-secret local inventory and retry explicitly:
-
-```sh
-npx @withandeo/cli auth list --json
-npx @withandeo/cli auth status --profile <name> --json
-```
-
-If the app has not been linked, run:
-
-```sh
-npx @withandeo/cli link --json
-```
-
-When one profile grants multiple projects, select the intended project once with `--project`; `link` records only the API origin and exact project guard. Profile activation remains machine-local.
-
-If the merchant wants Andeo to own the Git transport, use the CLI for either
-the linked gateway or service project:
-
-```sh
-npx @withandeo/cli source connect --publication preview-only --json
-npx @withandeo/cli source status --json
-npx @withandeo/cli source pull --json
-npx @withandeo/cli source push --json
-```
-
-Run these commands from the independently deployable app directory, or use its
-exact `--cwd`. `source connect` derives the project working directory and build
-contract from Git plus `tender-accounts.json`; do not recreate that contract by
-hand in the admin. Protected gateways must stay `preview-only`. Use
-`--publication default-branch` only for an ordinary service when the merchant
-explicitly wants successful default-branch previews promoted automatically.
-
-`source push` includes only the committed revision. On a reviewed repository it
-uploads a bounded Git bundle through Andeo; the trusted runner verifies the
-exact commit and may update only the named non-default branch. The developer
-never receives a provider write credential. On a repository that has not yet
-enabled reviewed changes, the legacy short-lived Git credential path remains
-available during migration. Never copy any credential into a remote URL,
-credential helper, repository file, shell script, or chat. `source pull` is the
-inverse operation for an already connected repository and never creates or
-replaces the source connection. `source token` is read-only.
-
-When `source status` reports `changeRequestProtection: enabled`, use the normal
-reviewed flow:
-
-```sh
-npx @withandeo/cli source push --branch feature/account-copy --json
-npx @withandeo/cli source change create \
-  --head feature/account-copy \
-  --title "Update account copy" --json
-npx @withandeo/cli source change show --change scr_... --json
-```
-
-Return the `scr_` ID and exact preview state to the user. A developer or coding
-agent stops after the exact preview is ready. Approval and **Land in main** are
-merchant-administrator actions in Andeo. Do not push the default branch,
-obtain a raw provider token, call internal APIs, or replace this flow with
-`source promote` after reviewed changes are enabled.
-
-After a successful landing, inspect `branchCleanup` in
-`source change show --change scr_... --json`. `requested` and `running` need no
-developer action. `succeeded` means the exact landed feature ref was deleted or
-already absent. `retained` means Andeo deliberately kept a moved, reused, or
-otherwise unsafe ref. `failed` does not undo landing; ask a merchant
-administrator to retry cleanup in Andeo. Never obtain a provider write token
-or delete the branch directly. All immutable build, release, composition,
-approval, landing, and audit records remain available after cleanup.
-Do not reuse the same feature branch or make it the default while cleanup is
-`requested`, `running`, or retryable: Andeo deliberately fences that ref until
-cleanup succeeds, retains it, or exhausts its bounded retry budget.
-
-Inspect branches and history through read-only ephemeral credentials:
-
-```sh
-npx @withandeo/cli source branches --json
-npx @withandeo/cli source log --branch main --limit 20 --json
-npx @withandeo/cli source compare --base main --head feature/account-copy --json
-```
-
-Use standalone source-administration commands only for repositories where
-reviewed changes are not enabled and when the user explicitly requests a
-default-branch or history change and the active profile belongs to a merchant
-source administrator. First record `source branches`, `source compare`, the
-successful exact preview for the proposed head, and the current production
-composition. Run the exact operation with `--dry-run` before applying it.
-
-For an ordinary checked fast-forward, supply the current target SHA and a
-stable idempotency key:
-
-```sh
-npx @withandeo/cli source promote \
-  --head feature/account-copy \
-  --expected-current <exact-current-default-sha> \
-  --idempotency-key account-copy-v1 \
-  --dry-run --json
-```
-
-For an exceptional migration, use only the guarded history workflow:
-
-```sh
-npx @withandeo/cli source history replace \
-  --head app-only-main \
-  --expected-current <exact-current-default-sha> \
-  --confirm <exact-src-repository-id> \
-  --idempotency-key app-only-history-v1 \
-  --dry-run --json
-```
-
-Inspect the returned `sop_` operation with `source operation status`. Apply the
-same request without `--dry-run` only after the dry-run evidence matches the
-intended repository, project, branches, SHA, preview build, and composition.
-Never substitute a raw token, direct API, Git force push, ref deletion, or database
-edit. Andeo creates and verifies an archive before history replacement and
-uses an expected-SHA compare-and-swap for the target. History migration always
-suppresses automatic production publication; protected gateways always remain
-preview-only.
-
-If a durable source operation fails for a transient provider or runner reason,
-inspect and resume that same reviewed intent by ID:
-
-```sh
-npx @withandeo/cli source operation status --operation sop_... --json
-npx @withandeo/cli source operation retry --operation sop_... --json
-```
-
-Do not create a replacement request merely to retry infrastructure. A stale
-target, missing preview, archive conflict, or rejected permission requires the
-stated remediation and a newly reviewed request instead.
-
-For reviewed repositories, a moved head invalidates the previous approval and
-the newest source build becomes the next exact snapshot. A moved base makes the
-change stale. Rebase or update the feature branch, push a new committed
-revision, wait for its exact preview, and have the administrator review that
-new snapshot. Source landing never calls the production publisher directly;
-after landing, the repository's already configured default-branch policy may
-publish the same successful exact preview. Protected gateways remain
-preview-only.
-
-Treat source administration and production publication as different acts. A
-source operation may create a new immutable preview lineage, but only the
-merchant's established exact-composition control can publish production. For a
-portal and gateway changed together, preview both immutable revisions and
-review the sealed combined composition; do not pretend two repository refs can
-be changed atomically or publish whatever happens to be on each default branch.
-
-## Build the requested portal as one customer journey
-
-Before editing, turn the request into a small delivery contract:
-
-- the customer journeys and states that must work;
-- the source of truth for each read and mutation;
-- the existing same-origin gateway routes that already satisfy it;
-- whether the change is portal-only or also requires gateway code, bindings, runtime configuration, or a newly approved provider;
-- the signed-out, signed-in, empty, failure, desktop, and mobile states that materially affect the request.
-
-Inspect the merchant's current storefront or portal, repository, existing API clients, and supplied tickets or wishlist before inventing a new information architecture. Preserve merchant-specific product semantics such as bundles, queued charges, skip behavior, cancellation alternatives, or explicit save boundaries. Do not turn a visual mock into a claim that a provider mutation works.
-
-Use the smallest correct application slice:
-
-- **Portal only:** presentation, interaction, accessibility, responsive behavior, or a feature already supported by existing same-origin routes.
-- **Portal and gateway:** a new authenticated read or mutation, Shopify Customer Account query, provider integration, application database state, runtime variable, resource, service, or security policy.
-- **Gateway only:** authentication, session, route, provider, binding, or runtime-policy work with no visual change.
-
-A portal release cannot add a gateway API contract. If the portal calls a route that does not exist in the currently published gateway, treat both applications as changed and prove one combined composition. Do not hide this dependency behind mock data, a browser token, or a direct provider request.
-
-For every new authenticated route:
-
-1. Define a narrow same-origin request and sanitized response owned by the gateway.
-2. Authenticate the Andeo shopper session and authorize the requested customer resource server-side.
-3. Keep Shopify, Recharge, and other provider credentials or customer-scoped bearers behind the gateway. The gateway may call an explicitly approved provider directly; it does not need a separate Andeo App solely for outbound egress.
-4. Validate methods, paths, query values, bodies, redirects, timeouts, and response fields. Never proxy an arbitrary provider URL.
-5. Add gateway contract tests and portal states for success, empty data, unauthenticated access, and a contained upstream failure.
-
-Render the useful shell immediately. Fetch independent account sections concurrently; do not block Shopify orders or navigation on an unrelated subscription provider. Each section owns its loading, timeout, empty, and error state. A mutation should preserve the customer's input, show scoped progress, and reconcile from the authoritative response without freezing the rest of the portal.
-
-## Implement and validate
-
-1. Inspect the existing application and tests before changing code.
-2. Use the repository's own development workflow. `npx @withandeo/cli dev` delegates to the committed `commands.dev`, starts local development, and never creates an Andeo deployment.
-3. Make the smallest source change that satisfies the request.
-4. Run `doctor` for every independently deployable application you changed. In a generated repository:
-
-   ```sh
-   npx @withandeo/cli doctor --cwd apps/portal --json
-   npx @withandeo/cli doctor --cwd apps/gateway --json
-   ```
-
-   Do not require gateway access for a portal-only task. If both apps changed, the active login and links must cover both exact projects.
-5. Run the deterministic repository checks:
-
-   ```sh
-   npx @withandeo/cli check --json
-   ```
-
-6. Validate the complete portable artifact without uploading it:
-
-   ```sh
-   npx @withandeo/cli preview --dry-run --json
-   ```
-
-Do not weaken checks, remove declared bindings, or place runtime values in the artifact to make validation pass.
-
-## Retain a local build for administrator publication
-
-When the user requests the manual build path, use `andeo upload --dry-run --json`
-and then `andeo upload --json`. This runs the repository checks and packaging,
-verifies and retains the artifact, and returns its exact release ID and digest.
-It does not create a preview runtime or publish production. An administrator
-reviews the artifact in **Changes → Publish a retained artifact** and approves
-publication explicitly. Local builds do not require a GitHub run for this
-manual path; their source labels remain unverified. The CLI cannot approve
-publication, and automatic source publication still requires trusted main
-evidence. Continue to honor explicit production approval from the user.
+## Materialize the right app
 
-## Create an exact preview
+For an existing exact project and empty workspace, authenticate to that project, then use `andeo source status --project prj_... --json` and `andeo source pull --project prj_... --json`. Read the managed-source reference first. Do not create a replacement repository or source connection. Merchant-hosted Git uses its existing checkout and `andeo link --project prj_... --json` instead.
 
-After local validation succeeds, preview each changed application. For a portal-only change, run:
+Only create a new application when requested:
 
 ```sh
-npx @withandeo/cli preview --cwd apps/portal --json
+andeo init --name "Merchant customer account" --directory ./merchant-account --dry-run --json
+andeo init --name "Merchant customer account" --directory ./merchant-account --json
 ```
 
-For a new account stack or a change spanning both apps, package and preview the portal and gateway as separate projects:
+Never initialize over an existing app. The starter does not install dependencies, authenticate, link projects or deploy.
 
-```sh
-npx @withandeo/cli preview --cwd apps/portal --json
-npx @withandeo/cli preview --cwd apps/gateway --json
-```
-
-On the first stack preview, the first command may retain its exact release and return `bootstrap_counterpart_release_missing`. This is an expected incomplete stack, not permission to change IDs or bypass Andeo: build the named counterpart once, then rerun the failed side only if the second command did not already seal the composition. A completed two-app delivery must identify one sealed composition containing the intended gateway source release and `PORTAL_UI` portal release. Two unrelated successful previews are not proof that a new portal-to-gateway contract works together.
-
-Treat stdout as one machine-readable JSON object. Preserve and report:
-
-- `previewUrl`;
-- `deliveryId`;
-- `releaseId`;
-- `bundleDigest`;
-- `compositionId` when the delivery sealed one;
-- validation performed before delivery.
-
-The CLI may label an uncommitted local preview with a `local-...` source revision. The immutable bundle digest remains the content identity. Do not claim the change is committed or pushed unless separately verified.
-
-## Prove the customer journey
-
-Local development proves layout and explicitly local behavior; it intentionally stays signed out for the generated Shopify starter. Real Shopify sign-in must be tested on an immutable HTTPS Andeo preview.
-
-Inspect the actual rendered application, not only an HTTP `200` or deployment result. For the requested journey:
-
-- verify `/api/bootstrap`, `/api/session`, and every new same-origin route on the exact preview;
-- prove signed-out and signed-in behavior without reading or exposing tokens;
-- exercise the requested read or mutation and confirm the authoritative response is reflected in the UI;
-- verify a relevant empty or non-subscriber state and a contained provider failure;
-- inspect desktop and 390 x 844 mobile behavior, including keyboard focus and pending/saved feedback.
-
-If the portal shell works but an authenticated route returns `404`, classify it as gateway release or composition evidence. Do not repair it with client-side fallback data. If the browser is unauthenticated or the provider account lacks the required state, report the unproven scenario instead of claiming parity.
-
-## Diagnose a delivery
-
-Read exact workflow state:
-
-```sh
-npx @withandeo/cli delivery status --delivery <delivery-id> --json
-```
-
-Retry only a requested or failed preview workflow:
+## Define the smallest delivery contract
 
-```sh
-npx @withandeo/cli delivery retry --delivery <delivery-id> --json
-```
+- Identify customer journeys and loading, empty, signed-out, success and failure states.
+- Name the source of truth for each read/mutation. Keep merchant providers authoritative for business data; reserve application storage for app-owned state.
+- Reuse same-origin gateway APIs. Portal-only changes must not rebuild the gateway. New APIs, confidential integrations, resources and bindings require gateway/service scope.
+- Authorize customer resources server-side. Validate methods, inputs, origins, destinations, redirects and timeouts. Never proxy arbitrary URLs or expose credentials to the browser.
+- Render independent sections independently. Preserve customer input on failure and reconcile uncertain provider outcomes instead of blindly repeating mutations.
+- Keep merchant policy in app adapters; avoid speculative shared modules or a platform dependency on merchant source.
 
-Mint a new browser session for an already-succeeded delivery without rebuilding:
+## Deliver and prove
 
-```sh
-npx @withandeo/cli preview entries --json
-npx @withandeo/cli preview open --from <delivery-id> --json
-npx @withandeo/cli preview open --from sbl_EXAMPLE --return-path /account --json
-```
+Read the delivery reference for commands and recovery. Run app checks and artifact dry-run before delivery. Preserve exact source, digest, release, delivery and composition identities.
 
-Preview entry selection follows published app connections automatically. When the response requires a choice, select an eligible app using `--through prj_ENTRY`. Only the previewed app's developer grant is needed. Private apps cannot open directly; a connection administrator must enable an eligible entry. Preserve the exact `from` ID when recovering from a session error and use `preview open` instead of rebuilding. Opening replaces the browser's previous preview selection and preserves sign-in.
+Distinguish local check, retained upload, ready preview, administrator approval, production activation and live acceptance. None substitutes for the next. Prove the intended combined composition for connected changes, not two unrelated releases.
 
-`<delivery-id>` is the `dly_` value returned by `preview`. A `dwf_` value is a production workflow ID and must not be passed to developer-delivery commands. If a merchant administrator sees a `dwf_` publish waiting with zero attempts, the supported recovery is **Activity → Resume exact publish**; it resumes the stored exact composition without rebuilding. Use the error code, request ID, and suggested command from the CLI. Do not retry with altered IDs, another project, or raw HTTP requests.
+Verify rendered behavior and authenticated APIs, not just HTTP 200. Exercise the requested mutation, reconcile its authoritative result and reload to prove persistence. A workflow start is not completion: inspect status/history and the business effect. Check generated/custom domains after routing or auth changes. Perform relevant mobile and keyboard checks for UI changes.
 
-When runtime evidence is needed, stream only the linked project and exact target:
-
-```sh
-npx @withandeo/cli tail --delivery <delivery-id> --status error --json
-```
-
-Use `--production` only when the user is a merchant administrator and explicitly wants current production diagnostics. Tail output is sensitive even though Andeo omits request headers and redacts known secret fields. Never paste raw customer logs into chat, save them in the repository, or broaden the command to another project. Stop the stream as soon as the diagnostic is complete.
-
-## Finish with a one-shot handoff
-
-Report one compact result containing:
-
-- customer journeys implemented and deliberately out of scope;
-- portal-only, gateway-only, or combined scope and the data authority for each new route;
-- checks and dry runs for every changed app;
-- exact preview URL, `deliveryId`, `releaseId`, `bundleDigest`, and combined `compositionId` when applicable;
-- signed-out, signed-in, relevant empty/failure, desktop, and mobile proof actually completed;
-- remaining merchant-admin actions such as Shopify callback/origin registration, runtime configuration, initial production bootstrap, or exact publication.
-
-Do not describe an admin-only prerequisite as completed, and do not publish, merge, commit, or push unless the user separately requested that action.
+Production publication stays with the protected policy or authenticated administrator console; no CLI publish command exists. Commit, push, merge, publish and destructive operations require user authorization. Read-only discovery never grants mutation authority.
 
 ## Hard boundaries
 
-- Never bypass Andeo delivery by deploying directly or using underlying infrastructure credentials.
-- Never call Andeo internal APIs with `curl` or custom scripts.
-- Never print, read back, commit, or copy `.dev.vars`, CLI login, refresh, or access-token values.
-- Never put Shopify, subscription-provider, or other merchant credentials in source, build output, logs, or screenshots.
-- Never claim the log relay can redact a credential that merchant code writes as an unlabelled string; application logging must avoid customer data and secrets.
-- Never change `.tender/link.json` by hand; use `andeo link`.
-- Never publish production from an agent credential. The CLI intentionally has no publish command.
-- Never expand project scope. Ask a merchant administrator for a different credential when the requested app is outside the current grant.
-- Never treat a successful preview as a production release, merge, commit, or push.
+- Never bypass Andeo delivery with direct provider deployment, raw internal APIs, ledger edits or provider credentials.
+- Never print, read back, commit or copy `.dev.vars`, CLI credentials, refresh tokens, customer cookies or provider secrets. Use declared bindings and write-only administrator controls.
+- Never edit `.tender/link.json` by hand or let repository files select a local authentication profile.
+- Never silently remove declarations or weaken authorization to pass deployment.
+- Never infer support from a Cloudflare feature, emulator, entitlement switch or successful upload. Require documented support and scoped hosted proof.
+- 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.
+
+## Finish with exact evidence
 
-Production moves only through the merchant's protected default-branch policy or an authenticated merchant administrator in the Andeo console.
+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/references/authentication.md

@@ -0,0 +1,38 @@
+# Authentication and project scope
+
+If authentication is missing, start the agent-safe device flow:
+
+```sh
+npx @withandeo/cli auth create <merchant-or-work-context> --device --no-open --json
+```
+
+Derive a stable lowercase profile from the merchant or work context; when the exact project ID is known, it is also a safe profile name and should be supplied as the `--project prj_...` authorization hint. Return the exact `verificationUrlComplete` and `userCode` to the user. Do not start another login while this request is pending. After the user approves the organization and exact apps in Andeo, resume the same request with:
+
+```sh
+<the exact profile-aware auth status command returned by auth create>
+```
+
+Then activate that profile from the repository root so it applies to every descendant app:
+
+```sh
+npx @withandeo/cli auth activate <merchant-or-work-context> --json
+```
+
+Multiple merchant profiles and their machine-local directory activations coexist outside the repository. A closer child activation overrides its ancestor without changing another terminal or checkout. Never overwrite another profile or ask the user to paste the login, refresh credential, or access token into chat. `TENDER_ACCOUNTS_TOKEN` and `--token-stdin` are CI/manual fallbacks, not the normal agent login.
+
+Never add `authProfile` to `.tender/link.json` or let repository content select a machine-local identity. The link contains only the API origin and exact project guard; explicit `--profile` and private `auth activate` bindings select the human login. Ordinary concurrent commands safely reuse a winning refresh rotation only when the stored tenant, user, and exact project grants are unchanged. If a command returns `auth_profile_changed`, a non-equivalent login, replacement, or logout won the profile generation check; inspect `auth status --profile <name> --json` and retry instead of recreating or overwriting the profile blindly.
+
+If profile selection is ambiguous, inspect only the non-secret local inventory and retry explicitly:
+
+```sh
+npx @withandeo/cli auth list --json
+npx @withandeo/cli auth status --profile <name> --json
+```
+
+If the app has not been linked, run:
+
+```sh
+npx @withandeo/cli link --json
+```
+
+When one profile grants multiple projects, select the intended project once with `--project`; `link` records only the API origin and exact project guard. Profile activation remains machine-local.

package/skill/tender-accounts/references/configuration-secrets.md

@@ -0,0 +1,9 @@
+# Configuration and secrets
+
+Declare public values in the portable artifact's `vars` and native secret names in `secrets`. Public values are retained with artifacts: never place a private token there. Keep local values in ignored environment files without reading or printing credentials in agent output.
+
+Use Settings → Secrets through the signed-in administrator to create/rotate declared secrets. Values are write-only. Native app secrets use the same value in preview and production and require shared-preview mode; independent secret-bearing previews are unsupported. Do not promise per-environment values from legacy documentation.
+
+Public configuration changes require a new artifact and approved publication. Secret setup is a separate administrator operation. Verify applied state on required targets; never copy tokens between apps. Workflow code receives public string vars and scoped services, not native secrets. Keep token-backed calls in a connected service and pass only non-secret business inputs/results through workflows.
+
+Inspect desired/applied revisions rather than revealing values. Uncertain writes block later mutations; use supported status/readback recovery, never blind repeated rotation. Code rollback does not restore old secret values. Do not delete a secret required by serving code. Verify authorized operation, signed-out denial and sanitized errors without exposing credentials.

package/skill/tender-accounts/references/delivery.md

@@ -0,0 +1,125 @@
+# Build, preview and publish
+
+## Implement and validate
+
+1. Inspect the existing application and tests before changing code.
+2. Use the repository's own development workflow. `npx @withandeo/cli dev` delegates to the committed `commands.dev`, starts local development, and never creates an Andeo deployment.
+3. Make the smallest source change that satisfies the request.
+4. Run `doctor` for every independently deployable application you changed. In a generated repository:
+
+   ```sh
+   npx @withandeo/cli doctor --cwd apps/portal --json
+   npx @withandeo/cli doctor --cwd apps/gateway --json
+   ```
+
+   Do not require gateway access for a portal-only task. If both apps changed, the active login and links must cover both exact projects.
+5. Run the deterministic repository checks:
+
+   ```sh
+   npx @withandeo/cli check --json
+   ```
+
+6. Validate the complete portable artifact without uploading it:
+
+   ```sh
+   npx @withandeo/cli preview --dry-run --json
+   ```
+
+Do not weaken checks, remove declared bindings, or place runtime values in the artifact to make validation pass.
+
+## Retain a local build for administrator publication
+
+When the user requests the manual build path, use `andeo upload --dry-run --json`
+and then `andeo upload --json`. This runs the repository checks and packaging,
+verifies and retains the artifact, and returns its exact release ID and digest.
+It does not create a preview runtime or publish production. An administrator
+reviews the artifact in **Changes → Publish a retained artifact** and approves
+publication explicitly. Local builds do not require a GitHub run for this
+manual path; their source labels remain unverified. The CLI cannot approve
+publication, and automatic source publication still requires trusted main
+evidence. Continue to honor explicit production approval from the user.
+
+## Create an exact preview
+
+After local validation succeeds, preview each changed application. For a portal-only change, run:
+
+```sh
+npx @withandeo/cli preview --cwd apps/portal --json
+```
+
+For a new account stack or a change spanning both apps, package and preview the portal and gateway as separate projects:
+
+```sh
+npx @withandeo/cli preview --cwd apps/portal --json
+npx @withandeo/cli preview --cwd apps/gateway --json
+```
+
+On the first stack preview, the first command may retain its exact release and return `bootstrap_counterpart_release_missing`. This is an expected incomplete stack, not permission to change IDs or bypass Andeo: build the named counterpart once, then rerun the failed side only if the second command did not already seal the composition. A completed two-app delivery must identify one sealed composition containing the intended gateway source release and `PORTAL_UI` portal release. Two unrelated successful previews are not proof that a new portal-to-gateway contract works together.
+
+Treat stdout as one machine-readable JSON object. Preserve and report:
+
+- `previewUrl`;
+- `deliveryId`;
+- `releaseId`;
+- `bundleDigest`;
+- `compositionId` when the delivery sealed one;
+- validation performed before delivery.
+
+The CLI may label an uncommitted local preview with a `local-...` source revision. The immutable bundle digest remains the content identity. Do not claim the change is committed or pushed unless separately verified.
+
+## Prove the customer journey
+
+Local development proves layout and explicitly local behavior; it intentionally stays signed out for the generated Shopify starter. Real Shopify sign-in must be tested on an immutable HTTPS Andeo preview.
+
+Inspect the actual rendered application, not only an HTTP `200` or deployment result. For the requested journey:
+
+- verify `/api/bootstrap`, `/api/session`, and every new same-origin route on the exact preview;
+- prove signed-out and signed-in behavior without reading or exposing tokens;
+- exercise the requested read or mutation and confirm the authoritative response is reflected in the UI;
+- verify a relevant empty or non-subscriber state and a contained provider failure;
+- inspect desktop and 390 x 844 mobile behavior, including keyboard focus and pending/saved feedback.
+
+If the portal shell works but an authenticated route returns `404`, classify it as gateway release or composition evidence. Do not repair it with client-side fallback data. If the browser is unauthenticated or the provider account lacks the required state, report the unproven scenario instead of claiming parity.
+
+## Diagnose a delivery
+
+Read exact workflow state:
+
+```sh
+npx @withandeo/cli delivery status --delivery <delivery-id> --json
+```
+
+Retry only a requested or failed preview workflow:
+
+```sh
+npx @withandeo/cli delivery retry --delivery <delivery-id> --json
+```
+
+CLI 0.12.0 carries artifact/delivery access across automatic token refresh within
+the same login. Logout, session expiry, or revoked owner/project access still
+stop background work. For a pre-session-tracking preview stranded by an expired
+credential, only its original owner may explicitly recover it from the linked
+app with `delivery retry --delivery <delivery-id> --reauthorize --json`. This
+requires current developer access, retains the exact artifact and upload
+receipts, and cannot replace an already tracked login or publish production.
+Do not clear pending provider holds or rewrite credential IDs to recover work.
+
+Mint a new browser session for an already-succeeded delivery without rebuilding:
+
+```sh
+npx @withandeo/cli preview entries --json
+npx @withandeo/cli preview open --from <delivery-id> --json
+npx @withandeo/cli preview open --from sbl_EXAMPLE --return-path /account --json
+```
+
+Preview entry selection follows published app connections automatically. When the response requires a choice, select an eligible app using `--through prj_ENTRY`. Only the previewed app's developer grant is needed. Private apps cannot open directly; a connection administrator must enable an eligible entry. Preserve the exact `from` ID when recovering from a session error and use `preview open` instead of rebuilding. Opening replaces the browser's previous preview selection and preserves sign-in.
+
+`<delivery-id>` is the `dly_` value returned by `preview`. A `dwf_` value is a production workflow ID and must not be passed to developer-delivery commands. If a merchant administrator sees a `dwf_` publish waiting with zero attempts, the supported recovery is **Activity → Resume exact publish**; it resumes the stored exact composition without rebuilding. Use the error code, request ID, and suggested command from the CLI. Do not retry with altered IDs, another project, or raw HTTP requests.
+
+When runtime evidence is needed, stream only the linked project and exact target:
+
+```sh
+npx @withandeo/cli tail --delivery <delivery-id> --status error --json
+```
+
+Use `--production` only when the user is a merchant administrator and explicitly wants current production diagnostics. Tail output is sensitive even though Andeo omits request headers and redacts known secret fields. Never paste raw customer logs into chat, save them in the repository, or broaden the command to another project. Stop the stream as soon as the diagnostic is complete.