# PUBLIC_API — mgf-fed

> Tracks the live `__all__` of `mgf.fed` (AP-10 / DOC-08). The machine companion
> [`PUBLIC_API.json`](PUBLIC_API.json) is generated from `__all__` and pinned in CI. May be ahead
> of the published registry during a release window (REL-03).

`mgf-fed` is primarily a **CLI tool**, not an import library — its real interface is the
`mgf-fed` command surface, not a Python API. The importable public surface is intentionally minimal.

## `mgf.fed`

| Name | Tier | Notes |
|---|---|---|
| `__version__` | **stable** | the package version (AP-13: in sync with `pyproject.toml`). |

All other modules are single-underscore **private** (`mgf.fed._status`, `_drift`, `_gates`,
`_localci`, `_index`, `_release`, `_scaffold`, `_registry`, `_doctor`, `_roster`, `_template`,
`__main__`) — internal to the CLI, **not** a supported import surface (AP-14).

`mgf.fed.sessionhooks` is the one subpackage without a leading underscore, and it is **not an
exception to that rule**: every module inside it is single-underscore private (`_state`, `_events`,
`_session_start`, `_gate`, `_install`, `_cli`), nothing from it is re-exported through
`mgf.fed.__all__`, and its supported surface is the `mgf-fed hooks` **CLI verbs** below — not a
Python API. The package name is un-underscored only because a hook shim in a repo's
`settings.json` names it in plain sight; treat it as internal (AP-14). It is **stdlib-only by
contract**: `mgf-fed hooks` is a native verb precisely so the shim keeps working on a base install
with no `[cli]` extra, and adding a `mgf-common` import to the hook path would silently break that.

## CLI surface (the operational interface)

`mgf-fed {status, drift-check, local-index, gates, local-ci, release-local, release-remote,
scaffold, registry, doctor}` — **stable** for the documented flags; run `mgf-fed --help` /
`mgf-fed <cmd> --help`. New subcommands/flags are additive; removals follow a deprecation cycle (AP-04).

`mgf-fed hooks {status, install, uninstall, emit, log}` — the session-hook kit
([`docs/howto/session-hooks.md`](docs/howto/session-hooks.md)). `mgf-fed hooks
{session-start, writeset, gate}` are **harness entrypoints**: invoked by the installed shim, they
read the harness's hook JSON on stdin and are not a human-facing surface. The installed shim text
(`mgf-fed hooks session-start`) is itself a compatibility surface — every adopting repo carries it
in `.claude/settings.json`, so renaming that action breaks them all at once.
