kitsune-kit 0.4.0 → 0.5.0

data/docs/architecture/decisions/0005-operation-semantics.md

@@ -0,0 +1,19 @@
+# ADR 0005: Plan, apply, rollback, remove and destroy semantics
+
+- Status: accepted
+- Date: 2026-08-14
+
+## Decision
+
+- `plan` observes and describes changes without mutation.
+- `apply` converges actual state to desired state and verifies postconditions.
+- `rollback` restores captured prior state when restoration is safe and supported.
+- `remove` stops and removes a managed capability while preserving data.
+- `destroy` permanently removes a provider resource.
+- `destroy-data` permanently removes service data and is always separately confirmed.
+
+Destructive operations show exact IDs and require the resource name as confirmation in an interactive terminal or an explicit confirmation option in non-interactive mode.
+
+## Consequences
+
+The word rollback is never used as a synonym for deleting a server or Docker volume. Operations that cannot restore prior state say so before execution.

data/docs/architecture/decisions/0006-tui-backend.md

@@ -0,0 +1,21 @@
+# ADR 0006: Optional TUI backend
+
+- Status: accepted
+- Date: 2026-08-14
+
+## Context
+
+Kitsune Kit needs a full-screen terminal interface without making it necessary for automation or conventional CLI use. RatatuiRuby 1.5 provides excellent widgets and headless testing, but currently requires Ruby 3.2.9 or newer, distributes native platform artifacts, and is LGPL-3.0-or-later. Kitsune Kit currently supports the Ruby 3.2 series and must remain installable as one portable Ruby gem.
+
+## Decision
+
+- The domain emits presentation-neutral events.
+- `Tui::Store`, `Tui::Renderer`, `Tui::Controller` and `Tui::Terminal` are separate components.
+- The initial renderer uses a small ANSI terminal backend and a deterministic text buffer.
+- Every TUI action invokes the same workflow used by the conventional CLI.
+- A future RatatuiRuby backend may replace only renderer, input and terminal lifecycle components.
+- The TUI remains optional at runtime; non-TTY use never initializes it.
+
+## Consequences
+
+The gem has no native TUI dependency and works completely through CLI/JSON. The initial widget set is intentionally smaller than RatatuiRuby, but its state, navigation, worker and snapshots remain reusable if a richer backend is adopted.

data/docs/architecture/provider-adapters.md

@@ -0,0 +1,49 @@
+# Provider and transport adapters
+
+Kitsune Kit's adapter API version is `Kitsune::Kit::Adapters::API_VERSION`, currently `1`. It is a small internal extension boundary, not a dynamic plugin system. A breaking signature or semantic change must increment this value and the corresponding JSON/event schemas when affected.
+
+## Provider contract
+
+A provider subclasses `Kitsune::Kit::Adapters::Provider` and implements:
+
+| Method | Contract |
+| --- | --- |
+| `validate_credentials!` | Return `true`, or raise a typed authentication/provider error. |
+| `validate_server_spec!(spec:)` | Check region, size and image availability without creating anything. |
+| `find_server(name:, tags:)` | Return an exact owned `ServerRecord` or `nil`; never adopt by name alone. |
+| `find_server_by_id(id:)` | Return the exact record or `nil`. |
+| `create_server(spec:)` | Create once and return the provider ID immediately. |
+| `wait_until_ready(id:, timeout:)` | Return an active record with a public IP or raise `TimeoutError`. |
+| `delete_server(id:)` | Delete by exact provider ID. |
+| DNS methods | Find/upsert/delete records while preserving exact IDs and zones. |
+
+Provider exceptions must be translated into `Kitsune::Kit::Errors` without copying tokens or raw provider response bodies into messages. Availability errors are configuration errors because the user can correct the desired spec; transient API failures remain retryable provider errors.
+The CLI `--timeout` value configures both DropletKit open/read timeouts and the separate readiness deadline.
+
+## Transport contract
+
+A transport subclasses `Kitsune::Kit::Adapters::Transport`. `execute` receives a command and a separate argument array, applies a deadline, and returns `CommandResult` with independent `stdout`, `stderr`, `exit_status` and `duration_ms`. It does not infer success from output. `upload` accepts explicit content, absolute normalized path and restrictive mode. Host-key verification belongs to the connection adapter and must never silently disable verification.
+
+## Verification
+
+The same shared examples run against `FakeProvider`/`DigitalOceanProvider` and `FakeTransport`/`NetSshTransport`. They cover credentials, spec validation, lifecycle, DNS, reachability, result shape, uploads and timeout mapping. Adapter-specific tests cover provider error translation, SSH quoting, unsafe paths, host keys and failed uploads.
+
+Run them with:
+
+```bash
+bundle exec rspec spec/adapters spec/contracts
+```
+
+Do not add a provider until it can pass these contracts and an opt-in real lifecycle test. The Hetzner
+feasibility/sequencing review and the decision not to create a premature hook system are recorded in
+[Roadmap and extension decisions](../roadmap.md).
+
+The state boundary follows the same rule: `StateStores::Store` defines the port, while `StateStore` is the locked atomic filesystem adapter and `Adapters::FakeStateStore` is the deterministic in-memory adapter. Both execute `spec/contracts/state_store_contract.rb`.
+
+`SecretStores::Store` and `Reporters::Reporter` are also explicit ports. Environment/fake secret stores and
+human/JSON/fake reporters execute their shared contracts in `spec/adapters`; fakes make complete workflow tests
+independent of the process environment and terminal.
+
+`Clock` is the time port for workflow event timestamps, monotonic durations, journals and bounded waits.
+`Adapters::FakeClock` advances deterministically without sleeping; both implementations execute
+`spec/contracts/clock_contract.rb`.

data/docs/architecture.md

@@ -0,0 +1,89 @@
+# Architecture
+
+Kitsune Kit is a desired-state infrastructure tool with two replaceable presentation layers over one domain core.
+
+```text
+Conventional CLI ─┐
+                  ├─ workflows ─ operations ─ provider / SSH / state / secrets
+Optional TUI ─────┘       │
+                          └─ domain events ─ human / JSON / TUI / run log
+```
+
+Presentation code does not create provider clients, open SSH connections or implement infrastructure rules. CLI and TUI call the same workflow objects and consume the same event stream.
+
+## Layers
+
+### Configuration and domain values
+
+`Configuration` loads/merges typed schema values and validates them before adapters are constructed. `Change`, `Plan`, `Result`, typed errors and versioned events are presentation-neutral values.
+
+### Workflows
+
+Workflows coordinate use cases:
+
+- initialize/select an environment;
+- build/apply/resume a plan;
+- inspect/doctor/rollback/destroy;
+- generate support diagnostics.
+
+They emit events but do not print. Apply uses `RunJournal` to record a compatible plan and step status for safe resume.
+
+The event vocabulary includes run/plan start and finish, operation start/progress/success/failure/skip, and warnings. All subscribers receive the same versioned event values; progress currently guarantees operation boundary percentages and can become finer-grained without changing presentations.
+
+### Operations
+
+Each operation exposes a non-mutating `plan`, idempotent `apply` and, where meaningful, ownership-aware `rollback`. Operations include server creation, versioned remote scripts, services and DNS.
+
+An operation verifies its result before writing a managed marker/state. Destructive replacement appears in the plan and is never applied implicitly.
+
+### Ports and adapters
+
+- `Provider`: server-spec validation, exact server/DNS lookup, create/wait/delete and credential validation.
+- `Transport`: reachability, command execution with separate output/status/timing, and safe upload.
+- `StateStores::Store`: read/update/delete and per-environment mutation-lock port; filesystem and in-memory fake adapters share a contract.
+- `SecretStores::Store`: resolves secret values without adding them to domain configuration/state; environment
+  and deterministic fake adapters execute the same contract.
+- `Reporters::Reporter`: event-consumer port for human output, stable JSON, TUI state and redacted logs.
+- `Clock`: UTC wall time, monotonic durations and sleeping, with a deterministic nonblocking fake.
+
+Real DigitalOcean/Net::SSH adapters and deterministic fakes satisfy shared contracts. This permits full workflow failure injection without a VPS while reserving real behavior for integration/E2E suites.
+
+The public adapter contract is versioned as `Kitsune::Kit::Adapters::API_VERSION`. See [Provider and transport adapters](architecture/provider-adapters.md).
+
+## State and ownership
+
+State schema version 1 contains environment, timestamps, resource identities, operation history and run journals. The server provider ID is recorded immediately after creation. DNS records are persisted one at a time. Remote resources carry script/config fingerprints and previous-state metadata.
+
+State updates acquire a per-environment file lock, validate the whole document, preserve a backup, fsync a restricted temporary file and atomically rename it. Unsupported schemas/environment mismatches are rejected.
+
+Names/tags help find resources, but provider IDs plus recorded ownership authorize destructive operations.
+
+## Remote execution
+
+Remote setup is stored in versioned Bash files under `lib/kitsune/kit/scripts`. `RemoteScript` fingerprints script bytes plus validated arguments, compares a remote marker, uploads through stdin-safe base64 transport, applies, verifies and records the marker.
+
+SSH host verification is explicit. Commands and arguments are distinct at the transport boundary. Root and deploy transports are selected per operation; user bootstrap rollback deliberately uses root access.
+
+Safety-critical SSH/firewall operations execute inside one preserved authenticated transport session while their postconditions are tested through separate fresh connections. The preserved session restores the captured policy if either fresh check fails.
+
+## Services
+
+`EnsureService` composes smaller collaborators for generated Compose YAML, file transaction/backups, firewall reconciliation, data backup and state transitions. Data lifecycle is deliberately separate from container/config lifecycle.
+
+An enabled service in `external` mode is configuration metadata, not an operation. It is visible through the
+CLI but excluded from VPS plans, Docker, firewall, doctor port checks and destructive lifecycle methods.
+
+## TUI
+
+The initial TUI is a pure-Ruby ANSI backend with deterministic renderer/store/controller boundaries. It has no native dependency and can be replaced without changing workflows. Headless tests feed events and keys into the store/controller and compare stable rendered buffers.
+
+## Decisions
+
+Detailed accepted decisions are in [architecture/decisions](architecture/decisions):
+
+- product boundary and direct 0.5 rewrite;
+- core/interface separation;
+- configuration/state/secrets;
+- supported platforms;
+- operation semantics;
+- optional TUI backend.

data/docs/commands.md

@@ -0,0 +1,210 @@
+# Command reference
+
+The authoritative runtime reference is `kit help`, `kit help COMMAND` and the equivalent `kit COMMAND help`.
+This document explains the semantics and automation contract that short help cannot capture.
+
+## Global options
+
+Global options may be passed to infrastructure commands:
+
+| Option | Meaning |
+| --- | --- |
+| `-e`, `--env NAME` | Select an environment for this invocation. |
+| `--root PATH` | Project root containing `.kitsune/`. Defaults to the current directory. |
+| `--config PATH` | Use an alternative base configuration file. |
+| `--format human|json` | Select human or versioned machine output. |
+| `--no-color` | Disable ANSI styling. `NO_COLOR` is also respected by the entrypoint environment. |
+| `--no-input` | Never prompt; fail with an actionable error when confirmation is required. |
+| `--yes` | Approve reviewed, non-destructive changes. It never confirms permanent data/server destruction. |
+| `--dry-run` | Build/display the plan without applying it. |
+| `--quiet` | Limit human output to important findings and summaries. |
+| `--verbose` | Include additional domain-event detail. |
+| `--debug` | Include technical context/stack information for failures. |
+| `--log` / `--no-log` | Enable/disable restricted redacted local logs. Enabled by default. |
+| `--timeout SECONDS` | Upper bound for each remote step, provider HTTP request and readiness wait; must be positive. |
+| `--trust-host-key SHA256:...` | Trust only this exact first-seen SSH fingerprint. |
+
+## Core workflow
+
+### `kit init [--force]`
+
+Creates `.kitsune/config.yml`, a development overlay and environment selection. Existing generated files cause exit 9 unless `--force` is explicit. It also appends runtime artifacts to `.gitignore`.
+
+### `kit doctor`
+
+Read-only checks include Ruby/runtime, configuration, SSH-key permissions, security defaults, provider credentials, state schema, exact server ownership, verified SSH access, Ubuntu version, passwordless sudo, Docker/Compose, listening ports and managed drift.
+
+Statuses are `pass`, `warn`, or `fail`. Warnings do not make the command fail; any failed check returns exit 1.
+
+### `kit plan`
+
+Calculates changes without mutation. Details exclude provider key IDs and secrets. Actions are `create`, `update`, `delete` and `no_change`; plans flag destructive changes.
+
+### `kit apply`
+
+Builds a fresh plan, displays it, rejects destructive replacement and asks for confirmation. `--yes --no-input` is the automation form. `--dry-run` guarantees no mutation.
+
+Every run and step is journaled. The provider ID is saved immediately after server creation; remote markers and local state are saved after verified operations.
+Human output ends with the redacted local log path and a post-apply `doctor`/zero-change-plan next step. Failed or
+cancelled applies report the last confirmed step, run ID and exact `kit resume RUN_ID` command. JSON carries the
+same guidance as a `warning_emitted` event and never receives an extra human-output line.
+
+### `kit resume [RUN_ID]`
+
+Resumes the named run or latest incomplete run. It rejects successful runs and saved operation sets that no longer match configuration. Completed steps are skipped. Confirmation is required (`--yes` in automation).
+
+### `kit status`
+
+Displays the selected environment, exact provider server and locally tracked resources. It does not run remote diagnostics; use `doctor` for that.
+
+### `kit rollback`
+
+Runs rollback in reverse dependency order for resources recorded as managed. It preserves the Droplet and service data volumes. It is not a universal snapshot restore: provider resources or pre-existing files that Kitsune Kit never owned are not touched.
+
+## Server
+
+```text
+kit server show
+kit server status
+kit server create
+kit server configure
+kit server ssh
+kit server import --provider-id DROPLET_ID --confirm-import SERVER_NAME
+kit server destroy --confirm-destroy SERVER_NAME
+```
+
+- `show`/`status`: inspect server and state.
+- `create`: apply only the server operation.
+- `configure`: apply remote, service and DNS operations after the server operation.
+- `ssh`: verify the managed connection, then replace the process with the system `ssh` client using strict known-host checking.
+- `import`: recover only the server identity after state loss. It requires an exact numeric Droplet ID and configured server-name confirmation, then verifies name, tags, region, size, image, active status and public IP. It never imports remote-resource ownership.
+- `destroy`: delete only the exact recorded provider ID after verifying name/tags, then restore/remove managed DNS and clear state. If provider deletion fails, DNS is left untouched; if DNS cleanup fails afterward, retrying completes cleanup without deleting a second server. It never deletes by name alone.
+
+Interactive destruction asks the operator to type the exact server name. Automation must use `--confirm-destroy SERVER_NAME`; `--yes` is insufficient.
+Before an interactive confirmation, Kitsune Kit prints the environment, provider, resource, recorded provider ID and recoverability. JSON confirmation errors include the same safe target context.
+
+## Docker
+
+```text
+kit docker status
+kit docker install
+kit docker uninstall --yes
+```
+
+Uninstall refuses to run while managed services remain. Docker installation uses the official apt repository and creates the `kitsune-private` network.
+
+## Services
+
+```text
+kit service postgres status
+kit service postgres install
+kit service postgres backup
+kit service postgres remove --yes
+kit service postgres destroy-data --backup-before-destroy --confirm-destroy postgres@ENV
+```
+
+Replace `postgres` with `redis` for Redis.
+
+- `install`: service must be enabled and its secret environment variable present.
+- `backup`: pauses the service, creates a restricted tar archive of the volume on the server and always unpauses it.
+- `remove`: removes containers/network attachment and firewall rules owned by Kitsune Kit, but keeps the volume and managed files needed for recovery.
+- `destroy-data`: optionally creates a restricted data archive, then removes containers, volume, owned
+  configuration backups/files and state. In an interactive terminal it offers the backup and requires typing
+  `TYPE@ENV`; automation can request it with `--backup-before-destroy` and must supply `--confirm-destroy`.
+  The data archive is retained outside the service directory, but must be copied to independent storage.
+
+When an enabled service has `mode: external`, `status` returns only its configured host/port and
+`managed: false`. All local lifecycle actions fail safely; Kitsune Kit never treats an external provider's data as
+a VPS Docker volume.
+
+## DNS
+
+```text
+kit dns list
+kit dns plan
+kit dns apply
+kit dns remove --yes
+```
+
+DNS operations use exact record IDs and store original values. `remove` restores updated records and deletes only records created by Kitsune Kit.
+
+## Environments
+
+```text
+kit env list
+kit env current
+kit env use NAME
+```
+
+`use` validates that `.kitsune/environments/NAME.yml` exists and writes the selection atomically. An explicit `--env`/`KITSUNE_ENV` wins without changing the persisted selection.
+
+## Support
+
+```bash
+kit support bundle
+```
+
+The human-readable command prints the complete redacted bundle after writing it, so it can be reviewed before
+sharing. JSON mode returns the local path without adding non-JSON output. Kitsune Kit never uploads the bundle.
+
+Creates a permission-restricted JSON file under `.kitsune/support/` with versions, platform, redacted configuration/state, doctor results and selected redacted logs. The path is printed; Kitsune Kit never uploads it. Inspect it before sharing.
+
+## TUI
+
+`kit ui` starts the optional full-screen interface. Bare `kit` does the same only with interactive stdin/stdout; otherwise it prints help. See [TUI](tui.md).
+
+## Version
+
+`kit version`, `kit --version` and `kit -v` print the installed Kitsune Kit version without loading project configuration or contacting a provider.
+
+## JSON output
+
+Successful workflow documents use schema version 1 and include:
+
+```json
+{
+  "schema_version": 1,
+  "command": "plan",
+  "environment": "production",
+  "run_id": "...",
+  "status": "success",
+  "duration_ms": 12,
+  "result": {},
+  "warnings": [],
+  "events": []
+}
+```
+
+Errors are JSON on standard error:
+
+```json
+{
+  "schema_version": 1,
+  "status": "failure",
+  "error": {
+    "code": "configuration_error",
+    "message": "...",
+    "hint": "...",
+    "context": {}
+  }
+}
+```
+
+Treat unknown additive keys as forward-compatible, but reject unsupported `schema_version` values in consumers.
+
+## Exit codes
+
+| Code | Meaning |
+| ---: | --- |
+| 0 | Success, including a no-change plan/apply. |
+| 1 | Unexpected failure or failed `doctor` check. |
+| 2 | Invalid CLI syntax/unknown command. |
+| 3 | Invalid/missing configuration or unsupported environment. |
+| 4 | Authentication failure. |
+| 5 | Provider API failure. |
+| 6 | SSH/network connection failure. |
+| 7 | Remote command failure. |
+| 8 | Post-change verification failure. |
+| 9 | Unsafe operation or missing confirmation. |
+| 10 | Timeout. |
+| 130 | Interrupted by `SIGINT`. |

data/docs/configuration.md

@@ -0,0 +1,210 @@
+# Configuration
+
+Kitsune Kit configuration schema version 1 is YAML with a fixed structure. Unknown keys at any nesting level,
+malformed sections and future schema versions are rejected instead of being ignored.
+
+## Files and precedence
+
+The base file is `.kitsune/config.yml`. The selected overlay is `.kitsune/environments/NAME.yml`. Values are combined in this order, with later sources winning:
+
+1. built-in safe defaults;
+2. `.kitsune/config.yml`;
+3. `.kitsune/environments/NAME.yml`;
+4. supported environment-variable overrides;
+5. explicit overrides supplied by the internal API.
+
+Environment selection itself uses:
+
+1. `--env NAME`;
+2. `KITSUNE_ENV`;
+3. `.kitsune/environment`;
+4. `development`.
+
+Names start with a lowercase letter or digit and may then contain lowercase letters, numbers, `_` and `-`; uppercase names and path traversal are rejected so Compose project identity remains stable.
+
+Use:
+
+```bash
+kit env list
+kit env current
+kit env use production
+```
+
+## Complete schema
+
+```yaml
+version: 1
+
+provider:
+  name: digitalocean
+  token_env: DO_API_TOKEN
+
+server:
+  name: myapp-production
+  region: sfo3
+  size: s-1vcpu-1gb
+  image: ubuntu-24-04-x64
+  ssh_key_id: "12345678"
+  tags:
+    - kitsune-managed
+
+ssh:
+  user: deploy
+  port: 22
+  key_path: ~/.ssh/id_ed25519
+  allowed_cidrs:
+    - 203.0.113.10/32
+
+services:
+  postgres:
+    enabled: false
+    mode: managed
+    host:
+    image: postgres:17
+    publish: false
+    bind: 127.0.0.1
+    allowed_cidrs: []
+    port: 5432
+    password_env: POSTGRES_PASSWORD
+  redis:
+    enabled: false
+    mode: managed
+    host:
+    image: redis:7.2
+    publish: false
+    bind: 127.0.0.1
+    allowed_cidrs: []
+    port: 6379
+    password_env: REDIS_PASSWORD
+
+system:
+  swap_size_gb: 2
+  swap_swappiness: 10
+  unattended_upgrades: true
+  metrics: false
+  metrics_installer_sha256:
+
+dns:
+  domains: []
+  ttl: 3600
+```
+
+## Field reference
+
+### `provider`
+
+| Field | Meaning |
+| --- | --- |
+| `name` | Must currently be `digitalocean`. |
+| `token_env` | Name of the environment variable containing the token. Must look like an uppercase environment-variable name. |
+
+### `server`
+
+| Field | Validation |
+| --- | --- |
+| `name` | Lowercase DNS-style resource name, 1–63 characters. |
+| `region` | Non-empty DigitalOcean region slug. Provider validity is checked by the API. |
+| `size` | Non-empty DigitalOcean size slug. |
+| `image` | `ubuntu-22-04-x64` or `ubuntu-24-04-x64`. |
+| `ssh_key_id` | ID of a public key already uploaded to DigitalOcean. |
+| `tags` | Tags used to establish ownership. Keep `kitsune-managed`; a same-name untagged server is not adopted. |
+
+Region/size/image differences are immutable in the current model. A plan reports replacement as destructive; Kitsune Kit never silently replaces the server.
+
+### `ssh`
+
+| Field | Validation |
+| --- | --- |
+| `user` | Linux username: lowercase letters/numbers plus `_`/`-`, maximum 32 characters. |
+| `port` | Integer from 1 through 65535. |
+| `key_path` | Expanded local path to an existing regular private-key file with mode `0600` or stricter. |
+| `allowed_cidrs` | Valid IPv4 or IPv6 CIDRs permitted through UFW. Empty means the SSH port is not CIDR-restricted by this list. |
+
+SSH policy is ordered to keep a verified path open: create/verify the deploy user, install and validate the new policy, open the new firewall route, then remove obsolete managed rules.
+
+### `services.postgres` and `services.redis`
+
+| Field | Meaning |
+| --- | --- |
+| `enabled` | Include the service in the desired plan. |
+| `mode` | `managed` installs on the VPS; `external` records an endpoint and forbids local lifecycle actions. |
+| `host` | Required hostname/IP for `external`; must be empty for `managed`. |
+| `image` | Valid Docker image reference. Pin a digest for stronger reproducibility. |
+| `publish` | Publish a host port. Defaults to false. |
+| `bind` | IPv4 bind address used only when publishing. |
+| `allowed_cidrs` | Required and non-empty when `publish` is true. |
+| `port` | Host port, 1–65535. Container ports remain 5432/6379. |
+| `password_env` | Environment-variable name containing the required secret. |
+
+Images, binds, ports and secret names reject newline/shell/YAML injection patterns before any SSH connection is opened.
+
+External example:
+
+```yaml
+services:
+  postgres:
+    enabled: true
+    mode: external
+    host: db.internal.example
+    port: 5432
+    publish: false
+```
+
+External mode is metadata and a safety boundary, not a database-provisioning integration. `kit service postgres
+status` reports the endpoint without its secret. Install, backup, remove and destroy-data refuse to act; manage
+availability, TLS, backups and destruction with the external provider. External services never add Docker,
+firewall or private-port checks to the VPS plan.
+
+### `system`
+
+| Field | Validation |
+| --- | --- |
+| `swap_size_gb` | Integer 0–64. Zero disables swap managed by Kitsune Kit. |
+| `swap_swappiness` | Integer 0–100. |
+| `unattended_upgrades` | Boolean. |
+| `metrics` | Boolean; false by default. |
+| `metrics_installer_sha256` | Required lowercase 64-character SHA256 when metrics is enabled. |
+
+Kitsune Kit downloads the DigitalOcean metrics installer to a file, verifies the configured digest and only then executes it. Re-verify the digest whenever the upstream installer changes.
+
+### `dns`
+
+| Field | Validation |
+| --- | --- |
+| `domains` | Valid hostnames. Public Suffix List parsing determines the provider zone and record name. |
+| `ttl` | Integer 30–86400 seconds. |
+
+Each created/updated record is persisted immediately, including its previous value, so a partially failed run can resume and rollback safely.
+
+## Supported environment-variable overrides
+
+| Variable | Field |
+| --- | --- |
+| `KITSUNE_PROVIDER` | `provider.name` |
+| `KITSUNE_SERVER_NAME` | `server.name` |
+| `KITSUNE_REGION` | `server.region` |
+| `KITSUNE_SIZE` | `server.size` |
+| `KITSUNE_IMAGE` | `server.image` |
+| `KITSUNE_SSH_KEY_ID` | `server.ssh_key_id` |
+| `KITSUNE_SSH_USER` | `ssh.user` |
+| `KITSUNE_SSH_PORT` | `ssh.port` |
+| `KITSUNE_SSH_KEY_PATH` | `ssh.key_path` |
+| `KITSUNE_METRICS_INSTALLER_SHA256` | `system.metrics_installer_sha256` |
+
+Secrets are indirect: `provider.token_env` and each `password_env` name which environment variable Kitsune Kit reads. Their values are registered with the redactor and never written to state.
+Enabled services require at least 12 bytes and reject empty values and common defaults such as `password`, `postgres`, `redis`, `changeme` and `secret` before any provider or SSH request.
+
+## Schema evolution
+
+Version 1 is the direct-rewrite baseline and has no supported predecessor to migrate: the old preview `.env`
+format is intentionally not interpreted. A future schema change must ship an explicit, tested `N -> N+1`
+migrator that preserves a backup before changing configuration or state. Kitsune Kit never guesses at an unknown
+version. Until such a migrator exists, open the project with a compatible Kitsune Kit version and follow that
+release's documented migration path; never copy provider IDs by hand.
+
+JSON/event consumers must reject unknown `schema_version` values while tolerating documented additive fields
+within a supported version. Breaking adapter signatures increment `Adapters::API_VERSION`.
+
+## State is not configuration
+
+`.kitsune/state/ENV.json` is Kitsune Kit's ownership journal. Do not edit it manually or commit it. Writes use a per-environment lock, atomic rename and `.backup` copy. Losing state removes Kitsune Kit's proof of ownership; it intentionally refuses destructive actions rather than guessing by name.