> ## Documentation Index
> Fetch the complete documentation index at: https://internal.softcrum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentation Generation Plan — CRM + Loyalty (v1.0)

> Turns the decision registry into the actual repository and Mintlify documentation. English in the repository (DEC-I1), English and Spanish in Mintlify. Each batch closes against verifiable criteria.

> Translation. Authoritative: [`../../design/documentation-plan-v1.md`](/design/documentation-plan-v1).
>
> Turns `decision-registry-v1.md` into the real documentation of the repository and Mintlify.
> Languages: repository in English (DEC-I1); Mintlify EN/ES. Each batch closes with verifiable
> criteria. Batches are generated in order; within a batch the documents are parallelisable across
> agents.

## Batch 0 — Constitution amendment (1 document, the only one that touches the root constitution)

* Amendment: add `QueuePort` and `NotificationChannelPort` to the allowed port categories (DEC-C3);
  encode the per-module composition-root binding rule (DEC-C4); reference the new (`notifications.md`)
  and updated standards.
* **Closing:** a minimal diff over the root constitution, approved by Daniel line by line (the same
  ritual as the original constitution).

## Batch 1 — Standards (6 documents, all in `/docs/standards/`)

1. `data.md` (major update): parametric tables (DEC-B2/B3/B4), money (DEC-B5/B6), partitioning
   (DEC-B8), retention/export (DEC-B7), data classification and `national_id` (DEC-A4), the
   tenant-extensible rule.
2. `events.md`: domain event catalog for the four contexts, end-to-end correlation\_id (DEC-E7),
   naming convention.
3. `jobs.md`: QueuePort, idempotent consumers (`processed_jobs`, DEC-C6), retries/DLQ/`dead_letters`
   (DEC-C5), per-channel queues with transactional priority (DEC-E8).
4. `api.md`: per-module paths (DEC-D1/D2), `module.resource.action` permissions (DEC-D5),
   Runtime/Management SLOs (DEC-D7), deprecation (DEC-D3), published rate limits (DEC-D4),
   third-party access without an IP allowlist (DEC-D6).
5. `notifications.md` (NEW): levels 0–3 cascade, `resolveChannels()`, preference center, quiet
   hours/caps, traceability, channel × phase matrix (DEC-E1..E8).
6. `security.md` (update): machine roles, write keys, `national_id` masking and dedicated permission,
   access auditing.

* **Closing:** each standard with MUST/NEVER rules plus anti-examples; dependency-cruiser and CI
  updated where applicable.

## Batch 2 — ADRs (12 documents, a cross-cutting series in `/docs/adr/`)

| ADR    | Topic                                                                         | Decisions it enshrines |
| ------ | ----------------------------------------------------------------------------- | ---------------------- |
| ADR-09 | customer-core as a shared bounded context                                     | v0.2 §1, DEC-B1        |
| ADR-10 | Member identity: separate Better Auth realm + token exchange                  | D4, DEC-D5             |
| ADR-11 | Points ledger: immutable, dual currency, FIFO lots, pending→available         | v0.2 §2.2              |
| ADR-12 | Segment DSL v1 + incremental evaluation + nightly reconciliation              | D6                     |
| ADR-13 | Ingestion pipeline: fast-ack + queues + partitioning                          | DEC-B8, DEC-D7         |
| ADR-14 | Billable metric: marketable contact                                           | DEC-G3                 |
| ADR-15 | Dual-rail multi-channel sending (shared Resend rate-limit risk)               | DEC-E8                 |
| ADR-16 | Vercel-style pricing + rating engine + variable MoR charging                  | DEC-G3/G4              |
| ADR-17 | CQRS-lite + audit log; event sourcing discarded as a norm                     | DEC-C1/C2              |
| ADR-18 | Partitioning standard on Supabase (incl. the pg\_partman spike result)        | DEC-B8                 |
| ADR-19 | Cascading notification system                                                 | DEC-E2                 |
| ADR-20 | Mobile white-label: single app with theming, extensible to a dedicated binary | DEC-F2/F3              |

* Declared placeholders (written when their turn comes): SMS provider (F1b), wallet passes (F2),
  multi-currency/FX (F2), WhatsApp (F2).
* **Closing:** existing ADR format; status Accepted after Daniel's sign-off.

## Batch 3 — Module specs (4 documents, `/docs/specs/`)

* `core-spec.md`, `loyalty-spec.md`, `messaging-spec.md`, `crm-spec.md`: entities and invariants,
  tables per schema (with parametric and partitioned ones marked), domain events emitted and
  consumed, endpoints with their single permission, RBAC rules, SLOs, and extension points
  (`program_id`, `money_component`, open `rule_effect_types` — DEC-H2/H3/H4).
* **Closing:** every table in the registry appears in exactly one spec; zero contradictions with the
  standards (cross-review by an agent).

## Batch 4 — Glossary, diagrams and canonical slices

* Glossary: EN↔ES additions (contact, member, ledger, lot, redemption, suppression, marketable
  contact…) plus forbidden synonyms ("cliente final" NEVER "usuario"; "member" NEVER "user").
* Diagrams with the `diagram-design` skill (DEC-I2), HTML sources in the repository plus SVG export to
  Mintlify: C4 context and containers of the expanded suite; ERD per schema (4); sequences of the four
  hot paths (track→effects, idempotent redeem, dual-rail blast, notification with traceability); state
  machines for send\_status and for redemption.
* Spec of canonical slice #2 `trackEvent` (asynchronous pipeline archetype, DEC-I5), seven layers,
  analogous to the existing one.
* **Closing:** the diagram gallery renders with the Softcrum brand palette (skill onboarding against
  the site).

## Batch 5 — Runbooks (`/docs/runbooks/`)

* 72-hour data breach (DEC-J4, blocking pre-launch) · deliverability and domain warm-up · partition
  management (creation, default, export + purge by retention) · tenant restore extended with module
  data · dead letter replay.
* **Closing:** each runbook executable step by step by a person with no prior context.

## Batch 6 — Initial task specs (existing template)

1. Foundational migration: schemas + parametric seeds + designated partitions + audit\_log +
   processed\_jobs/dead\_letters.
2. Amendment applied: QueuePort/NotificationChannelPort ports + Vercel Queues/Resend/FCM/in-app/webhook
   adapters.
3. Ingestion pipeline (fast-ack + idempotent processor).
4. Complete canonical slice `trackEvent` (validates the WHOLE system against reality — analogous to
   the role of `createInitiative`).
5. CI extensions: partition lint (partition key in queries), per-endpoint permission validation,
   parametric seeds.

* **Closing:** each spec passes the updated Definition of Done (which includes the p95 budgets as
  items).

## Batch 7 — Legal package (drafts for lawyer review — DEC-J2, pending P-2)

* DPA (processing annex) ES · privacy policy ES/EN · ToS ES/EN · Softcrum internal RAT + spec of the
  per-tenant RAT generator · sub-processor list with international transfer basis · DPIA template ·
  annex of technical and organizational measures · DPO designation record (Daniel, provisional).
* **RULE:** no document in this batch is signed or published without review by a Chilean
  data-protection lawyer. They are professional working drafts.
* **Closing:** package delivered to the lawyer; observations incorporated; versioned in Comply.

## Batch 8 — Mintlify (docs.softcrum.com, bilingual — DEC-I1/I3)

* EN/ES structure per module: overview, concepts, processes and procedures, diagrams (export from
  batch 4), integration guides (track/identify quickstart, token exchange, webhooks, widget), API
  reference generated from OpenAPI, changelog and deprecation policy, rate limits per plan page
  (DEC-D4), sub-processors and trust center.
* **Closing:** complete navigation in both languages; API reference synchronised with the code
  (OpenAPI as the source).

***

## Critical sequence and dependencies

```
Batch 0 ──► Batch 1 ──► Batch 2 ──► Batch 3 ──► Batch 6 (construction)
                           │            └────► Batch 4 (parallel from Batch 3)
                           └──► Batch 5 (parallel from Batch 2)
Batch 7: independent, starts when Daniel confirms P-2 (lawyer)
Batch 8: fed by 3+4; published per module as they come to exist
```

External legal milestone: Ley 21.719 fully in force 2026-12-01 → batch 7 lawyer-reviewed and the
breach runbook operational BEFORE commercial launch.