# START HERE

> **Audience:** anyone — human or AI agent — bringing a project
> (this library, a sibling, or a consumer application) to the
> Magogi engineering bar.
> **AI agents:** the *"For the AI agent in any Magogi project"*
> section directly below is the single canonical briefing — point
> every Magogi project's agent there. There is no per-project
> variant; one message, the whole federation.

`mgf-common` is the cornerstone library + reference implementation
for the team; the engineering standards + federation contract live
in its [`mgf-standard`](https://codeberg.org/magogi-admin/mgf-standard)
sibling (read any rule with `mgf-fed standards <topic>`). Every
project that depends on mgf-common inherits the same quality bar
(typed exceptions, structured logging, four-gate CI, the
AP/EH/LG/CF/SC/TS rule discipline).

> **Reading order.** This file is the *procedural* entry — "do this,
> then this." The *contract* — "by depending on mgf-common, here is
> what you've committed to" — lives in [`FEDERATION.md`](FEDERATION.md).
> If you read only one page, read FEDERATION.md.

> **Onboarding a project? Start with `mgf-fed start`.** It is the single
> front-door over the four onboarding prompts — it detects your case and prints
> the right one: a brand-new member (`--mode new`), existing external code
> joining (`--mode onboard`), an existing member syncing (`--mode sync`), or a
> non-member adopting the standards (`--mode adopt`). `mgf-fed start --list`
> shows the menu. Print-only: it never edits files.

---

## For the AI agent in any Magogi project — read this first

> **This is the canonical agent briefing — printed verbatim by
> `mgf-fed agents`.** That command ships with the library, so it
> works in every Magogi project with no setup and no assumptions —
> the reliable way to deliver this message is *"run `mgf-fed
> agents` and do what it prints."* The text below and the
> `mgf-fed agents` output are kept identical by a test
> (`tests/unit/cli/test_agents.py`). One message for the whole
> federation; no per-project variant.

**You are an AI agent working inside a Magogi Foundation project.**
The Foundation is a family of Python projects that share one
engineering bar. Writing correct code for this project is only half
your job — the other half is keeping the project a good citizen of
the federation. Concretely:

**1 — Know the shape.** The Foundation has three rings: `mgf-common`
(the cornerstone library + reference implementation, which depends
on `mgf-standard` — the standards + federation-contract source
of truth), the
`mgf-*` sibling libraries (`mgf-http`, `mgf-fastapi`, `mgf-sqlalchemy`, `mgf-alembic`, `mgf-django`, `mgf-apiprobe`, `mgf-test-supervisor`, `mgf-auth`, `mgf-livepush`, `mgf-tele-core`, `mgf-tele-teltonika`, …), and consumer
applications that depend on them. Domain logic is built as a library FIRST; applications
consume libraries and never embed reusable domain logic.

**2 — Read the contract before you write code.** `FEDERATION.md` in
the `mgf-standard` repo is the canonical contract: required docs
layout, conformance levels, the federation-first principle,
catch-up cadence, feedback discipline. If you read one document,
read that one. The engineering rules are numbered families (AP, CF,
EH, LG, SC, TS, DP, DOC, …): run `mgf-fed standards` to list
them and `mgf-fed standards <topic>` to print any one. Cite
rules by ID.

**3 — Use the federation; do not reinvent it.** Before writing any
infrastructure code — logging, configuration, typed errors,
retries, vault, process management, HTTP client, DB layer,
rate-limiting, caching — check whether `mgf-common` or a sibling
already ships it. It almost certainly does (`FEDERATION.md §5` has
the "need X → use Y" table). Depend on the federation package, not
a competing third-party one. A hand-rolled version of something the
federation already provides is a defect, not a shortcut.

**4 — Follow the documentation layout + standards.** Every project
ships the universal root-doc baseline (`README`, `LICENSE`,
`CHANGELOG`, `CONTRIBUTING`, `SECURITY`, `FEEDBACK`, `AGENTS`,
`FEDERATION`, `STARTHERE`, `DEPS` — plus a `docs/` directory; for
non-cornerstone projects `FEDERATION.md` is a pointer stub, not a
copy) plus the federation trackers (`MGF_ADOPTION.md` for consumer
apps, `MGF_STANDARDS_CONFORMANCE.md` for every project). Every repo
also keeps committed in-repo memory at `docs/memory/` (a `MEMORY.md`
index + one-fact-per-file notes; AG-17) so durable agent context
travels with the repo, and uses the standardized `.gitignore` that
never commits `my_stuff/` local secrets (AG-18). The project
declares a conformance level — L1 / L2 / L3 — measuring how
strictly it follows the rules. Match the federation's structure;
never invent a parallel one.

**5 — Pick the federation's chosen tools — don't litigate them.**
Three infrastructure choices are already made; you don't redo them
per project. **CI/CD:** Woodpecker CI on Codeberg (rules WF-01..WF-13
in `mgf-fed standards workflows`) — same `.woodpecker.yml` runs
on Codeberg natively AND locally via `woodpecker-cli exec`. That
`.woodpecker.yml` is a GENERATED artifact (rendered by `mgf-fed
scaffold` from the canonical template; `mgf-fed drift-check`
enforces it) — never hand-edit it (WF-13); see the `run-ci` recipe.
**Testing:** the federation test runner is the published sibling
`mgf-test-supervisor` (rules TS-22..TS-28 in `mgf-fed standards
testing`) — install in dev extras, then `mgf-test-supervisor
--self-check` confirms it's wired. **Packages:** every `mgf-*`
package publishes to and resolves from the Codeberg PyPI registry
(rules PKG-01..PKG-12 in `mgf-fed standards pkg`), NOT pypi.org;
wire the `codeberg-mgf` named index + `[tool.uv.sources]` per
PKG-06 (third-party deps still resolve from public PyPI).
Per-project CI tools or hand-rolled test orchestrators are a
defect, not a shortcut.

**6 — Keep the project in sync — new, existing, or behind.** Run
`mgf-fed catch-up` in the project root. It audits drift (stale
dependency pin, missing four-gate CI, missing Woodpecker config,
missing test-supervisor dev dep, missing or stale agent files,
missing federation artifacts); `mgf-fed catch-up --apply` fixes
the mechanical parts. A project that has fallen behind the
federation must be caught up, not worked around. Consistency across
every project — old and new — is a goal, not an accident.

**7 — Leave feedback in the RIGHT place. This is how the federation
improves, and it is the most important item on this list.** When you
hit friction with another project — `mgf-common`, any sibling, or any
project you depend on — a missing capability, a sharp edge, an API
that does not fit, a document that misled you — do NOT silently work
around it, and do NOT record it only in your own repo where the
target's maintainer will never see it. **File a PAPER in the
`FEEDBACK.md` of the project that caused the friction — the target's
own repository.** Routing rule: friction with a specific project →
THAT project's `FEEDBACK.md`; a standards rule, the federation contract, or
the library registry → `mgf-standard`'s `FEEDBACK.md`; other cross-cutting
issues → `mgf-common`'s `FEEDBACK.md`. Give the target enough to **triage and
act without coming back to ask you** — every paper states: **what
hurts** (the concrete friction), **why it matters** (impact / who it
blocks), **concrete evidence** (a repro, `file:line`, commit SHA, and
the version you hit it on), and a **suggested shape** for the fix.
Run `mgf-fed feedback-howto` for the entry template. **You do NOT edit,
PR, or version-bump another project's library yourself — only the
mgf-common supervisor changes a library (AG-13); your job is the
paper, the supervisor's job is the fix + keeping the whole federation
consistent (`MGF_LIBRARIES.md` is the registry of what exists).** A
workaround buried in one consumer helps it once; a well-written paper in the target's
`FEEDBACK.md` improves that project for every consumer, forever. If
you routed around the federation instead of feeding back, the task is
not done — even when the code runs.

**8 — Consistency is the point.** Every Magogi project should read
as though one hand wrote it: the same structure, the same rule
discipline, the same primitives, the same feedback channel. When
you face a choice the federation has already made, make the same
choice.

**9 — You are empowered, not just bound (AG-15).** This corpus is
MUST-heavy so consistency is cheap — but it does NOT ask for blind
compliance. You MAY push back on a rule you believe is wrong or
misapplied here, propose a better path, refine scope up front (confirm
the project mode — greenfield / unconstrained-brownfield /
production-constrained — before substantial autonomous work; do not
apply production guardrails to a throwaway spike), decline a primitive
with recorded rationale, ask a clarifying question, and report
"reviewed; no change needed" as a first-class result. Exercising
judgment WITH a recorded rationale (a FEEDBACK paper per item 7, an
ADR, or a documented decline) is conformant; silent non-compliance is
not. When you hit an ambiguity that is not a risky/irreversible action,
do not stall: record the open question, choose a sensible default, mark
dependent conclusions inferred, and continue. The full license — the
six rights, the mode handshake, the never-block protocol, and what it
does NOT cover — is the **Agent Empowerment Charter** in the standards
corpus (`mgf-fed standards`; `principles/agent-empowerment-charter.md`).

**Startup checklist for this session:**

- **Ensure the standards corpus is installed:** `pip install -U 'mgf-common[standards]'`
  (or `uv add 'mgf-common[standards]'`). The `standards`, `agents` federation
  map, `catch-up` federation-position, `federation`/`design`, and `sync-prompt`
  commands resolve the rules + contract + design + registry from this OPTIONAL
  extra; a plain `mgf-common` install does NOT carry it and those commands
  degrade with an install prompt — never a silent partial answer.
- To bring this project current with the federation, run `mgf-fed sync-prompt`
  and follow it exactly — the enforced comprehend → conform → verify procedure.
- Run `mgf-fed agents` (this briefing — federation-wide duties) and
  `mgf-fed agents --project` (the SAME shape scoped to THIS project:
  its own `AGENTS.md` + `docs/claude/CLAUDE.md`). Every project has the
  project-scoped briefing via this one command.
- Run `mgf-fed catch-up` — audit this project's standing in the
  federation; read the report.
- Run `mgf-fed standards` — the rule topics; read whichever your
  task touches.
- Starting a brand-new project? Run `mgf-fed init-project`.
- **Before you call a change done (AG-14 / DOC-18):** walk the
  change-propagation matrix (`mgf-fed standards DOCUMENTATION` §10.4)
  for every surface you touched and update each dependent IN THE SAME
  commit — a new public symbol ripples to `PUBLIC_API.{md,json}` +
  CHANGELOG; a new/changed rule ripples to the README *Index of MUSTs*
  + the `standards`/`agents` CLI; a wire-schema change ripples to every
  parallel copy + its alignment test. Run `mgf-fed app-doctor --standards`
  as the backstop. "Update the docs in a follow-up" is the habit DOC-18
  forbids — leaving a dependent stale is a defect even when nothing is
  visibly broken.

**Canonical references, in order:** `FEDERATION.md` (the contract)
→ `STARTHERE.md` (procedural how-to) → `mgf-fed standards
<topic>` (the rules) → `docs/audience/ai-agents.md` (the
consumer ↔ maintainer feedback-relay protocol) → this project's
`docs/CLAUDE.md` (project-specific state). If anything conflicts,
`FEDERATION.md` wins — it is the canonical contract.

---

## Browsing the docs as a web UI

The repo has ~80 docs (standards, recipes, references, audience
pages, design papers, cutover guides). The fastest way to find
your way around without getting lost:

```bash
python tools/docs_explorer/serve.py
```

Opens `http://127.0.0.1:8765/` in your browser. Sidebar grouped by
category, full-text search, cross-doc links resolved, per-page TOC.
Stdlib-only, localhost-only (never exposed). `Ctrl+C` to stop.

Options: `--port 9000`, `--no-open`. Full notes at
[`tools/docs_explorer/README.md`](tools/docs_explorer/README.md).

---

## I'm starting a NEW project

```bash
mkdir my-new-app && cd my-new-app && git init                                # 1
mgf-fed init-project --name my-new-app --kind fastapi                     # 2
$EDITOR pyproject.toml   # paste the snippet step 2 printed                  # 3
uv sync && uv run ruff check && uv run mypy --strict src/ && uv run pytest   # 4
```

Replace `--kind` with: `cli` / `fastapi` / `django` / `library` / `service`.

What landed:

| Path | Role |
|---|---|
| `docs/CLAUDE.md` | Auto-loaded by Claude every session — top-30 rules inline. |
| `.claude/settings.json` | Safe Claude permission defaults. |
| `pyproject.toml` (printed snippet) | Four green gates pre-tuned. |

Open the project in Claude Code → CLAUDE.md auto-loads → standards
adherence is automatic from here.

| Want more? | Read |
|---|---|
| Full walkthrough | [`docs/recipes/new_project.md`](docs/recipes/new_project.md) |
| First-time tutorial (zero → working app, ~30 min) | [`docs/tutorial.md`](docs/tutorial.md) |
| Web-project reading order | `mgf-fed standards` → [mgf-standard `docs/standards/web/`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/web/README.md) |

---

## I have an EXISTING project (catch up to current standards)

```bash
cd /path/to/your/project
mgf-fed catch-up               # audit — read-only
mgf-fed catch-up --apply       # mechanical fixes (originals get .bak.*)
```

What `catch-up` audits:

| Row | What it checks |
|---|---|
| **pin** | `mgf-common` listed in `pyproject.toml` with a sensible version bound. |
| **four gates** | `[tool.ruff]`, `[tool.mypy] strict`, `[tool.pytest filterwarnings=error]`, coverage threshold. |
| **`docs/CLAUDE.md`** | Exists, has BEGIN/END auto-managed markers, content is current. |
| **`.claude/settings.json`** | Exists with safe defaults. |
| **patterns** | Legacy `configure() / setup_logging() / install_excepthook()` calls that should migrate to `bootstrap()`. |

`--apply` is mechanical only: creates missing files, refreshes the
auto-managed CLAUDE.md block (project content below the END marker
is preserved), backs up originals. It does NOT touch `pyproject.toml`
(prints the suggested snippet) or rewrite legacy call sites.

> **Telling another Claude session?** One sentence does it:
> *"Run `mgf-fed catch-up` in this project's root, review the drift
> report, apply with `--apply`."*

---

## When something feels off — debugging

| Command | What it tells you |
|---|---|
| `mgf-fed app-doctor` | Install-state + wiring health check. First thing to run when "is mgf-common bootstrapped here?" is the question. Modes: `--live` (runtime snapshot), `--redaction` (test redactor on stdin), `--standards` (audit against AP/DP/TS rules). |
| `mgf-fed explain` | Prints the active `MgfSettings` with each field's source (CLI / env / `.env` / file / default). The "why is this setting taking that value?" command. |
| `mgf-fed standards <topic>` | Prints any standards doc — `LOGGING`, `SECURITY`, `ERROR_HANDLING`, etc. |

Standards topics: `API_DESIGN`, `COMMON_COMPONENTS`, `CONFIGURATION`,
`DEPLOYMENT`, `DESIGN_PRINCIPLES`, `DOCUMENTATION`, `ERROR_HANDLING`,
`LOGGING`, `OPERABILITY`, `README`, `RELEASING`, `SCOPE`,
`SECURITY_STANDARD`, `TESTING`, `WORKFLOWS`, `WORKFLOWS_PATTERNS`.
Aliases (case-insensitive): `logging`, `errors`, `config`, `api`,
`security`, `testing`, `scope`, `components`, `design`. Run
`mgf-fed standards` (no argument) for the live list.

---

## Upgrading mgf-common across versions

```bash
mgf-fed migrate 0.18 0.19 src/    # mechanical renames + import fixes
mgf-fed migrate 0.18 0.19 src/ --dry-run --backup
```

Per-release migration narratives live in [`docs/cutover/`](docs/cutover/)
(v0.22 onward; pre-v0.22 in `archive/`). Federation-alignment cycles
also get an aggregated cutover — `docs/cutover/federation-v<X.Y>.md`.
The cutover guide is the canonical migration story; `migrate` handles
the mechanical parts.

---

## Filing feedback against mgf-common

```bash
mgf-fed feedback-howto              # how to submit + the entry template
mgf-fed feedback-howto --template   # entry template, ready to paste
mgf-fed feedback-howto --url        # FEEDBACK.md on codeberg
```

---

## CLI cheat-sheet

| Command | Use when |
|---|---|
| `mgf-fed init-project` | NEW project — scaffold the skeleton. |
| `mgf-fed catch-up` | EXISTING project — audit + apply current standards. |
| `mgf-fed app-doctor` | "Is mgf-common bootstrapped correctly here?" |
| `mgf-fed explain` | "Why is this setting taking that value?" |
| `mgf-fed standards <topic>` | Read any engineering-standards doc. |
| `mgf-fed migrate` | Upgrade across mgf-common versions. |
| `mgf-fed feedback-howto` | File feedback against mgf-common itself. |

Add `--help` to any subcommand for full options.

---

## Where to look next

**By audience** — pick the one that matches you:

| If you are… | Read |
|---|---|
| **Building** with mgf-common | [`docs/audience/users.md`](docs/audience/users.md) |
| **Evaluating** (is this a fit?) | [`docs/audience/shoppers.md`](docs/audience/shoppers.md) |
| **Contributing** to mgf-common | [`docs/audience/developers.md`](docs/audience/developers.md) |
| A **test/QA** engineer | [`docs/audience/qa.md`](docs/audience/qa.md) |
| Cutting **releases** | [`docs/audience/release.md`](docs/audience/release.md) |
| Doing a **security** review | [`docs/audience/security.md`](docs/audience/security.md) |
| An **AI agent** | [`docs/audience/ai-agents.md`](docs/audience/ai-agents.md) |

**By content** — what you're looking for:

| Looking for… | Path |
|---|---|
| Recipe index (every how-to in one place) | [`docs/recipes/README.md`](docs/recipes/README.md) |
| Engineering rules (MUST/SHOULD/MAY) | `mgf-fed standards <topic>` (corpus in [mgf-standard](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/)) |
| API reference per module | [`docs/reference/`](docs/reference/) |
| Tutorial (zero → working app) | [`docs/tutorial.md`](docs/tutorial.md) |
| Per-release migration | [`docs/cutover/`](docs/cutover/) |
| Public-API contract | [`PUBLIC_API.md`](PUBLIC_API.md) · [`PUBLIC_API.json`](PUBLIC_API.json) (machine-readable) |
| Design papers | [`docs/design/`](docs/design/) |
| Federation pattern (sibling `mgf-*` packages) | [mgf-standard `docs/design/federation.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/design/federation.md) |
| Architecture (for mgf-common contributors) | [`docs/design/architecture.md`](docs/design/architecture.md) |

*This document is the user-facing entry point. Maintainers: keep it
short; deep-dives go in `docs/`.*
