diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e14d92c..6818fe8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,8 @@
 
 ### tl;dr
 
-You need a Wayland-capable Linux system, Rust, and a small set of system dependencies. Once installed, `./run-dev` will start a development instance.
+You need a Wayland-capable Linux system, Rust, and a small set of system
+dependencies. Once installed, `./run-dev` will start a development instance.
 
 ### Requirements
 
@@ -15,14 +16,40 @@ You need a Wayland-capable Linux system, Rust, and a small set of system depende
 
 2. **System dependencies**
 
-   * Platform-specific packages are required.
-   * For Ubuntu, see the [`SYSTEM_DEPS` section in the CI configuration](./.github/workflows/ci.yml).
+   * Platform-specific packages are required for building and running.
+   * View packages with: `./scripts/shepherd deps print dev`
+   * Install all dev dependencies: `./scripts/shepherd deps install dev`
+   * **Note**: Rust is automatically installed via rustup when installing build or dev dependencies.
 
-3. **Rust toolchain**
+### Unified script system
 
-   ```sh
-   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-   ```
+`shepherd-launcher` provides a unified script system for managing dependencies, building, and running:
+
+```sh
+# View and install dependencies
+./scripts/shepherd deps print dev        # List all dev dependencies
+./scripts/shepherd deps install dev      # Install all dev dependencies
+
+# Build binaries
+./scripts/shepherd build                 # Debug build
+./scripts/shepherd build --release       # Release build
+
+# Development
+./scripts/shepherd dev run               # Build and run in nested Sway
+```
+
+For CI/build-only environments:
+```sh
+./scripts/shepherd deps install build    # Build dependencies only
+./scripts/shepherd build --release       # Production build
+```
+
+For runtime-only systems:
+```sh
+./scripts/shepherd deps install run      # Runtime dependencies only
+```
+
+See `./scripts/shepherd --help` for all available commands.
 
 ### Running in development
 
diff --git a/README.md b/README.md
index 06361d6..1314839 100644
--- a/README.md
+++ b/README.md
@@ -74,29 +74,6 @@ If it can run on Linux in *any way, shape, or form*, it can be supervised by
 
 > [A Short Hike](https://ashorthike.com/) running via Steam
 
-Contributions are welcome for improvements and not yet implemented backends,
-such as:
-* Content-aware media player with supervised libraries
-  ([#3](https://github.com/aarmea/shepherd-launcher/issues/3))
-* Pre-booted Steam to improve launch time
-  ([#4](https://github.com/aarmea/shepherd-launcher/issues/4))
-* Android apps via Waydroid, including pre-booting Android if necessary
-  ([#5](https://github.com/aarmea/shepherd-launcher/issues/5))
-* Legacy Win9x via DOSBox, QEMU, or PCem, including scripts to create a boot-to-app image
-  ([#6](https://github.com/aarmea/shepherd-launcher/issues/6))
-* Chrome
-  ([#7](https://github.com/aarmea/shepherd-launcher/issues/7)),
-  including strict sandboxing and support for firewall rules
-  ([#8](https://github.com/aarmea/shepherd-launcher/issues/8))
-* Awareness of whether an Internet connection is available, and an availability
-  rule that gates activities based on this
-  ([#9](https://github.com/aarmea/shepherd-launcher/issues/9))
-* Porting to other *host* platforms, such as a Microsoft Windows shell
-  replacement or macOS kiosk via MDM. `shepherd-launcher` is architected such
-  that `shepherdd`, the core enforcement service, does not render any UI and
-  performs platform-specific functions like process management in
-  platform-specific crates.
-
 ## Core concepts
 
 * **Launcher-first**: only one foreground activity at a time
@@ -113,16 +90,12 @@ such as:
 
 ## Installation
 
-`shepherd-launcher` is pre-alpha and in active development. As such, end-user
-binaries and installation instructions are not yet available.
+`shepherd-launcher` is pre-alpha and in active development. The helper at
+`./scripts/shepherd` can be used to build and install a *fully functional*
+local kiosk setup from source:
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to run in development.
-
-Contributions are welcome for:
-* a CI step that generates production binaries
-  ([#1](https://github.com/aarmea/shepherd-launcher/issues/1))
-* an installation script
-  ([#2](https://github.com/aarmea/shepherd-launcher/issues/2))
+Check out this repository and run `./scripts/shepherd --help` or see
+[INSTALL.md](./docs/INSTALL.md) for more.
 
 ## Example configuration
 
@@ -158,11 +131,6 @@ max_run_seconds = 1800  # 30 minutes (roughly 3 in-game days)
 daily_quota_seconds = 3600  # 1 hour per day
 cooldown_seconds = 600  # 10 minute cooldown
 
-[[entries.warnings]]
-seconds_before = 600
-severity = "info"
-message = "10 minutes left - start wrapping up!"
-
 [[entries.warnings]]
 seconds_before = 120
 severity = "warn"
@@ -178,7 +146,12 @@ See [config.example.toml](./config.example.toml) for more.
 
 ## Development
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md)
+Build instructions and contribution guidelines are described in
+[CONTRIBUTING.md](./CONTRIBUTING.md).
+
+If you'd like to help out, look on
+[GitHub Issues](https://github.com/aarmea/shepherd-launcher/issues) for
+potential work items.
 
 ## Written in 2025, responsibly
 
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
new file mode 100644
index 0000000..a5e1982
--- /dev/null
+++ b/docs/INSTALL.md
@@ -0,0 +1,66 @@
+# Installation
+
+`shepherd-launcher` can be installed on Linux with a modern Wayland compositor.
+It is currently developed and tested on Ubuntu 25.10.
+
+`shepherd-launcher` currently must be built from source. `./scripts/shepherd`
+can help set up your build environment and manage your installation.
+
+## Basic setup
+
+```sh
+# 0. Install build dependencies
+sudo ./scripts/shepherd deps build run
+
+# 1. Install runtime dependencies
+sudo ./scripts/shepherd deps install run
+
+# 2. Build release binaries
+./scripts/shepherd build --release
+
+# 3. Install everything for a kiosk user
+sudo ./scripts/shepherd install all --user kiosk
+```
+
+This installs:
+- Binaries to `/usr/local/bin/`
+- System Sway configuration to `/etc/sway/shepherd.conf`
+- Display manager desktop entry ("Shepherd Kiosk" session)
+- System config template to `/etc/shepherd/config.toml`
+- User config to `~kiosk/.config/shepherd/config.toml`
+
+For custom installation paths:
+```sh
+# Install to /usr instead of /usr/local
+sudo ./scripts/shepherd install all --user kiosk --prefix /usr
+```
+
+Individual installation steps can be run separately:
+```sh
+sudo ./scripts/shepherd install bins --prefix /usr/local
+sudo ./scripts/shepherd install config --user kiosk
+```
+
+## Kiosk hardening (optional)
+
+Kiosk hardening is optional and intended for devices primarily used by
+children, not developer machines.
+
+```sh
+sudo ./scripts/shepherd harden apply --user kiosk
+```
+
+This restricts the user to only access the Shepherd session by:
+- Denying SSH access
+- Restricting console (TTY) login
+- Denying sudo access
+- Restricting shell to Sway sessions only
+
+To revert (all changes are reversible):
+```sh
+sudo ./scripts/shepherd harden revert --user kiosk
+```
+
+## Complete documentation
+
+See the scripts' [README](../scripts/README.md) for more.
diff --git a/docs/ai/history/2025-12-31 001 scripts.md b/docs/ai/history/2025-12-31 001 scripts.md
new file mode 100644
index 0000000..cd62078
--- /dev/null
+++ b/docs/ai/history/2025-12-31 001 scripts.md	
@@ -0,0 +1,231 @@
+This prompt created the setup script ecosystem, including CI setup, dev setup, and end-user installation and configuration. It was provided to Claude Opus 4.5 via VSCode Agent mode.
+
+The first draft was written by ChatGPT after some back-and-forth [in this conversation](https://chatgpt.com/share/6955f5ee-46f4-800b-87bc-db0e3df16541).
+
+The output was committed as fc0c1ce51d739aafcdce66f6958f008ef056a76a.
+
+-----
+
+# Task: Implement unified script system for dev, build, install, and user hardening
+
+## Objective
+
+Implement a **single, composable script system** that:
+
+* Avoids duplication between CI, developer, and runtime workflows
+* Exposes clear, reversible primitives for build, install, and user hardening
+* Uses one authoritative entrypoint with subcommands
+* Allows CI, developers, and administrators to invoke the *same logic* with different scopes
+
+The system must support:
+
+* CI build-only environments
+* Runtime-only systems
+* Developer systems (union of build + runtime deps)
+* Production installation and kiosk-style user hardening
+
+---
+
+## High-level design constraints
+
+* **One CLI entrypoint** (script-based), with subcommands
+* **Shared logic lives in libraries**, not duplicated scripts
+* **All tasks must be independently callable**
+* **All destructive actions must be reversible**
+* **Dependency sets must be defined once and derived programmatically**
+* Shell scripts are acceptable and preferred for system integration
+
+---
+
+## Required repository layout
+
+```
+scripts/
+  shepherd              # main CLI dispatcher
+  dev                   # thin wrapper → shepherd dev run
+  admin                 # optional wrapper → shepherd admin ...
+
+  lib/
+    common.sh            # logging, error handling, sudo helpers
+    deps.sh              # dependency set logic
+    build.sh             # cargo build logic
+    sway.sh              # nested sway execution helpers
+    install.sh           # binary + config installation
+    harden.sh            # harden / unharden user logic
+
+  deps/
+    build.pkgs           # build-only system packages
+    run.pkgs             # runtime-only system packages
+    dev.pkgs             # optional dev-only extras
+```
+
+No business logic should live in `Makefile` (if present).
+
+---
+
+## CLI interface (must be implemented)
+
+### Dependency management
+
+```
+shepherd deps print build|run|dev
+shepherd deps install build|run|dev
+```
+
+Behavior:
+
+* `build` = build.pkgs
+* `run` = run.pkgs
+* `dev` = union(build, run, dev.pkgs)
+* No duplicated lists anywhere
+
+The build packages are currently listed in the CI definition (./.github/workflows/ci.yml). The CI definition should be updated to use this script for package management.
+You may leave a stub for the runtime packages that only includes `sway`.
+
+You may assume Ubuntu 25.10 or higher. Warn but do not fail if the environment indicates otherwise.
+
+---
+
+### Build
+
+```
+shepherd build            # debug build
+shepherd build --release  # production build
+```
+
+Internals:
+
+* Wrap `cargo build`
+* Centralize binary names and target paths
+* No logic duplication in dev/run/install paths
+
+---
+
+### Development run
+
+```
+shepherd dev run
+```
+
+This should be functionally equivalent to what is currently in `./run-dev` and will serve as its replacement.
+
+Behavior:
+
+* Builds (debug)
+* Launches **nested sway**
+* Executes built binaries with correct environment
+
+This should reuse shared sway helpers (not inline logic).
+
+---
+
+### Installation (composable steps)
+
+Each step must be callable independently.
+
+```
+shepherd install bins [--prefix PREFIX]
+shepherd install config --user USER [--source CONFIG]
+shepherd install all --user USER [--prefix PREFIX]
+```
+
+Requirements:
+
+* Install release binaries to standard paths
+* Install our global Sway configuration to a standard path
+* Install desktop entry that tells the display manager to run shepherd-launcher via the Sway configuration (you will need to write this)
+* Support PREFIX and DESTDIR
+* Deploy example config to a specified user
+* Do not assume hardening is enabled
+
+---
+
+### User hardening (reversible)
+
+```
+shepherd harden apply  --user USER
+shepherd harden revert --user USER
+```
+
+Requirements:
+
+* Harden a user so it can only run shepherd-launcher
+* Support reverting to original system state
+* Persist rollback state under:
+
+  ```
+  /var/lib/shepherdd/hardening/<user>/
+  ```
+* Hardening and unharden must be idempotent
+
+No assumptions about display manager; logic should be isolated.
+
+---
+
+## Shared library responsibilities
+
+### `lib/common.sh`
+
+* Logging (`info`, `warn`, `error`)
+* `require_root`, `maybe_sudo`
+* Safe command execution helpers
+
+### `lib/deps.sh`
+
+* Read package lists
+* Compute unions
+* Install or print packages
+
+### `lib/build.sh`
+
+* Cargo build abstraction
+* Debug vs release handling
+* Binary discovery
+
+### `lib/sway.sh`
+
+* Nested sway environment setup
+* Command execution inside sway
+* Shared by dev and production paths
+
+### `lib/install.sh`
+
+* Binary install logic
+* Config deployment logic
+
+### `lib/harden.sh`
+
+* Apply hardening
+* Revert hardening
+* Track system state changes
+
+---
+
+## Wrapper scripts
+
+* `./run-dev` → `exec ./scripts/shepherd dev run`
+* Optional `Makefile` targets may call `shepherd`, but must contain no logic
+
+---
+
+## Non-goals
+
+* No Docker/Nix/devcontainer required
+* No GUI tooling
+* No distro-specific packaging beyond apt-style package lists
+* No Rust rewrite of scripts unless strictly necessary
+
+---
+
+## Acceptance criteria
+
+* CI can install **only build deps** and run `shepherd build`
+* Runtime system can install **only run deps**
+* Developer can install **dev deps** and run `./run-dev`
+* Admin can:
+
+  * install binaries
+  * deploy config
+  * harden and unharden a user safely
+* No duplicated dependency lists
+* No duplicated build or sway logic