# ToeStub

[![toestub-ci](https://github.com/RogueGringo/ToeStub/actions/workflows/ci.yml/badge.svg)](https://github.com/RogueGringo/ToeStub/actions/workflows/ci.yml)

**Job OS cognitive governor** for external systems — pin-sealed multi-source oilfield job coherence, explore-vs-certify firewall, multi-well rotation, partner audit, and optional **MCP** attachment for agent hosts (Cursor / Claude / Grok).

> Pin sealed. Explore never certifies. Never λ=γ.

This is a **standalone distribution** extracted from the 123abc-grok research monorepo. External teams can clone, configure, and run without the protein dual-gate stack.

**License:** MIT

---

## Quick start (Windows)

```bat
git clone https://github.com/RogueGringo/ToeStub.git
cd ToeStub
install.bat
menu.bat
```

| Script | Role |
|--------|------|
| `install.bat` | Python deps + import check |
| `menu.bat` | CMD menu (cfg, smoke, rotation, audit, MCP) |
| `run_mcp.bat` | Start stdio MCP server for hosts |
| `cfg\toestub.ini` | Paths and job defaults |

### Menu map

1. Show configuration  
2. Edit `cfg\toestub.ini` (Notepad)  
3. Fixture smoke (expects **certified**)  
4. Custom run (LAS/MP/survey from cfg)  
5. Multi-well rotation (fixture dual well)  
6. Catalog runs  
7. Audit latest run  
8. MCP connect help  
9. Start MCP server (stdio)  
T. Unit tests  
I. Re-install deps  
0. Exit  

---

## Configure

Edit [`cfg/toestub.ini`](cfg/toestub.ini):

```ini
[paths]
default_las = C:\path\to\well.las
default_micropulse = C:\path\to\MicroPulse_dir
default_survey = C:\path\to\SURVEY.csv
out_dir = out\job_os

[job]
channel_pack = surface_min
max_rows = 500
max_depth_mono_violations = 5
with_dynamical_topology = true
```

Free params are closed-set only (`align_mode`, `window_scale`, `channel_pack`, `null_policy`, `survey_gate`, `regime_mode`).  
Pin knobs (`depth_mono_eps`, mono violations) are **pin_config**, not free.

---

## MCP (agent hosts)

```bat
run_mcp.bat
```

Or host JSON ([`examples/toestub.mcp.json`](examples/toestub.mcp.json)):

```json
{
  "mcpServers": {
    "toestub": {
      "command": "python",
      "args": ["-m", "toestub.mcp_server"],
      "env": {
        "PYTHONPATH": "C:/PRIMEdEV-1/ToeStub",
        "TOESTUB_REPO_ROOT": "C:/PRIMEdEV-1/ToeStub"
      }
    }
  }
}
```

Point `PYTHONPATH` / `TOESTUB_REPO_ROOT` at **your** clone path.

### Tools

| Tool | Purpose |
|------|---------|
| `toestub_job_run` | Job OS OS-mode loop |
| `toestub_job_catalog` | INDEX of runs |
| `toestub_job_rotation` | Multi-well same pin |
| `toestub_job_audit` | Partner audit (no re-ingest) |
| `toestub_firewall_read` | Read FIREWALL.json |

---

## CLI (operators)

```bat
set PYTHONPATH=%CD%
python job_coherence.py --os --las fixtures\mini_edr.las --out-dir out\job_os
python job_coherence.py --catalog --out-dir out\job_os
python job_coherence.py --audit out\job_os\<run_id>
python job_coherence.py --rotation examples\job_rotation_fixture.manifest.json --out-dir out\rotation
```

---

## Law

- **CERTIFY** = pin hard seal + fixed-point (empty free board × K)  
- **EXPLORE** = science / topology / λ1 trends — `not_acceptance`  
- Near-miss: explore looks good, certify fails → **reject for ship**  
- No shell tool; no soft_T / pin rewrite via free params  

Design: [`docs/design-toestub-mcp.md`](docs/design-toestub-mcp.md)

---

## Requirements

- Windows 10+ (menu.bat) or any OS for Python/MCP  
- Python 3.11+  
- `pip install -r requirements.txt`  

---

## Provenance

Kernel modules: `realm/job_os`, `realm/dynamical_topology`, `realm/kb_geometry`, `toestub`  
Upstream research monorepo: [RogueGringo/123abc-grok](https://github.com/RogueGringo/123abc-grok)

---

## License

Same as upstream monorepo unless otherwise noted. Contact maintainer for commercial terms.