# Confirmation and Preview Overview

Use this reference to choose the preview and confirmation path for every mutating `sup` invocation. Load [preview-and-dry-run.md](preview-and-dry-run.md) for preview mechanics and [confirmation-template.md](confirmation-template.md) for the operator-facing template.

## Required Steps

1. **Preview.** Use the native `--dry-run` flag where it exists: `sup sync run --dry-run`, `sup user push --dry-run`, `sup user invite --dry-run`. For `sup chart push` / `sup dashboard push` / `sup dataset push`, pull the current target state with the matching `sup ... pull` command and diff against the assets folder.
2. **Summarize.** Fill out the confirmation template from [confirmation-template.md](confirmation-template.md) with the preview results.
3. **Wait.** Pause for explicit user confirmation that names the target workspace by its human-readable name. If the run uses `--force` or `--overwrite`, the confirmation message must also contain the literal flag strings (`--force`, `--overwrite`).
4. **Execute.** Run the mutating command only after the confirmation is received.
5. **Record.** Log the preview summary, the user's confirmation, and the resulting `sup` exit code in a place that survives the agent session (PR description, ticket comment, run log).

## Always Dry-Run

Always preview before any mutating run. The native `--dry-run` flag is available on `sup sync run`, `sup user push`, and `sup user invite`; use it there. For `sup chart push`, `sup dashboard push`, and `sup dataset push`, use pull-and-diff. See [preview-and-dry-run.md](preview-and-dry-run.md).

## Audit-Log Expectations

Every mutating `sup` run leaves a trace in the target workspace's audit log. The agent should:

- Record the timestamp and operator before running.
- Capture the `sup` exit code afterward.
- Note where the corresponding audit log can be reviewed (the workspace audit log in Preset Manage, or the Management API audit endpoints).

## Chain to Safety Policy

After the confirmation template is shown and before the mutating run executes, load `preset-cli` and then `references/safety-policy.md` so the disclosure, confirmation, and rollback expectations are recorded against the CLI safety policy. This skill is for CLI workflows only; if the user wants direct HTTP mutations, route to the separate `preset-api-skills` package instead.

# CLI Mutation Confirmation Template

Use this template after previewing a mutating command and before execution.

```text
About to run a state-changing `sup` command.

  Operation:       <sup chart push | sup dashboard push | sup dataset push | sup user push | sup user invite | sup sync run>
  Source ws:       <name> (id: <id>)             # for sync; omit otherwise
  Target ws:       <name> (id: <id>)             # required
  Assets to push:  <count> charts, <count> dashboards, <count> datasets, <count> databases, <count> users, <count> invites
                   # include only the entity counts the operation actually touches.
                   # note: dataset push pushes referenced database connections first.
                   # note: sup user invite creates invite records; sup user push updates user records.
  Asset IDs/UUIDs: <comma-separated list or "see preview output above">
  Overwrite:       <yes / no>
  --force:         <yes / no>                    # skips interactive prompts inside sup (chart/dashboard/dataset push)
  Jinja context:   <env=production, region=us-east-1, ...>   # sync only
  Rollback plan:   <git revert + re-run | manual UI fix | snapshot restore | ...>
  Audit trail:     <PR/ticket/run-log location>

Preview output (native --dry-run for sync / user push / user invite, or pull-and-diff for chart/dashboard/dataset push):
<paste the preview output, redacted of any tokens or credentials>

To proceed, reply with the literal target workspace name: "<name>".
If this run uses --force or --overwrite, your reply MUST also contain the
literal flag string(s): "<--force>", "<--overwrite>", or both.
Reply anything else, or omit the workspace name or any required flag string,
to abort.
```

## Abort Triggers

Abort and do not execute when any of the following holds:

- The user did not type the exact target workspace name.
- The user's confirmation message does not contain the literal `--force` string when `--force` is part of the planned command, or does not contain the literal `--overwrite` string when `--overwrite` is part of the planned command.
- The preview failed, errored, or produced an empty diff that the user did not expect.
- The preview shows changes outside the asset set the user described.
- The target workspace is production and the user has not confirmed production scope explicitly.
- Tokens, passwords, or database credentials appeared anywhere in the preview output and have not been redacted from the transcript.
- A required dataset push references a database connection the user did not authorize.

# Cross-Workspace Sync

Use this reference for cross-workspace promotion via `sup sync create`, `sup sync run`, and `sup sync validate`.

## Sync Commands

| Command | Effect |
|---|---|
| `sup sync create <dir> --source <id> --targets <ids>` | Scaffold a sync configuration that exports assets from the source workspace and pushes them to one or more target workspaces. |
| `sup sync run <dir> --dry-run` | Preview the sync without writing to any target. Required before any real `sup sync run`. |
| `sup sync run <dir>` | Execute the sync: pulls from source, applies Jinja2 templating, pushes to targets. |
| `sup sync run <dir> --pull-only` | Pull from source into the local directory only; safe inspection step. |
| `sup sync validate <dir>` | Validate the sync configuration without executing any pull or push. |

## Source vs. Target

Every sync has exactly one source workspace and one or more target workspaces:

- **Source**: the workspace whose assets are exported. Reading is non-destructive; the source is unaffected by `sup sync run`.
- **Target**: each workspace that receives the pushed assets. Targets are mutated: charts, dashboards, datasets, and database connections may be created, updated, or overwritten.

Sync operations are always overwrite-style at the target — sync's design assumption is that the target should match the source. There is no `overwrite=false` mode for sync once it runs.

For Jinja2 target context, rollback expectations, and multi-target escalation, load [sync-templating-and-rollback.md](sync-templating-and-rollback.md).

## Sync Workflow

1. `sup sync validate <dir>` to validate the sync configuration before any run.
2. `sup sync run <dir> --dry-run` to preview the asset list per target.
3. Summarize the target effects (assets created/updated/overwritten per target) and the rollback expectations — sync is overwrite-style with no `overwrite=false`, so state how each target would be restored if the result is wrong.
4. Stop before execution and present the dry-run with the confirmation template from [confirmation-template.md](confirmation-template.md); wait for typed confirmation.
5. After typed confirmation, run `sup sync run <dir>` without `--dry-run` to execute the sync.

Run the dry-run for every sync, even repeated syncs of the same configuration. Source assets evolve; the dry-run is the only way to see what will actually change in this run.

For rollback and multi-target blast-radius details, load [sync-templating-and-rollback.md](sync-templating-and-rollback.md).

# Mutation Preview and Dry-Run Handling

Use this reference before any state-changing `sup` command.

## Native Dry-Run

Use native `--dry-run` for commands that expose it:

```bash
sup sync run <dir> --dry-run
sup user push --dry-run
sup user invite --dry-run
```

Capture the full dry-run output, redact credentials, and summarize the target workspace, affected entities, and any destructive flags before asking for confirmation.

## Pull-and-Diff Substitute

`sup chart push`, `sup dashboard push`, and `sup dataset push` do not expose native `--dry-run`. For those commands:

1. Confirm the target workspace name and ID.
2. Pull the current target state with the matching `sup chart pull`, `sup dashboard pull`, or `sup dataset pull` command.
3. Diff the pulled target YAML against the local assets folder.
4. Summarize changed entity counts, IDs/UUIDs, database dependencies, `--force`, and `--overwrite`.
5. Load [confirmation-template.md](confirmation-template.md) and wait for explicit confirmation.

The pull-and-diff substitute is required, not optional. Run it even when the same assets were previewed earlier in the session because source and target workspaces can drift.

## Failure Handling

Stop before execution when the preview fails, returns an unexpected empty diff, shows assets outside the requested scope, or exposes credentials that cannot be redacted cleanly.

# Sync Templating, Rollback, and Multi-Target Risk

Use this reference after [cross-workspace-sync.md](cross-workspace-sync.md) when a sync configuration has Jinja2 context, multiple targets, or rollback requirements.

## Jinja2 Templating

Sync configurations support Jinja2 templating so a single source can produce environment-specific targets:

```yaml
target_defaults:
  jinja_context:
    company: Default Company
    region: us-east-1

targets:
  - workspace_id: 456
    name: production
    jinja_context:
      environment: production
  - workspace_id: 789
    name: staging
    jinja_context:
      environment: staging
```

Templating runs after the source pull and before each target push. Template errors surface during `sup sync validate` and `sup sync run --dry-run`; never run a real sync that has not first cleanly validated.

## Rollback Story

Sync does not provide an automatic rollback. The accepted recovery model is:

- The sync configuration directory lives in git; the previous commit represents the previous source state.
- To roll back, revert the sync directory to the prior commit and run `sup sync run` again with the same targets.
- For assets edited directly in the target UI between syncs, those edits are lost on the next overwrite-style sync. Document this in the confirmation step.

Never describe sync as safe to retry without thinking. It is safe to retry only if the user has accepted the overwrite semantics.

## Multi-Target Blast Radius

A single `sup sync run` can mutate every target workspace listed in the configuration. Before executing:

1. Confirm every target workspace by name, not just ID.
2. Confirm the asset counts per target from the dry-run output.
3. Confirm whether any target hosts production-facing dashboards; if so, escalate the confirmation step in [confirmation-template.md](confirmation-template.md).

# Single-Workspace Write Operations

Use this reference for `sup` commands that create, update, or overwrite assets within a single workspace.

## Mutating Commands

| Command | Effect |
|---|---|
| `sup chart push` | Push chart YAML from filesystem into the workspace; creates or updates charts. Supports `--overwrite` and `--force`. |
| `sup dashboard push` | Push dashboard YAML; creates or updates dashboards. Supports `--overwrite` and `--force`. |
| `sup dataset push` | Push dataset YAML; pushes database dependencies first, then datasets. Supports `--overwrite` and `--force`. |
| `sup user push` | Push user YAML; creates or updates user records. Supports `--dry-run`. |
| `sup user invite` | Invite users to a workspace. Supports `--dry-run`. |
| `<entity> push --overwrite` | Overwrite existing assets matching the local IDs/UUIDs. |
| `<entity> push --force` | Skip the CLI's interactive confirmation prompt. Treat this as elevated permission. |

There is no `sup database push` — database connections are not mutated through the CLI's push surface. Dataset push will push the database connection referenced by the dataset YAML, so creating a dataset that references a new database can result in a new database connection being created in the workspace; flag that explicitly in the confirmation step.

There is no general `sup … delete` surface. If a user asks to delete an asset via the CLI, stop and route to the separate `preset-api-skills` package (where the Phase 5 mutation skills live) rather than fabricating a CLI command.

## `--force` and `--overwrite` Semantics

- `--overwrite` matches assets by ID/UUID and replaces their bodies wholesale. Custom edits made in the target workspace UI are lost.
- `--force` is surfaced on `sup chart push`, `sup dashboard push`, and `sup dataset push`. It skips the interactive confirmation prompt inside `sup`. It does **not** skip the confirmation required by this skill; an agent must still present the confirmation template from [confirmation-template.md](confirmation-template.md) before invoking `--force` on any of those commands.
- Combining `--overwrite --force` on any entity push (chart, dashboard, or dataset) is the most destructive single-workspace combination available via the CLI. Refuse to run it without the literal target workspace name and the literal flag string(s) in the user's confirmation message.

## Pushed-Dependency Behavior

- `sup chart push` pushes the chart definitions in the assets folder. Dataset and database YAML files that the chart references must already exist (in the workspace or in the assets folder for the same push). Chart push does not silently create database connections.
- `sup dataset push` pushes datasets and, per upstream behavior, pushes referenced database connections first. This means pushing a dataset can create or update a database connection in the target workspace.
- `sup dashboard push` pushes dashboards and the chart/dataset YAML they reference; the same dataset-then-database dependency applies if those YAML files are present in the assets folder.

Always run the assets-folder discovery step first (`ls assets/`, `sup chart pull` against the target if needed) so the agent can summarize exactly which entity types will be touched.

## Ownership Caveats

- Asset ownership in the target workspace may be reassigned to the pushing user. Confirm whether the user wants ownership preserved before running.
- Dashboards inherit chart ownership; pushing a dashboard can transfer ownership of every embedded chart.

## Pre-Push Checklist

`sup chart push`, `sup dashboard push`, and `sup dataset push` do not currently expose a `--dry-run` flag. (`sup sync run`, `sup user push`, and `sup user invite` do — use the native `--dry-run` there.) For entity push without a native `--dry-run`, the agent must instead:

1. Confirm the target workspace name and ID with the user.
2. Inventory the assets folder (`ls`, `head`) and pull the current target state with `sup chart pull` / `sup dataset pull` / `sup dashboard pull` for diff. Present the diff between local YAML and pulled-target YAML.
3. Confirm whether `--overwrite` is required and why.
4. Confirm whether `--force` is required and why interactive confirmation must be skipped.
5. Load [preview-and-dry-run.md](preview-and-dry-run.md), then [confirmation-template.md](confirmation-template.md), and present the template.

Only after explicit user confirmation that names the target workspace (and names every `--force` / `--overwrite` flag the run will use) should the agent execute the mutating run.