# Reference consumers

> **Audience:** anyone reading `docs/standards/` who wants to see
> what a specific consumer actually did, vs. anyone reading
> `docs/standards/` who wants the cross-project rule. The standards
> stay consumer-neutral; the consumer-specific evidence lives here.

This folder closes the full restructure asked for in
[FEEDBACK PAPER-06](../../FEEDBACK.md). The partial fix (line-range
citations stripped + caveat banner) shipped in earlier minors; this
folder is the home for the consumer-specific paragraphs that used
to clutter `docs/standards/`.

---

## Why this folder exists

The standards (`docs/standards/`) describe what "world-class" looks
like for each cross-cutting concern (error handling, logging,
configuration, etc.). They're written to apply to **any** Magogi
project — VM-management library, web service, CLI tool, data
pipeline, future not-yet-built thing.

When the standards docs interleave their abstract rules with "AS-IS
in vm-vmanager-app…" paragraphs, two problems show up:

1. **Rot.** A consumer's code reorganises. The line ranges drift.
   The paragraph contradicts the consumer's current shape. The
   reader trusts the standards doc less.

2. **Consumer-shaped perception.** Readers (especially new ones)
   start to think the standards are descriptions of one specific
   consumer's habits, rather than industry-shaped engineering
   discipline. That undermines the cornerstone-library positioning.

Separating concerns: standards are the rule; this folder is the
**evidence**. Multiple consumers' evidence sits side-by-side; the
rule doesn't care which one you're looking at.

---

## How to read this folder

Each file describes ONE consumer's shape, organised by the same
concerns the standards cover. Pick the consumer that's closest to
your own project, read its profile, see what they actually did,
then go back to the standards doc for the canonical rule.

| Consumer | Profile | Project type | Why it's a useful reference |
|---|---|---|---|
| **vm-vmanager-app** | [`vm-vmanager-app.md`](vm-vmanager-app.md) | Desktop / Qt VM-management application | The original reference consumer. Carries the longest history; many of the standards were extracted from vm-vmanager-app's shape. The "AS-IS reference" for desktop / CLI / GUI-heavy patterns. |
| **inthewords** | [`inthewords.md`](inthewords.md) | Django web application | The second consumer; the first web-shape consumer. Pip-tools `requirements/*.txt` layout, Django app config + middleware, DRF exception mapping. The reference for framework-native patterns + the `non-adoption-is-valid` walk for CLI/desktop-shaped rules that don't fit web. |
| **TelePlasma** | [`TelePlasma.md`](TelePlasma.md) | FastAPI SaaS application | The third consumer; the first SaaS / multi-tenant web-shape consumer. Auth-provider abstractions (Clerk), webhook receivers (Svix), bearer-session pattern (PAPER-29). The reference for tenant-isolated request handling + 3rd-party auth integration. |

---

## How to add a new reference consumer

When a fourth consumer adopts mgf-common and surfaces a distinct
project shape that's worth documenting:

1. **Wait for evidence.** A profile file is useful only when the
   consumer has 1+ minor cycle of real use behind it. Premature
   profiles are speculation.

2. **Mirror the existing structure.** Each profile follows roughly
   the same outline: project type → key shape decisions →
   pattern-by-pattern (config, logging, errors, etc.) → known
   non-adoptions (with rationale).

3. **Cross-reference from the standards.** If your consumer's
   profile changes how a standard reads, file a follow-up FEEDBACK
   paper proposing the rule edit. Don't quietly let the standards
   drift to match the new consumer — that re-creates the
   consumer-shape problem PAPER-06 closed.

4. **Add a row to the table above.**

---

## How the standards docs reference this folder

Consumer-specific evidence in `docs/standards/*` should be either:

- A brief, neutral mention (e.g., "vm-vmanager-app uses pattern X" — one
  clause, no file:line); OR
- A cross-link into this folder (e.g.,
  "see [`reference-consumers/vm-vmanager-app.md`](../reference-consumers/vm-vmanager-app.md#error-handling)").

The caveat banner in `docs/standards/README.md` flags this pattern
for readers who land directly on a standards doc.

---

## Out of scope for these profiles

These profiles are NOT:

- **Tutorials** for adopting mgf-common — that's
  `docs/standards/`'s job (with each topic doc's "Adopt" section).
- **Bug reports or feature requests** — those go to
  [`FEEDBACK.md`](../../FEEDBACK.md).
- **Roadmaps for the consumer project** — each consumer manages its
  own roadmap internally.
- **Authoritative descriptions of the consumer's current code** —
  these are snapshots-of-shape, not auto-generated docs. They drift;
  refresh on each minor when needed; they're "the shape at the time
  this profile was written" not "the shape right now."

---

## Cross-references

- [`docs/standards/README.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/README.md) — the master
  index that points at this folder.
- [`FEEDBACK.md` — PAPER-06](../../FEEDBACK.md) — the filing this
  folder closes (full restructure).
- [`FEEDBACK.md` — ASPIRE-02](../../FEEDBACK.md) — the second-consumer
  arrival that unblocked the restructure.
