# LESSON_LEARNED — mgf-cloud-web

> Append-only, dated log of non-obvious lessons learned working in this repo.
> Newest first. One entry per lesson. Supersede a wrong past entry with a new
> one — never rewrite history. Federation rule: **DOC-19**; template:
> `mgf-fed sync-prompt` / docs/recipes/lesson-learned-md-template.md.

---

## 2026-06-29 — Extracted from mgf-cloud's `[web]` extra into its own sibling

- **Context:** the cloud console started life as `mgf-cloud`'s optional `[web]`
  extra (`mgf-cloud web`). It was extracted into this standalone sibling so the
  UI could be re-skinned to the Magogi brand and reused as the pattern for other
  internal web tools, while `mgf-cloud` stays a pure lib+CLI.
- **What I learned:** a sibling sub-project must own its OWN namespace package
  (`mgf.cloud_web`, matching `mgf-cloud-provision`'s `mgf.cloud_provision`), not
  a subpackage of `mgf.cloud` — two distributions installing into `mgf/cloud/`
  fights PEP 420. The provider/cost/models/credential layers are imported from
  `mgf-cloud` as a dependency; only the FastAPI app + templates + brand assets
  live here.
- **Why it matters:** keeps the two wheels from colliding and keeps the console
  a thin consumer of the library's stable surface.
- **How to apply:** when splitting a federation lib's optional surface into its
  own repo, give it a fresh `mgf.<name>` package and depend back on the origin.
- **Generalizes?:** yes — the namespace + thin-consumer pattern applies to any
  future extraction (and to the brand-web kit reuse).

---

## 2026-06-29 — File seeded (repo creation)

- **Context:** `mgf-cloud-web` scaffolded as a conformant federation sibling.
- **What I learned:** (seed entry).
- **Why it matters:** lessons left only in chat transcripts evaporate.
- **How to apply:** when you hit a gotcha / corrected assumption / reusable
  technique in this repo, add a dated entry here. If it generalises beyond this
  repo, ALSO file a `pending-feedback/<target>.md` paper.
- **Generalizes?:** n/a (seed entry).

---
