Sync docs: clarify background behavior, complete command list

- README: command table now says "in background (survives terminal close)"
  and explains foreground alternative
- THE_STORY Part 5: all 13 app.sh commands listed, background/foreground
  behavior explained, JupyterManager reference added
- THE_STORY Part 7.1: recommend app.sh bootstrap as primary setup path
This commit is contained in:
saymrwulf 2026-04-16 09:52:24 +02:00
parent d4ca5f99dc
commit e7674ee5c0
2 changed files with 52 additions and 17 deletions

View file

@ -119,9 +119,9 @@ The `app.sh` lifecycle manager handles the entire consumer experience:
| Command | What it does | | Command | What it does |
|---------|-------------| |---------|-------------|
| `bash scripts/app.sh bootstrap` | Create venv, install deps, register Jupyter kernel, verify imports | | `bash scripts/app.sh bootstrap` | Create venv, install deps, register Jupyter kernel, verify imports |
| `bash scripts/app.sh start` | Launch JupyterLab (auto-opens `00_START_HERE.ipynb`) | | `bash scripts/app.sh start` | Launch JupyterLab in background (survives terminal close; stop with `app.sh stop`) |
| `bash scripts/app.sh start --no-open` | Launch without opening browser | | `bash scripts/app.sh start --no-open` | Launch in background without opening browser |
| `bash scripts/app.sh start --foreground` | Run in foreground (Ctrl-C to stop cleanly) | | `bash scripts/app.sh start --foreground` | Run in foreground (Ctrl-C or closing terminal stops it) |
| `bash scripts/app.sh start --port 9999` | Use a specific port | | `bash scripts/app.sh start --port 9999` | Use a specific port |
| `bash scripts/app.sh stop` | Stop JupyterLab (graceful SIGTERM, SIGKILL fallback) | | `bash scripts/app.sh stop` | Stop JupyterLab (graceful SIGTERM, SIGKILL fallback) |
| `bash scripts/app.sh restart` | Stop + start | | `bash scripts/app.sh restart` | Stop + start |

View file

@ -491,21 +491,49 @@ The project includes a lifecycle manager (`scripts/app.sh`) that handles the
entire consumer experience from first clone to running notebooks: entire consumer experience from first clone to running notebooks:
```bash ```bash
bash scripts/app.sh bootstrap # venv, pip install, kernel registration, import check bash scripts/app.sh bootstrap # venv, pip install, kernel registration, import check
bash scripts/app.sh start # launch JupyterLab, open 00_START_HERE.ipynb bash scripts/app.sh start # launch JupyterLab in background, open browser
bash scripts/app.sh stop # graceful shutdown bash scripts/app.sh start --foreground # run in foreground (Ctrl-C to stop)
bash scripts/app.sh status # venv, server, notebook, progress summary bash scripts/app.sh start --no-open # launch without opening browser
bash scripts/app.sh validate # ruff + mypy + full test suite bash scripts/app.sh start --port 9999 # use a specific port
bash scripts/app.sh validate --quick # lint + type check + unit tests only bash scripts/app.sh stop # graceful shutdown (SIGTERM, wait, SIGKILL fallback)
bash scripts/app.sh logs # tail JupyterLab output bash scripts/app.sh restart # stop + start
bash scripts/app.sh reset # delete learner progress files bash scripts/app.sh status # venv, server, ports, orphan detection
bash scripts/app.sh validate # ruff + mypy + full test suite
bash scripts/app.sh validate --quick # lint + type check + unit tests only
bash scripts/app.sh logs [-f] # show or follow JupyterLab output
bash scripts/app.sh reset # delete learner progress files
bash scripts/app.sh reset-state # reset Jupyter runtime + UI state
``` ```
Bootstrap checks Python >= 3.11, creates the venv, installs the package with Bootstrap checks Python >= 3.11, creates the venv, installs the package with
dev and notebook dependencies, registers a Jupyter kernel, and verifies that dev and notebook dependencies, registers a Jupyter kernel with `--sys-prefix`
core imports succeed. Start finds a free port (8888-8899), launches JupyterLab (venv-local, not user-global), and verifies that core imports succeed.
in the background with PID tracking, and opens the browser directly to
`00_START_HERE.ipynb`. **Start runs Jupyter in the background by default.** The process survives
terminal close. The terminal prints the URL and returns immediately --- you are
free to close the tab or use it for other work. Jupyter keeps running until you
explicitly stop it with `app.sh stop`. The `--foreground` flag is the
alternative: it occupies the terminal, and Ctrl-C or closing the tab stops
Jupyter cleanly with no orphan process left behind.
Start finds a free port by scanning 8888-8899 via `lsof`, writes a PID file
at `.logs/jupyter.pid`, and opens the browser directly to
`00_START_HERE.ipynb`. All Jupyter state (config, data, runtime, IPython,
matplotlib cache) is isolated into project-local directories, preventing
cross-project interference.
This project follows the [JupyterManager](https://github.com/saymrwulf/JupyterManager)
lifecycle specification. The cross-project `jupyter-hub` CLI can discover and
manage this project alongside other Jupyter-enabled projects:
```bash
jupyter-hub status # show all projects (running/stopped)
jupyter-hub ports # port allocation map (8888-8899)
jupyter-hub stop-all # stop all Jupyter instances
jupyter-hub orphans # find untracked processes
jupyter-hub kill-orphans # kill them
```
Validation runs the full quality pipeline: ruff linting, mypy strict type Validation runs the full quality pipeline: ruff linting, mypy strict type
checking, and the pytest suite (335 tests, excluding browser UX by default). checking, and the pytest suite (335 tests, excluding browser UX by default).
@ -632,9 +660,16 @@ output. Everything below runs in your terminal.
```bash ```bash
cd autoresearch-quantum cd autoresearch-quantum
bash scripts/app.sh bootstrap
```
This creates the venv, installs all dependencies, registers the Jupyter kernel,
and verifies imports. If you prefer manual setup:
```bash
python -m venv .venv python -m venv .venv
source .venv/bin/activate source .venv/bin/activate
pip install -e ".[dev]" pip install -e ".[dev,notebooks]"
``` ```
### 7.2 Run a single experiment ### 7.2 Run a single experiment
@ -835,6 +870,6 @@ ratchet runs multiple rungs. The lessons tighten the circle with every pass.
--- ---
*This document was last updated on 2026-04-15 to describe the system as *This document was last updated on 2026-04-16 to describe the system as
built. The code is the ground truth. If this document contradicts the code, built. The code is the ground truth. If this document contradicts the code,
the code is correct.* the code is correct.*