# Recipe: the onboard prompt (bring an EXISTING external project into the federation)

> **Front door:** reachable via `mgf-fed start --mode onboard`. `mgf-fed start`
> is the single onboarding front-door over all four prompts.

> **Audience:** an AI agent (or human) in an **existing, non-MGF** project (it has
> code + history) that should **become a federation member** — a new `mgf-*`
> sibling library, or a consumer application that joins under the standards.
> **What this is:** the migrate/onboard prompt — the join-decision *plus* the
> full first-time conformance of existing code. It is the fourth federation
> entry point. `mgf-fed onboard-prompt` prints it (self-updating).

## When to use

- An **existing outside project** you are bringing **into** the federation.
- **Not** `new-project` (that's an *empty* repo), **not** `sync` (that's an
  *already-member* resync — though onboard routes through the same conformance
  engine), and **not** `adopt` (that's a non-member staying *outside*).

## The prompt

Copy the block below into an agent launched from the root of the existing project.

```text
ROLE: You are bringing an EXISTING, non-MGF project INTO the Magogi Foundation (MGF) federation as a
NEW member (a sibling library, or a consumer application). It already has code, history, and its own
conventions — UNDERSTAND the federation, DECIDE the join shape, then CONFORM the existing code COMPLETELY.
Treat your MODE as NEW. Zero assumptions; read the living sources, never work from memory.

STEP 0 — INSTALL + UNDERSTAND (read the federation; do not guess):
  pip install -U 'mgf-common[standards]'   # needs the codeberg-mgf index + $CB token (magogi-admin is PRIVATE)
  mgf-fed agents        # the canonical AI briefing + a live "you are here" federation map
  mgf-fed standards     # list EVERY topic and read them all (mgf.standard.list_standards / read_standard)
  # the contract + the WHY: mgf.standard.federation()  and  mgf.standard.read_design("federation")
  GUARD: if these error "install [standards]" or show no map, STOP and install the extra; never proceed degraded.

STEP 1 — DECIDE THE JOIN SHAPE (this is what makes onboarding different from a plain resync):
  • SHAPE: join as a SIBLING LIBRARY (reusable domain code → `mgf-<name>` dist + `mgf.<name>` import, per NM-*) or
    as a CONSUMER APPLICATION (an app that depends on mgf-* but isn't itself a library)? The contract
    (federation()) + DOCUMENTATION.md §2.0 define the shapes — pick one deliberately.
  • DEPENDENCY: add `mgf-common` (the cornerstone) as a real dependency — you are now downstream of it.
  • NAMING: a sibling RENAMES to `mgf-<name>` (dist + Codeberg slug) and `mgf.<name>` (import namespace) — plan the
    rename, it ripples (imports, pyproject, CI, on-disk); a consumer app keeps its name but adopts the standards.
  • Write this decision (shape + new name + the mgf-* deps you'll take) at the top of your plan BEFORE editing.

STEP 2 — CONFORM the existing code COMPLETELY (the heavy first pass):
  Run the federation conformance procedure end-to-end — it is `mgf-fed sync-prompt`, and all of it applies to
  you as a NEW member. Comprehend the whole federation (its PHASE A), then give EVERY current MUST a row in a new
  MGF_STANDARDS_CONFORMANCE.md (✅ / N/A-with-reason / ⏳ / 🚫-declined), retrofit the code, and ADD what a member
  needs that an outside project lacks: the uniform root-doc baseline (DOC-*), `.importlinter` layering (DP-*), the
  four-gate `.woodpecker` CI (WF-*), typed errors (EH-*), redaction/security (SC-*/LG-*), `py.typed` + PUBLIC_API
  for a library. Existing external code typically starts with MANY ⏳ — expected; COMPLETENESS (every MUST
  addressed, none silently skipped) is the bar, and you triage the ⏳ by priority. Prove the gates green:
  ruff check · ruff format --check · mypy --strict · lint-imports · pytest at/above the coverage floor · gitleaks.

STEP 3 — DECLARE + ASK TO BE REGISTERED:
  • Set your conformance level (L1/L2/L3) — L1 is the realistic start for a freshly-onboarded project.
  • Fill DEPS.md (what you depend on); pin mgf-* siblings `>=X,<X+1`.
  • You are a new leaf; the registry/roster is owned by mgf-standard. Request "add me to the federation registry"
    via a `pending-feedback/mgf-standard.md` note — do NOT edit the roster yourself.

GUARDRAILS: read-only on every OTHER repo (mgf-standard / mgf-common / siblings) — cross-repo needs go to a
`pending-feedback/<target>.md` outbox, never a direct edit (FB-05). Commit on a branch with the AG-03 trailers. Do
NOT publish/tag/release unless explicitly asked (the supervisor's REL-13 step). A big rename or a public-API change
is IRREVERSIBLE/cross-cutting — STOP and confirm with the human before doing it (the ASK gate).

DELIVERABLE: the join decision (shape + new name + mgf-* deps); identity + resolved versions; the §Z ledger with
EVERY MUST addressed (mostly ⏳ at first is fine); the gates' status; the request-to-be-registered note; and OPEN
QUESTIONS for the human (the rename, the level, any ambiguous applicability or irreversible change).
```

## Notes

- **Onboard = decide-to-join + the sync engine on existing code.** STEP 2 routes
  through `sync-prompt` deliberately (one conformance engine, no duplication); the
  onboard-specific value is STEP 1 (shape + naming + dependency) and the
  expectation that existing code starts with many ⏳.
- **Distinct from the other three:** `sync` (already a member), `new-project`
  (empty repo), `adopt` (stays a non-member). Self-updating via `read_recipe`.

## Related

- [`federation-sync-prompt.md`](federation-sync-prompt.md) — the conformance engine STEP 2 runs.
- [`federation-new-project-prompt.md`](federation-new-project-prompt.md) · [`federation-adopt-prompt.md`](federation-adopt-prompt.md) — the empty-repo + stay-outside cases.
- [`sibling_rename.md`](sibling_rename.md) — the eight-surface checklist for the STEP-1 rename, if joining as a sibling.
