feat(launcher): add 'just run'/'just launch' + rewrite QUICKSTART-USER

The user-facing launcher was missing: the Justfile had no run/setup/install
recipe, and QUICKSTART-USER.adoc was an unfilled RSR template promising
'just run', 'just setup', 'just uninstall', 'just stapeln-run' — none of which
existed.

- Add 'just run *ARGS' (alias 'just launch'): builds and starts the interactive
  vsh shell, passing extra args through to the binary. Verified end-to-end:
  'just run --version' -> vsh 0.9.0 (exit 0); the REPL banner starts; and
  'just run <script>' executes and exits 0.
- Rewrite QUICKSTART-USER.adoc to the real, working flow. Every 'just' command
  it cites is a real recipe (verified via 'just --show'): run/launch, build-cli,
  install-cli, test-cli, container-build/run/shell, doctor, heal, tour, help-me,
  clean. Uninstall documents the honest 'cargo uninstall vsh' path. Removes the
  template placeholder/instruction cruft.
- Point the wiki For-Users page at 'just run' as the primary launch path.

Note: full alignment to the external launcher standard (hyperpolymath/standards)
is not attempted here — that repo is outside this session's scope. This adds a
real, verified launch entry point consistent with what the quickstart promised.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KfgJznd6jzSeDYsSXGAXkU

Author: claude

CHANGELOG.adoc

@@ -17,6 +17,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Full POSIX shell compliance (subset)
 - RMO (Remove-Match-Obliterate) proofs for GDPR compliance
 
+=== Added — 2026-07-16
+
+==== Launcher
+- `just run` (alias `just launch`) — the user-facing launcher for the `vsh`
+  shell, previously missing. Builds and starts the interactive REPL; passes
+  extra arguments through to the binary (`just run --version`,
+  `just run script.vsh`). Verified end-to-end: `--version` prints `vsh 0.9.0`
+  (exit 0), the REPL banner starts interactively, and script execution runs and
+  exits 0.
+- `QUICKSTART-USER.adoc` rewritten from the unfilled RSR template to the real,
+  working flow — it no longer references non-existent recipes (`just setup`,
+  `just uninstall`, `just stapeln-run`, `just install --portable`); every `just`
+  command it now cites is a real recipe (verified via `just --show`). Uninstall
+  documents the honest `cargo uninstall vsh` path.
+
 === Verified — 2026-07-16
 
 ==== Proofs

Justfile

@@ -4,6 +4,9 @@
 # Default recipe - show available commands
 import? "contractile.just"
 
+# `just launch` is a synonym for `just run` (launch the vsh shell)
+alias launch := run
+
 default:
     @just --list
 
@@ -123,6 +126,14 @@ test-cli:
     cd impl/rust-cli && cargo test
     @echo "✓ Rust CLI tests passed"
 
+# Launch the interactive vsh shell (the primary deliverable). Extra args pass
+# through to the binary:
+#   just run              # start the interactive REPL
+#   just run --version    # print version and exit
+#   just run script.vsh   # run a script
+run *ARGS:
+    cd impl/rust-cli && cargo run -- {{ARGS}}
+
 # Build all FFI layers
 build-ffi: build-ffi-zig build-ffi-ocaml
     @echo "✓ All FFI layers built"

QUICKSTART-USER.adoc

@@ -1,125 +1,123 @@
 // SPDX-License-Identifier: CC-BY-SA-4.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
-// Template: QUICKSTART-USER.adoc — 5-minute path to working software
-// Replace valence-shell, Valence Shell — See README.adoc for details., just run, Valence Shell started successfully. with actuals
 = valence-shell — Quick Start for Users
 :toc:
 :toclevels: 2
 
 == What is valence-shell?
 
-Valence Shell — See README.adoc for details.
+Valence Shell (`vsh`) is a formally verified, reversible Unix-style shell: its
+core filesystem operations are backed by machine-checked proofs, and it provides
+a proven undo/redo layer, named checkpoints, and proof-annotated dry runs. See
+link:README.adoc[README.adoc] for the full overview.
 
-== Prerequisites
-
-Before you begin, ensure you have:
-
-* **just** — task runner (https://github.com/casey/just[install guide])
-* Platform-specific requirements listed below
-
-[cols="1,3"]
-|===
-| Platform | Additional Requirements
+[IMPORTANT]
+====
+v0.9.0 is an **advanced research prototype — NOT production-ready**. Great for
+learning and experimentation; do not use it as your login shell or trust it with
+irreplaceable data.
+====
 
-| Linux
-| See README.adoc
-
-| macOS
-| See README.adoc
+== Prerequisites
 
-| Windows
-| See README.adoc
-|===
+* **Rust toolchain 1.88+** — to build and run the `vsh` CLI
+  (https://rustup.rs[install via rustup]).
+* **just** — task runner (https://github.com/casey/just[install guide]).
 
-== Install
+The six proof systems (Coq, Lean 4, Agda, Isabelle, Mizar, Z3) are **optional** —
+they are only needed to re-check the formal proofs, not to build or run the shell.
 
-=== Option 1: Standard Install (recommended)
+== Launch it (fastest path)
 
 [source,bash]
 ----
-# Clone and set up
 git clone https://github.com/hyperpolymath/valence-shell.git
 cd valence-shell
-just setup
-----
-
-The setup script will:
 
-* Detect your platform and shell
-* Install missing dependencies (with your permission)
-* Configure the application
-* Offer install location choices
-* Run a self-diagnostic to verify everything works
+just run          # build (debug) and start the interactive shell
+# or, equivalently:
+just launch
+----
 
-=== Option 2: Container (via Stapeln)
+`just run` passes any extra arguments through to the binary:
 
 [source,bash]
 ----
-just stapeln-run
+just run --version        # print version and exit
+just run path/to/script   # execute a script non-interactively
 ----
 
-=== Option 3: Portable (no system changes)
+Expected first-run output is the `vsh` banner followed by an interactive prompt.
+Type `help` for commands, `undo` to reverse the last operation, and `exit` to
+leave.
+
+== Build / install
 
 [source,bash]
 ----
-just install --portable --prefix=./valence-shell-portable
+just build-cli     # release build -> impl/rust-cli/target/release/vsh
+just install-cli   # cargo install to ~/.cargo/bin (then just run `vsh`)
+just test-cli      # run the CLI test suite
 ----
 
-== First Run
+After `just install-cli`, the `vsh` binary is on your `PATH`:
 
 [source,bash]
 ----
-just run
+vsh --version
+vsh                # start the shell
 ----
 
-Expected output:
+You can also drive Cargo directly if you prefer:
 
-[source]
+[source,bash]
 ----
-Valence Shell started successfully.
+cd impl/rust-cli
+cargo run                       # start the interactive shell
+cargo build --release           # build the release binary
+./target/release/vsh --version
 ----
 
-== Self-Diagnostic
-
-If something isn't working:
+== Run in a container
 
 [source,bash]
 ----
-just doctor
+just container-build    # build the container image (uses Containerfile)
+just container-run      # run verification in the container
+just container-shell    # interactive shell inside the container
 ----
 
-This checks all dependencies, permissions, paths, and connectivity.
-If it finds issues, it will suggest fixes.
-
-To attempt automatic repair:
+== Self-diagnostic
 
 [source,bash]
 ----
-just heal
+just doctor    # check required tools, hardcoded paths, environment
+just heal      # attempt automatic repair (permissions, stale caches)
 ----
 
-== Get Help
+== Get help
 
-* **In-app**: `just run --help`
 * **Guided tour**: `just tour`
-* **Report a problem**: `just help-me` (pre-fills diagnostic context)
+* **Report a problem** (pre-fills platform diagnostics): `just help-me`
+* **All recipes**: `just --list`
+* **In-shell help**: type `help` at the `vsh` prompt, or `vsh --help`
 * **Wiki**: https://github.com/hyperpolymath/valence-shell/wiki
 
 == Uninstall
 
+If you installed with `just install-cli` (which uses `cargo install`):
+
 [source,bash]
 ----
-just uninstall
+cargo uninstall vsh
 ----
 
-You will be asked:
-
-1. Which uninstall tier (Bennett reversible, parameter-based, standard, or secure)
-2. Whether to include or exclude your data
-3. Whether to clear caches and LLM models
+A source checkout leaves nothing outside the repository directory — delete the
+clone to remove it. Build artifacts can be cleared with `just clean`.
 
-== Next Steps
+== Next steps
 
-* Read the link:README.adoc[README] for full feature overview
-* Read the link:EXPLAINME.adoc[EXPLAINME] for architecture and design decisions
-* Try `just tour` for a guided walkthrough
+* link:README.adoc[README] — full feature overview and verification status
+* link:EXPLAINME.adoc[EXPLAINME] — architecture and the claims-vs-evidence trail
+* link:docs/USER_GUIDE.md[User Guide] — detailed usage
+* link:FAQ.adoc[FAQ] — common questions

docs/wiki/For-Users.md

@@ -18,18 +18,21 @@ detailed canonical guides live in the repository and are linked throughout.
 ## Install & run (the short path)
 
 The interactive shell is the Rust CLI in `impl/rust-cli/`. It needs only a Rust
-toolchain (1.88+); the six proof systems are **optional** and only needed if you
-want to re-check the proofs yourself.
+toolchain (1.88+) and [`just`](https://github.com/casey/just); the six proof
+systems are **optional** and only needed if you want to re-check the proofs
+yourself.
 
 ```bash
 git clone https://github.com/hyperpolymath/valence-shell.git
-cd valence-shell/impl/rust-cli
+cd valence-shell
 
-cargo build --release            # builds the `vsh` binary
-cargo run                        # start the interactive shell
-./target/release/vsh --version   # or run the release binary directly
+just run              # build and launch the interactive shell (alias: just launch)
+just run --version    # print version and exit
+just install-cli      # install `vsh` to ~/.cargo/bin, then just run `vsh`
 ```
 
+Prefer Cargo directly? `cd impl/rust-cli && cargo run` does the same thing.
+
 Canonical, longer install guide (containers, portable install, self-diagnostics):
 [`QUICKSTART-USER.adoc`](https://github.com/hyperpolymath/valence-shell/blob/main/QUICKSTART-USER.adoc).