# Agent instructions — execute K3s Phase 1 qualification-first package

Audience: the trusted agent/operator running the downloaded package
Goal: one command performs package verification, repository tests, live qualification, transactional apply, and candidate Git publication

## Required downloads

Place these files in the same directory:

```text
overdeck-k3s-phase1-qualified.zip
apply-overdeck-k3s-phase1-qualified.sh
```

Use the accompanying checksum file when provided.

## Normal command

Run as the normal owner of the repository, not as root:

```bash
chmod +x ./apply-overdeck-k3s-phase1-qualified.sh

./apply-overdeck-k3s-phase1-qualified.sh \
  /home/user/Projects/overdeck
```

The launcher may request sudo once for local `age` installation or enabling user lingering. Do not wrap the launcher itself in `sudo`.

## Operator contract

Do not:

- edit package contents;
- use an older Phase 1 launcher with this ZIP;
- apply v1, v2, or v3 candidates;
- delete prior failed worktrees before the replacement receipt is reviewed;
- hand-merge or push the candidate to `main`;
- run root helper commands manually;
- expose the age key, K3s token, kubeconfig, or decrypted backup.

The launcher verifies that its own bytes match the embedded launcher.

## What the launcher does

### Repository preparation

1. Verify ZIP paths, file types, checksums, declared changed paths, patch contract, and launcher coupling.
2. Fetch current `origin/main` without modifying the shared checkout.
3. Create a fresh isolated worktree and branch.
4. Apply stable paths with three-way Git patching.
5. Merge the Phase 1 migration-plan section and K3s plan-index receipt semantically while preserving newer unrelated coordination content.
6. Fail if any undeclared path changes.

### Required gates

The launcher runs locally against the exact candidate worktree:

- Bash syntax;
- Python compilation;
- semantic migration-plan and plan-index tests;
- Phase 1 unit/failure-injection suite;
- full fake-cluster qualification/apply transaction;
- Phase 0 collector and presentation regressions;
- execution-locality proof;
- legacy K3s unit gate;
- fleet core and CLI tests;
- Git whitespace/path checks;
- focused Factory Kubernetes regression when pytest is available.

The legacy live K3s integration gate remains optional because it exercises the older SSH/host-path experiment rather than the Phase 1 control-plane transaction. Its result is recorded.

### Live qualification and apply

After repository gates, the launcher obtains local sudo authorization when required and invokes one `--mode apply` run.

The orchestrator itself performs complete qualification and creates a verified pre-change encrypted backup before publishing configuration. It then converges, re-verifies, creates a post-change backup, installs the recurring timer, and finalizes.

### Git publication

The launcher does not stage or commit before live success. It reads:

```text
<live-receipt>/phase1-result.json
```

and requires:

```json
{
  "status": "success",
  "git_publication_allowed": true
}
```

Only then does it:

1. stage exactly declared paths;
2. commit the candidate;
3. push the candidate branch when enabled;
4. open a draft PR when `gh` is authenticated.

It never pushes directly to `main` or merges the PR.

## Qualification-only mode

To gather a complete compatibility receipt and verified pre-change backup without configuration or Git publication:

```bash
./apply-overdeck-k3s-phase1-qualified.sh \
  /home/user/Projects/overdeck \
  --qualification-only
```

Expected outcome:

- repository gates pass;
- live qualification passes or reports all known failures;
- a verified encrypted pre-change backup may be retained;
- no managed K3s file changes;
- no K3s restart;
- no timer installation;
- no Git stage/commit/push/PR.

Normal execution is preferred now because the replacement’s apply mode already has the same qualification boundary.

## Supported options

```text
--package PATH
--server NAME
--kubeconfig PATH
--backup-dir PATH
--age-identity PATH
--retention COUNT
--ssh-door tailscale_ip|tailscale_ssh|lan
--result-root PATH
--qualification-only
--no-push
--no-pr
--no-enable-linger
--gate-timeout SECONDS
--live-timeout SECONDS
--skip-live              testing only; repository validation, no production claim
```

Do not use `--skip-live` for the migration. It cannot establish Phase 1 completion.

## Expected live surfaces

On `debian3`, apply may create or update:

```text
/etc/rancher/k3s/config.yaml.d/90-overdeck-control-plane.yaml
/etc/rancher/k3s/overdeck/control-plane.json
/etc/rancher/k3s/overdeck/version-lock.json
/var/lib/overdeck/k3s-phase1/transactions/
/var/lib/overdeck/k3s-phase1/backups/     # temporary plaintext staging
```

On the workstation:

```text
~/.config/overdeck/k3s-backup.agekey
~/.config/overdeck/k3s-backup.json
~/.local/lib/overdeck/k3s/
~/.local/state/overdeck/k3s-backups/debian3/
~/.local/state/overdeck/k3s-phase1-debian3.lock
~/.config/systemd/user/overdeck-k3s-backup.service
~/.config/systemd/user/overdeck-k3s-backup.timer
```

K3s restarts only when the managed YAML differs.

## What is forbidden in this phase

The launcher and helpers must not:

- replace or upgrade the K3s binary;
- change the datastore type;
- run cluster reset;
- activate a restore;
- rewrite the existing installer unit/arguments;
- change server node IP or flannel interface;
- reboot hosts;
- enroll a new node;
- deploy Kubernetes workload policy;
- modify Tailscale ACLs;
- push or merge `main`.

## Success output

The launcher prints:

```text
Worktree: ...
Branch: ...
Commit: ...
Live: success
Push: pushed|skipped
PR: created|skipped...
Return this archive for review: /.../overdeck-k3s-phase1-result-<stamp>.tar.gz
```

The result archive contains redacted logs, package metadata, gate results, live receipts, the committed patch when applicable, and Git publication status. It does not contain encrypted backups or private keys.

Upload the result archive exactly as printed. Keep the draft PR unmerged.

## Failure output

The launcher still creates a result archive and leaves the isolated worktree and transaction evidence intact.

On qualification failure:

- no K3s configuration is published;
- no Git commit/push occurs;
- a verified pre-change backup may remain;
- `qualification.json` lists all failed and blocked checks.

On apply failure:

- timer rollback is attempted;
- server rollback is attempted when configuration was published;
- Git publication is forbidden;
- pre-change backup remains retained;
- any interrupted post-change archive is marked as failure evidence.

Do not debug manually. Upload the result archive.

## Post-success owner action

After receipt review but before considering Phase 1 operationally complete:

1. securely copy encrypted backups off the workstation;
2. securely escrow the age private key separately;
3. merge only the reviewed exact candidate commit;
4. retain the pre-change archive through at least the Phase 2 enrollment canary;
5. confirm the recurring timer produces a later verified scheduled backup.

## UI boundary

This phase contains no product UI delta, no new UI primitive, and no Astryx dependency.