# TOOLS_STARTHERE.md — the MGF Family tools front-door

**One place to find and run every MGF Family 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.

> **Scope, said plainly.** This page and `fed-tools` cover the **MGF Family** — the
> installable `mgf-*` tools. The Magogi Foundation has **two** families; the **Sooth
> Family** keeps its own tooling, and it is *not* listed here. See
> [Sooth Family tools](#sooth-family-tools) at the bottom for where those live.
> ("MGF" is the whole Foundation; "MGF Family" is one of its two families — this
> file used to claim the first while delivering the second.)

> **Prefer a launcher?** Run **`./fed-tools install`** once (symlinks it into
> `~/.local/bin`), then **`fed-tools`** works from any directory. **`fed-tools list`**
> shows every tool — with a **`▶ running`** marker + live URL for any console that's
> up — then **`fed-tools run <web-tool>`** installs + launches one 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`** — exits non-zero if any are
> outdated), and **`fed-tools doctor`** checks the registry still covers every web
> console **and command-line tool** in the fleet *and* that each is current (add
> `--offline` to skip the devpi round-trip). This file is the written reference
> behind that CLI.

---

## Install once, then any tool

Every MGF tool is a CLI **application**, so install each into its own isolated
environment with [`uv`](https://docs.astral.sh/uv/) — the same tool the fleet's
`.venv`s and `uv.lock` already use. `uv tool install` puts each command on your
PATH (`~/.local/bin`) without touching the OS Python. (Modern Ubuntu/Debian mark
the system Python "externally managed" per PEP 668, so a plain system-wide
install is refused by design — `uv tool` sidesteps that cleanly; never override
the marker with `--break-system-packages`.)

```bash
# one-time: point uv at the self-hosted devpi index (add to your shell profile).
# $DEVPI_URL is the same variable CI uses (MGF_INFRA.md §2); this is its default.
export UV_DEFAULT_INDEX=https://195.15.203.250.sslip.io/magogi/prod/+simple/

# then install any tool — its command lands on your PATH
uv tool install "mgf-fed[cli]"
mgf-fed status        # ← the federation tracking matrix; a good first run

# manage them:  uv tool list  ·  uv tool upgrade mgf-fed  ·  uv tool uninstall mgf-fed
```

No uv yet? `curl -LsSf https://astral.sh/uv/install.sh | sh` — or `pipx` works the
same way (`pipx install "mgf-fed[cli]"`).

The **only** exception is `mgf-cloud-web`, which is intentionally **off devpi** —
install it from source (shown in its section), or just **`fed-tools run cloud-web`**
to clone + install + launch it for you. Everything else is `uv tool 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
uv tool install ./mgf-cloud-web    # its deps still resolve from devpi
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
uv tool 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:
uv tool install "mgf-test-web[web]"
proofwarden                       # → http://127.0.0.1:8789

# CLI only (CI-installable, no FastAPI):
uv tool 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
uv tool 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
```

### `mgf-secrets` — the credential plane
**The system of record for "what credentials exist and what can they do."** Ask it
before concluding a credential is missing — the filesystem is a cache, this is the
truth. `exec` is the agent-safe path: it injects values into a child process, so a
secret never has to pass through a transcript.

```bash
uv tool install mgf-secrets
mgf-secrets list             # the registry table (metadata only — never values)
mgf-secrets doctor           # declared == deployed == consumed (read-only)
mgf-secrets show <id>        # full metadata for one entry
mgf-secrets probe <id>       # that entry's liveness probe
mgf-secrets exec --with <id> -- <cmd>   # run a child with the value injected as env
mgf-secrets rotate <id>      # staged: generate → register → probe → cutover → verify → retire
mgf-secrets --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
uv tool 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
uv tool 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
uv tool 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
uv tool 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
uv tool install "mgf-apiprobe[openapi]"
apiprobe --help
```

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

```bash
uv tool 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`. Being a library it arrives as a dependency of the consoles —
you don't `uv tool install` it; a project that consumes it adds it with
`uv add mgf-brand-web` (or `uv pip install mgf-brand-web` into that project's venv).

---

## Sooth Family tools

The Foundation's **other** family keeps its tooling in
[`sooth-standard/tools/`](../../sooth-standard/tools/) — repo-local scripts run with
`python3`, not installed CLIs, so there is deliberately nothing to `uv tool install`
and nothing for `fed-tools` to launch. **Its canonical entrypoint is a command, not a
list:**

```bash
cd sooth-standard
tools/validate.sh                       # THE validation entrypoint — mirrors .woodpecker.yml, in CI order
python3 tools/verify_standard.py        # the bundle validator — the definition of done (prints PASS)
python3 tools/verify_family_conformance.py   # the family conformance matrix, whole fleet, one screen
python3 tools/gen_rules.py --check      # determinism gate over rules.json + the Index-of-MUSTs
```

Plus the intake/verification gates (`verify_ci.py`, `verify_handoff.py`,
`verify_court_return.py`, `verify_gap_finding.py`, `verify_settings_guard.py`),
the `preflight.py` observability check, and the SHP wiring in `shp_adopt.py`.

**Why they are not merged into `fed-tools`:** the MGF → Sooth edge is one-directional
and by-reference (sooth `SECRETS.md` **SEC-06**, `PKG-01`). MGF owns the *mechanism*;
Sooth owns its *usage* and its own gates. Listing them here would be MGF claiming a
surface it does not own — the pointer is the correct shape.

The credential plane is the one genuinely shared surface: `mgf-secrets` covers **both**
families (`mgf-secrets list` shows the `sooth` family column), and the cross-family CI
obligations are written down in
[`cross-family-ci-contract.md`](../../mgf-standard/docs/recipes/cross-family-ci-contract.md).

---

## 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 |
| **mgf-secrets** | CLI | `mgf-secrets <cmd>` | credential plane — registry, doctor, store |
| **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.*
