# TOOLS_STARTHERE.md — the Magogi Foundation tools front-door

**One place to find and run every MGF tool.** The browser **web consoles**, the
**command-line tools**, what each is *for*, how to **install** it, and a real
**run** example. If you're new, start here and work down.

> **Prefer a launcher?** Run **`./fed-tools list`** (same directory) to see every
> tool, then **`fed-tools run <web-tool>`** to install + launch a web console for you
> — or **`fed-tools show <web-tool>`** to just print the commands. Keep them current
> with **`fed-tools update`** (or **`fed-tools update --check`** to only detect what's
> outdated — exits non-zero if any are). This file is the written reference behind
> that CLI.

---

## Install once, then any tool

Every MGF tool publishes to the self-hosted **devpi** index. Point pip/uv at it
once, and installs are clean:

```bash
# one-time (shell profile, pip.conf, or uv config)
export PIP_INDEX_URL=https://195.15.203.250.sslip.io/magogi/prod/+simple/

# then install any tool (swap `pip` for `uv pip` if you use uv)
pip install "mgf-fed[cli]"
mgf-fed status        # ← the federation tracking matrix; a good first run
```

The **only** exception is `mgf-cloud-web`, which is intentionally **off devpi** —
install it from source (shown in its section). Everything else is `pip install`.

---

## 🌐 Web consoles

Three browser GUIs, each bound to `127.0.0.1` on its own port, all rendered on the
shared **mgf-brand-web** kit (consistent Magogi styling + clean print).

### `mgf-cloud-web` — cloud console · http://127.0.0.1:8787
A single-user web GUI over `mgf-cloud`: create + manage Infomaniak/OpenStack VMs,
volumes, object storage, keypairs, and security groups without memorising the CLI.

```bash
# off devpi — install from source (or just: fed-tools run cloud-web)
git clone https://codeberg.org/magogi-admin/mgf-cloud-web.git
pip install -e ./mgf-cloud-web
mgf-cloud-web                      # → open http://127.0.0.1:8787
```
Needs working cloud credentials (see **mgf-cloud** below).

### `mgf-fed-web` — federation dashboard ("review web") · http://127.0.0.1:8788
The read-mostly cockpit for the whole federation. Per project it shows real
**status**, the end-to-end **roadmap**, what's **in-progress / stalled / next /
awaiting-decision**, a rounds-based human↔AI **feedback & review** loop, and a
**live activity** view. It's never a second source of truth: every panel is
*generated* from each repo's `fed-resources/`, anything computed is tagged
`derived`, and a freshness gate (`regenerate → byte-identical`) keeps "in sync" real.

```bash
pip install mgf-fed-web
mgf-fed-web                        # → http://127.0.0.1:8788
mgf-fed-web --host 0.0.0.0 --port 9000   # override the bind
```

### `mgf-test-web` / **ProofWarden** — test & CI authority console · http://127.0.0.1:8789
The console for **ProofWarden**. A resident **warden** daemon is the *sole*
executor of tests, so a given test can **never run twice at once** — no matter the
launcher (CLI, web, AI agent, or CI). You submit run *requests*; single-flight is
enforced by construction (coalesce a duplicate, queue a different one), with live
logs, a History view (effective config + lease audit), and **fail-closed** when the
warden is down. Base install = the warden + `testctl`; the `[web]` extra adds the console.

```bash
# the web console:
pip install "mgf-test-web[web]"
proofwarden                       # → http://127.0.0.1:8789

# CLI only (CI-installable, no FastAPI):
pip install mgf-test-web
testctl serve                     # start the resident warden (the sole test executor)
testctl run <test>                # single-flight; coalesces a duplicate, queues a different test
testctl status                    # what's running / queued
testctl catalog                   # the discoverable test catalog
```

---

## ⚙️ Core federation CLIs

### `mgf-fed` — the federation orchestrator
The meta-tool that runs the recurring cross-repo work. Install the `[cli]` extra
for the full surface.

```bash
pip install "mgf-fed[cli]"
mgf-fed status               # read-only tracking matrix across every repo
mgf-fed gates                # fast static gates (ruff lint + format) across a selection
mgf-fed drift-check          # diff each repo against the canonical scaffolding
mgf-fed scaffold <repo>      # apply the template's byte-exact files to a repo
mgf-fed registry --check     # REL-13 registry consistency + currency gate
mgf-fed app-doctor --standards   # audit a repo against the MGF standards + conformance ledger
mgf-fed release-remote <repo>    # tag → publish → verify on devpi
mgf-fed feedback --check         # relay cross-repo feedback outboxes
mgf-fed --help                   # the complete subcommand list
```

### `fedres` (mgf-fedres) — the fed-resources spine
The engine the web tools are built on: the `fed-resources/` convention, the
JSON-Schemas, the manifest + sha256 sync engine, and the freshness gate.

```bash
pip install mgf-fedres
fedres status                # shallow sync verdict (manifest)
fedres check                 # deep verdict: regenerate → byte-identical (the freshness gate)
fedres generate              # (re)generate fed-resources/generated/ from source + projectors
fedres run <op>              # record a live run into the NDJSON activity stream
fedres tail                  # follow that live stream
fedres-validate <payload.json>   # validate a payload against its schema
```

### `mtest` (mgf-test-supervisor) — the test supervisor
Budget-aware, crash-survivable, resumable; drives pytest from the outside in
chunks, writes a structured JSONL run record, and auto-quarantines flakes. This is
the runner the ProofWarden warden drives.

```bash
pip install mgf-test-supervisor
mtest                        # run the suite via the supervisor
mtest --self-check           # verify the supervisor's own prerequisites
```

---

## ☁️ Cloud & infra CLIs

### `mgf-cloud` — cloud resources
Create + manage VMs and storage on Infomaniak / OpenStack. Also the engine behind
`mgf-cloud-web`.

```bash
pip install "mgf-cloud[infomaniak]"
mgf-cloud vm list                  # list VMs
mgf-cloud vm create <name> ...     # create a VM
mgf-cloud volume | object | image | keypair | secgroup ...   # the rest
mgf-cloud --help
```
Reads `~/.config/openstack/clouds.yaml` (the `openstack` entry).

### `mgf-cloud-provision` — self-hosted infra provisioning
Declarative, idempotent provisioning of the Foundation's own services (devpi, CI
agents, Vault, central logs).

```bash
pip install "mgf-cloud-provision[infomaniak]"
mgf-cloud-provision <service-spec>   # provision/converge a service from its spec
mgf-cloud-provision --help
```

---

## 🔧 Domain CLIs

### `mgf-apiprobe` / `apiprobe` — REST API verification
Typed probes, checks, and findings for verifying REST APIs (OpenAPI-aware, request
signing, fixtures).

```bash
pip install "mgf-apiprobe[openapi]"
apiprobe --help
```

### `mgf-hrb` — hardware resource broker
Userspace arbitration of hardware (PCIe, …).

```bash
pip install mgf-hrb
mgf-hrb info                 # what hardware is present / brokered
mgf-hrb scan
```

---

## The brand layer

**mgf-brand-web** is the shared CSS / font / asset kit the three web consoles
render on (consistent Magogi styling + print). It's a library, not a runnable
tool — every new MGF web tool installs it and mounts `static_dir()` at
`/static/brand` (`pip install mgf-brand-web`).

---

## Quick reference

| Tool | Kind | Run | Where |
|---|---|---|---|
| **mgf-cloud-web** | web | `mgf-cloud-web` | http://127.0.0.1:8787 |
| **mgf-fed-web** | web | `mgf-fed-web` | http://127.0.0.1:8788 |
| **mgf-test-web** / ProofWarden | web | `proofwarden` | http://127.0.0.1:8789 |
| **mgf-fed** | CLI | `mgf-fed <cmd>` | federation orchestration |
| **fedres** | CLI | `fedres <cmd>` | fed-resources spine + gate |
| **mtest** | CLI | `mtest` | test supervisor |
| **testctl** | CLI | `testctl <cmd>` | warden / single-flight tests |
| **mgf-cloud** | CLI | `mgf-cloud <cmd>` | cloud resources |
| **mgf-cloud-provision** | CLI | `mgf-cloud-provision <spec>` | self-hosted infra |
| **mgf-apiprobe** | CLI | `apiprobe` | REST API verification |
| **mgf-hrb** | CLI | `mgf-hrb <cmd>` | hardware broker |

*New MGF tool? Add a row here and a section above — this file is the front-door.*
