@withandeo/cli 0.19.6 → 0.19.8

package/package.json

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

package/skill/tender-accounts/SKILL.md

@@ -67,6 +67,18 @@ Never initialize over an existing app. The starter does not install dependencies
 
 ## Deliver and prove
 
+When pushing from GitButler or a checkout whose HEAD is not the intended source,
+read the managed-source reference and select the normal branch or exact commit:
+`andeo source push --source chore/andeo-agent-guidance --branch DESTINATION --json`.
+The source defaults to HEAD; the destination remains independent. Confirm the
+returned `sourceRevision` and `sourceDiffersFromHead`. Dirty files are excluded,
+and reviewed repositories still protect their default branch.
+
+For a protected managed repository, read the managed-source reference and use
+`andeo source merge --head BRANCH --title TITLE --expected-head PUSHED_SHA --idempotency-key KEY --wait --json`
+to request hosted landing and follow the saved publication policy. Inspect required
+human review, deployment and cleanup outcomes separately; do not push main to bypass them.
+
 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.
 
 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.

package/skill/tender-accounts/references/managed-source.md

@@ -1,5 +1,55 @@
 # Managed source
 
+## Request merge and deployment
+
+On a protected repository, push the committed feature branch, then request one
+exact hosted merge. Read `capabilities` and `source merge-policy show` first.
+
+```sh
+andeo source push --branch feat/account-copy --json
+andeo source merge --head feat/account-copy --title "Update account copy" \
+  --expected-head <sourceRevision-from-push> --idempotency-key account-copy-v1 \
+  --wait --json
+andeo source change show --change scr_... --json
+```
+
+Andeo pins the feature and default SHAs, validates the exact preview, lands using
+an expected-SHA fast-forward operation, and follows the saved publication policy.
+A diverged branch returns `update_required`: update the feature branch, push,
+and review a new snapshot. The command does not integrate Git in the local checkout.
+Use `--change scr_...` instead of `--head` and `--title` to attach to an existing
+review; `--expected-snapshot N` pins the inspected snapshot.
+
+Human review remains the default. A merchant administrator may explicitly grant
+stable principal IDs with `source merge-policy set --mode agent --principals IDS
+--expected-revision N --idempotency-key KEY [--execution-seconds 300..86400]`.
+Changed validation/dependency inputs and artifact capabilities still require
+review. Merge policy and default-branch publication policy are separate grants.
+Preview-only publication returns `publication_not_enabled` after successful landing.
+
+Reuse the original idempotency key after a lost acknowledgement. Waiting defaults
+to no wait; `--wait --timeout-seconds N` is bounded (maximum one hour). Exit 2 means
+required action or an unsuccessful outcome; exit 3 means waiting timed out while
+hosted execution continues. Exit 0 without waiting means accepted, so inspect
+`merge.stage`. Source, publication and cleanup are separate outcomes. `deployed`
+requires verified production activation; `currentlyServing` compares the current
+production head. Runtime health is reported separately as unknown.
+
+`source change resume --change scr_...` resumes the same eligible source operation
+or publication checkpoint; it cannot manufacture a new build or clear uncertain
+provider effects. Normal token expiry/rotation preserves the bounded execution
+grant. Explicit revocation, lost owner access, changed policy/inputs or expiry
+block new effects. An administrator can use `source change take-over --change
+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.
+
+An authorized production restore pauses automatic activation and invalidates old
+queued work. `source policy show` reports `automaticPaused` and `environmentEpoch`.
+An administrator must explicitly save the publication policy to resume future
+automatic builds; historical requests cannot undo the restore. A superseded
+publication identifies its newer verified successor and must not be replayed.
+
 If the merchant wants Andeo to own the Git transport, use the CLI for either
 the linked gateway or service project:
 
@@ -15,6 +65,32 @@ 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. New connections default to preview-only. Both gateways and services support `--publication default-branch` when a merchant administrator explicitly enables automatic publication. For an existing connection use `source policy show`, then `source policy set --repository SRC_ID --publication default-branch --expected-revision N --idempotency-key KEY`. Saving the policy affects future source builds; it does not publish an existing build. Reconnecting never changes the policy.
 
+Select a local commit independently from the destination branch, including from a GitButler workspace:
+
+```sh
+andeo source push --source chore/andeo-agent-guidance --branch main --json
+```
+
+`--source` accepts a resolvable local branch, ref or commit SHA and defaults to `HEAD`.
+The CLI resolves it once to a full commit SHA; both the push and any reviewed
+bundle use that exact commit even if the local ref moves. `--branch` remains the
+remote destination and keeps its existing default (current checkout branch,
+or the repository default when detached); selecting `--source` does not change it.
+Always specify `--branch` from a GitButler workspace. Uncommitted, staged and
+untracked files are excluded. JSON reports `source`, `sourceRevision` and
+`sourceDiffersFromHead`; a different source uses that commit's tree and ancestry,
+not the current workspace. Invalid or non-commit sources fail before obtaining
+a repository credential.
+
+The example targeting `main` applies only to unprotected repositories. Reviewed
+repositories still require a non-default destination and administrator review;
+`--source` does not bypass protection or allow a force push. Explicit sources
+also work from detached HEAD; omitting `--source` preserves the existing reviewed
+detached-HEAD rejection. Legacy pushes retain normal non-fast-forward rejection
+and the existing guarded `--expected-current` rules. Reconnect seeding accepts
+`--source` with `--reconnection ID --branch NAME`, defaults to `HEAD`, and reports
+the resolved SHA for `source reconnect complete --expected-sha`.
+
 `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
@@ -165,7 +241,7 @@ andeo source push --reconnection RECONNECT_ID --branch main --json
 andeo source reconnect complete --reconnection RECONNECT_ID --expected-sha EXACT_DEFAULT_BRANCH_SHA --json
 ```
 
-Use the actual default branch instead of `main`. The push sends local `HEAD` to the explicit destination branch, without force and without changing your managed remote. Push any other required branches from the corresponding commits before completion. The commands do not assume your checkout contains every remote branch or tag.
+Use the actual default branch instead of `main`. The push sends local `HEAD` by default, or the exact commit selected by `--source REF_OR_COMMIT`, to the explicit destination branch, without force and without changing your managed remote. Push any other required branches using their corresponding `--source` refs before completion. The commands do not assume your checkout contains every remote branch or tag.
 
 Preparation pauses the old connection and revokes its write credentials; deployed production continues serving. The destination is not a connected source while it is being seeded, so seed events do not build or publish. Reviewed repositories use this administrator-only seeding path too.