Restructure docs around conversational role dispatch

docs/artifact-lifecycle.md

@@ -46,6 +46,35 @@ working directory, worker process identity, thread continuity, usage, and
 verification. `result` intentionally reads the raw last-message artifact; its
 presence does not assert successful completion.
 
+## Receipt evidence
+
+A completed receipt includes evidence like:
+
+```json
+{
+  "state": "completed",
+  "role": "reviewer",
+  "requested": {
+    "model": "gpt-5.6-terra",
+    "effort": "medium"
+  },
+  "declaredSandboxMode": "read-only",
+  "effectivePolicy": {
+    "executionMode": "sandboxed",
+    "effectiveSandbox": "read-only",
+    "approvalBehavior": "never"
+  },
+  "threadId": "...",
+  "processExitStatus": 0,
+  "terminalEventType": "turn.completed",
+  "verificationErrors": []
+}
+```
+
+Together, the receipt, event stream, and final-message artifact record what the
+runner requested, what Codex emitted, and whether transport verification
+succeeded. They do not prove semantic compliance with the role instructions.
+
 ## Completion and interruption
 
 `status.json` is the terminal commit marker. Terminal publication writes the

docs/installation.md

@@ -0,0 +1,153 @@
+# Installation
+
+## Requirements
+
+Version 0.1 supports directly selected native-Linux hosts and requires:
+
+- Python 3.11 or newer with `venv` support;
+- the Codex CLI on `PATH`;
+- either `curl` or `wget`; and
+- `sha256sum` and the standard GNU/Linux userland used by the installer.
+
+Python 3.11, 3.12, and 3.13 are tested. The command and installer reject
+macOS, WSL, native Windows, and unknown platforms before creating package
+state, run artifacts, handles, or worker processes.
+
+## Stable installer
+
+Install or update with `curl`:
+
+```bash
+curl -fsSL https://antoinezambelli.github.io/codex-exec-subagents/install.sh | sh
+```
+
+If `curl` is unavailable, use `wget`:
+
+```bash
+wget -qO- https://antoinezambelli.github.io/codex-exec-subagents/install.sh | sh
+```
+
+The installer creates and manages its own private virtual environments. It
+does not install system packages, use `sudo`, or edit shell startup files.
+
+### Inspect before running
+
+Piping a remote script to a shell executes code that may have changed since
+you last reviewed it. Download and inspect the same script first if that is not
+appropriate for your environment:
+
+```bash
+curl -fsSLo install.sh \
+  https://antoinezambelli.github.io/codex-exec-subagents/install.sh
+less install.sh
+sh ./install.sh
+```
+
+### Versions, updates, and rollback
+
+Pin a normalized stable version:
+
+```bash
+sh ./install.sh --version 0.1.0
+```
+
+Rerun the unpinned installer to update, or rerun a version pin to install or
+verify that exact release. The installer verifies the tagged wheel against its
+published checksum, stages and probes a new environment, and only then
+promotes it. A failed update leaves the previous verified command usable.
+
+Older environments remain until uninstall so detached processes can finish.
+Pin an earlier hosted version to roll back.
+
+### Locations and `PATH`
+
+The default private installation root is
+`~/.local/share/codex-exec-subagents/`. The public command link is placed in
+`~/.local/bin/`.
+
+Custom paths, including paths with spaces, are supported:
+
+```bash
+sh ./install.sh \
+  --install-root "$HOME/tools/codex-exec-subagents" \
+  --bin-dir "$HOME/tools/bin"
+```
+
+If the selected bin directory is not an exact colon-delimited `PATH`
+component, the installer prints the `export PATH=...` command needed for the
+current shell. It does not edit shell startup files. Changing `--bin-dir`
+requires uninstall and reinstall.
+
+### Uninstall
+
+If you kept the inspected installer, reuse it with the same path overrides
+used for installation:
+
+```bash
+sh ./install.sh --uninstall
+```
+
+A piped install does not retain `./install.sh`. Obtain and inspect a fresh copy
+before uninstalling:
+
+```bash
+INSTALLER_COPY="$(mktemp)"
+curl -fsSLo "$INSTALLER_COPY" \
+  https://antoinezambelli.github.io/codex-exec-subagents/install.sh
+less "$INSTALLER_COPY"
+sh "$INSTALLER_COPY" --uninstall
+rm -f "$INSTALLER_COPY"
+```
+
+For a custom installation, repeat the exact paths:
+
+```bash
+sh "$INSTALLER_COPY" --uninstall \
+  --install-root "$HOME/tools/codex-exec-subagents" \
+  --bin-dir "$HOME/tools/bin"
+```
+
+Uninstall validates ownership markers and exact links, removes only recognized
+installer slots and bookkeeping, and preserves unknown files. It never
+inspects or removes a run root.
+
+## pipx
+
+`pipx` exposes the same runtime CLI:
+
+```bash
+pipx install codex-exec-subagents
+# or pin one stable release
+pipx install codex-exec-subagents==0.1.0
+```
+
+Update or uninstall with:
+
+```bash
+pipx upgrade codex-exec-subagents
+pipx uninstall codex-exec-subagents
+```
+
+Only `install.sh` provides the project-specific checksum verification, staged
+promotion, retained environments, and ownership-aware uninstall described
+above.
+
+## Development from source
+
+```bash
+git clone https://github.com/antoinezambelli/codex-exec-subagents.git
+cd codex-exec-subagents
+python3 -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+source .venv/bin/activate
+codex-exec-subagents --version
+```
+
+The default test command runs the fast unit suite. The green gate adds real
+subprocess, Git-boundary, release, installer, and other host-level integration
+tests under one 180-second wall-clock limit:
+
+```bash
+.venv/bin/python -m pytest
+.venv/bin/python scripts/green_gate.py
+```

docs/security.md

@@ -0,0 +1,57 @@
+# Security, privacy, and retention
+
+## Trust boundary
+
+The protection target is accidental exposure or deletion on a trusted,
+single-user native-Linux account. The package does not claim to isolate
+hostile users, root, or a compromised host.
+
+Owner-only permissions and ownership markers are not encryption. The package
+does not provide remote storage, scheduling, automatic retention, multi-user
+isolation, or protection from someone who already controls the account or
+host.
+
+## Persisted data
+
+Until explicit successful pruning, local artifacts may retain:
+
+- prompts and developer instructions;
+- role definitions, paths, and hashes;
+- task working directories;
+- model events, stderr, and final messages;
+- status, receipts, usage, and thread-continuity metadata; and
+- process identifiers and execution-policy evidence.
+
+Invocation text and command arguments may also be visible through local
+process inspection while a run is active. Review prompts and results for
+credentials, private repository content, personal data, and secrets. Do not
+commit raw run output without reviewing it.
+
+## Sandboxed and YOLO execution
+
+Sandboxed mode is the public default. It applies a role's declared read-only or
+workspace-write sandbox with approvals set to `never`.
+
+YOLO removes both approval and sandbox boundaries. Use it only when the role,
+prompt, repository, account, and host are trusted. Neither mode makes prompt
+instructions a dependable defense against hostile input.
+
+## What receipts prove
+
+Receipts, status, event streams, and final-message artifacts record what the
+runner requested, what Codex emitted, the effective execution policy, process
+outcome, verification errors, and exact thread continuity.
+
+They provide durable transport and configuration evidence. They do not attest
+that the model understood or semantically complied with its role. Review the
+result and any filesystem or repository changes independently.
+
+## Retention and deletion
+
+There is no automatic retention schedule. `prune` removes only recognizable,
+validated terminal handles and retains anything active or ambiguous. Installer
+updates and uninstall do not inspect or delete run roots.
+
+See [Roles and usage](usage.md#run-roots-and-pruning) for the commands and the
+[artifact lifecycle and local-security contract](artifact-lifecycle.md) for
+the exact permissions, publication, interruption, and pruning behavior.