saymrwulf/BraiinsRatchet
1
0
Fork 0
mirror of https://github.com/saymrwulf/BraiinsRatchet.git synced 2026-05-14 20:37:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add foolproof user and operator guides

Browse source
This commit is contained in:
saymrwulf 2026-04-28 17:50:54 +02:00
parent fd9e7df350
commit 2c3308a69a
7 changed files with 1034 additions and 126 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
README.md
View file

@ -74,10 +74,16 @@ To embed an already completed manual session from stored snapshots:
./scripts/ratchet retro 2026-04-25T19:08:00+00:00 2026-04-25T21:05:00+00:00
```
For the human operating guide:
For the noob-friendly user guide:
```bash
./scripts/ratchet explain
./scripts/ratchet guide
```
For the operator installation, migration, recovery, and architecture handbook:
```bash
./scripts/ratchet operator-guide
```
Import a manual Braiins market snapshot:
@ -120,6 +126,8 @@ The Braiins market report distinguishes visible top-of-book from executable dept
- `PROGRAM.md`: research charter and ratchet rules.
- `START_HERE.md`: no-prior-knowledge operating instructions.
- `docs/USER_GUIDE.md`: app-first noob guide for the complete autoresearch loop.
- `docs/OPERATOR_GUIDE.md`: architecture, installation, migration, backup, recovery, and diagnostics.
- `SECURITY.md`: token, computer, and trading safety guardrails.
- `docs/BRAIINS_PUBLIC_MARKET.md`: public market collector behavior.
- `docs/RATCHET_OPERATIONS.md`: day-to-day monitor cycle.

16
START_HERE.md
View file

@ -111,6 +111,20 @@ reports/run-*.md
Use the app's `Evidence` tab when you need raw artifacts. Flight Deck intentionally hides raw logs during normal operation.
## Full Guides
Read the user guide when you want the complete noob-friendly story:
```bash
./scripts/ratchet guide
```
Read the operator guide when you need installation, migration to another Mac, backup, recovery, or architecture:
```bash
./scripts/ratchet operator-guide
```
## Advanced Fallback Commands
Use these only if the native app cannot be opened or you are debugging:
@ -126,6 +140,8 @@ Use these only if the native app cannot be opened or you are debugging:
./scripts/ratchet position list
./scripts/ratchet report
./scripts/ratchet experiments
./scripts/ratchet guide
./scripts/ratchet operator-guide
```
The preferred workflow remains the native app.

19
docs/CLI_REFERENCE.md
View file

@ -13,6 +13,10 @@ Use `./scripts/ratchet raw-cycle` only when debugging the machine-readable cycle
Use `./scripts/ratchet app` to build and open the packaged native macOS app. It creates `macos/build/Braiins Ratchet.app`; `swift run` is only a developer fallback.
Use `./scripts/ratchet guide` for the user-facing operating story.
Use `./scripts/ratchet operator-guide` for architecture, installation, migration, backup, recovery, and diagnostics.
The raw Python CLI is documented below for debugging and development.
All raw commands should be run from the repository root.
@ -31,6 +35,21 @@ Prints the cockpit: current state, exact next operator action, interpretation, a
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli next
```
## Wrapper Guide Commands
These are wrapper commands, not raw Python subcommands:
```bash
./scripts/ratchet guide
./scripts/ratchet user-guide
./scripts/ratchet explain
./scripts/ratchet operator-guide
```
`guide`, `user-guide`, and `explain` print `docs/USER_GUIDE.md`.
`operator-guide` prints `docs/OPERATOR_GUIDE.md`.
## `pipeline`
Prints a monitor-only automation proposal and asks for `yes` or `no`.

678
docs/OPERATOR_GUIDE.md
View file

@ -1,199 +1,633 @@
# Operator Guide
# Braiins Ratchet Operator Guide
This project is a monitor and decision aid. It does not place Braiins orders.
This handbook is for installing, operating, migrating, recovering, and auditing the whole Braiins Ratchet system.
Think of it in Karpathy autoresearch terms:
The user guide is `docs/USER_GUIDE.md`. This file is lower-level and includes architecture, state ownership, host migration, and failure procedures.
1. Observe the world.
2. Score one small candidate action.
3. Do nothing unless the score clears strict guardrails.
4. If you manually act, wait for the result to mature.
5. Ratchet the strategy only after measured evidence improves.
## Operator Contract
## First-Time Setup
The system is monitor-only.
From the repository root:
It can:
1. Collect public Braiins market data.
2. Collect OCEAN dashboard data.
3. Store local snapshots.
4. Evaluate a shadow strategy.
5. Write run reports.
6. Start and stop a repo-local background monitor engine.
7. Track manual exposure entered by the user.
It cannot:
1. Place Braiins orders.
2. Modify Braiins orders.
3. Cancel Braiins orders.
4. Spend BTC.
5. Infer owner-token state that was not entered into the app.
6. Guarantee OCEAN block discovery.
Owner tokens must never be placed in this repository.
## System Architecture
### Tech Stack
The current stack is:
1. `SwiftUI` native macOS app in `macos/BraiinsRatchet`.
2. Swift tools `6.2` with `.macOS(.v26)`, targeting macOS Tahoe on Apple Silicon.
3. Python lifecycle and strategy engine in `src/braiins_ratchet`.
4. Python standard library only for runtime logic.
5. Repository-local Python virtual environment at `.venv`.
6. SQLite durable state at `data/ratchet.sqlite`.
7. Markdown evidence reports under `reports/`.
8. Bash launchers in `scripts/`.
9. Git and GitHub on branch `master`.
### Runtime Layers
Layer 1 is the native app.
The app lives at `macos/BraiinsRatchet`. It presents the Flight Deck, Hashflow, Ratchet, Bid Lab, Exposure, and Evidence views. It calls the local script interface and displays structured state.
Layer 2 is the script boundary.
`./scripts/ratchet` is the stable operator entry point. It creates `.venv` if missing, sets `PYTHONPATH`, runs the Python CLI, builds the Mac app, and opens the packaged bundle.
Layer 3 is the Python CLI.
`src/braiins_ratchet/cli.py` exposes commands such as `app-state`, `cycle`, `watch`, `engine`, `position`, `report`, and `experiments`.
Layer 4 is durable state.
`src/braiins_ratchet/storage.py` owns SQLite tables for OCEAN snapshots, market snapshots, proposals, lifecycle state, lifecycle events, and manual positions.
Layer 5 is research evidence.
`src/braiins_ratchet/experiments.py` writes `reports/EXPERIMENT_LOG.md`, `reports/run-*.md`, and the active watch marker.
Layer 6 is the background engine.
`src/braiins_ratchet/engine.py` starts a detached monitor-only supervisor, writes `data/supervisor.pid`, and logs to `logs/supervisor.log`.
### Data Flow
Normal data flow:
1. App asks for structured state with `./scripts/ratchet app-state`.
2. Python reads `data/ratchet.sqlite`.
3. Python computes current operator state and automation plan.
4. App renders the result graphically.
5. If the operator starts the engine, Python runs `supervise --yes` in the background.
6. The supervisor runs watch stages, records snapshots, writes reports, and enters cooldown.
One monitor cycle:
1. Fetch OCEAN snapshot.
2. Fetch public Braiins market snapshot.
3. Compute shadow proposal with `strategy.propose`.
4. Store proposal.
5. Return one of `observe`, `manual_canary`, or `manual_bid`.
### Durable Files
Critical files:
1. `data/ratchet.sqlite`: primary durable state.
2. `data/ratchet.sqlite-wal` and `data/ratchet.sqlite-shm`: possible SQLite WAL sidecar files.
3. `reports/EXPERIMENT_LOG.md`: master experiment ledger.
4. `reports/run-*.md`: run-level evidence.
5. `config.example.toml`: active default configuration unless a custom config is passed.
Operational files:
1. `data/supervisor.pid`: PID for the background engine.
2. `logs/supervisor.log`: background engine output.
3. `reports/ACTIVE_WATCH.json`: marker for a running watch.
4. `.venv`: local Python environment, disposable.
5. `macos/build/Braiins Ratchet.app`: generated app bundle, disposable.
Source files:
1. `src/braiins_ratchet`: Python engine.
2. `macos/BraiinsRatchet`: native app source.
3. `scripts`: operator launchers.
4. `tests`: network-free test suite.
## Installation On A New Mac
Requirements:
1. macOS Tahoe.
2. Apple Silicon Mac.
3. Xcode or Xcode command-line tools with Swift 6.2 support.
4. Python 3.
5. Git.
6. Network access to GitHub, OCEAN, and public Braiins endpoints.
Fresh clone:
```bash
git clone -b master https://github.com/saymrwulf/BraiinsRatchet.git
cd BraiinsRatchet
```
Initialize local runtime:
```bash
./scripts/ratchet setup
```
What this does:
- Creates `.venv` inside this repo if needed.
- Initializes `data/ratchet.sqlite`.
- Does not install packages.
- Does not touch anything outside the repo.
After setup, use the cockpit:
Run tests:
```bash
./scripts/ratchet
./scripts/ratchet test
```
The cockpit tells you exactly what to do next. If you are unsure, run it again.
Build and open the app:
## First Live Check
```bash
./scripts/ratchet app
```
Run:
First live sample:
```bash
./scripts/ratchet once
```
What this does:
Preferred normal operation:
- Fetches one OCEAN snapshot.
- Fetches one public Braiins market snapshot without a token.
- Computes the current breakeven and strategy recommendation.
- Prints a report.
1. Open the app.
2. Use `Start Forever Engine`.
3. Leave the engine alone unless manual exposure needs to be recorded.
It intentionally hides raw JSON. If debugging is needed, use:
## Daily Operation
Normal app-first routine:
1. Start with `./scripts/ratchet app`.
2. Read `Flight Deck`.
3. If `ENGINE LIVE`, do nothing.
4. If `REFRESH`, run one fresh sample from the app.
5. If `WATCH`, start the forever engine or run one bounded watch.
6. If `COOLDOWN`, wait.
7. If `HOLD`, supervise manual exposure.
8. If `REVIEW`, inspect `Bid Lab` and `Evidence`.
Terminal fallback:
```bash
./scripts/ratchet raw-cycle
./scripts/ratchet
./scripts/ratchet once
./scripts/ratchet engine status
./scripts/ratchet engine start
./scripts/ratchet engine stop
./scripts/ratchet report
./scripts/ratchet experiments
```
## How To Read The Report
Use terminal fallback only when the app cannot open or you are debugging.
Focus on `Strategy action`.
## Autoresearch Lifecycle
If it says:
The lifecycle is:
```text
Strategy action: observe
1. Sense.
2. Price.
3. Watch.
4. Mature.
5. Adapt.
`Sense` collects public OCEAN and Braiins inputs.
`Price` computes a shadow order and expected economics.
`Watch` records a bounded window without spending BTC.
`Mature` prevents the operator from judging evidence too early.
`Adapt` changes at most one strategy knob.
The allowed knobs are:
1. Depth target.
2. Overpay cushion.
3. Canary spend.
4. Duration.
5. Timing window.
Never change multiple knobs in one ratchet step.
## Manual Exposure Procedure
Manual exposure means the user placed a real Braiins order outside the app.
Immediately record it:
```bash
./scripts/ratchet position open --description "Braiins canary, 0.00010 BTC, 180 min, price 0.47741 BTC/EH/day, target OCEAN" --maturity-hours 72
```
Do not place a bid. The market is not cheap enough or required data is missing.
Check positions:
If it says:
```text
Strategy action: manual_bid
```bash
./scripts/ratchet position list
```
The strategy thinks a small manual profit-seeking bid clears the configured discount guardrails. You still decide manually in the Braiins UI.
Close only when the real position is finished:
If it says:
```text
Strategy action: manual_canary
```bash
./scripts/ratchet position close POSITION_ID
```
The market is not a money-printer setup, but the expected loss is inside the configured research budget. This is the scientific mode: a tiny canary may be useful to learn about execution, timing, OCEAN accounting, stale/reject behavior, and TIDES maturity.
While any position is active:
Important fields:
1. The lifecycle enters manual exposure hold.
2. New watch experiments are blocked.
3. The engine should not open a new passive research stage.
4. The operator must supervise the real-world Braiins/OCEAN position.
- `best_ask_btc_per_eh_day`: current buy reference from Braiins.
- `fillable_price_btc_per_eh_day`: depth-aware price where enough unmatched ask supply exists for the configured canary-sized target PH/s.
- `suggested_bid_btc_per_eh_day`: fillable price plus the configured overpay cushion; this is the shadow-autopilot would-bid price.
- `breakeven_btc_per_eh_day`: estimated mining EV at current OCEAN/network inputs.
- `score_btc`: risk-adjusted expected value. Negative means no action.
- `proposed_spend_btc`: canary spend, currently tiny by design.
- `maturity`: how long to wait before judging a manually executed canary.
## Background Engine
## Normal Monitoring Session
Start:
```bash
./scripts/ratchet engine start
```
Status:
```bash
./scripts/ratchet engine status
```
Stop:
```bash
./scripts/ratchet engine stop
```
Engine files:
1. PID: `data/supervisor.pid`.
2. Log: `logs/supervisor.log`.
3. State: `data/ratchet.sqlite`.
Crash behavior:
1. If the app crashes, the engine may keep running.
2. If the engine crashes, SQLite state remains.
3. If the Mac reboots, the engine is not guaranteed to restart automatically.
4. After reboot, run `./scripts/ratchet app` and start the engine again if desired.
## Switching To Another macOS Host
This is the safe migration procedure.
### On The Old Mac
Stop the background engine:
```bash
./scripts/ratchet engine stop
```
Check that it stopped:
```bash
./scripts/ratchet engine status
```
Commit and push source changes if any source files changed:
```bash
git status
git add README.md START_HERE.md docs src scripts tests macos config.example.toml pyproject.toml
git commit -m "Save Braiins Ratchet source state"
git push
```
Do not force commit runtime reports if you intentionally want them local only. If reports are part of the evidence you want on the new host, copy them in the backup step.
Create a state backup outside the repo or on external storage:
```bash
mkdir -p ~/Desktop/braiins-ratchet-backup
cp data/ratchet.sqlite* ~/Desktop/braiins-ratchet-backup/
cp -R reports ~/Desktop/braiins-ratchet-backup/
cp config.example.toml ~/Desktop/braiins-ratchet-backup/
```
Optional log backup:
```bash
cp -R logs ~/Desktop/braiins-ratchet-backup/
```
Do not copy `.venv` and do not copy `macos/build`. They are generated.
### On The New Mac
Clone the repository:
```bash
git clone -b master https://github.com/saymrwulf/BraiinsRatchet.git
cd BraiinsRatchet
```
Initialize runtime:
```bash
./scripts/ratchet setup
```
Restore state backup:
```bash
cp ~/Desktop/braiins-ratchet-backup/ratchet.sqlite* data/
cp -R ~/Desktop/braiins-ratchet-backup/reports .
cp ~/Desktop/braiins-ratchet-backup/config.example.toml config.example.toml
```
If you backed up logs:
```bash
cp -R ~/Desktop/braiins-ratchet-backup/logs .
```
Verify restored state:
```bash
./scripts/ratchet
./scripts/ratchet experiments
./scripts/ratchet position list
./scripts/ratchet engine status
```
Build and open the app:
```bash
./scripts/ratchet app
```
Start the engine only after verifying the state:
```bash
./scripts/ratchet engine start
```
### Migration With Active Manual Exposure
If a real Braiins order is active during migration:
1. Stop the engine on the old Mac.
2. Back up `data/ratchet.sqlite` and `reports/`.
3. Restore on the new Mac.
4. Run `./scripts/ratchet position list`.
5. Confirm the active exposure is still listed.
6. Do not start new experiments.
7. Start the engine only if you want it to hold and monitor around the active position.
8. Close the position only after the real Braiins/OCEAN exposure is finished.
The app cannot reconstruct unrecorded manual exposure. If the user placed an order but did not record it before migration, record it manually on the new host before starting experiments.
## State Recovery
### App Window Looks Wrong Or Old
Run:
```bash
./scripts/ratchet watch 6
./scripts/ratchet app
```
This watches for about 6 hours, sampling every 5 minutes.
The launcher rebuilds the bundle, closes stale `BraiinsRatchetMac`, and opens the fresh app.
During the watch:
### Engine Status Looks Stale
- Leave the terminal open.
- Do not babysit every line.
- 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`.
If you stop early, the tool writes a partial experiment report and then prints the cockpit.
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:
Run:
```bash
./scripts/ratchet engine status
```
The status command checks the PID file and process table. If the PID file is stale, it clears itself when possible.
### A Watch Was Interrupted
Run:
```bash
./scripts/ratchet
./scripts/ratchet experiments
```
## Ratchet Bookkeeping
If a partial report exists, treat it as instrumentation evidence. Do not treat it as a full strategy result.
The terminal report answers "what is happening now?"
If the app says no watch process exists but the ledger shows an unfinished run marker, do not delete data immediately. First inspect:
The experiment ledger answers "what did we learn and what should change next?"
```bash
./scripts/ratchet report
./scripts/ratchet experiments
```
Every completed `watch` records:
Then either run a fresh `once` or start a new watch only if the cockpit says it is safe.
- The hypothesis being tested.
- Start time, end time, sampling interval, and collected sample count.
- How many times the strategy said `observe`, `manual_canary`, or `manual_bid`.
- The min/avg/max visible strategy price.
- The min/avg/max expected net BTC.
- A plain-English adaptation note.
### SQLite State Exists But App Shows Empty
If you ran a session before automatic bookkeeping existed, embed it retroactively:
Check file location:
```bash
ls -l data/ratchet.sqlite
```
Run setup and next:
```bash
./scripts/ratchet setup
./scripts/ratchet
```
If the file was copied from another host while a process was writing to it, stop all engines and copy the database again from a clean backup.
### Reports Exist But Ledger Is Missing
If `reports/run-*.md` exists but `reports/EXPERIMENT_LOG.md` is missing, preserve the reports and restart normal monitoring. Future runs will recreate the ledger.
For old stored snapshots, use a retro report:
```bash
./scripts/ratchet retro 2026-04-25T19:08:00+00:00 2026-04-25T21:05:00+00:00
```
Use UTC timestamps from the raw report. This reconstructs the run from stored SQLite snapshots. It cannot recover operator intent that was not written down at the time, so the report marks the run as `retroactive`.
### Public Endpoint Failure
## When To Act
Symptoms:
Only consider a profit-seeking manual bid when all of these are true:
1. `once` fails.
2. App remains stale.
3. Reports do not update.
- `Strategy action: manual_bid`.
- `score_btc` is positive.
- `best_ask_btc_per_eh_day` is below the guardrail-adjusted breakeven.
- The proposed spend is acceptable to lose.
- You can wait through the maturity window before judging the result.
Immediate response:
Do not act because OCEAN is "due". Block discovery is memoryless.
1. Do not bid.
2. Wait and retry later.
3. Use `Evidence` or `./scripts/ratchet report` to inspect last known state.
Only consider a research canary when all of these are true:
Fallback for manual market fixture:
- `Strategy action: manual_canary`.
- `proposed_spend_btc` is acceptable to lose.
- `expected_net_btc` is not worse than the configured canary loss budget.
- You are explicitly buying information, not pretending the edge is proven.
- You can wait through the maturity window before judging the result.
## How Long To Wait After A Manual Canary
Use the report's `maturity` line.
With the current OCEAN estimate, it is about:
```text
72 hours
```bash
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli import-market examples/market_snapshot.example.json
PYTHONPATH=src ./.venv/bin/python -m braiins_ratchet.cli evaluate
```
That comes from the 8-block TIDES window and about 9 hours expected OCEAN block time. Do not judge the experiment after only minutes or a few hours.
Manual imported snapshots are for debugging and should not be treated as live price action unless the operator created them from a current source.
## Daily Routine
## Backup Policy
Practical routine:
Minimum backup:
1. Morning: `./scripts/ratchet once`
2. If `observe`: do nothing.
3. If you want live monitoring: `./scripts/ratchet watch 6`
4. If `manual_bid`: inspect `./scripts/ratchet report`
5. If you manually place a canary, write down the Braiins order parameters and wait through the maturity window.
1. `data/ratchet.sqlite*`.
2. `reports/`.
3. `config.example.toml` or any custom config file.
## Safety Boundaries
Optional backup:
- No owner token goes into this repo.
- No watcher token is needed for public price monitoring.
- No code here places orders.
- `.venv` and `data/` are local runtime state.
- The Git branch is `master`.
1. `logs/`.
2. `results.tsv` if you use it for external analysis.
Do not back up as authoritative state:
1. `.venv`.
2. `macos/build`.
3. Python cache directories.
4. Swift build directories.
## Git Policy
The branch is `master`.
Before risky changes:
```bash
git status
```
After source changes:
```bash
./scripts/ratchet test
swift build --package-path macos/BraiinsRatchet
git add README.md START_HERE.md docs src scripts tests macos config.example.toml pyproject.toml
git commit -m "Describe the change"
git push
```
Do not commit owner tokens.
Be deliberate with `reports/`. Reports can be evidence, but local live reports may also be operational artifacts. Check `git status` before staging.
## Security Model
Allowed:
1. Public Braiins market data.
2. Public OCEAN dashboard data.
3. Watcher-only token only if future read-only account data is needed.
Forbidden:
1. Braiins owner token.
2. Any token that can place orders.
3. Any automatic spend path.
4. Any code path that modifies Braiins orders without a separate reviewed change.
If a secret is accidentally placed in the repo:
1. Stop work.
2. Remove it from files.
3. Rotate the secret at the provider.
4. Treat Git history as contaminated until cleaned.
## Diagnostics
Check app state:
```bash
./scripts/ratchet app-state
```
Check latest plain report:
```bash
./scripts/ratchet report
```
Check ledger:
```bash
./scripts/ratchet experiments
```
Check engine:
```bash
./scripts/ratchet engine status
```
Check lifecycle:
```bash
./scripts/ratchet supervise --status
```
Check manual exposure:
```bash
./scripts/ratchet position list
```
Check tests:
```bash
./scripts/ratchet test
```
Check Swift build:
```bash
swift build --package-path macos/BraiinsRatchet
```
## Release Checklist
Before pushing a release-quality change:
1. Run `./scripts/ratchet test`.
2. Run `swift build --package-path macos/BraiinsRatchet`.
3. Run `./scripts/build_mac_app`.
4. Run `./scripts/ratchet app`.
5. Confirm the app opens as the native Flight Deck.
6. Confirm `git status` does not accidentally include runtime-only reports.
7. Commit on `master`.
8. Push to GitHub.
## Operator Do-Not-Do List
Do not delete `data/ratchet.sqlite` unless intentionally resetting all local lifecycle state.
Do not copy a live SQLite file while the engine is writing unless you have stopped the engine first.
Do not start two watches at the same time.
Do not run terminal watches while the app says the engine owns control.
Do not treat cooldown as wasted time.
Do not change more than one strategy knob per ratchet step.
Do not let an unrecorded manual Braiins order exist outside the ledger.
Do not use a Braiins owner token in this project.

361
docs/USER_GUIDE.md Normal file
View file

@ -0,0 +1,361 @@
# Braiins Ratchet User Guide
This guide is for operating the app without needing to understand the code.
The short version is:
1. Open the app with `./scripts/ratchet app`.
2. Stay on `Flight Deck`.
3. Read the giant decision word.
4. If the app says `ENGINE LIVE`, leave it alone.
5. If you manually place a Braiins order, immediately record it in `Exposure`.
6. Never start a second watch when the app says a watch, cooldown, engine, or exposure owns control.
## The Story
Braiins Ratchet is a research cockpit for one question:
Can we find better timing and sizing rules for manually buying hashpower on Braiins and pointing it at OCEAN, while minimizing loss and learning fast?
The system does not try to be a money printer. It does not assume that every opportunity must be profitable. It treats each run as an experiment. A small expected loss can be acceptable if it buys useful information and stays inside the configured research budget.
The app is monitor-only. It never places, modifies, or cancels Braiins orders. You remain the only actor with owner-token power.
## What The Tool Controls
The tool can influence only the research process:
1. When to observe.
2. When to run a passive watch.
3. How to evaluate public Braiins prices against OCEAN mining economics.
4. How to record evidence.
5. When to stop repeating the same experiment.
6. When manual exposure blocks further experiments.
7. Which strategy knob may be changed next.
The tool does not control:
1. Bitcoin price.
2. Global hashrate.
3. Energy prices.
4. OCEAN block luck.
5. Braiins order matching.
6. Your Umbrel, Knots, Datum, or OCEAN account.
7. Any Braiins owner-token action.
## Your Mental Model
Think of the system as a laboratory wheel:
1. `Sense`: fetch OCEAN and Braiins public market data.
2. `Price`: compute current breakeven and shadow order economics.
3. `Watch`: collect a bounded time window without spending BTC.
4. `Mature`: wait long enough that the last evidence is not misread.
5. `Adapt`: change exactly one knob only if the evidence justifies it.
This is the Karpathy-style ratchet. One run does not prove a strategy. One run moves the wheel by one click.
## First Open
From the repository root:
```bash
./scripts/ratchet app
```
This rebuilds and opens the native macOS app. If an old Braiins Ratchet window is open, the launcher replaces it with the fresh app.
The normal app tabs are:
1. `Flight Deck`: main decision cockpit.
2. `Hashflow`: how Umbrel, Knots, Datum, Braiins, OCEAN, and block luck interact.
3. `Ratchet`: the autoresearch loop and time horizons.
4. `Bid Lab`: shadow order, breakeven, expected net, and loss budget.
5. `Exposure`: manual Braiins position recorder.
6. `Evidence`: raw reports and diagnostic text.
If you are unsure, stay on `Flight Deck`.
## Flight Deck Reading Order
Read the screen in this order every time:
1. The giant decision word.
2. The `control` puck.
3. The `next` puck.
4. The four instrument chips.
5. The `Forever Engine` panel.
Do not start by reading raw reports. Raw reports are for checking details after the app tells you why they matter.
## The Decision Words
`LOAD` means the app is reading local state.
What you do: wait a few seconds.
`REFRESH` means the latest market data is missing or stale.
What you do: press `One Sample` or use the toolbar refresh path if enabled.
`WATCH` means a passive watch is useful.
What you do: prefer `Start Forever Engine` if you want the app to keep running the lifecycle. If you are using terminal fallback, run one watch only.
`ENGINE LIVE` means the forever engine owns passive research.
What you do: do nothing. Leave the app open or closed. The background engine keeps the monitor-only lifecycle moving.
`WAIT` means a watch is already running.
What you do: do not start anything else.
`COOLDOWN` means the last watch already produced evidence and the system is intentionally waiting.
What you do: wait until the earliest action time shown by the app.
`HOLD` means a manual Braiins exposure is active.
What you do: supervise the real-world position and do not start new experiments.
`REVIEW` means the stricter profit-seeking guardrails produced a manual review signal.
What you do: read `Bid Lab` and `Evidence`. Any Braiins order still remains manual.
`OBSERVE` means no useful action window is visible.
What you do: do not bid. Waiting is a valid action.
## The Three Strategy States
`observe` means the model does not recommend a bid or canary now.
Correct interpretation: the tool sees no useful window. This is not failure. It is evidence that the current market state did not clear even the research trigger.
`manual_canary` means a tiny research canary is inside the configured expected-loss budget.
Correct interpretation: this is not a profit claim. It means the system may recommend learning from a small bounded experiment, or watching the window more carefully before any manual spend.
`manual_bid` means the stricter profit-seeking guardrails cleared.
Correct interpretation: this is still not automatic execution. It is a manual review signal. You must inspect the evidence before doing anything in Braiins.
## What A Passive Watch Does
A passive watch does not spend BTC.
It collects repeated samples:
1. OCEAN pool and network state.
2. Public Braiins market data.
3. A strategy proposal for each sample.
4. A run report under `reports/run-*.md`.
5. A ledger entry in `reports/EXPERIMENT_LOG.md`.
The default watch stage used by the forever engine is 2 hours. It samples every 5 minutes, so a full stage normally has 24 cycles.
## What The Forever Engine Does
`Start Forever Engine` starts a repo-local background monitor loop.
The loop is:
1. Resume local SQLite state.
2. If a manual exposure is active, hold.
3. If cooldown is active, wait.
4. If ready, run one 2-hour passive watch.
5. Write reports and ledger entries.
6. Enter cooldown.
7. Repeat until stopped.
It never places Braiins orders.
If the app or Mac restarts, open the app again and start the engine again if needed. The app reads the same SQLite state and continues from the last recorded phase.
## The Time Horizons
The app always has three horizons.
`Immediate` means what is useful now.
Examples: wait, refresh once, hold exposure, start engine, inspect report.
`Midterm` means what is likely after the current stage finishes.
Examples: after cooldown, collect one fresh sample; after a watch, compare the run report; after manual exposure, close the position when finished.
`Longterm` means what may become reasonable only after repeated evidence.
Examples: lower overpay cushion, change depth target, change canary duration, change canary spend, test a different timing window.
Workflow probabilities are not profit probabilities. They estimate what the research process will probably ask you to do, not whether mining will win.
## What Counts As Evidence
Evidence is not a feeling. Evidence is written state.
Useful evidence includes:
1. A completed run report in `reports/run-*.md`.
2. A ledger entry in `reports/EXPERIMENT_LOG.md`.
3. A sequence of stored Braiins market snapshots.
4. A sequence of stored OCEAN snapshots.
5. A manually recorded exposure with opening and closing information.
Not evidence:
1. A single scary red number during a running watch.
2. OCEAN feeling due for a block.
3. A best ask that disappears before executable depth exists.
4. An unrecorded manual Braiins order.
5. A result judged before the OCEAN share window has had time to mature.
## Potential Findings
The ratchet can find several useful things even if no profit appears.
Finding type 1: Braiins price is usually too close to breakeven.
Response: keep observing; do not escalate spend.
Finding type 2: canary windows appear, but only at very shallow depth.
Response: test a smaller depth target before changing spend.
Finding type 3: overpay cushion dominates the loss.
Response: lower the overpay cushion for the next experiment.
Finding type 4: windows are time-of-day dependent.
Response: test a timing window, but keep all other knobs unchanged.
Finding type 5: OCEAN variance overwhelms short runs.
Response: increase patience and maturity tracking, not spend.
Finding type 6: manual execution friction is the biggest cost.
Response: improve operator procedure before strategy complexity.
Finding type 7: profit-seeking guardrails occasionally clear.
Response: inspect the full report and decide manually. Record any exposure immediately.
## The One-Knob Rule
Only change one knob at a time:
1. Depth target.
2. Overpay cushion.
3. Canary spend.
4. Duration.
5. Timing window.
If two knobs change together, the next run cannot tell which knob mattered.
## Manual Braiins Action Procedure
Only you can place a Braiins order.
Before doing anything in Braiins:
1. Confirm the app says `REVIEW` or the evidence explicitly supports a small `manual_canary`.
2. Open `Bid Lab`.
3. Read price, spend, duration, expected net, breakeven, and reason.
4. Decide whether the proposed spend is acceptable to lose.
5. Place the order manually only if you still want to.
6. Immediately record the exposure in `Exposure`.
When recording exposure, include enough text that future you understands it:
```text
Braiins canary, 0.00010 BTC, 180 min, price 0.47741 BTC/EH/day, target OCEAN
```
After recording exposure, the app should enter `HOLD`.
Do not start new watch experiments while real exposure is active.
## Maturity Rule
Do not judge a manual canary immediately after it ends.
OCEAN payouts depend on share accounting and block luck. The app currently treats canary evidence as immature for roughly the OCEAN share-log window, often about 72 hours with the current assumptions.
During maturity:
1. Do not declare victory.
2. Do not declare failure.
3. Do not increase spend.
4. Keep the exposure recorded.
5. Close it only when the real Braiins/OCEAN position is finished and you are ready to resume research.
## Crash Or Reboot
If the app crashes:
1. Reopen it with `./scripts/ratchet app`.
2. Read `Flight Deck`.
3. If the engine is not running and you want continuous monitoring, press `Start Forever Engine`.
If the Mac reboots:
1. Open Terminal.
2. Go to the repo.
3. Run `./scripts/ratchet app`.
4. Read `Flight Deck`.
5. Start the engine if you want the lifecycle to continue.
The important state is in `data/ratchet.sqlite`, not in the app window.
## What Not To Do
Do not start multiple watches.
Do not treat `manual_canary` as a profit signal.
Do not place an order because OCEAN feels due.
Do not increase spend after one lucky result.
Do not change several strategy knobs together.
Do not use owner tokens in this repo.
Do not delete `data/ratchet.sqlite` unless you intentionally want to lose local state.
## Where To Look When Confused
Use this order:
1. `Flight Deck`: what to do now.
2. `Ratchet`: where the experiment is in the loop.
3. `Bid Lab`: why the current proposal exists.
4. `Exposure`: whether real money blocks new experiments.
5. `Evidence`: raw report and ledger.
6. `docs/OPERATOR_GUIDE.md`: installation, recovery, migration, and diagnostics.
## Glossary
`Braiins`: the hashpower marketplace where you can manually buy temporary hashrate.
`OCEAN`: the mining pool where the purchased hashrate is pointed.
`Umbrel`: your local host environment.
`Knots`: your Bitcoin node implementation.
`Datum`: the mining template and routing path.
`TIDES`: OCEAN payout accounting model with a share window.
`Breakeven`: estimated Braiins price where expected mining reward equals spend.
`Expected net`: modeled reward minus spend before real-world luck.
`Score`: expected net after downside penalty.
`Canary`: tiny experiment that may lose money but should buy information.
`Manual exposure`: a real Braiins order you placed manually and recorded in the app.

13
scripts/ratchet
View file

@ -23,7 +23,9 @@ Commands:
retro SINCE [UNTIL] Write a retroactive report from stored snapshots.
raw-cycle Run one full monitor cycle and print raw JSON.
test Run the network-free test suite.
explain Print the operating procedure and interpretation guide.
guide Print the noob-friendly user guide.
operator-guide Print the installation, migration, and recovery guide.
explain Alias for guide.
Examples:
./scripts/ratchet
@ -37,6 +39,8 @@ Examples:
./scripts/ratchet position list
./scripts/ratchet report
./scripts/ratchet experiments
./scripts/ratchet guide
./scripts/ratchet operator-guide
./scripts/ratchet retro 2026-04-25T19:08:00+00:00 2026-04-25T21:05:00+00:00
USAGE
}
@ -169,6 +173,10 @@ cmd_test() {
}
cmd_explain() {
cat "$ROOT_DIR/docs/USER_GUIDE.md"
}
cmd_operator_guide() {
cat "$ROOT_DIR/docs/OPERATOR_GUIDE.md"
}
@ -193,7 +201,8 @@ main() {
retro) cmd_retro "$@" ;;
raw-cycle) cmd_raw_cycle "$@" ;;
test) cmd_test "$@" ;;
explain) cmd_explain "$@" ;;
guide|user-guide|explain) cmd_explain "$@" ;;
operator-guide|operator) cmd_operator_guide "$@" ;;
help|-h|--help) usage ;;
*)
echo "Unknown command: $command" >&2

61
tests/test_docs.py Normal file
View file

@ -0,0 +1,61 @@
from pathlib import Path
import unittest
ROOT = Path(__file__).resolve().parents[1]
class DocumentationContractTests(unittest.TestCase):
def test_user_guide_covers_full_autoresearch_loop(self):
text = (ROOT / "docs" / "USER_GUIDE.md").read_text()
self.assertIn("# Braiins Ratchet User Guide", text)
self.assertIn("The Story", text)
self.assertIn("Sense", text)
self.assertIn("Price", text)
self.assertIn("Watch", text)
self.assertIn("Mature", text)
self.assertIn("Adapt", text)
self.assertIn("Immediate", text)
self.assertIn("Midterm", text)
self.assertIn("Longterm", text)
self.assertIn("Potential Findings", text)
self.assertIn("manual_canary", text)
self.assertIn("manual_bid", text)
self.assertIn("observe", text)
self.assertIn("never places, modifies, or cancels Braiins orders", text)
def test_operator_guide_covers_architecture_and_host_recovery(self):
text = (ROOT / "docs" / "OPERATOR_GUIDE.md").read_text()
self.assertIn("# Braiins Ratchet Operator Guide", text)
self.assertIn("System Architecture", text)
self.assertIn("Tech Stack", text)
self.assertIn("SwiftUI", text)
self.assertIn(".macOS(.v26)", text)
self.assertIn("Python standard library only", text)
self.assertIn("SQLite durable state", text)
self.assertIn("Switching To Another macOS Host", text)
self.assertIn("State Recovery", text)
self.assertIn("data/ratchet.sqlite*", text)
self.assertIn("reports/EXPERIMENT_LOG.md", text)
self.assertIn("git clone -b master", text)
self.assertIn("owner token", text.lower())
def test_readme_and_wrapper_expose_guides(self):
readme = (ROOT / "README.md").read_text()
start_here = (ROOT / "START_HERE.md").read_text()
wrapper = (ROOT / "scripts" / "ratchet").read_text()
self.assertIn("docs/USER_GUIDE.md", readme)
self.assertIn("docs/OPERATOR_GUIDE.md", readme)
self.assertIn("./scripts/ratchet guide", readme)
self.assertIn("./scripts/ratchet operator-guide", readme)
self.assertIn("./scripts/ratchet guide", start_here)
self.assertIn("./scripts/ratchet operator-guide", start_here)
self.assertIn("guide|user-guide|explain", wrapper)
self.assertIn("operator-guide|operator", wrapper)
if __name__ == "__main__":
unittest.main()