docs: define capability and authority boundaries

README.md

@@ -65,6 +65,13 @@ write_authority=NONE
 promotion_authority=NONE
 ```
 
+## Capability boundaries
+
+Simulation_Invariant deliberately separates portable observation and evidence
+verification from the Linux/POSIX containment required by the full candidate
+executor. Read the [capability boundary](docs/CAPABILITY_BOUNDARIES.md) before
+interpreting a receipt, status, skip, or validated candidate.
+
 ## Contributing
 
 Contributions are welcome when they preserve the project's evidence and authority boundaries. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

docs/CAPABILITY_BOUNDARIES.md

@@ -0,0 +1,52 @@
+# Capability boundaries
+
+Simulation_Invariant records what was observed and verified inside a bounded
+cycle. It does not turn that evidence into authority over the source.
+
+## Current surfaces
+
+| Surface | Platform boundary | What it establishes | Authority |
+| --- | --- | --- | --- |
+| `simulation-invariant monitor` | Windows and POSIX | A read-only environment coverage packet for the selected root and exclusions | None |
+| `simulation-invariant inspect` | Windows and POSIX | A bounded byte presentation and hash-bound presentation receipt | None |
+| Presentation and evidence verification | Windows and POSIX | Structural, hash, range, and chain checks declared by each verifier | None |
+| Candidate observation, copying, and patching | Tested according to each component's declared platform properties | A disposable candidate can be compared with bound source and expected tree states | Candidate only |
+| Full bounded-candidate executor | Linux/POSIX with mount, network, and PID namespace support | Declared tests ran against the approved candidate input while the named executor properties held | None |
+| Wheel and console command | Python 3.10+ on Windows and Linux CI | The package builds, installs, and exposes the existing dispatcher | None |
+
+Platform-specific tests skip when a required property cannot be established.
+A skip records an unavailable check; it is not a successful verification.
+
+## Status meanings
+
+- `VALIDATED_CANDIDATE` closes one candidate-validation cycle. It does not mean
+  accepted, promoted, deployed, merged, or written to the source.
+- `STOP` means no further action remains inside the current bounded task. New evidence can start a later task.
+- `PASS` applies only to the checks named by the receipt that carries it.
+- `STALE`, `UNKNOWN`, `BLOCKED`, and `FAILED` cannot be interpreted as
+  acceptance.
+
+Every result is bound to its recorded source identity, policy, inputs, and
+observation moment. A later environmental difference requires a new check.
+
+## Explicitly absent
+
+The project currently provides no:
+
+- live source writer;
+- promotion or deployment command;
+- package-publishing workflow;
+- autonomous permission escalation;
+- inherited acceptance, truth, or semantic-understanding authority;
+- guarantee that a validated candidate remains current after its final bound
+  observation.
+
+The bounded-candidate result therefore retains:
+
+```text
+write_authority=NONE
+promotion_authority=NONE
+```
+
+Humans or external systems may make later decisions, but those decisions are
+separate evidence and require their own explicit contract.

tests/test_capability_boundaries.py

@@ -0,0 +1,42 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+README = ROOT / "README.md"
+BOUNDARIES = ROOT / "docs" / "CAPABILITY_BOUNDARIES.md"
+
+
+def _boundaries() -> str:
+    return BOUNDARIES.read_text(encoding="utf-8")
+
+
+def test_readme_links_capability_boundary() -> None:
+    readme = README.read_text(encoding="utf-8")
+    assert "[capability boundary](docs/CAPABILITY_BOUNDARIES.md)" in readme
+
+
+def test_platform_boundary_distinguishes_portable_and_namespace_surfaces() -> None:
+    text = _boundaries()
+    assert "Windows and POSIX" in text
+    assert "Linux/POSIX with mount, network, and PID namespace support" in text
+    assert "A skip records an unavailable check" in text
+
+
+def test_validated_candidate_and_stop_are_bounded() -> None:
+    text = _boundaries()
+    assert "`VALIDATED_CANDIDATE` closes one candidate-validation cycle" in text
+    assert "`STOP` means no further action remains inside the current bounded task" in text
+    assert "New evidence can start a later task" in text
+
+
+def test_absent_authorities_are_explicit() -> None:
+    text = _boundaries()
+    for absent in (
+        "live source writer",
+        "promotion or deployment command",
+        "package-publishing workflow",
+        "autonomous permission escalation",
+    ):
+        assert absent in text
+    assert "write_authority=NONE" in text
+    assert "promotion_authority=NONE" in text