# Cross-project notification — Standards v2.6

> **Audience:** every Magogi project maintainer.
> **TL;DR:** the standards now have a project-shape taxonomy
> (cornerstone / federation sibling / consumer application) and
> docs requirements differ per shape. Plus `LICENSE` is now a
> MUST in the universal-four root docs. Most projects need 0–2
> additions to claim v2.6 compliance. Per-project action lists
> at the bottom.

---

## What changed

The `mgf-common/docs/standards/` documentation standard
(DOC-01 + DOC-02) was rewritten to acknowledge that not every
Magogi project needs the same docs. Previously the standard
demanded the seven-doc root + six-bucket `docs/` hierarchy
from everyone. In practice:

- Federation siblings (`mgf-django`, `mgf-fastapi`, etc.) don't
  have downstream consumers separate from the cornerstone —
  `FEEDBACK.md` is overkill.
- Consumer applications (`VManager`, `PlasmaMapper`,
  `inthewords`) don't expose a public API, so `PUBLIC_API.md`
  is N/A.
- Both groups still need `LICENSE`, `SECURITY.md`, and a
  pointer-only `docs/standards/README.md` so contributors and
  AI agents know where to find the canonical rules.

The v2.6 standard codifies this:
[`docs/standards/DOCUMENTATION.md`](../standards/DOCUMENTATION.md) §2.0
and
[`docs/standards/README.md`](../standards/README.md) "What's new in v2.6".

---

## The three shapes

| Shape | Examples | What you ship |
|---|---|---|
| **Cornerstone library** | `mgf-common` | Full eight-doc root + full six-bucket hierarchy. Owns the canonical `docs/standards/`. |
| **Federation sibling** | `mgf-django`, `mgf-fastapi`, `mgf-http`, `mgf-sqlalchemy`, `mgf-alembic`, `mgf-apiprobe`, `mgf-website-template` | Universal four (README + LICENSE + CHANGELOG + SECURITY) + `PUBLIC_API.md`. `docs/{cutover,recipes,claude}/` + a pointer-only `docs/standards/README.md` pointing at `mgf-common`. |
| **Consumer application** | `VManager`, `PlasmaMapper`, `inthewords`, `magogi-website` | Universal four (LICENSE if open-source, CHANGELOG if released). NO `PUBLIC_API.md`. NO `FEEDBACK.md`. `docs/{inprogress,claude}/` minimum + a pointer-only or extension-only `docs/standards/`. May add `docs/{design,adrs,runbooks}/`. |

---

## Two universal asks (every project)

1. **Declare your shape** in your `README.md` front-matter or
   first paragraph. One line is enough:

   ```
   > **Shape:** Federation sibling of `mgf-common`; depends on
   > `mgf-common>=0.33,<0.34`.
   ```

   (Or "Consumer application — Django web app", or
   "Cornerstone library", etc.)

2. **Ship `LICENSE` at the repo root.** Even closed-source
   apps benefit from a license file making the terms explicit.
   For open-source projects on PyPI / Codeberg, this is
   already required by the platform.

---

## The `docs/standards/` pointer-only pattern (§2.0.4)

If your project is a federation sibling or a consumer app,
your `docs/standards/` MUST NOT duplicate `mgf-common`'s
content. Two valid shapes:

### Shape A — pointer-only

`docs/standards/README.md` only, with this first paragraph:

```markdown
# Engineering Standards

This folder is **NOT a duplicate** of `mgf-common/docs/standards/`.
The cross-project engineering standards (logging, configuration,
exceptions, design principles, security, testing, API design,
operability) live in `mgf-common`. This project depends on
those — pinned via `mgf-common>=<X.Y>,<<X+1>.0>`. Read them on
demand via `mgf-common standards <topic>` or directly at
`https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/standards/`.

**Conformance level:** L<0/1/2> per `mgf-common/docs/standards/`.
```

### Shape B — pointer + project-specific extensions

Same `README.md` first paragraph as Shape A, **plus** one or
more project-specific standards files for concerns the
cornerstone explicitly leaves out of scope:

- Multi-tenant SaaS web app → `MULTI_TENANCY.md`
- Frontend / UI app → `FRONTEND.md`, `I18N_RTL.md`,
  `UI_TESTING.md`
- API probing service → project-specific `SCOPE.md`

`PlasmaMapper/docs/standards/` is the reference shape for
Shape B; `VManager/docs/standards/` for Shape A.

---

## Per-project action lists

Based on a cross-project audit run on 2026-05-15. Items
flagged ⚠ are real gaps; items flagged ℹ are informational.

### `mgf-common` (cornerstone)

✅ Already fully compliant with v2.6. All eight root docs ship;
all six buckets exist; the standards system itself is here.

### `mgf-django` (federation sibling)

- ⚠ Add `SECURITY.md` (vuln-reporting policy per **SC-12**).
  Use the template at
  [`mgf-common/SECURITY.md`](../../SECURITY.md).
- ⚠ Add `docs/standards/README.md` pointer-only stub per §2.0.4
  Shape A.
- ⚠ Add `docs/claude/CLAUDE.md` in the dense-lookup format
  (per **DOC-07**). Use
  [`mgf-common/docs/claude/CLAUDE.md`](../claude/CLAUDE.md)
  as the format reference.
- ℹ Already ships: README, LICENSE, CHANGELOG, PUBLIC_API.md,
  PUBLIC_API.json, `docs/cutover/`, `docs/recipes/`.

### `mgf-fastapi` (federation sibling)

Same checklist as `mgf-django`:
- ⚠ Add `SECURITY.md`.
- ⚠ Add `docs/standards/README.md` pointer-only stub.
- ⚠ Add `docs/claude/CLAUDE.md`.

### `mgf-http` (federation sibling)

Same checklist as `mgf-django`:
- ⚠ Add `SECURITY.md`.
- ⚠ Add `docs/standards/README.md` pointer-only stub.
- ⚠ Add `docs/claude/CLAUDE.md`.

### `mgf-sqlalchemy` (federation sibling)

Same checklist as `mgf-django`:
- ⚠ Add `SECURITY.md`.
- ⚠ Add `docs/standards/README.md` pointer-only stub.
- ⚠ Add `docs/claude/CLAUDE.md`.

### `mgf-alembic` (federation sibling)

Same checklist as `mgf-django`:
- ⚠ Add `SECURITY.md`.
- ⚠ Add `docs/standards/README.md` pointer-only stub.
- ⚠ Add `docs/claude/CLAUDE.md`.

### `mgf-apiprobe` (federation sibling)

- ⚠ Add `LICENSE` (currently missing).
- ⚠ Add `CHANGELOG.md` (currently missing — needed before
  first PyPI release).
- ⚠ Add `SECURITY.md`.
- ⚠ Add `docs/cutover/` (empty until first breaking change).
- ⚠ Add `docs/recipes/`.
- ⚠ Update `docs/standards/SCOPE.md` to follow the §2.0.4
  Shape B pattern (add `docs/standards/README.md` with the
  "NOT a duplicate" framing).
- ⚠ Add `docs/claude/CLAUDE.md` (currently `docs/CLAUDE.md`
  exists — move it to the subfolder per **DOC-07**).
- ℹ Already ships: README, PUBLIC_API.md.

### `mgf-website-template` (federation sibling / template)

This is a template project so the requirements are partial:
- ⚠ Ensure the **generated** project from this template will
  produce all required docs. The template itself can be
  thin, but `gen-website --new-project` SHOULD emit
  README + LICENSE + CHANGELOG + SECURITY + a `docs/`
  scaffold that matches the consumer-application shape.
- ℹ Already ships: README, LICENSE.

### `VManager` (consumer application — Qt desktop)

- ⚠ Add `LICENSE` at repo root (currently missing).
- ℹ Already ships: README, CHANGELOG, CONTRIBUTING, PUBLIC_API
  (the PUBLIC_API.md is overkill for an app — consider whether
  it's still useful or whether to demote to internal docs).
- ℹ `SECURITY.md` is present — keep.
- ℹ `docs/standards/README.md` already follows the §2.0.4
  Shape A pointer pattern.
- ℹ Move `docs/CLAUDE.md` → `docs/claude/CLAUDE.md` per
  **DOC-07** (optional but standardising).

### `PlasmaMapper` (consumer application — FastAPI SaaS)

- ⚠ Add `LICENSE` (if planning to open-source) — flag for
  decision otherwise.
- ⚠ Add `CHANGELOG.md` (the app is iterating; even
  per-deploy-tag notes count).
- ℹ `SECURITY.md` is present — keep.
- ℹ `docs/standards/README.md` already follows the §2.0.4
  Shape B (pointer + extensions) pattern — excellent.
- ℹ Move `docs/CLAUDE.md` → `docs/claude/CLAUDE.md` per
  **DOC-07**. Delete `docs/CLAUDE.md.bak.*` files.

### `inthewords` (consumer application — Django web)

- ⚠ Add `LICENSE` (if planning to open-source).
- ⚠ Add `SECURITY.md` (vuln-reporting policy required).
- ⚠ Add `CHANGELOG.md`.
- ℹ `docs/standards/web/` exists — wrap it with a
  `docs/standards/README.md` per §2.0.4 Shape B framing.
- ℹ Move `docs/CLAUDE.md` → `docs/claude/CLAUDE.md` per
  **DOC-07**.

### `magogi-website` (consumer application — website)

- ⚠ Add `LICENSE` (if planning to open-source).
- ⚠ Add `SECURITY.md`.
- ⚠ Add `CHANGELOG.md` if going through release cycles.
- ⚠ Add `docs/standards/README.md` pointer-only stub.
- ℹ Move `docs/CLAUDE.md` → `docs/claude/CLAUDE.md` per
  **DOC-07**.

---

## What this does NOT change

- **No existing doc gets deleted.** v2.6 is additive — adding
  shape declaration, adding LICENSE, adding the pointer-only
  pattern. Existing content stands.
- **No CI gates change.** This is doc-only.
- **No code changes.** Standards work; not code.
- **No urgency.** Roll these in at your next docs-touching PR.
  No project is broken by this update; the rule is now clearer
  about what each project needs to ship.

---

## Reference

- New standard: [`mgf-common/docs/standards/DOCUMENTATION.md`](../standards/DOCUMENTATION.md) §2.0
- v2.6 release notes: [`mgf-common/docs/standards/README.md`](../standards/README.md) "What's new in v2.6"
- Pointer-only template: [`VManager/docs/standards/README.md`](https://codeberg.org/magogi-admin/VManager/src/branch/main/docs/standards/README.md)
- Pointer + extensions template: [`PlasmaMapper/docs/standards/README.md`](https://codeberg.org/magogi-admin/PlasmaMapper/src/branch/main/docs/standards/README.md)
- Cornerstone shape (full set): [`mgf-common/docs/`](../)

Questions? File a FEEDBACK paper at
[`mgf-common/FEEDBACK.md`](../../FEEDBACK.md) or open an issue
on the mgf-common Codeberg.
