diff --git a/docs/install/installation-and-distribution.md b/docs/install/installation-and-distribution.md
index a37e455..1283a50 100644
--- a/docs/install/installation-and-distribution.md
+++ b/docs/install/installation-and-distribution.md
@@ -32,7 +32,7 @@ kitout status --config ./kitout.yaml
kitout apply --config ./kitout.yaml --dry-run
```
-See `docs/setup/first-real-run.md` for the full first-run checklist.
+See the [first-run guide](../setup/first-real-run.md) for the full checklist.
To produce a local build artifact with embedded metadata:
@@ -43,12 +43,13 @@ bin/kitout version
## Release baseline
-Kitout is distributed through GitHub releases and an external Homebrew tap. The
-project is now at the `v2.7.0` minor release. Supported config files still use
-`version: 1`, cask apps must be listed under `brew.casks`, and the command
-surface includes local-first `init`, agent-friendly `context`, `explain`,
-managed and targeted Homebrew upgrades, reliable interruption handling,
-grouped symlink target prefixes, and repo-local `AGENTS.md` guidance.
+Kitout is distributed through
+[GitHub releases](https://github.com/vwall/kitout/releases/latest) and an
+external Homebrew tap. Supported config files use `version: 1`, cask apps must
+be listed under `brew.casks`, and the command surface includes local-first
+`init`, agent-friendly `context`, `explain`, managed and targeted Homebrew
+upgrades, reliable interruption handling, grouped symlink target prefixes, and
+repo-local `AGENTS.md` guidance.
The intended Homebrew install path is:
@@ -65,11 +66,11 @@ Before tagging a release on macOS, run:
make release-check VERSION=X.Y.Z
```
-The release gate runs `go test ./...`, then `go vet ./...`, then
-`make smoke-distribution`. The smoke target builds `bin/kitout` and covers
-temporary starter configs, `init`, `doctor`, `status`, `apply --dry-run`, a
-temp-only directory copy apply, and, when the host can report the current user's
-`UserShell`, a safe login-shell status/dry-run plan.
+The release gate checks formatting, runs `go test ./...` and `go vet ./...`,
+then runs `make smoke-distribution`. The smoke target builds `bin/kitout` and
+covers temporary starter configs, `init`, `doctor`, `status`,
+`apply --dry-run`, a temp-only directory copy apply, and, when the host can
+report the current user's `UserShell`, a safe login-shell status/dry-run plan.
Before tagging, also verify these release-specific items:
diff --git a/docs/references/references.md b/docs/references/references.md
deleted file mode 100644
index 7317abb..0000000
--- a/docs/references/references.md
+++ /dev/null
@@ -1,24 +0,0 @@
-# References
-
-These references informed the initial documentation.
-
-## Bork
-
-Bork describes itself as a Bash DSL for making declarative assertions about system state.
-
-- https://github.com/borksh/bork
-- https://bork.sh/manpage.html
-
-## Go CLI libraries
-
-Potential CLI libraries for Kitout:
-
-- https://cli.urfave.org/
-- https://github.com/spf13/cobra
-
-## Homebrew distribution
-
-Homebrew taps are external sources of formulae, casks, and external commands.
-
-- https://docs.brew.sh/How-to-Create-and-Maintain-a-Tap
-- https://docs.brew.sh/Taps
diff --git a/docs/testing/test-strategy.md b/docs/testing/test-strategy.md
index 9b5ce85..96b2409 100644
--- a/docs/testing/test-strategy.md
+++ b/docs/testing/test-strategy.md
@@ -100,8 +100,8 @@ Before release, run the macOS-local release gate:
make release-check
```
-The target runs `go test ./...`, then `go vet ./...`, then
-`make smoke-distribution`. The smoke target builds `bin/kitout`, creates a
+The target checks formatting, runs `go test ./...` and `go vet ./...`, then
+runs `make smoke-distribution`. The smoke target builds `bin/kitout`, creates a
temporary HOME, writes starter configs with `kitout init --config`, runs
`kitout doctor`, expects `kitout status` to report the missing starter
directories such as `~/code`, verifies `kitout apply --dry-run` exits without
diff --git a/retro-modern-mac.png b/retro-modern-mac.png
deleted file mode 100644
index 15c02d6..0000000
Binary files a/retro-modern-mac.png and /dev/null differ
diff --git a/rfcs/0001-core-resource-model.md b/rfcs/0001-core-resource-model.md
deleted file mode 100644
index 02c3b98..0000000
--- a/rfcs/0001-core-resource-model.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# RFC 0001: Core Resource Model
-
-## Status
-
-Draft
-
-## Context
-
-Kitout needs a consistent way to represent desired machine state. The tool will manage different resource types, but each resource should follow the same lifecycle.
-
-## Decision
-
-Represent each desired state item as a resource with a stable ID, type, status check, and apply operation.
-
-```go
-type Resource interface {
- ID() string
- Type() string
- Status(ctx context.Context) (StatusResult, error)
- Apply(ctx context.Context) (ApplyResult, error)
-}
-```
-
-The engine will not know the details of each resource. It will only orchestrate resource checks and applies.
-
-## Consequences
-
-Benefits:
-
-- simple mental model
-- easy to test resources independently
-- easy to add resources later
-- consistent output
-
-Costs:
-
-- some resource types may need extra metadata
-- dependency handling is limited at first
-
-## Alternatives considered
-
-### Imperative scripts
-
-Rejected for the core model because scripts are hard to inspect safely and hard to make idempotent.
-
-### Full dependency graph
-
-Deferred. A fixed execution order is enough for the MVP.
-
-### Plugin API
-
-Rejected for the MVP. Built-in resources are easier to test and document.
diff --git a/rfcs/0002-config-format.md b/rfcs/0002-config-format.md
deleted file mode 100644
index f2b1b7d..0000000
--- a/rfcs/0002-config-format.md
+++ /dev/null
@@ -1,62 +0,0 @@
-# RFC 0002: Config Format
-
-## Status
-
-Draft
-
-## Context
-
-Kitout needs a human-editable config format that is easy to read, easy to generate, and easy for Codex to modify.
-
-## Decision
-
-Use YAML for the MVP config format.
-
-Require:
-
-```yaml
-version: 1
-```
-
-Support top-level sections:
-
-```yaml
-brew:
-directories:
-repos:
-symlinks:
-macos_defaults:
-shell:
-```
-
-Homebrew casks belong under `brew.casks`; the older top-level `casks` section is
-kept only as a deprecated schema-version-1 compatibility form.
-
-## Consequences
-
-Benefits:
-
-- readable by humans
-- common for developer tools
-- easy to document
-- supports simple and expanded forms
-
-Costs:
-
-- YAML has edge cases
-- comments are not preserved if the tool rewrites config
-- schema validation must be strict
-
-## Alternatives considered
-
-### TOML
-
-TOML is simpler to parse in some ways, but nested repeated resources can become verbose.
-
-### JSON
-
-JSON is easy for machines, but not pleasant for hand-written setup files.
-
-### Bash DSL
-
-Rejected because Kitout should not parse shell syntax or reproduce Bork's implementation model.
diff --git a/rfcs/0003-command-surface.md b/rfcs/0003-command-surface.md
deleted file mode 100644
index 059634a..0000000
--- a/rfcs/0003-command-surface.md
+++ /dev/null
@@ -1,56 +0,0 @@
-# RFC 0003: Command Surface
-
-## Status
-
-Draft
-
-## Context
-
-Kitout should feel simple and obvious. The first commands should cover initialization, checking, applying, and diagnosing setup problems.
-
-## Decision
-
-The MVP command surface is:
-
-```sh
-kitout init
-kitout status
-kitout apply
-kitout apply --dry-run
-kitout doctor
-kitout version
-```
-
-Optional:
-
-```sh
-kitout list
-```
-
-## Consequences
-
-Benefits:
-
-- small command surface
-- easy to explain
-- maps to Bork-like status and satisfy flows without copying names
-- gives users a safe dry-run path
-
-Costs:
-
-- no advanced workflows at first
-- no automatic config editing beyond init
-
-## Alternatives considered
-
-### `kitout satisfy`
-
-Rejected for the initial command surface because `apply` is more common and clearer.
-
-### `kitout reconcile`
-
-Accurate, but too formal for the primary command.
-
-### `kitout bootstrap`
-
-Useful for first install, but less natural for repeated runs.
diff --git a/rfcs/0004-asdf-resource.md b/rfcs/0004-asdf-resource.md
deleted file mode 100644
index ba726a0..0000000
--- a/rfcs/0004-asdf-resource.md
+++ /dev/null
@@ -1,178 +0,0 @@
-# RFC 0004: asdf Resource
-
-## Status
-
-Draft
-
-## Context
-
-Kitout should support developer runtimes that are commonly managed with
-`asdf`, such as Ruby and Node.js.
-
-`asdf` uses plugins to manage different tools. A useful Kitout integration
-needs to represent three pieces of desired state:
-
-- an installed asdf plugin
-- installed tool versions for that plugin
-- explicit `.tool-versions` entries
-
-This should be a built-in Kitout resource, not a Kitout plugin system.
-Shell commands can run `asdf` manually, but they cannot give Kitout clear
-status, dry-run, or idempotent apply behavior for plugins and versions.
-
-Official asdf documentation is the reference for command behavior:
-
-- https://asdf-vm.com/manage/plugins.html
-- https://asdf-vm.com/manage/versions.html
-
-## Decision
-
-Add a future built-in `asdf` resource.
-
-The first config shape should be:
-
-```yaml
-version: 1
-
-brew:
- packages:
- - asdf
-
-asdf:
- plugins:
- - name: ruby
- url: https://github.com/asdf-vm/asdf-ruby.git
- versions:
- - 3.3.6
-
- tool_versions:
- - path: ~/.tool-versions
- tools:
- ruby: 3.3.6
-```
-
-The `asdf` resource does not install `asdf` itself. Users who want Kitout to
-install `asdf` should list it in `brew.packages`. If `asdf` is still not
-available when the asdf resource runs, the resource should fail with an
-actionable prerequisite message.
-
-Plugin URLs are required. This avoids depending on the asdf short-name plugin
-repository and makes the config more reproducible.
-
-Only exact versions are supported in the first implementation. Do not support
-`latest` in v1 because it makes status and apply behavior mutable over time.
-
-`.tool-versions` files are updated only when explicitly configured. Kitout
-must preserve unrelated entries in those files.
-
-The fixed execution order should become:
-
-1. doctor prerequisites
-2. Homebrew packages
-3. asdf plugins and versions
-4. casks
-5. directories
-6. repositories
-7. symlinks
-8. macOS defaults
-9. shell commands
-
-## Status behavior
-
-The asdf resource should check:
-
-- `asdf` command availability
-- plugin installed with the expected URL
-- configured versions installed
-- configured `.tool-versions` files contain expected tool/version entries
-
-Missing `asdf` should be reported as a failed prerequisite, not as a plugin
-or version failure.
-
-## Apply behavior
-
-The asdf resource should:
-
-- add missing plugins with `asdf plugin add `
-- install missing exact versions with `asdf install `
-- update only configured `.tool-versions` files
-- leave unrelated `.tool-versions` entries unchanged
-
-The first implementation should not:
-
-- install `asdf` directly
-- remove asdf plugins
-- uninstall tool versions
-- update plugins
-- rewrite unrelated `.tool-versions` entries
-- support `latest`
-
-## Dry-run behavior
-
-Dry-run should show planned plugin additions, version installs, and
-`.tool-versions` file updates.
-
-Dry-run must not:
-
-- add plugins
-- install versions
-- write `.tool-versions` files
-
-## Testing expectations
-
-Future implementation tests should cover:
-
-- missing asdf prerequisite
-- plugin satisfied
-- plugin missing
-- plugin installed with the wrong URL
-- version satisfied
-- version missing
-- explicit `.tool-versions` entry satisfied
-- explicit `.tool-versions` entry missing
-- explicit `.tool-versions` entry changed
-- dry-run command construction
-- dry-run file update rendering
-- no mutation during dry-run
-
-Unit tests must not call a real `asdf` binary. External commands should use
-the command runner interface.
-
-## Consequences
-
-Benefits:
-
-- asdf-managed runtimes become visible in `kitout status`
-- dry-run can show exact plugin, version, and file changes
-- Ruby and other runtime setup can be represented declaratively
-- shell commands remain a fallback instead of the primary path
-
-Costs:
-
-- config schema grows beyond the initial MVP resource list
-- asdf plugin behavior may vary by tool
-- `.tool-versions` editing requires careful preservation of unrelated entries
-
-## Alternatives considered
-
-### Shell commands
-
-Rejected as the primary model. Shell commands are useful as an escape hatch,
-but they do not provide reliable status checks or structured dry-run output
-for asdf plugins and versions.
-
-### Kitout plugin system
-
-Rejected. This feature manages asdf plugins as local machine state. It should
-not introduce a plugin API for Kitout itself.
-
-### Install asdf inside the asdf resource
-
-Rejected for the first implementation. Homebrew package installation already
-belongs to the Homebrew resource. Keeping asdf installation there makes the
-asdf resource independent and easier to test.
-
-### Optional plugin URLs
-
-Rejected for the first implementation. Required URLs are more explicit and
-avoid relying on the asdf short-name plugin repository.
diff --git a/tmp/imagegen/retro-modern-mac-key.png b/tmp/imagegen/retro-modern-mac-key.png
deleted file mode 100644
index 0e8af33..0000000
Binary files a/tmp/imagegen/retro-modern-mac-key.png and /dev/null differ