post-bootstrap doc refinements: tagline, philosophy, install instructions, constitution wording, templates/ description, doc maintenance section

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sweverett

CLAUDE.md

@@ -30,7 +30,7 @@ src/parallax/           # Main package
   cli/                  # Typer CLI commands
   core/                 # Hypothesis, state, templates, workflow logic
   db/                   # SQLite models + queries
-templates/              # Templates Parallax generates for user projects
+templates/              # Source templates rendered by parallax init into user projects
 tests/                  # pytest
 docs/                   # VISION.md, ROADMAP.md, plans/
 .claude/skills/         # Claude Code skills for Parallax development
@@ -99,6 +99,12 @@ pixi run check       # all of the above
 - Never add backward-compat shims — just change the code
 - Never create docs/READMEs unless explicitly requested
 
+## Documentation Maintenance
+
+- At the end of every plan, verify README.md and other markdown docs reflect current state
+- If code changes affect documented behavior, update the relevant docs in the same PR
+- @README.md and other key docs should be reviewed before marking any plan complete
+
 ## References
 
 - @CONSTITUTION.md — core scientific values (import into agent context)

CONSTITUTION.md

@@ -5,9 +5,9 @@ These are *values*, not procedures. They inform decision-making at every level.
 
 ## Principles
 
-1. **Robust science over fast science.** Accelerate as fast as possible but no faster. Speed is a means, not an end.
+1. **Robust science over fast science.** Accelerate as fast as is safe, quantifiable, and verifiable, but no faster.
 
-2. **NEVER weaken tests to pass.** Loud failure over silent success. If a test fails, the code is wrong or the test expectations need explicit human review — never quietly relax tolerances.
+2. **NEVER weaken tests to pass — unless a human user explicitly instructs it.** Loud failure over silent success. If a test fails, the code is wrong or the test expectations need explicit human review — never quietly relax tolerances.
 
 3. **Hypotheses before implementation.** Think before you code. Formalize what you expect and why before writing the first line.
 

README.md

@@ -2,11 +2,13 @@
 
 Scientific augmentation tool encoding best practices for reproducible, hypothesis-driven science into agentic AI workflows.
 
-Two perspectives (human + AI) to get a stronger result.
+*True depth requires two lines of sight.*
 
 ## Philosophy
 
-Accelerate excellent science — but no faster than that. AI supplements scientific work, never drives it. See [CONSTITUTION.md](CONSTITUTION.md) for core values.
+Accelerate as fast as is safe, quantifiable, and verifiable — but no faster. Parallax encodes scientific best practices into agentic AI workflows so that speed gains never come at the cost of rigor, reproducibility, or correctness. AI supplements scientific work; it never drives it.
+
+See [CONSTITUTION.md](CONSTITUTION.md) for core values.
 
 ## Architecture
 
@@ -24,15 +26,28 @@ See [VISION.md](docs/VISION.md) for details.
 
 ```
 src/parallax/           # Main package (cli/, core/, db/)
-templates/              # Templates generated for user projects
+templates/              # Source templates (rendered by parallax init)
 tests/                  # pytest
 docs/                   # VISION.md, ROADMAP.md, plans/
 .claude/                # Skills and hooks for development
 ```
 
 ## Installation
 
-Requires [pixi](https://pixi.sh).
+Requires [pixi](https://pixi.sh). Install via:
+
+```bash
+# macOS / Linux
+curl -fsSL https://pixi.sh/install.sh | bash
+
+# macOS (Homebrew)
+brew install pixi
+
+# Windows
+powershell -c "irm https://pixi.sh/install.ps1 | iex"
+```
+
+Then:
 
 ```bash
 pixi install

docs/VISION.md

@@ -1,17 +1,17 @@
 # Parallax Vision
 
-> Two perspectives (human + AI) to get a stronger result.
+> *True depth requires two lines of sight.*
 
 ## Mission
 
-Parallax is a scientific augmentation tool that encodes best practices for reproducible, hypothesis-driven science into agentic AI workflows. It accelerates excellent science — but no faster than that.
+Parallax is a scientific augmentation tool that encodes best practices for reproducible, hypothesis-driven science into agentic AI workflows. It accelerates science as fast as is safe, quantifiable, and verifiable — but no faster.
 
 Personal science use case. Not enterprise/team tooling (yet).
 
 ## Core Principles
 
 - AI supplements scientific work, never drives it
-- Robust science over fast science
+- Robust science over fast science — accelerate only as fast as is safe, quantifiable, and verifiable
 - Reproducibility is non-negotiable
 - Loud errors over silent failures
 - Negative results are scientifically valuable