# START HERE

> **Audience:** anyone (human or AI agent) using `mgf-common` to
> bring a project to the team's engineering-standards bar.
> **Two flows:** new project, existing project. **Both are one
> command.**

`mgf-common` is the cornerstone library + standards source-of-truth
for the team. Every project that depends on it inherits the same
quality bar (typed exceptions, structured logging, four-gate CI,
the AP/EH/LG/CF/SC/TS rule discipline).

---

## I'm starting a NEW project

```bash
# 1. Create + cd into the project directory
mkdir my-new-app && cd my-new-app && git init

# 2. Bootstrap the standards
mgf-common init-project --name my-new-app --kind fastapi
# Replace --kind with: cli / fastapi / django / library / service

# 3. Paste the printed pyproject.toml block
$EDITOR pyproject.toml # paste the snippet from step 2's stdout

# 4. Install + run the four gates
uv sync
uv run ruff check
uv run mypy --strict src/
uv run pytest

# 5. Open in Claude Code — CLAUDE.md auto-loads.
# Standards adherence is automatic from this point.
```

What `init-project` created:

- `docs/CLAUDE.md` — auto-loaded by Claude every session. Inlines
  the top-30 most-violated rules; points at
  `mgf-common standards <topic>` for full text.
- `.claude/settings.json` — sensible Claude permission defaults.
- (printed, not auto-written) `pyproject.toml` snippet with the
  four green gates pre-tuned.

That's the entire onboarding. Subsequent Claude sessions in this
project automatically know the team's standards — no manual
prompting required.

---

## I have an EXISTING project that should catch up

```bash
cd /path/to/your/project

# 1. Audit (read-only — shows drift, no changes)
mgf-common catch-up

# 2. Apply mechanical fixes (creates missing files, refreshes
# auto-managed CLAUDE.md block; backs up originals)
mgf-common catch-up --apply
```

What `catch-up` audits:

| Row | What it checks |
|---|---|
| ✅ pin | Is `mgf-common` in your `pyproject.toml` dependencies, with a sensible version bound? |
| ✅ four gates | Are `[tool.ruff]`, `[tool.mypy] strict`, `[tool.pytest filterwarnings=error]`, and a coverage threshold all configured? |
| ✅ docs/CLAUDE.md | Does it exist? Does it have the BEGIN/END auto-managed markers? Is the auto-block content current? |
| ✅ .claude/settings.json | Does it exist with safe defaults? |
| ✅ patterns | Are there any legacy `configure() / setup_logging() / install_excepthook()` calls that should migrate to `bootstrap()`? |

Read-only by default — you see the drift report before any changes
land. `--apply` is the explicit opt-in.

`--apply` ONLY does mechanical updates:
- Creates missing `docs/CLAUDE.md` from the current template.
- Creates missing `.claude/settings.json` with safe defaults.
- Refreshes the auto-managed block in an existing CLAUDE.md (between
  `<!-- BEGIN mgf-common ... -->` and `<!-- END mgf-common ... -->`).
- **Project-specific content below the END marker is preserved.**
- Originals get a `.bak.<timestamp>` backup before any rewrite.

It does NOT auto-modify:
- Your `pyproject.toml` (prints the suggested snippet; you paste it).
- Legacy call sites of `configure() / setup_logging() /
  install_excepthook()` (the migration to `bootstrap()` is
  structural; surfaced as a warning so you can plan the work).

---

## Telling another Claude session about this project

If you're directing another AI agent (in another project) to bring
that project to current standards, **one sentence does the job:**

> *"Run `mgf-common catch-up` in this project's root. It'll audit
> against the current mgf-common standards and print a drift report
> with mechanical suggestions. Apply ones you agree with via
> `--apply`."*

That's the entire instruction. The other agent reads the audit
report, decides what to apply, and runs it. No version-specific
guidance needed — `catch-up` ships from the running mgf-common
version, so it's always current.

---

## Reading the standards on demand

The 10 engineering-standards docs are bundled with `mgf-common`.
Read any of them via:

```bash
mgf-common standards # list all topics
mgf-common standards LOGGING # print the LOGGING.md doc
mgf-common standards security # alias also works (case-insensitive)
mgf-common standards --paths # absolute paths to the doc files
```

Available topics: `DESIGN_PRINCIPLES`, `ERROR_HANDLING`, `LOGGING`,
`CONFIGURATION`, `SECURITY`, `TESTING`, `API_DESIGN`, `SCOPE`,
`COMMON_COMPONENTS`, `README`.

Aliases: `logging`, `errors`, `config`, `api`, `security`,
`testing`, `scope`, `components`, `design`.

---

## Filing feedback against mgf-common

Hit a sharp edge? Want a primitive lifted? File an entry in
mgf-common's `FEEDBACK.md`:

```bash
mgf-common feedback # how to submit
mgf-common feedback --template # entry template, ready to paste
mgf-common feedback --url # FEEDBACK.md URL on codeberg
```

---

## Recap — the four CLI moves

```bash
mgf-common init-project # NEW project: scaffold the skeleton
mgf-common catch-up # EXISTING project: audit + apply current standards
mgf-common standards # read any engineering-standards doc on demand
mgf-common feedback # file feedback against mgf-common itself
```

That's it. Everything else (logging, exceptions, settings, OTel,
crash reporter, FastAPI / Django / DB / alembic adapters, vault,
provider seams, etc.) is API surface — read the recipe at
`docs/public/recipes/<topic>.md` or `mgf-common standards <topic>`.

---

## Where to look next

- **End-to-end tutorial:** [`docs/public/tutorial.md`](docs/public/tutorial.md) — zero → working app in ~30 min.
- **Federation pattern:** [`docs/public/federation.md`](docs/public/federation.md) — how `mgf-common` + sibling packages compose under the `mgf.*` namespace.
- **Per-recipe how-to:** `docs/public/recipes/` (one file per integration).
- **Component-level deep dives:** `docs/public/01_lifecycle.md` … `10_full_app.md`.
- **Public-API contract:** `PUBLIC_API.md` (every public name + stability tier).
- **Architecture (for contributors to mgf-common itself):** `docs/internal/ARCHITECTURE.md`.

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