Make uv base installation the clear first-user path

README.md

@@ -9,7 +9,7 @@ and any errors.
 In a JSONL exporter experiment, checks through the real command line caught
 three defects that serializer-only tests missed.
 [Read the historical 1.3.0 experiment and its limits](https://github.com/Smart-AI-Memory/attune-harness/blob/v1.3.0/docs/plan-build-native-results.md).
-For a small working example, see [how checks and receipts work](https://github.com/Smart-AI-Memory/attune-harness/blob/ca55b3aa39c0b8e003c0523244db9da14f901d23/docs/cli-guide.md#checks-and-receipts).
+For a small working example, see [how checks and receipts work](https://github.com/Smart-AI-Memory/attune-harness/blob/69f645bd4f471926554d1919c92b8cad2b06274d/docs/cli-guide.md#checks-and-receipts).
 
 **1.4.0 · saved forms and readable consultation evidence.**
 This guide describes the 1.4.0 package and its supported limits.
@@ -22,7 +22,7 @@ The v1 compatibility contract remains in effect; experimental features and
 platform limits are listed below.
 [Qualification status](#what-is-qualified-and-what-is-not).
 
-[Install Attune Harness](#installation) · [User guide](https://github.com/Smart-AI-Memory/attune-harness/blob/ca55b3aa39c0b8e003c0523244db9da14f901d23/docs/cli-guide.md)
+[Install Attune Harness](#installation) · [User guide](https://github.com/Smart-AI-Memory/attune-harness/blob/69f645bd4f471926554d1919c92b8cad2b06274d/docs/cli-guide.md)
 
 ## Plan, build, review, fix, and test
 
@@ -62,7 +62,7 @@ participants need `--allow-external`, and native model participants also need
 Many of these commands are there for the agent and its integrations to call.
 Learning their syntax is not the price of entry, and `attune-harness COMMAND --help`
 covers direct use. Full usage, exit codes and recovery controls are in the
-[CLI guide](https://github.com/Smart-AI-Memory/attune-harness/blob/ca55b3aa39c0b8e003c0523244db9da14f901d23/docs/cli-guide.md).
+[CLI guide](https://github.com/Smart-AI-Memory/attune-harness/blob/69f645bd4f471926554d1919c92b8cad2b06274d/docs/cli-guide.md).
 
 ## Use Harness with Codex, Claude, or other models
 
@@ -74,7 +74,7 @@ execution permissions. The older `/attune` command belongs to Attune AI.
 
 For an **Attune Harness** entry in Codex Plugins, use the
 [plugin packaging and installation guide](https://github.com/Smart-AI-Memory/attune-harness/blob/ca55b3aa39c0b8e003c0523244db9da14f901d23/docs/codex-plugin.md). You can also use
-[standalone skill discovery](https://github.com/Smart-AI-Memory/attune-harness/blob/ca55b3aa39c0b8e003c0523244db9da14f901d23/docs/cli-guide.md#codex-skill) in this checkout or
+[standalone skill discovery](https://github.com/Smart-AI-Memory/attune-harness/blob/69f645bd4f471926554d1919c92b8cad2b06274d/docs/cli-guide.md#codex-skill) in this checkout or
 another project. Installing the Python package alone installs neither integration.
 
 In **Claude Code**, add this repository as a plugin marketplace, then install the
@@ -93,14 +93,20 @@ paid calls.
 
 ## Installation
 
+Start with a managed base installation:
+
 ```sh
-pipx install 'attune-harness[all]==1.4.0'
+uv tool install 'attune-harness==1.4.0'
 ```
 
-or `uv tool install 'attune-harness[all]==1.4.0'`, or `pip install 'attune-harness[all]==1.4.0'`
-into an environment of its own. This is the recommended install: everything the
-review, test, MCP and acceptance journeys need, plus Redis and Voyage retrieval.
-Python 3.10 or later. The [worked example](https://github.com/Smart-AI-Memory/attune-harness/blob/ca55b3aa39c0b8e003c0523244db9da14f901d23/docs/cli-guide.md#checks-and-receipts) needs no API key or attune-ai installation;
+uv keeps Harness and its dependencies isolated and provides the `attune-harness`
+command. The base includes forms, verification, local retrieval, review, test,
+MCP and acceptance dependencies. Add Redis or Voyage when needed; `all` includes
+both. See the [installation and getting-started guide](https://github.com/Smart-AI-Memory/attune-harness/blob/69f645bd4f471926554d1919c92b8cad2b06274d/docs/installation.md)
+for executable checks, optional profiles, pipx/pip alternatives and separate
+agent-plugin setup.
+
+Python 3.10 or later. The [worked example](https://github.com/Smart-AI-Memory/attune-harness/blob/69f645bd4f471926554d1919c92b8cad2b06274d/docs/cli-guide.md#checks-and-receipts) needs no API key or attune-ai installation;
 Voyage retrieval needs a Voyage API key and makes paid calls.
 Harness and attune-ai cannot share one environment:
 they pin different lines of the MCP SDK, and installing Harness over attune-ai
@@ -111,10 +117,10 @@ if it finds the two side by side.
 
 | You want | Install |
 | --- | --- |
-| **Recommended:** the base package plus the Redis reader and Voyage retrieval. The experimental extra below stays explicit | `pip install 'attune-harness[all]==1.4.0'` |
-| The contracts and CLI; the evidence-review, test, acceptance and MCP journeys: forms (`attune-forms` 0.17.0), document claim verification (`attune-verify` 0.6.0), local Markdown retrieval with source hashes (`attune-rag` 1.2.0), MCP stdio serving (`mcp` 2.2.0) and token counting (`tiktoken` 0.12.0). No model calls | `pip install 'attune-harness==1.4.0'` |
+| **Recommended base:** the contracts and CLI; the evidence-review, test, acceptance and MCP journeys: forms (`attune-forms` 0.17.0), document claim verification (`attune-verify` 0.6.0), local Markdown retrieval with source hashes (`attune-rag` 1.2.0), MCP stdio serving (`mcp` 2.2.0) and token counting (`tiktoken` 0.12.0). No model calls | `pip install 'attune-harness==1.4.0'` |
 | Read the Redis memory a hydration keeps warm: the recall digest, related nodes, one record, full-text search over the index (`redis` 5.3.1); read-only, the `text` body of a file, lesson or rule pointer is never served; needs a reachable Redis Stack with the hydration's index and function library. Also the Redis backend for working memory (`memory scratch`), shared across processes and machines; the file backend is in the base | `pip install 'attune-harness[redis]==1.4.0'` |
 | Repository-first retrieval on Voyage embeddings. Needs a Voyage API key, makes paid calls | `pip install 'attune-harness[voyage]==1.4.0'` |
+| The base plus both Redis and Voyage; experimental native memory stays separate | `pip install 'attune-harness[all]==1.4.0'` |
 | Experimental: memory proposals from a Claude model over a pinned, data-only Anthropic API transport (`anthropic` 1.6.0, `httpx2` 2.13.0). POSIX only, needs `ANTHROPIC_API_KEY`, makes paid calls | `pip install 'attune-harness[memory-native]==1.4.0'` |
 
 Before 0.4.0 the base had no dependencies and `verify`, `rag`, `review`, `mcp`
@@ -206,7 +212,7 @@ journey, its current boundary and what to keep using while a successor is qualif
 ## Links
 
 - [Qualification guide (1.3.0 baseline)](https://github.com/Smart-AI-Memory/attune-harness/blob/v1.3.0/docs/qualification.md)
-- [CLI guide](https://github.com/Smart-AI-Memory/attune-harness/blob/ca55b3aa39c0b8e003c0523244db9da14f901d23/docs/cli-guide.md)
+- [CLI guide](https://github.com/Smart-AI-Memory/attune-harness/blob/69f645bd4f471926554d1919c92b8cad2b06274d/docs/cli-guide.md)
 - [Portable contract (1.3.0 baseline)](https://github.com/Smart-AI-Memory/attune-harness/blob/v1.3.0/docs/portable-contract.md)
 - [Repository](https://github.com/Smart-AI-Memory/attune-harness) and
   [issues](https://github.com/Smart-AI-Memory/attune-harness/issues)

docs/README.md

@@ -12,6 +12,7 @@ Generated on September 22, 2026 from the 191 Markdown files under
 
 ## Start here
 
+- [Install Harness and get started](installation.md): Managed base installation, optional integrations, executable checks and separate agent-plugin setup
 - [Writing and entered-text guide](writing-guide.md): Approved Google writing baseline, UI instructions, and user-entered text presentation
 - [First checked repair with Harness 1.3.0](first-repair-1.3.0.md): Fresh setup, current bound approval, pause/resume and unchanged-check evidence; deterministic participant limits
 - [Four training walkthroughs for Harness 1.3.0](tutorials-1.3.0.md): Action sequences, visible results and release limits shared with the PowerPoint and HTML tutorials

docs/cli-guide.md

@@ -13,15 +13,20 @@ environment. The [preparation readiness record](release-readiness-1.4.0.md) reta
 dated checks and source identities; its older preparation statements are
 historical, rather than installation instructions.
 
+Start with a managed base installation:
+
 ```sh
-pipx install 'attune-harness[all]==1.4.0'
+uv tool install 'attune-harness==1.4.0'
 ```
 
-or `uv tool install 'attune-harness[all]==1.4.0'`, or `pip install 'attune-harness[all]==1.4.0'`
-into an environment of its own. This is the recommended install: everything the
-review, test, MCP and acceptance journeys need, plus Redis and Voyage retrieval.
-Python 3.10 or later. The example below needs no API key or attune-ai installation;
-Voyage retrieval needs a Voyage API key and makes paid calls.
+The base carries the forms, verification, local retrieval, review, test, MCP and
+acceptance dependencies. Add Redis or Voyage when you need those integrations;
+`all` includes both and excludes experimental native memory. Python 3.10 or later.
+The [installation guide](installation.md) covers executable checks, alternatives,
+optional profiles, selection of the managed Python interpreter for module and
+fixture commands, and separate host-plugin setup. The example below needs no
+API key or attune-ai installation; Voyage retrieval needs a Voyage API key and
+makes paid calls.
 Harness and attune-ai cannot share one environment:
 they pin different lines of the MCP SDK, and installing Harness over attune-ai
 replaces attune-ai's; an isolated install avoids that, and `mcp-serve` says so
@@ -54,7 +59,9 @@ output and the check's evidence still attached. If the participant or the check
 raises, the status is `failed` and the receipt names the stage and the error. `run`
 executes once. It never retries on its own.
 
-`python -m attune_harness` runs the installed demonstration and prints a JSON receipt.
+`attune-harness` with no arguments runs the installed demonstration and prints a
+JSON receipt. For `python -m` commands or Python API examples, use the
+[selected runtime's interpreter](installation.md#select-python-for-module-and-fixture-examples).
 
 ## How people and AI work together
 

docs/installation.md

@@ -0,0 +1,132 @@
+# Install Harness and get started
+
+Use this guide for the released `attune-harness` 1.4.0 runtime. Python 3.10 or
+later is required. Start with the base package: it includes forms, document
+verification, local Markdown retrieval, MCP serving and token counting. Redis
+and Voyage are optional integrations.
+
+## Install the runtime
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if it is not
+already available. Then install Harness:
+
+```sh
+uv tool install 'attune-harness==1.4.0'
+```
+
+uv manages an isolated environment and exposes the `attune-harness` command;
+you do not need to create or activate a project virtual environment. See
+[uv's tool guide](https://docs.astral.sh/uv/guides/tools/) for how it manages
+executables and dependencies. Keep Harness and Attune AI in separate
+environments: they require different MCP SDK versions.
+
+Check the selected installation:
+
+```sh
+uv tool list --show-paths
+attune-harness --help
+```
+
+Expect `attune-harness v1.4.0` in the tool list and the command help with
+`init`, `plan`, `build`, `review`, `fix`, `test`, `status` and `resume`.
+If the command is not found, follow uv's reported executable-directory guidance
+or its tool guide before continuing.
+
+If Harness is already installed, inspect its version and path before changing
+it. A version-pinned `uv tool upgrade attune-harness` respects the existing pin;
+install the newly selected version explicitly when you choose to update.
+Preserve saved task directories and separately retained evidence environments.
+Changing the tool version does not qualify migration of older saved work.
+
+You can also install the base package with
+`pipx install 'attune-harness==1.4.0'`, or use
+`pip install 'attune-harness==1.4.0'` in a dedicated virtual environment.
+
+## Select Python for module and fixture examples
+
+The `attune-harness` command uses the managed runtime. Commands such as
+`python -m attune_harness.gui` and source-checkout fixture scripts also need
+that runtime's interpreter; an unrelated `python` command may not contain
+Harness. Use the environment path shown beside `attune-harness` in
+`uv tool list --show-paths`.
+
+For a normal uv installation, select it on macOS or Linux:
+
+```sh
+harness_python="$(uv tool dir)/attune-harness/bin/python"
+"$harness_python" -c "import importlib.metadata; print(importlib.metadata.version('attune-harness'))"
+"$harness_python" -m attune_harness
+```
+
+On Windows, use PowerShell:
+
+```powershell
+$harnessPython = Join-Path (uv tool dir) 'attune-harness\Scripts\python.exe'
+& $harnessPython -c "import importlib.metadata; print(importlib.metadata.version('attune-harness'))"
+& $harnessPython -m attune_harness
+```
+
+Expect version `1.4.0`, then a JSON receipt with status `verified` for the
+deterministic arithmetic example. If the listed environment is at a different
+path, use its `bin/python` on macOS/Linux or `Scripts\python.exe` on Windows.
+Substitute that same interpreter for `python` in module and fixture commands
+in the linked guides; for example, use `"$harness_python" -m attune_harness.gui`
+on macOS/Linux. The GUI still requires an existing registered task and the
+documented launch options. Check the selected interpreter's version before
+running those examples; no shell activation is needed.
+
+## Choose optional integrations when needed
+
+Select a profile when installing or deliberately updating your managed tool:
+
+| You need | Install |
+| --- | --- |
+| Forms, verification, local retrieval and the task workflows | `uv tool install 'attune-harness==1.4.0'` |
+| Redis memory access, with a separately configured reachable Redis service | `uv tool install 'attune-harness[redis]==1.4.0'` |
+| Voyage retrieval, with a Voyage API key and separate paid-call authority | `uv tool install 'attune-harness[voyage]==1.4.0'` |
+| Both Redis and Voyage | `uv tool install 'attune-harness[all]==1.4.0'` |
+
+Selecting another profile changes that tool's environment; it does not start a
+Redis service, configure credentials or authorize model calls. `all` excludes
+experimental native memory. For that separate profile and its platform limits,
+see the [CLI guide](cli-guide.md) and [qualification guide](qualification.md).
+
+## Connect the agent and open a first task
+
+The Python runtime and the agent integration are separate installations.
+Choose the host you use:
+
+- **Codex:** Follow the [Harness plugin guide](codex-plugin.md), or the
+  [standalone skill instructions](cli-guide.md#codex-skill). Confirm that the
+  selected integration uses the runtime checked above.
+- **Claude Code:** Follow the [README's marketplace instructions](../README.md#use-harness-with-codex-claude-or-other-models).
+  The marketplace installs the skills; the runtime remains separately installed.
+- **Direct CLI:** Read [checks and receipts](cli-guide.md#checks-and-receipts)
+  or use `attune-harness COMMAND --help` for the chosen task.
+
+Practice the [1.4.0 forms walkthrough](tutorials-next-release-candidate.md#save-and-approve-a-clear-work-request).
+Ask the agent or operator running Harness for a fresh practice form and its
+complete private launcher link. Saving answers, approving the request and
+executing work remain separate actions. Keep the launcher running while using
+the form; saved work is stored in its task directory, not in the launcher URL.
+
+## What was checked
+
+On October 12, 2026, the actual published 1.4.0 wheel was installed on macOS
+arm64 with Python 3.10.11 using both a fresh dependency-complete `[all]`
+environment and a separate uv 0.11.28 base tool environment. All 105 runtime
+modules matched the published source. Both environments passed the existing
+29-case offline CLI check and plan/accept/build/review/status journey with
+zero model calls. The base environment correctly reported Redis as absent.
+
+The base installation resolved 48 distributions and `[all]` resolved 93,
+excluding installer packages, on that machine. Counts vary by environment;
+this comparison does not establish equal feature coverage or measured speed.
+
+The release also passed the six installed-platform profiles described in the
+[qualification guide](qualification.md). Those profiles are separate from
+this Mac uv experiment. A fresh uv install on Linux or Windows, an existing-tool
+upgrade, native browser comprehension and saved-work migration were not
+established by the experiment. The published
+[release](https://github.com/Smart-AI-Memory/attune-harness/releases/tag/v1.4.0)
+links the exact source, publishing run and archive checksums.