# K3s node enrollment runbook

## Phase 2 package execution

Run the external package launcher as the normal repository owner. Do not use `sudo` around the launcher.

```bash
./apply-overdeck-k3s-phase2.sh /home/user/Projects/overdeck
```

The default run uses the shipped sanitized `debian4` fixture. It cannot contact or modify a real candidate. It creates an isolated worktree, runs the test gates, creates and validates a dry-run receipt, commits the exact Phase 2 repository delta, pushes a candidate branch, and opens a draft pull request when GitHub CLI authentication is available.

To perform read-only qualification of a real machine that already has its OS and Tailscale installed:

```bash
./apply-overdeck-k3s-phase2.sh /home/user/Projects/overdeck \
  --candidate debian4 \
  --live-candidate
```

That mode reads Tailscale identity, candidate preflight, Phase 1 control-plane contracts and Kubernetes Node inventory. It still cannot install K3s, create a token, change SSH, label a Node, run a proof Job, edit registries, or authorize Phase 3.

## Package results

The launcher prints a result archive similar to:

```text
/home/user/Projects/overdeck-k3s-phase2-result-<timestamp>.tar.gz
```

Return that archive for review. Keep the pull request as a draft and unmerged until the receipt is accepted.

The result contains:

- outer launcher result;
- gate ledger and logs;
- exact base, branch and candidate commit;
- Phase 2 plan and text summary;
- candidate preflight and uniqueness proof;
- durable unexecuted transaction ledger;
- paired registry previews;
- independent receipt-validation result;
- sanitized package metadata.

It must not contain SSH keys, K3s token values, kubeconfig contents, Age identities, private keys, process environments, or GitHub credentials.

## Direct repository command

After Phase 2 is merged, the repository entrypoint may be used directly:

```bash
tools/k3s/enroll-node.sh debian4 --dry-run \
  --fixture tools/k3s/test/fixtures/phase2-debian4.json
```

For live read-only planning:

```bash
tools/k3s/enroll-node.sh debian4 --plan
```

The direct command writes a new receipt directory in the current directory unless `--receipt-dir` is supplied.

## Interpreting failure

A failed Phase 2 run is safe by construction. Confirm the result records:

```text
git_publication_allowed=false
live_mutation_performed=false
candidate_mutation_performed=false
cluster_mutation_performed=false
registry_mutation_performed=false
phase3_authorized=false
```

The launcher leaves its isolated worktree and logs intact. Do not manually copy registry previews into the repository. Return the archive for correction.

## Phase 3 prerequisite

Before the canary package is generated, provide:

1. the accepted Phase 2 result archive;
2. the exact merged Phase 2 commit or a fresh `main` checkout containing it;
3. the intended candidate name;
4. confirmation that the operating system and Tailscale are installed and authenticated;
5. approval for any required Tailscale SSH/tag policy change.

Phase 3 will be the first package allowed to perform live enrollment. It will bind authorization to one candidate identity and one reviewed plan digest.