simjecture 0.4.0__tar.gz → 0.5.1__tar.gz

{simjecture-0.4.0 → simjecture-0.5.1}/CHANGELOG.md

@@ -2,7 +2,62 @@
 
 This project follows semantic versioning. Dates use ISO 8601.
 
-## Unreleased
+## 0.5.1 — 2026-09-26
+
+- Update bundled FLASH and Python experiment skills with guided-study/HDF5 lessons,
+  mode-correct interfaces, pilot interpretation and acceptance-rule checks.
+
+- Preserve classic instrument access across assignment rollover; retain role and branch scope.
+- Require explicit methods-review prerequisites and reject conditional approval; distinguish
+  timing/parity pilots from scientific evidence.
+- Surface output eligibility annotations to review without forcing metadata-only solver reruns.
+- Check explicit numerical repair bounds for empty intersections before execution.
+- Cancel through the complete durable job store, report unknown outcomes, and continue cleanup
+  when one job fails cancellation.
+- Document the guided MiMo v2.6 Pro / DeepSeek V4.1 Flash comparison, including tool-protocol,
+  duration and usage limitations; refresh the README around current modes and trust boundaries.
+- Restore guided anchors in all native study modes, with a separate model-free readiness run
+  and instrument-scoped review that cannot authorize hypothesis evidence.
+- Add explicit non-root PRoot cooperative execution for hosts without Linux namespaces;
+  keep Bubblewrap the default and never silently weaken isolation.
+- Retry transient provider failures with interruptible backoff until the original deadline;
+  pause authentication, permission and exhausted-quota failures for operator attention.
+
+- Make experiment journaling and bounded context delivery automatic in minimal mode,
+  following AIDE's controller-managed pattern. Add budget-limited checkpoint synthesis
+  with receipt-bound citations and no authority over scientific acceptance.
+
+- Add optional evidence-linked research notes, preserved corrections, discriminating
+  test plans and experiment lineage, informed by autoresearch/AIDE source inspection.
+- Resume from a bounded research brief and generate a machine-readable attempt ledger;
+  compare hash-verified result metrics without replacing missing values with zeros.
+
+- Add source-bound methods review for new instrument-backed minimal studies,
+  optional immutable instrument requirements, and append-only registration of new builds.
+- Recover native sessions that repeat intentions without work; add independent progress
+  review, bounded host checkpoints and immediate handoff of durable review requests.
+- Separate exploration from evidence and compact review documents from hashed binary
+  outputs; detect changed inputs, dead workers and questionable result fields.
+- Generate a live host evidence ledger with missing-case coverage, budget warnings,
+  review status and incomplete token-accounting indicators.
+- Support operator-authorized read-only solver-source inspection and useful build
+  diagnostics. Record the reconnection-run audit and live MiMo validation results.
+
+## 0.5.0 — 2026-09-21
+
+- Default new native-agent studies to minimal, with structured and frontier
+  selectable in the CLI, browser and TUI. Mode and backend are separate choices;
+  DSH/API remain explicitly labelled legacy routes. Existing records retain their mode.
+- Preserve active counterexample search, minimal-change repair rationale,
+  branching hypothesis ancestry and fresh prospective validation in the smaller service.
+- Add live terminal activity, job/review counts and remaining budget; project
+  minimal evidence and hypothesis trees into the browser and terminal interface.
+- Preserve deadlines across pause/resume, surface provider failures as resumable
+  states, and verify numerical-worker identity before cancellation.
+- Make the launch package usable with native agent logins without installing DSH;
+  retain an optional `setup.sh --with-dsh` path.
+- Retain measured limitations: simple-task follow-ups completed faster but used
+  more tokens; the previous hard FLASH trial did not establish superiority to a plain agent.
 
 ## 0.4.0 — 2026-09-20
 

{simjecture-0.4.0 → simjecture-0.5.1}/CITATION.cff

@@ -2,8 +2,8 @@ cff-version: 1.2.0
 message: "If you use this software, please cite the exact software version and Git commit."
 title: "Simjecture"
 type: software
-version: 0.4.0
-date-released: 2026-09-20
+version: 0.5.1
+date-released: 2026-09-26
 abstract: >-
   An evidence-governed runtime for autonomous computational experimentation and
   falsification over hypothesis trees.

simjecture-0.5.1/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.5
+Name: simjecture
+Version: 0.5.1
+Summary: Evidence-governed autonomous experimentation and falsification for computational science
+Project-URL: Homepage, https://github.com/tomzhu0225/simjecture
+Project-URL: Documentation, https://github.com/tomzhu0225/simjecture/tree/main/docs
+Project-URL: Repository, https://github.com/tomzhu0225/simjecture
+Project-URL: Issues, https://github.com/tomzhu0225/simjecture/issues
+Author: Bowen Zhu
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: autonomous science,computational physics,falsification,hypothesis testing,scientific agents,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: matplotlib<4,>=3.8
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: pandas<4,>=2.2
+Requires-Dist: pillow<13,>=10
+Requires-Dist: pydantic<3,>=2.9
+Requires-Dist: scipy<2,>=1.12
+Provides-Extra: dsh
+Requires-Dist: mcp<3,>=2; extra == 'dsh'
+Provides-Extra: flash-demo
+Requires-Dist: h5py<4,>=3.10; extra == 'flash-demo'
+Provides-Extra: process
+Requires-Dist: psutil<8,>=6; extra == 'process'
+Provides-Extra: tui
+Requires-Dist: textual<9,>=2.0; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# Simjecture
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21945748.svg)](https://doi.org/10.5281/zenodo.21945748)
+
+**Hypothesize. Simulate. Falsify.**
+
+Simjecture is a research harness for computational science. An agent writes and runs
+experiments, searches for counterexamples, and proposes small, testable repairs to
+failed hypotheses. The harness records what actually ran and requires independent
+review before a scientific claim can close.
+
+**v0.5.1 is a research preview.** Minimal mode is the default: agents keep their
+native tools and choose their research strategy, while Simjecture manages recorded
+evidence, review and deadlines. Structured and frontier modes remain available.
+The system does not establish physical truth from a successful simulation or promise
+that a long agent run will produce a useful result.
+
+## Start a study
+
+Use Linux with Python 3.11+, [uv](https://docs.astral.sh/uv/), and an installed,
+authenticated native agent CLI. Bubblewrap is the default numerical execution backend.
+
+```bash
+uv tool install 'simjecture[tui]==0.5.1'
+simjecture install core
+simjecture doctor --execution-backend bubblewrap
+
+simjecture study --campaign ./runs/my-study \
+  --hypothesis-file hypothesis.txt --instructions-file instructions.md \
+  --backend codex-glm --model glm-5.3 --wall-seconds 3600
+```
+
+Write a falsifiable hypothesis in `hypothesis.txt`. In `instructions.md`, specify
+physical scope, available instruments, resource limits and the evidence needed to
+accept or reject it. Configure provider credentials in your agent's own credential
+store, outside the study directory. The model name must match that configuration.
+
+A terminal launch shows activity, backend/model, remaining time and experiment/review
+counts. Inspect the same study in either interface:
+
+```bash
+simjecture web ./runs/my-study
+simjecture tui ./runs/my-study
+```
+
+Resume using the same campaign path and launch options. Its recorded mode and original
+wall deadline remain fixed. A normal agent exit or inconclusive result does not mark
+research complete. Transient provider disconnects retry with backoff until the deadline;
+authentication, permission and exhausted-quota errors pause for attention. Waiting for
+a provider counts against wall time.
+
+See [minimal-mode usage](docs/how-to/research-service.md),
+[terminal progress](docs/getting-started/terminal-ui.md) and the
+[browser interface](docs/getting-started/web-interface.md).
+
+## Choose the agent, workflow and execution backend separately
+
+| Choice | Options | What it controls |
+|---|---|---|
+| Native agent | `codex-glm`, `codex`, `grok`, `agy` | CLI, configured provider/model, login and native tools |
+| Research mode | `minimal` (default), `structured`, `frontier` | How scientific work is organized |
+| Numerical execution | `bubblewrap` (default), `proot-cooperative` | How recorded experiment processes execute |
+| Legacy engine | DSH or built-in API routes | Existing campaign integrations; separate from native-study modes |
+
+Use `--mode structured` or `--mode frontier` for another workflow. Minimal lets the
+agent organize its investigation around a small evidence API; structured uses explicit
+claim-scoped roles and contracts; frontier gives a persistent researcher control of
+the classic claim tree. Existing campaigns retain their recorded semantics.
+
+Native agents retain their own shell, search, file and configured provider tools.
+They are trusted, cooperative processes on the study host; they are **not** enclosed
+by the numerical experiment sandbox. Simjecture's supplied tools record experiments,
+provenance and reviews. Native scratch work is not automatically scientific evidence.
+
+If namespaces are unavailable, explicitly select `--execution-backend proot-cooperative`
+on a dedicated non-root account. It provides execution bookkeeping and limits, **not
+an OS security boundary**. Simjecture never silently falls back to it. See
+[restricted containers](docs/how-to/restricted-containers.md).
+
+[DSH integration](docs/how-to/deepseek-harness.md) remains available with native research
+tools and a governed MCP boundary. [Simote integration](docs/how-to/simote-agent-roles.md)
+is optional; Simjecture can run independently on a local or remote host. Deployment
+to a remote host does not itself create a multi-machine experiment scheduler.
+
+## What minimal mode enforces
+
+The agent chooses hypotheses, code, diagnostics and the next discriminating experiment.
+The host maintains the scientific record:
+
+- **Immutable question and scope.** Operator requirements cannot be waived by a worker
+  or reviewer. Repairs preserve ancestry and explain each changed assumption or bound.
+- **Recorded execution.** Commands, declared inputs, runtime identity and output hashes
+  accompany each experiment. Interrupted attempts remain visible.
+- **Commissioning before evidence.** Instrument-backed studies receive source-bound
+  methods review. Exploration and supplied examples cannot be relabelled as new evidence.
+- **Counterexample search and fresh repairs.** Support includes an actual challenge
+  attempt. Repaired predictions are committed before their fresh tests.
+- **Independent acceptance.** A methods approval permits evidence collection; it does
+  not accept a scientific claim. Unconverged, censored or missing results are not
+  physical counterexamples.
+- **Persistent context.** The host maintains an experiment journal and bounded research
+  brief. Evidence-linked notes and comparisons help retain failed approaches and findings.
+- **Bounded work.** The original deadline survives restart. Cancellation uses durable job
+  records and reports unresolved cleanup rather than assuming that agent exit stopped
+  every computation.
+
+A study completes when its original claim is independently supported, or when a
+falsified original leads to an independently supported repair with the required
+ancestry. A deadline may end the campaign unresolved; that is recorded, not promoted
+to a success.
+
+See [methods and progress oversight](docs/how-to/minimal-oversight.md),
+[research memory](docs/how-to/research-memory.md) and
+[evidence and claims](docs/concepts/evidence-and-claims.md).
+
+## Begin with a working scientific instrument
+
+For expensive solver setup, provide a guided commissioning package: exact working
+source and command, output reader, observable, validation checks, runtime and known
+limitations. Reproduce that anchor in a separate bounded readiness run before spending
+hours on hypothesis testing.
+
+```bash
+simjecture study --campaign ./runs/guided-study \
+  --hypothesis-file hypothesis.txt --instructions-file instructions.md \
+  --guided-commission /path/to/guided_commission.json \
+  --capabilities /path/to/installed-capabilities \
+  --backend codex-glm --model glm-5.3 --wall-seconds 3600
+```
+
+Guided examples are starting instruments, not fresh evidence for the new hypothesis.
+An executable smoke test does not validate a new geometry or diagnostic. The
+[guided commissioning guide](docs/how-to/guided-commissioning.md) explains readiness
+budgets, immutable anchors and instrument versus production review.
+
+Optional instruments include WarpX CPU/CUDA, operator-supplied FLASH, and EOS/opacity
+capabilities. For example:
+
+```bash
+simjecture install warpx-cpu
+simjecture doctor --profile warpx-cpu
+```
+
+FLASH source is not redistributed. Solver source inspection can be configured separately
+from a writable problem/build area. See [runtime deployment](docs/how-to/deploy-runtimes.md)
+and the [scientific skills](skills/).
+
+## What v0.5.1 changes
+
+This release builds on v0.5.0's minimal default and shared interfaces:
+
+- Methods/progress oversight, stalled-session recovery and deadline-bounded provider retry.
+- Automatic research journaling, bounded context and evidence-linked comparisons.
+- Guided anchors in native studies and explicit cooperative execution for restricted hosts.
+- Updated FLASH/Python skills with guided-study, HDF5 and decision-rule lessons.
+- Preserved instrument ownership across classic assignment rollover.
+- Explicit unmet review prerequisites; conditional approval cannot open the evidence gate.
+- Numerical checks for contradictory prospective acceptance bounds.
+- Output eligibility annotations exposed for review without forcing metadata-only solver reruns.
+- Durable cancellation cleanup independent of CLI-response parsing.
+
+The [changelog](CHANGELOG.md) and [repair report](research/evaluations/guided-model-comparison-2026-09-26/RESULTS.md)
+include validation and remaining limitations. General reuse of raw solver data under
+independently versioned analysis still needs a fuller provenance API.
+
+## Measured evidence and limitations
+
+Minimal is the default by design preference, not a demonstrated universal performance
+advantage. The latest [MiMo v2.6 Pro / DeepSeek V4.1 Flash comparison](docs/research/llm-comparison.md)
+found faster useful progress with DeepSeek in a guided minimal FLASH study, but **no
+independently accepted scientific conclusion** from either model configuration.
+Unequal duration, different provider tool protocols and one trial per configuration
+limit that comparison. Token totals distinguish cached input, uncached input and
+output; they are not billed-cost estimates.
+
+| Recorded evaluation | What can be inspected |
+|---|---|
+| [Gray–Scott](demos/gray_scott_counterexample/) | A completed 23.8-minute finite-domain counterexample campaign, programs, numerical evidence and replay |
+| [Collisionless GEM](demos/collisionless_gem_reconnection/) | 12 fresh CUDA runs; finite-sample child falsification with an unresolved population root |
+| [FLASH island coalescence](demos/resistive_mhd_island_coalescence/) | Working guided anchor, real fields and a historical audit; the repair remained open |
+| [Guided model comparison](research/evaluations/guided-model-comparison-2026-09-26/) | MiMo/DeepSeek progress, usage, harness failures and corrective tests |
+
+The historical FLASH narrative recorded an exponent-band falsification with an interval
+that overlaps the allowed band. That overlap alone does not establish such falsification;
+the earlier summary is not independently endorsed here. Provenance enables inspection,
+but cannot make a faulty scientific decision correct.
+
+Replay a completed example without an API key or new simulations:
+
+```bash
+git clone https://github.com/tomzhu0225/simjecture.git
+cd simjecture
+uv sync --frozen
+uv run python demos/gray_scott_counterexample/verify_record.py
+uv run simjecture web demos/gray_scott_counterexample/record --read-only
+```
+
+![Gray–Scott recorded numerical evidence](docs/_static/demos/gray-scott-result.png)
+
+## Documentation and development
+
+Start at [the documentation index](docs/index.md). Linux release assets include a
+launch archive with matching Python/DSH packages, setup scripts and SHA-256 checksums.
+Native-agent setup does not require installing DSH.
+
+```bash
+uv sync --all-groups --extra tui --extra dsh
+uv run ruff check .
+uv run pytest
+uv run simjecture schemas --output schemas --check
+uv run --group docs sphinx-build -W -b html docs docs/_build/html
+```
+
+`conjecture-solver` and `acs` remain compatibility aliases. The Python package remains
+`conjecture_solver`. See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md)
+and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+## Citation and license
+
+Use [CITATION.cff](CITATION.cff) and cite the exact version and Git commit used for a
+result. The [concept DOI](https://doi.org/10.5281/zenodo.21945748) identifies the software
+release series.
+
+Copyright 2026 Bowen Zhu and contributors. Licensed under the
+[Apache License 2.0](LICENSE).

simjecture-0.5.1/README.md

@@ -0,0 +1,225 @@
+# Simjecture
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21945748.svg)](https://doi.org/10.5281/zenodo.21945748)
+
+**Hypothesize. Simulate. Falsify.**
+
+Simjecture is a research harness for computational science. An agent writes and runs
+experiments, searches for counterexamples, and proposes small, testable repairs to
+failed hypotheses. The harness records what actually ran and requires independent
+review before a scientific claim can close.
+
+**v0.5.1 is a research preview.** Minimal mode is the default: agents keep their
+native tools and choose their research strategy, while Simjecture manages recorded
+evidence, review and deadlines. Structured and frontier modes remain available.
+The system does not establish physical truth from a successful simulation or promise
+that a long agent run will produce a useful result.
+
+## Start a study
+
+Use Linux with Python 3.11+, [uv](https://docs.astral.sh/uv/), and an installed,
+authenticated native agent CLI. Bubblewrap is the default numerical execution backend.
+
+```bash
+uv tool install 'simjecture[tui]==0.5.1'
+simjecture install core
+simjecture doctor --execution-backend bubblewrap
+
+simjecture study --campaign ./runs/my-study \
+  --hypothesis-file hypothesis.txt --instructions-file instructions.md \
+  --backend codex-glm --model glm-5.3 --wall-seconds 3600
+```
+
+Write a falsifiable hypothesis in `hypothesis.txt`. In `instructions.md`, specify
+physical scope, available instruments, resource limits and the evidence needed to
+accept or reject it. Configure provider credentials in your agent's own credential
+store, outside the study directory. The model name must match that configuration.
+
+A terminal launch shows activity, backend/model, remaining time and experiment/review
+counts. Inspect the same study in either interface:
+
+```bash
+simjecture web ./runs/my-study
+simjecture tui ./runs/my-study
+```
+
+Resume using the same campaign path and launch options. Its recorded mode and original
+wall deadline remain fixed. A normal agent exit or inconclusive result does not mark
+research complete. Transient provider disconnects retry with backoff until the deadline;
+authentication, permission and exhausted-quota errors pause for attention. Waiting for
+a provider counts against wall time.
+
+See [minimal-mode usage](docs/how-to/research-service.md),
+[terminal progress](docs/getting-started/terminal-ui.md) and the
+[browser interface](docs/getting-started/web-interface.md).
+
+## Choose the agent, workflow and execution backend separately
+
+| Choice | Options | What it controls |
+|---|---|---|
+| Native agent | `codex-glm`, `codex`, `grok`, `agy` | CLI, configured provider/model, login and native tools |
+| Research mode | `minimal` (default), `structured`, `frontier` | How scientific work is organized |
+| Numerical execution | `bubblewrap` (default), `proot-cooperative` | How recorded experiment processes execute |
+| Legacy engine | DSH or built-in API routes | Existing campaign integrations; separate from native-study modes |
+
+Use `--mode structured` or `--mode frontier` for another workflow. Minimal lets the
+agent organize its investigation around a small evidence API; structured uses explicit
+claim-scoped roles and contracts; frontier gives a persistent researcher control of
+the classic claim tree. Existing campaigns retain their recorded semantics.
+
+Native agents retain their own shell, search, file and configured provider tools.
+They are trusted, cooperative processes on the study host; they are **not** enclosed
+by the numerical experiment sandbox. Simjecture's supplied tools record experiments,
+provenance and reviews. Native scratch work is not automatically scientific evidence.
+
+If namespaces are unavailable, explicitly select `--execution-backend proot-cooperative`
+on a dedicated non-root account. It provides execution bookkeeping and limits, **not
+an OS security boundary**. Simjecture never silently falls back to it. See
+[restricted containers](docs/how-to/restricted-containers.md).
+
+[DSH integration](docs/how-to/deepseek-harness.md) remains available with native research
+tools and a governed MCP boundary. [Simote integration](docs/how-to/simote-agent-roles.md)
+is optional; Simjecture can run independently on a local or remote host. Deployment
+to a remote host does not itself create a multi-machine experiment scheduler.
+
+## What minimal mode enforces
+
+The agent chooses hypotheses, code, diagnostics and the next discriminating experiment.
+The host maintains the scientific record:
+
+- **Immutable question and scope.** Operator requirements cannot be waived by a worker
+  or reviewer. Repairs preserve ancestry and explain each changed assumption or bound.
+- **Recorded execution.** Commands, declared inputs, runtime identity and output hashes
+  accompany each experiment. Interrupted attempts remain visible.
+- **Commissioning before evidence.** Instrument-backed studies receive source-bound
+  methods review. Exploration and supplied examples cannot be relabelled as new evidence.
+- **Counterexample search and fresh repairs.** Support includes an actual challenge
+  attempt. Repaired predictions are committed before their fresh tests.
+- **Independent acceptance.** A methods approval permits evidence collection; it does
+  not accept a scientific claim. Unconverged, censored or missing results are not
+  physical counterexamples.
+- **Persistent context.** The host maintains an experiment journal and bounded research
+  brief. Evidence-linked notes and comparisons help retain failed approaches and findings.
+- **Bounded work.** The original deadline survives restart. Cancellation uses durable job
+  records and reports unresolved cleanup rather than assuming that agent exit stopped
+  every computation.
+
+A study completes when its original claim is independently supported, or when a
+falsified original leads to an independently supported repair with the required
+ancestry. A deadline may end the campaign unresolved; that is recorded, not promoted
+to a success.
+
+See [methods and progress oversight](docs/how-to/minimal-oversight.md),
+[research memory](docs/how-to/research-memory.md) and
+[evidence and claims](docs/concepts/evidence-and-claims.md).
+
+## Begin with a working scientific instrument
+
+For expensive solver setup, provide a guided commissioning package: exact working
+source and command, output reader, observable, validation checks, runtime and known
+limitations. Reproduce that anchor in a separate bounded readiness run before spending
+hours on hypothesis testing.
+
+```bash
+simjecture study --campaign ./runs/guided-study \
+  --hypothesis-file hypothesis.txt --instructions-file instructions.md \
+  --guided-commission /path/to/guided_commission.json \
+  --capabilities /path/to/installed-capabilities \
+  --backend codex-glm --model glm-5.3 --wall-seconds 3600
+```
+
+Guided examples are starting instruments, not fresh evidence for the new hypothesis.
+An executable smoke test does not validate a new geometry or diagnostic. The
+[guided commissioning guide](docs/how-to/guided-commissioning.md) explains readiness
+budgets, immutable anchors and instrument versus production review.
+
+Optional instruments include WarpX CPU/CUDA, operator-supplied FLASH, and EOS/opacity
+capabilities. For example:
+
+```bash
+simjecture install warpx-cpu
+simjecture doctor --profile warpx-cpu
+```
+
+FLASH source is not redistributed. Solver source inspection can be configured separately
+from a writable problem/build area. See [runtime deployment](docs/how-to/deploy-runtimes.md)
+and the [scientific skills](skills/).
+
+## What v0.5.1 changes
+
+This release builds on v0.5.0's minimal default and shared interfaces:
+
+- Methods/progress oversight, stalled-session recovery and deadline-bounded provider retry.
+- Automatic research journaling, bounded context and evidence-linked comparisons.
+- Guided anchors in native studies and explicit cooperative execution for restricted hosts.
+- Updated FLASH/Python skills with guided-study, HDF5 and decision-rule lessons.
+- Preserved instrument ownership across classic assignment rollover.
+- Explicit unmet review prerequisites; conditional approval cannot open the evidence gate.
+- Numerical checks for contradictory prospective acceptance bounds.
+- Output eligibility annotations exposed for review without forcing metadata-only solver reruns.
+- Durable cancellation cleanup independent of CLI-response parsing.
+
+The [changelog](CHANGELOG.md) and [repair report](research/evaluations/guided-model-comparison-2026-09-26/RESULTS.md)
+include validation and remaining limitations. General reuse of raw solver data under
+independently versioned analysis still needs a fuller provenance API.
+
+## Measured evidence and limitations
+
+Minimal is the default by design preference, not a demonstrated universal performance
+advantage. The latest [MiMo v2.6 Pro / DeepSeek V4.1 Flash comparison](docs/research/llm-comparison.md)
+found faster useful progress with DeepSeek in a guided minimal FLASH study, but **no
+independently accepted scientific conclusion** from either model configuration.
+Unequal duration, different provider tool protocols and one trial per configuration
+limit that comparison. Token totals distinguish cached input, uncached input and
+output; they are not billed-cost estimates.
+
+| Recorded evaluation | What can be inspected |
+|---|---|
+| [Gray–Scott](demos/gray_scott_counterexample/) | A completed 23.8-minute finite-domain counterexample campaign, programs, numerical evidence and replay |
+| [Collisionless GEM](demos/collisionless_gem_reconnection/) | 12 fresh CUDA runs; finite-sample child falsification with an unresolved population root |
+| [FLASH island coalescence](demos/resistive_mhd_island_coalescence/) | Working guided anchor, real fields and a historical audit; the repair remained open |
+| [Guided model comparison](research/evaluations/guided-model-comparison-2026-09-26/) | MiMo/DeepSeek progress, usage, harness failures and corrective tests |
+
+The historical FLASH narrative recorded an exponent-band falsification with an interval
+that overlaps the allowed band. That overlap alone does not establish such falsification;
+the earlier summary is not independently endorsed here. Provenance enables inspection,
+but cannot make a faulty scientific decision correct.
+
+Replay a completed example without an API key or new simulations:
+
+```bash
+git clone https://github.com/tomzhu0225/simjecture.git
+cd simjecture
+uv sync --frozen
+uv run python demos/gray_scott_counterexample/verify_record.py
+uv run simjecture web demos/gray_scott_counterexample/record --read-only
+```
+
+![Gray–Scott recorded numerical evidence](docs/_static/demos/gray-scott-result.png)
+
+## Documentation and development
+
+Start at [the documentation index](docs/index.md). Linux release assets include a
+launch archive with matching Python/DSH packages, setup scripts and SHA-256 checksums.
+Native-agent setup does not require installing DSH.
+
+```bash
+uv sync --all-groups --extra tui --extra dsh
+uv run ruff check .
+uv run pytest
+uv run simjecture schemas --output schemas --check
+uv run --group docs sphinx-build -W -b html docs docs/_build/html
+```
+
+`conjecture-solver` and `acs` remain compatibility aliases. The Python package remains
+`conjecture_solver`. See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md)
+and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+## Citation and license
+
+Use [CITATION.cff](CITATION.cff) and cite the exact version and Git commit used for a
+result. The [concept DOI](https://doi.org/10.5281/zenodo.21945748) identifies the software
+release series.
+
+Copyright 2026 Bowen Zhu and contributors. Licensed under the
+[Apache License 2.0](LICENSE).

{simjecture-0.4.0 → simjecture-0.5.1}/docs/conf.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 project = "Simjecture"
 author = "Bowen Zhu"
 copyright = "2026, Bowen Zhu and contributors"
-release = "0.4.0"
+release = "0.5.1"
 
 extensions = [
     "myst_parser",

simjecture-0.5.1/docs/getting-started/first-run.md

@@ -0,0 +1,68 @@
+# First autonomous run
+
+To explore the interface before supplying an API key, replay the committed
+Gray–Scott record. This is read-only and starts neither a model call nor a
+simulation:
+
+```bash
+uv sync --frozen
+uv run python demos/gray_scott_counterexample/verify_record.py
+uv run simjecture web demos/gray_scott_counterexample/record --read-only
+```
+
+See [Recorded Gray–Scott demo](../demos/gray-scott.md) for the scientific result
+and the boundaries of that record.
+
+To start a new study, install and log in to a supported native agent CLI
+(Codex GLM, Codex, Grok or AGY), then open the browser:
+
+```bash
+uv run simjecture web
+```
+
+In **New hypothesis**, choose mode, backend and model separately. **Minimal** is
+the default. It keeps the agent's native tools and planning freedom while recording
+experiments, counterexample searches, hypothesis repairs and independent reviews.
+Structured and frontier modes remain selectable. DSH and direct API routes are
+explicit legacy choices and require their separate provider configuration.
+
+For a terminal run, write a bounded statement in `hypothesis.txt` and its test
+scope, resource constraints and acceptance criteria in `instructions.md`:
+
+```bash
+uv run simjecture study --campaign artifacts/first-study \
+  --hypothesis-file hypothesis.txt --instructions-file instructions.md \
+  --backend codex-glm --model glm-5.3 --wall-seconds 3600
+```
+
+The terminal shows current activity, elapsed/remaining time and experiment/review
+counts. Use `--quiet` to suppress progress. Select `--mode structured` or
+`--mode frontier` when starting a new directory. Existing mode, backend and wall
+deadline are retained on resume.
+
+Minimal records include `research.json`, immutable experiment snapshots,
+prospective repair commitments, independent review receipts and a final
+`research_report.json`. A clean agent exit is only a checkpoint. A supported root
+or an accepted falsification followed by a supported repair completes the study;
+uncertainty stays unresolved. Numerical convergence and physical validity remain
+scientific obligations. See [minimal research](../how-to/research-service.md).
+
+Inspect or control the same directory:
+
+```bash
+uv run simjecture status artifacts/first-study
+uv run simjecture watch artifacts/first-study
+uv run simjecture web artifacts/first-study
+uv run simjecture pause artifacts/first-study
+uv run simjecture resume artifacts/first-study
+```
+
+Pause stops the native agent at the supervisor boundary. Already recorded jobs
+may finish within their existing limits; the wall deadline continues. Cancel or
+deadline exhaustion terminates active recorded jobs. A provider outage pauses
+with the evidence intact rather than inventing a scientific conclusion.
+
+The optional [Terminal interface](terminal-ui.md) offers the same mode/backend
+selection and a dashboard for SSH and headless machines. The legacy `simjecture
+mvp` and [DSH](../how-to/deepseek-harness.md) entry points remain available; their
+workbench/commissioning contracts are unchanged.

{simjecture-0.4.0 → simjecture-0.5.1}/docs/getting-started/installation.md

@@ -17,7 +17,15 @@ uv run simjecture install core
 uv run simjecture doctor --profile core
 ```
 
-## Model credentials
+## Native agent login
+
+New studies default to minimal mode. Install and log in with Codex GLM, Codex,
+Grok or AGY independently, then choose that backend and model in the launcher.
+Simjecture does not redistribute those CLIs or subscriptions. Native tools remain
+available; numerical execution still uses the Bubblewrap sandbox. No DeepSeek
+API key or DSH install is required for native-agent studies.
+
+## Legacy API credentials
 
 Credentials are process-local harness inputs. They are never mounted into the
 agent workspace.