diff --git a/START_HERE.md b/START_HERE.md index 6acc73c..08705fd 100644 --- a/START_HERE.md +++ b/START_HERE.md @@ -23,9 +23,22 @@ Your job is: 1. Run `./scripts/ratchet`. 2. Do only what it says under `DO THIS NOW`. 3. Ignore every other command unless `DO THIS NOW` tells you to run it. -4. After a watch finishes, run `./scripts/ratchet` again. +4. If it tells you to run `./scripts/ratchet watch 2`, start it, leave the terminal open, and come back after about 2 hours. 5. If you manually place a Braiins canary, write down the order details outside this repo and wait through the maturity window before judging it. +## Who Is In Control? + +If `watch` is running, the Python process is in control of that terminal. + +You do not need to babysit it. It will: + +1. Collect samples every 5 minutes. +2. Write the run report when it finishes. +3. Print the cockpit again. +4. Return control to your shell prompt. + +If you want the technical report, run `./scripts/ratchet report`. The normal workflow intentionally shows the cockpit first. + ## What The Actions Mean `observe` means do not bid. diff --git a/docs/OPERATOR_GUIDE.md b/docs/OPERATOR_GUIDE.md index c3607e3..c00b107 100644 --- a/docs/OPERATOR_GUIDE.md +++ b/docs/OPERATOR_GUIDE.md @@ -106,8 +106,8 @@ During the watch: - Leave the terminal open. - Do not babysit every line. -- If it prints `observe`, do nothing. -- If it prints `manual_bid`, stop and run `./scripts/ratchet report` before deciding manually. +- Ignore intermediate cycle lines unless you intentionally want to stop early. +- Wait for the final cockpit. The final `DO THIS NOW` section is the instruction that matters. Stop early with `Ctrl-C`. @@ -117,6 +117,7 @@ When the watch completes normally, it writes: - `reports/EXPERIMENT_LOG.md`: the master ratchet ledger. - `reports/run-*.md`: the detailed report for this one run. +- The final cockpit, then control returns to your shell prompt. Read the ledger with: diff --git a/scripts/ratchet b/scripts/ratchet index 86add55..1c59baa 100755 --- a/scripts/ratchet +++ b/scripts/ratchet @@ -11,7 +11,7 @@ Braiins Ratchet Commands: next Show exactly what to do next. Default command. setup Create the local .venv and initialize the local database. - once Run one full monitor cycle, then print the human report. + once Fetch one fresh sample, then print the cockpit. watch [hours] Run repeated monitor cycles for N hours. Default: 6. report Print the latest stored report without fetching new data. experiments Print the Karpathy-style experiment ledger. @@ -58,7 +58,8 @@ cmd_next() { cmd_once() { run_python -m braiins_ratchet.cli cycle >/dev/null echo - run_python -m braiins_ratchet.cli report + echo "Fresh sample collected. Reading the cockpit now." + echo "Technical report is available with: ./scripts/ratchet report" echo run_python -m braiins_ratchet.cli next } @@ -78,9 +79,12 @@ cmd_watch() { fi cycles=$((hours * 3600 / interval_seconds)) - echo "Running $cycles cycles over about $hours hour(s), one cycle every $interval_seconds seconds." - echo "Stop early with Ctrl-C. This only reads public/OCEAN data and writes local snapshots." - echo "At completion it writes reports/EXPERIMENT_LOG.md and reports/run-*.md." + echo "Watch started. This terminal is now controlled by Braiins Ratchet for about $hours hour(s)." + echo "You do not need to babysit it. Leave this terminal open and come back later." + echo "It will run $cycles cycles, one cycle every $interval_seconds seconds." + echo "It only reads public/OCEAN data and writes local snapshots inside this repo." + echo "At the end it writes reports/EXPERIMENT_LOG.md plus a run report, then prints DO THIS NOW." + echo "Stop early only if you intentionally want a partial run: Ctrl-C." echo set +e @@ -91,7 +95,7 @@ cmd_watch() { exit "$status" fi echo - run_python -m braiins_ratchet.cli report + echo "Watch finished. Reading the cockpit now." echo run_python -m braiins_ratchet.cli next return "$status" diff --git a/src/braiins_ratchet/guidance.py b/src/braiins_ratchet/guidance.py index ecafbd4..85fecec 100644 --- a/src/braiins_ratchet/guidance.py +++ b/src/braiins_ratchet/guidance.py @@ -81,7 +81,8 @@ def _do_this_now( if active_watch: return [ " WAIT.", - " A watch is already running. Do not start another command.", + " The running watch process is in control. Do not start another ratchet command.", + " You can leave it alone; it will write the experiment report when it finishes.", " After the watch terminal finishes by itself, run exactly:", " ./scripts/ratchet", ] @@ -113,7 +114,9 @@ def _do_this_now( return [ " Run exactly:", " ./scripts/ratchet watch 2", - " Reason: manual_canary means the model sees a bounded learning opportunity, not proven profit. The watch command will print this cockpit again when it ends.", + " Then leave that terminal alone for about 2 hours.", + " The watch command keeps control, writes the run report, and prints this cockpit again when it ends.", + " Reason: manual_canary means the model sees a bounded learning opportunity, not proven profit.", ] return [