# START HERE — mgf-standard

> **Audience:** anyone — human or AI agent — working in THIS repo (the
> federation's standards / contract / registry source of truth), or trying
> to find where the Magogi rules live.

`mgf-standard` is the **standards leaf** of the Magogi Foundation: it
owns the engineering-standards corpus ([`docs/standards/`](docs/standards/)),
the federation contract ([`FEDERATION.md`](FEDERATION.md) — canonical
here), the library registry ([`MGF_LIBRARIES.md`](MGF_LIBRARIES.md)), and a
tiny zero-dependency data package (`mgf.standard`) that ships the corpus
so `mgf-common`'s CLI can surface it. See [`README.md`](README.md) for the
full picture.

## If you just want to READ the rules

You don't need this repo checked out. In any federation project:

```sh
mgf-fed standards            # list topics
mgf-fed standards LOGGING    # print one
mgf-fed agents               # the canonical AI-agent briefing
```

Those resolve this repo's corpus via `mgf.standard.standards_dir()`.

## If you're an AI agent working IN this repo

> **Note:** unlike every other federation repo, `mgf-common` is **not** a
> dependency here (this repo sits *below* it), so `mgf-fed agents` may
> not be installed. Read the canonical briefing from the source:
> [`mgf-common/STARTHERE.md` §"For the AI agent in any Magogi project"](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/STARTHERE.md).

Then:

1. Read [`FEDERATION.md`](FEDERATION.md) — the contract lives **here**; you
   are editing the source of truth.
2. Read [`docs/claude/CLAUDE.md`](docs/claude/CLAUDE.md) — this repo's
   dense-lookup agent notes — and [`docs/memory/`](docs/memory/), this repo's
   committed durable memory ([AG-17](docs/standards/AGENTS.md#AG-17)): the
   `MEMORY.md` index plus one-fact-per-file topic notes that survive a fresh
   clone.
3. **Changing a rule?** Follow DOC-18 change-propagation: update the
   README *Index of MUSTs* + every dependent named in the doc's
   *Propagation (DOC-18)* header — including the `mgf-fed standards` /
   `agents` CLI surfaces (which live in the `mgf-common` repo, so the
   ripple crosses repos) — in the same change.
4. **You are empowered, not just bound.** Read the
   [Agent Empowerment Charter](docs/standards/principles/agent-empowerment-charter.md)
   ([AG-15](docs/standards/AGENTS.md#AG-15)) — your explicit license to
   push back, propose, refine scope, ask, decline-with-rationale, and
   conclude "no change needed." This corpus guarantees consistency; it
   does not ask for blind compliance.

## If you're developing the package

```sh
uv sync --extra dev
ruff check src tests scripts && ruff format --check src tests scripts
mypy --strict src/
pytest
lint-imports
```

Regenerate the library registry (run from the federation parent dir that
holds all sibling checkouts):

```sh
python scripts/gen_mgf_libraries.py           # write MGF_LIBRARIES.md
python scripts/gen_mgf_libraries.py --check    # the REL-13 consistency gate
```

## Where things are

| Looking for… | Path |
|---|---|
| The rules | [`docs/standards/`](docs/standards/) |
| The contract | [`FEDERATION.md`](FEDERATION.md) |
| The registry | [`MGF_LIBRARIES.md`](MGF_LIBRARIES.md) |
| Federation-pattern paper | [`docs/design/federation.md`](docs/design/federation.md) |
| Federation-ops recipes | [`docs/recipes/`](docs/recipes/) |
| This repo's durable agent memory | [`docs/memory/`](docs/memory/) (AG-17) |
| The resolver package | `src/mgf/standard/__init__.py` |
| Feedback (standards / contract / registry) | [`FEEDBACK.md`](FEEDBACK.md) |
