<!-- BEGIN mgf-common auto-generated — managed by `mgf-fed catch-up`.
Edit only between this block's BEGIN/END markers if you want catch-up to
refresh your changes; project-specific content goes BELOW the END marker
in the "Project-specific lookup" section. -->

Project-specific lookup for Claude sessions. Cross-project
engineering standards live in `mgf-common`; run
`mgf-fed standards <topic>` to read any one of them.

**▶ First, run `mgf-fed agents`** — it prints the canonical
federation-wide agent briefing (always installed; `mgf-common` is a
dependency of this project). The briefing covers the federation
shape, using the library + its siblings instead of reinventing
them, the standards + docs layout, keeping this project in sync with
`mgf-fed catch-up`, and filing feedback in the relevant library's
`FEEDBACK.md` when you hit friction so the library itself can improve.

> **Project kind:** cli
> **Cornerstone library:** `mgf-common` (this project depends on it).
> **Conformance level:** declare yours in
> `docs/inprogress/MGF_STANDARDS_CONFORMANCE.md` (L1 / L2 / L3) — see
> `mgf-fed standards README` §"Conformance levels for projects".

---

## Standing instructions — every session

Claude reads this file on every session start. The rules below are
canonical; the full text lives in `mgf-common` standards docs and
is accessible via:

```bash
mgf-fed standards            # list all topics
mgf-fed standards LOGGING    # print the full doc
mgf-fed standards security   # alias also works
```

**Before writing or editing code in any of these areas, read the
corresponding topic doc:**

| Area | Topic | Run |
|---|---|---|
| API surface (public functions, modules) | API_DESIGN | `mgf-fed standards api` |
| Error handling, exceptions, retries | ERROR_HANDLING | `mgf-fed standards errors` |
| Logging, redaction, OTel | LOGGING | `mgf-fed standards logging` |
| Configuration, settings, env vars | CONFIGURATION | `mgf-fed standards config` |
| Secrets, TLS, subprocess, crypto | SECURITY | `mgf-fed standards security` |
| Tests, fixtures, isolation | TESTING | `mgf-fed standards testing` |
| Architecture, layering, replaceability | DESIGN_PRINCIPLES | `mgf-fed standards design` |
| Scope (what belongs in this project) | SCOPE | `mgf-fed standards scope` |

---

## The top-30 most-violated rules (inline so they're always in context)

These are the rules that come up most often in code review. Treat
every MUST as non-negotiable. The ID prefix tells you which doc
the full rationale lives in (DP- = DESIGN_PRINCIPLES, EH- =
ERROR_HANDLING, etc.).

### Architecture (DP-)

- **DP-01** Layering MUST be enforced: UI MUST NOT be imported by
  core; core MUST NOT import third-party SDKs that have a provider
  in front of them.
- **DP-02** Every third-party I/O dep MUST sit behind an ABC with
  a production AND a mock implementation.
- **DP-03** Domain types passed between modules MUST be frozen
  dataclasses (or pydantic `frozen=True`); never bare strings/dicts.
- **DP-04** Every public function MUST have a typed signature;
  `mypy --strict` MUST pass on `src/`.
- **DP-09** Cancellation MUST be explicit. Long-running ops take
  an explicit `CancellationToken`-like parameter; never thread-global.
- **DP-11** Async tasks MUST have an owner. Bare
  `asyncio.create_task(...)` without retention is a defect.
- **DP-12** Time MUST be UTC at every boundary. `datetime.now()`
  is forbidden; use `datetime.now(UTC)`. Naive datetimes never
  cross module boundaries.
- **DP-13** Every owned external resource MUST be released
  deterministically via context manager or `try / finally`.
  GC-based cleanup is a defect.

### Error handling (EH-)

- **EH-01** Every exception raised by app code MUST be a subclass
  of the application's base error class (typically
  `mgf.common.exceptions.AppError`).
- **EH-02** Third-party exceptions MUST be translated to typed
  application exceptions at the boundary. Use
  `mgf.common.providers.ProviderABC` + `@translate_at_seam` for
  this.
- **EH-03** When re-raising a translated exception, the original
  cause MUST be chained via `raise NewError(...) from original`.
- **EH-04** Every entry point MUST install a top-level handler
  (folded into `mgf.common.bootstrap()` automatically).
- **EH-07** Bare `except Exception:` (without re-raise or typed
  translation) MUST NOT appear except in narrow cleanup paths.
- **EH-11** Retries MUST use exponential backoff with full jitter
  and a finite cap. Use `mgf.http.RetryPolicy` (sibling `mgf-http`).

### Logging (LG-)

- **LG-01** Every module MUST acquire its logger via
  `logging.getLogger(__name__)`. No bare `logging.info(...)`.
- **LG-04** Sensitive fields MUST be redacted by the formatter
  before any sink sees them. The default
  `mgf.common.observability.Redactor` covers the canonical set.
- **LG-05** Error-level logs MUST include the exception via
  `LOG.exception(...)` or `exc_info=True`.
- **LG-08** Log messages MUST use lazy `%`-style formatting
  (`LOG.info("processing %s", x)`), NOT f-strings.
- **LG-09** Structured fields MUST be passed via `extra={...}`.
- **LG-12** Log emission MUST be cheap (≤100 µs per record).
  Heavy work belongs in the handler, not the call site. Use
  `mgf.common.observability.AsyncJsonHandler` for non-blocking I/O.

### Configuration (CF-)

- **CF-01** Application config MUST live in a single typed object
  (`mgf.common.config.BaseAppSettings`-derived). No module reads
  config files / env vars directly.
- **CF-02** Precedence: CLI flags → env vars → `.env` → on-disk
  config → typed defaults.
- **CF-05** Secrets MUST NOT live in the config file; they live in
  a vault. Use `mgf.common.vault.VaultProtocol`.
- **CF-08** `Settings` is loaded once at the entry point and
  passed down by constructor injection. No module-global singletons.
- **CF-10** Tests MUST construct `Settings` with explicit values
  (no env-var leakage).

### Security (SC-)

- **SC-01** Secrets MUST live in a Vault, never in config / env /
  source / logs / crash reports.
- **SC-02** Subprocess invocation MUST use `argv` lists with
  `shell=False`.
- **SC-06** TLS verification MUST be enabled on every outbound
  connection.
- **SC-07** Every external request MUST carry a finite timeout.
- **SC-15** Filesystem operations MUST validate against directory
  traversal via `Path.resolve()` + `is_relative_to()`.

### Testing (TS-)

- **TS-01** `tests/` MUST mirror `src/` 1:1.
- **TS-02** The unit suite MUST run with no production
  credentials, no network, no real third-party daemon.
- **TS-04** `filterwarnings = ["error"]` MUST be set in
  `pyproject.toml`.
- **TS-06** Coverage gate ≥80% project-wide; ≥90% on changed
  lines.

### API design (AP-)

- **AP-01** Public API surface MUST be enumerated explicitly via
  `__all__` at every package and module boundary.
- **AP-04** Deprecation cycle MUST be: announce → still works
  (≥1 MINOR) → removed; deprecated names emit
  `DeprecationWarning`.
- **AP-08** Public modules MUST use
  `from __future__ import annotations`; runtime-unused imports go
  in `if TYPE_CHECKING:`.
- **AP-14** Internal modules MUST NOT be imported by consumers.
  Single-underscore module names are private.

---

## Quick start — bootstrapping this project

This project depends on `mgf-common`. The canonical entry point
is `mgf.common.bootstrap()`:

```python
# src/mgf-cloud/__main__.py
import mgf.common
from mgf.common.cli import run_and_translate, build_cli, dispatch

def main(argv=None) -> int:
    parser = build_cli(prog="mgf-cloud")
    args = parser.parse_args(argv)
    with mgf.common.bootstrap(app_name="mgf-cloud", app_version="0.1.0"):
        return dispatch(args, parser=parser)

if __name__ == "__main__":
    raise SystemExit(run_and_translate(main))
```

For test fixtures, use `mgf.common.bootstrap_for_test()`:

```python
import pytest
from mgf.common import bootstrap_for_test, AppContext

@pytest.fixture
def app_ctx() -> AppContext:
    with bootstrap_for_test() as ctx:
        yield ctx
```

For the full integration shape (settings, exceptions, observability,
recipes), see `mgf-common`'s
`docs/recipes/cli.md` (run `mgf-fed standards
components` to find it).

---

## Four green gates — every PR

Before any commit, all four MUST pass:

```bash
ruff check src tests
mypy --strict src/
pytest --cov --cov-fail-under=80
lint-imports
```

The pyproject.toml snippet generated alongside this file pre-tunes
ruff + mypy + pytest. Add `import-linter` rules for layering as
the project grows.

---

## Federation-discipline reminders (v2.8 DOC-13 / DOC-14 / DOC-15)

Three living disciplines apply to every consumer of mgf-common.
Each has a one-paragraph reminder below; the full rules live in
[`mgf-common/docs/standards/DOCUMENTATION.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/standards/DOCUMENTATION.md).

<!-- BEGIN mgf-common: feedback-discipline -->

### Feedback discipline (DOC-13 + FB-01..FB-04)

Hit friction in mgf-common OR any federation sibling? **File a
`PAPER-NN` entry in the target repo's `FEEDBACK.md`** — not
ad-hoc emails, not lost one-off issues.

- Touches one library's surface (e.g., mgf-http retries,
  mgf-fastapi middleware) → file in that library's `FEEDBACK.md`
  (sibling-scoped per DOC-13).
- Touches federation-wide concerns (cross-sibling patterns,
  standards proposals, cornerstone APIs) → file in
  [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md).

```bash
mgf-fed feedback-howto              # how to submit + severity guide
mgf-fed feedback-howto --template   # entry template, ready to paste
mgf-fed feedback-howto --url        # canonical FEEDBACK.md URL
```

Severity guide:
- 🔴 **Blocker** — getting it wrong requires a breaking change later.
- 🟡 **High** — real quality-of-life pain, additive to fix.
- 🟢 **Nice-to-have** — real value, not urgent.
- 💭 **Aspirational** — long-term direction input.

Don't wait for permission. The maintainer triages.

<!-- END mgf-common: feedback-discipline -->

<!-- BEGIN mgf-common: adoption-discipline -->

### Adoption-tracker discipline (DOC-14 + ADP-01..ADP-04)

This project's adoption of mgf-common (which versions, which
features, which phase) lives in
`docs/inprogress/MGF_ADOPTION.md` (or `docs/MGF_ADOPTION.md`).
**Update it on every pin bump AND every closed FEEDBACK paper**
that touches this project's adoption surface (per ADP-03).

Template:
[mgf-standard/docs/recipes/mgf-adoption-md-template.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/recipes/mgf-adoption-md-template.md).

Federation siblings: the ADP-04 carve-out exempts you — your
adoption story is the federation_roadmap + your own CHANGELOG.

<!-- END mgf-common: adoption-discipline -->

<!-- BEGIN mgf-common: conformance-discipline -->

### Conformance-tracker discipline (DOC-15 + CFM-01..CFM-04)

This project's conformance to mgf-common's standards (per-rule
✅ / 🚫 / ⏳ / N/A status) lives in
`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`. **Update it on
every standards bump in mgf-common AND on every PR that changes
code touching a conformance rule** (per CFM-03).

Declared conformance level (L1 / L2 / L3 per CFM-02): see this
project's README. Decline-with-rationale (🚫) MUST carry a
paragraph per
[principles/non-adoption-is-valid.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/principles/non-adoption-is-valid.md).

Template:
[mgf-standard/docs/recipes/mgf-standards-conformance-md-template.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/recipes/mgf-standards-conformance-md-template.md).

<!-- END mgf-common: conformance-discipline -->

<!-- END mgf-common auto-generated. Project-specific content below

<!-- BEGIN mgf-common auto-generated — managed by `mgf-common catch-up`.
Edit only between this block's BEGIN/END markers if you want catch-up to
refresh your changes; project-specific content goes BELOW the END marker
in the "Project-specific lookup" section. -->

Project-specific lookup for Claude sessions. Cross-project
engineering standards live in `mgf-common`; run
`mgf-common standards <topic>` to read any one of them.

**▶ First, run `mgf-common agents`** — it prints the canonical
federation-wide agent briefing (always installed; `mgf-common` is a
dependency of this project). The briefing covers the federation
shape, using the library + its siblings instead of reinventing
them, the standards + docs layout, keeping this project in sync with
`mgf-common catch-up`, and filing feedback in the relevant library's
`FEEDBACK.md` when you hit friction so the library itself can improve.

> **Project kind:** library
> **Cornerstone library:** `mgf-common` (this project depends on it).
> **Conformance level:** declare yours in
> `docs/inprogress/MGF_STANDARDS_CONFORMANCE.md` (L1 / L2 / L3) — see
> `mgf-common standards README` §"Conformance levels for projects".

---

## Standing instructions — every session

Claude reads this file on every session start. The rules below are
canonical; the full text lives in `mgf-common` standards docs and
is accessible via:

```bash
mgf-common standards            # list all topics
mgf-common standards LOGGING    # print the full doc
mgf-common standards security   # alias also works
```

**Before writing or editing code in any of these areas, read the
corresponding topic doc:**

| Area | Topic | Run |
|---|---|---|
| API surface (public functions, modules) | API_DESIGN | `mgf-common standards api` |
| Error handling, exceptions, retries | ERROR_HANDLING | `mgf-common standards errors` |
| Logging, redaction, OTel | LOGGING | `mgf-common standards logging` |
| Configuration, settings, env vars | CONFIGURATION | `mgf-common standards config` |
| Secrets, TLS, subprocess, crypto | SECURITY | `mgf-common standards security` |
| Tests, fixtures, isolation | TESTING | `mgf-common standards testing` |
| Architecture, layering, replaceability | DESIGN_PRINCIPLES | `mgf-common standards design` |
| Scope (what belongs in this project) | SCOPE | `mgf-common standards scope` |

---

## The top-30 most-violated rules (inline so they're always in context)

These are the rules that come up most often in code review. Treat
every MUST as non-negotiable. The ID prefix tells you which doc
the full rationale lives in (DP- = DESIGN_PRINCIPLES, EH- =
ERROR_HANDLING, etc.).

### Architecture (DP-)

- **DP-01** Layering MUST be enforced: UI MUST NOT be imported by
  core; core MUST NOT import third-party SDKs that have a provider
  in front of them.
- **DP-02** Every third-party I/O dep MUST sit behind an ABC with
  a production AND a mock implementation.
- **DP-03** Domain types passed between modules MUST be frozen
  dataclasses (or pydantic `frozen=True`); never bare strings/dicts.
- **DP-04** Every public function MUST have a typed signature;
  `mypy --strict` MUST pass on `src/`.
- **DP-09** Cancellation MUST be explicit. Long-running ops take
  an explicit `CancellationToken`-like parameter; never thread-global.
- **DP-11** Async tasks MUST have an owner. Bare
  `asyncio.create_task(...)` without retention is a defect.
- **DP-12** Time MUST be UTC at every boundary. `datetime.now()`
  is forbidden; use `datetime.now(UTC)`. Naive datetimes never
  cross module boundaries.
- **DP-13** Every owned external resource MUST be released
  deterministically via context manager or `try / finally`.
  GC-based cleanup is a defect.

### Error handling (EH-)

- **EH-01** Every exception raised by app code MUST be a subclass
  of the application's base error class (typically
  `mgf.common.exceptions.AppError`).
- **EH-02** Third-party exceptions MUST be translated to typed
  application exceptions at the boundary. Use
  `mgf.common.providers.ProviderABC` + `@translate_at_seam` for
  this.
- **EH-03** When re-raising a translated exception, the original
  cause MUST be chained via `raise NewError(...) from original`.
- **EH-04** Every entry point MUST install a top-level handler
  (folded into `mgf.common.bootstrap()` automatically).
- **EH-07** Bare `except Exception:` (without re-raise or typed
  translation) MUST NOT appear except in narrow cleanup paths.
- **EH-11** Retries MUST use exponential backoff with full jitter
  and a finite cap. Use `mgf.http.RetryPolicy` (sibling `mgf-http`).

### Logging (LG-)

- **LG-01** Every module MUST acquire its logger via
  `logging.getLogger(__name__)`. No bare `logging.info(...)`.
- **LG-04** Sensitive fields MUST be redacted by the formatter
  before any sink sees them. The default
  `mgf.common.observability.Redactor` covers the canonical set.
- **LG-05** Error-level logs MUST include the exception via
  `LOG.exception(...)` or `exc_info=True`.
- **LG-08** Log messages MUST use lazy `%`-style formatting
  (`LOG.info("processing %s", x)`), NOT f-strings.
- **LG-09** Structured fields MUST be passed via `extra={...}`.
- **LG-12** Log emission MUST be cheap (≤100 µs per record).
  Heavy work belongs in the handler, not the call site. Use
  `mgf.common.observability.AsyncJsonHandler` for non-blocking I/O.

### Configuration (CF-)

- **CF-01** Application config MUST live in a single typed object
  (`mgf.common.config.BaseAppSettings`-derived). No module reads
  config files / env vars directly.
- **CF-02** Precedence: CLI flags → env vars → `.env` → on-disk
  config → typed defaults.
- **CF-05** Secrets MUST NOT live in the config file; they live in
  a vault. Use `mgf.common.vault.VaultProtocol`.
- **CF-08** `Settings` is loaded once at the entry point and
  passed down by constructor injection. No module-global singletons.
- **CF-10** Tests MUST construct `Settings` with explicit values
  (no env-var leakage).

### Security (SC-)

- **SC-01** Secrets MUST live in a Vault, never in config / env /
  source / logs / crash reports.
- **SC-02** Subprocess invocation MUST use `argv` lists with
  `shell=False`.
- **SC-06** TLS verification MUST be enabled on every outbound
  connection.
- **SC-07** Every external request MUST carry a finite timeout.
- **SC-15** Filesystem operations MUST validate against directory
  traversal via `Path.resolve()` + `is_relative_to()`.

### Testing (TS-)

- **TS-01** `tests/` MUST mirror `src/` 1:1.
- **TS-02** The unit suite MUST run with no production
  credentials, no network, no real third-party daemon.
- **TS-04** `filterwarnings = ["error"]` MUST be set in
  `pyproject.toml`.
- **TS-06** Coverage gate ≥80% project-wide; ≥90% on changed
  lines.

### API design (AP-)

- **AP-01** Public API surface MUST be enumerated explicitly via
  `__all__` at every package and module boundary.
- **AP-04** Deprecation cycle MUST be: announce → still works
  (≥1 MINOR) → removed; deprecated names emit
  `DeprecationWarning`.
- **AP-08** Public modules MUST use
  `from __future__ import annotations`; runtime-unused imports go
  in `if TYPE_CHECKING:`.
- **AP-14** Internal modules MUST NOT be imported by consumers.
  Single-underscore module names are private.

---

## Quick start — bootstrapping this project

This project depends on `mgf-common`. As a library, `mgf-cloud`
acquires loggers but does NOT call `bootstrap()` at import time;
the host (the CLI entry point, or a consumer like `mgf-fed`) owns
the bootstrap:

```python
# src/mgf/cloud/__init__.py
"""mgf-cloud — library shape; do NOT call bootstrap() here."""
from mgf.common.observability import get_logger, operation_span

LOG = get_logger(__name__)

# Library code uses get_logger + operation_span (no-op-safe when no
# host has bootstrapped). The CLI entry point (`mgf-cloud`, in
# __main__) calls mgf.common.bootstrap(); a consumer like mgf-fed
# bootstraps in its own entry point.
```

For test fixtures, use `mgf.common.bootstrap_for_test()`:

```python
import pytest
from mgf.common import bootstrap_for_test, AppContext

@pytest.fixture
def app_ctx() -> AppContext:
    with bootstrap_for_test() as ctx:
        yield ctx
```

For the full integration shape (settings, exceptions, observability,
recipes), see `mgf-common`'s
`docs/recipes/library.md` (run `mgf-common standards
components` to find it).

---

## Four green gates — every PR

Before any commit, all four MUST pass:

```bash
ruff check src tests
mypy --strict src/
pytest --cov --cov-fail-under=80
lint-imports
```

The pyproject.toml snippet generated alongside this file pre-tunes
ruff + mypy + pytest. Add `import-linter` rules for layering as
the project grows.

---

## Federation-discipline reminders (v2.8 DOC-13 / DOC-14 / DOC-15)

Three living disciplines apply to every consumer of mgf-common.
Each has a one-paragraph reminder below; the full rules live in
[`mgf-standard/docs/standards/DOCUMENTATION.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md).

<!-- BEGIN mgf-common: feedback-discipline -->

### Feedback discipline (DOC-13 + FB-01..FB-04)

Hit friction in mgf-common OR any federation sibling? **File a
`PAPER-NN` entry in the target repo's `FEEDBACK.md`** — not
ad-hoc emails, not lost one-off issues.

- Touches one library's surface (e.g., mgf-http retries,
  mgf-fastapi middleware) → file in that library's `FEEDBACK.md`
  (sibling-scoped per DOC-13).
- Touches federation-wide concerns (cross-sibling patterns,
  standards proposals, cornerstone APIs) → file in
  [mgf-common/FEEDBACK.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md).

```bash
mgf-common feedback              # how to submit + severity guide
mgf-common feedback --template   # entry template, ready to paste
mgf-common feedback --url        # canonical FEEDBACK.md URL
```

Severity guide:
- 🔴 **Blocker** — getting it wrong requires a breaking change later.
- 🟡 **High** — real quality-of-life pain, additive to fix.
- 🟢 **Nice-to-have** — real value, not urgent.
- 💭 **Aspirational** — long-term direction input.

Don't wait for permission. The maintainer triages.

<!-- END mgf-common: feedback-discipline -->

<!-- BEGIN mgf-common: adoption-discipline -->

### Adoption-tracker discipline (DOC-14 + ADP-01..ADP-04)

This project's adoption of mgf-common (which versions, which
features, which phase) lives in
`docs/inprogress/MGF_ADOPTION.md` (or `docs/MGF_ADOPTION.md`).
**Update it on every pin bump AND every closed FEEDBACK paper**
that touches this project's adoption surface (per ADP-03).

Template:
[mgf-common/docs/recipes/mgf-adoption-md-template.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/recipes/mgf-adoption-md-template.md).

Federation siblings: the ADP-04 carve-out exempts you — your
adoption story is the federation_roadmap + your own CHANGELOG.

<!-- END mgf-common: adoption-discipline -->

<!-- BEGIN mgf-common: conformance-discipline -->

### Conformance-tracker discipline (DOC-15 + CFM-01..CFM-04)

This project's conformance to mgf-common's standards (per-rule
✅ / 🚫 / ⏳ / N/A status) lives in
`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`. **Update it on
every standards bump in mgf-common AND on every PR that changes
code touching a conformance rule** (per CFM-03).

Declared conformance level (L1 / L2 / L3 per CFM-02): see this
project's README. Decline-with-rationale (🚫) MUST carry a
paragraph per
[principles/non-adoption-is-valid.md](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/principles/non-adoption-is-valid.md).

Template:
[mgf-common/docs/recipes/mgf-standards-conformance-md-template.md](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/recipes/mgf-standards-conformance-md-template.md).

<!-- END mgf-common: conformance-discipline -->

<!-- END mgf-common auto-generated. Project-specific content below
this marker is preserved across `mgf-common catch-up --apply` runs. -->

# mgf-cloud — Claude Reference

Dense lookup document. No prose. Facts only.

> **See also:** [`mgf-common/docs/claude/CLAUDE.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/claude/CLAUDE.md)
> — cornerstone reference shared across the federation. The
> cross-cutting patterns (atomic-write, never-raises observers,
> redaction layering) documented there apply to this sibling
> too. THIS file is the mgf-cloud-specific addenda.

---

## Project shape

- **Federation sibling** of `mgf-common` (per
  [`DOCUMENTATION.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md) §2.0).
- **What it is:** the provider-agnostic interface to create + manage
  cloud VMs and storage (Infomaniak/OpenStack first, AWS-ready);
  ships a CLI (`mgf-cloud`) + a local single-user web GUI
  (`mgf-cloud web`). **Stateless** (cloud is the source of truth)
  with `mgf:owner` resource tagging.
- **Conformance target:** L1 (default for a new sibling) — inherited
  via the `mgf-common` pin declared in `pyproject.toml`. Full per-MUST audit + any L2/L3 bump
  in Pass 7. See [`../inprogress/MGF_STANDARDS_CONFORMANCE.md`](../inprogress/MGF_STANDARDS_CONFORMANCE.md).
- **Registry:** `mgf-cloud` on the Codeberg index (PKG-06), not
  pypi.org. Currently **0.1.0**, Pass 1 (scaffold) of a 7-pass build.
- **Codeberg:** `magogi-admin/mgf-cloud`; default branch `main`.
- **Consumer:** `mgf-fed` is the sole intended consumer + the owner
  of the resources mgf-cloud provisions (wiring lands in Pass 6).

## File map (where things live)

The package layout below is the **planned** shape from
[`../design/DESIGN.md`](../design/DESIGN.md) §3.1; today (Pass 1)
only `__init__.py` + `__main__.py` exist as the scaffold. The
modules land across Passes 2–5.

| Path | Purpose | Pass |
|---|---|---|
| `src/mgf/cloud/__init__.py` | version + the thin public surface. PEP 420 namespace package — no top-level `mgf/__init__.py`. | 1 |
| `src/mgf/cloud/__main__.py` + `cli/` | the `mgf-cloud` argparse CLI (dispatch + subcommands); `--json` / `--dry-run` / `--yes`. | 1 / 4 |
| `src/mgf/cloud/models.py` | typed resource models (Server, Flavour, Image, Keypair, SecurityGroup/Rule, FloatingIP, Network, Volume, …) + `CloudConfig`/`Credentials`. | 2 |
| `src/mgf/cloud/config.py` | load credentials from `clouds.yaml` / `OS_*` env / `my_stuff` token (pydantic-settings). | 2 |
| `src/mgf/cloud/exceptions.py` | error types mapped onto `mgf-common`'s `AppError` hierarchy. | 2 |
| `src/mgf/cloud/providers/base.py` | the `CloudProvider` Protocol (compute/block/object/network) + an in-memory `FakeProvider` for tests. | 2 |
| `src/mgf/cloud/providers/__init__.py` | `get_provider(name)` factory — lazy import of the adapter (keeps the core light). | 2 |
| `src/mgf/cloud/providers/infomaniak.py` | the openstacksdk adapter (`[infomaniak]`). | 3 |
| `src/mgf/cloud/providers/aws.py` | AWS stub (`[aws]`). | 3 |
| `src/mgf/cloud/remote.py` | SSH exec / file-push + `bootstrap()` (`[remote]`). | 3 |
| `src/mgf/cloud/web/` | the local FastAPI GUI via mgf-fastapi (`[web]`). | 5 |
| `PUBLIC_API.md` | Contract list — every public name with stability tier + description (per **AP-10**). | — |
| `CHANGELOG.md` | Per-release record (Keep a Changelog format). | — |
| `SECURITY.md` | Vulnerability-reporting policy + the credential-handling note (per **SC-12**). | — |
| `docs/standards/README.md` | Pointer-only stub — points at `mgf-standard/docs/standards/`. NOT a duplicate. | — |
| `docs/cutover/v0.1.0.md` | Maiden-release note (greenfield — no migration). | — |

## Cross-cutting patterns

1. **Core stays light.** `import mgf.cloud` MUST NOT pull a
   provider SDK or the web framework. `get_provider("infomaniak")`
   does an `importlib`-style lazy import of the adapter, so
   openstacksdk loads only when a provider is actually constructed.
   Enforced by the `.importlinter` closed-box contract (tightened
   in Pass 2).

2. **Stateless / live-query.** The cloud is the source of truth;
   there is no local state file. Federation resources are
   identified by the `mgf:owner` metadata tag (OpenStack server /
   object metadata), not a tracked id list.

3. **Provider abstraction.** One `CloudProvider` Protocol defines
   compute / block / object / network ops; `get_provider(name,
   config)` returns the concrete adapter. Adapters are stateless —
   every call queries the live cloud. A `FakeProvider` (in-memory)
   backs unit + CLI tests so the suite needs no live cloud.

4. **Library shape — host owns bootstrap.** mgf-cloud acquires
   loggers via `get_logger(__name__)` but does NOT call
   `mgf.common.bootstrap()` at import time. The CLI entry point
   (`mgf-cloud`, in `__main__`) bootstraps; a consumer like
   `mgf-fed` bootstraps in its own entry point.

5. **Guardrails on live infrastructure.** Create/delete require
   `--yes` or an interactive confirm; `--dry-run` plans before
   applying; credentials are read only from `clouds.yaml`/`OS_*`/
   `my_stuff` and never logged; openstacksdk TLS verification stays
   on; the web GUI binds `127.0.0.1` only.

## Build and release

The canonical sequence per
[`mgf-standard/docs/standards/RELEASING.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/RELEASING.md):

1. Bump `version` in `pyproject.toml`.
2. Add the `[X.Y.Z] — YYYY-MM-DD` entry in `CHANGELOG.md` in
   the same commit.
3. Update `PUBLIC_API.md` if the public surface changed
   (validated by the pinned public-API test against `__all__`).
4. Run the full test suite locally (`pytest`).
5. Run `mypy --strict src/mgf/cloud/`.
6. Build: `uv build`.
7. `twine check dist/*` — both wheel and sdist MUST pass.
8. Commit (`chore: cut vX.Y.Z`).
9. Tag annotated: `git tag -a vX.Y.Z -m '...'`.
10. Push commit + tag: `git push origin main && git push origin vX.Y.Z`.
11. Upload to the Codeberg index (PKG-06): `twine upload --repository codeberg dist/*`.
12. Regen the federation registry (REL-13) + REST 200 verify.

## Common pitfalls

(Forward-looking — the surface lands across Passes 2–5; revisit as
the code arrives.)

- **Importing a provider SDK in the core.** Anything under
  `mgf.cloud` that is not the adapter module itself must NOT
  `import openstacksdk` / `boto3` / `paramiko` — the import-linter
  contract fails the build. Use the lazy `get_provider` factory.
- **Assuming local state.** There is no state file; never cache
  "what we created" locally — re-query the cloud and filter by the
  `mgf:owner` tag.
- **Leaking credentials.** Never log, print, or serialise a
  credential / app-credential secret / EC2 key into an error,
  traceback, or the web GUI. They come only from `clouds.yaml` /
  `OS_*` / `my_stuff`.
- **Skipping the guardrail.** A mutating op without `--yes`/confirm,
  or without a `--dry-run` path, is a defect — it manages billable,
  live infrastructure.

## Recently-touched areas

(Rolling list, last N changes. Update on every commit that
changes a load-bearing fact.)

- **v0.1.0 scaffold (2026-06-14, Pass 1)** — new repo seeded as a
  conformant skeleton: `pyproject.toml` (core deps + extras
  `[infomaniak]`/`[s3]`/`[aws]`/`[remote]`/`[web]`/`[standards]`),
  `src/mgf/cloud/` (`__init__` + `__main__` CLI dispatch + `py.typed`),
  `.importlinter` closed-box contract, four gates green, registered
  in `MGF_LIBRARIES`, keystone + supporting docs adapted to mgf-cloud.

---

*Last updated: 2026-06-14.*
