---
title: "Ringization playbook"
description: "Settler clone critical path — Final-Split thin overlays, Tier-1/2/3 ringize, Reggie exclude, dual-path skill vs manual"
locale: "en"
---
# Ringization playbook

> **Info**
> Use **Founder** / **Developer** tabs in the docs sidebar to filter this page. Shared sections apply to both audiences.

> **Tip**
> **Status:** This page is the long-form **white-label ringization** SSOT for settlers and integrators. The Order Lab **Playbook** tab is the **per-order checklist**; this article is the methodology. Product steps also live in code at `features/crm/lab/ringization-playbook.ts` (seeded into the project room on integrator assign).

Ringization means shipping a **clone-local feature overlay** on Layer1 **`ring/web`** — brand, presets, and optional Tier-3 domain modules — **without editing** the platform tree (and without treating `ring-platform-org` as your vertical). Build merge: platform copy → tmp, then clone overlay overwrite (`ringdom-clone-build` / Forgejo Lab path).

| Surface | Role |
|---------|------|
| **This playbook** | Full vertical / brand / Tier-1–3 methodology |
| [Configuration playbook](/docs/configuration/playbook.md) | Order Lab `?tab=playbook` — this order’s gates |
| [Vertical presets](/docs/customization/vertical-presets.md) | Named `entities` / `home` / productField catalogs |
| [Customization guide](/docs/customization/customization-guide.md) | Config-first branding + thin exclude hygiene |
| [Owner Project Lab](/docs/features/owner-project-lab.md) | Buyer `/my-orders` · integrator `/my-jobs` chrome |

| Previous habit | Ring equivalent |
|----------------|-----------------|
| Fork all of platform into `ring-*` | Thin `ring-*/web/` overlay + `ringdom-clone-build` |
| Patch `lib/i18n.ts` / `home-wrapper` per brand | Overlay `lib/overlay/registry.ts` + `features//` |
| Nest product under `features.n9life: true` | Top-level `"n9life": { … }` domain block |
| Exclude whole `lib/` or `lib/overlay/` | Exclude **`web/lib/overlay/registry.ts` plug only** (+ domain dirs) |
| `reggie-ringize` plan files as factory | **`reggie_autonomous_clone`** → merge → forge |

## Settler pipeline (shared)

1. **Calculator** → paid `project_order`
2. **Order Project Config** — `home.preset`, `domainFeatureId`, brand fields
3. **Integrator assign** → playbook markdown seeded in the project room (`PLAYBOOK_SEED_MARKER`)
4. **Factory** — `reggie_autonomous_clone` (thin disk overlay) → Forgejo `ringdom-clones/` → BuildKit / Lab deploy

Buyers and integrators open the in-app panel on `/my-orders/[id]` and `/my-jobs/[id]` (`?tab=playbook`). Docs deep-link: `/docs/customization/ringization-playbook`.

## Kingdom layers (Final-Split)

```text
Layer1     ring/web/              Next.js SSOT — never ringize product here
Empire     ring-platform-org/     Order Lab / CRM / calculator (not your vertical)
White-label ring-/web/      Endemic overlay only (Final-Split)
Compose    ringdom-clone-build    Layer1 web + clone web → build tmp (clone wins)
```

Hostname / AI-CONTEXT id `ring-platform.org` is **not** a checkout directory. Legacy flat clones (package at clone root) should migrate with **layer2-clone-operator Mode B** before endemic Tier-3 work.

## Hard bans

- No Cosmic Mirror / brand locales in platform `home-wrapper` or `lib/i18n`
- Platform `lib/overlay/registry.ts` stays **maps-empty**; clones overlay registrations (**maps only**)
- Platform `lib/overlay/runtime.ts` + `types.ts` are SSOT — never fork loaders onto the clone plug
- Factory = `reggie_autonomous_clone` (not `reggie-ringize` plans)
- Do not `cp -r ring/web` into the clone as a permanent fork

---

## Recommended path

Use Cursor agent **`clone-customization-with-implementer`** (orchestrates **`layer2-clone-operator`** + **`ringization-implementer`**). It does **not** mutate until you approve the plan / dry-run.

**Starter prompt (paste, fill blanks):**

> Ringize `TARGET_CLONE=ring-` with `FEATURE_ID=` and `MODE=A_new_thin` \| `B_migrate_flat_to_web` \| `C_ringize_existing`. Overlay root = Final-Split `web/`. Follow `.cursor/agents/layer2-clone-operator.md` then `.cursor/agents/ringization-implementer.md`. Zero edits under `ring/web/` or unsolicited `ring-platform-org/`. Update `.reggie-propagate-exclude.json` with `web/…` paths; exclude `web/lib/overlay/registry.ts` plug only. Dry-run `ringdom-clone-build` then pause for my approval before apply.

**Inputs checklist**

- `TARGET_CLONE`, `FEATURE_ID`, display name / SEO
- Home: `platform` \| `mvm-landing` \| `-landing`
- Scope: thin brand \| Tier-2 presets \| full Tier-3
- Locales (match clone env)

**Reggie MCP (after overlay plan approved)**

1. Scaffold / refresh thin overlay: `reggie_autonomous_clone` with `dry_run: true` first (`clone_name`, `customization`, optional `skip_merge`)
2. Propagate Layer1 shared code later with `reggie_ringdom_propagate` — `source_project: "ring"`, `dry_run: true`, then review `files_planned[]` / `files_rejected_list[]` before `dry_run: false`
3. Compose always via **`ringdom-clone-build`** (ringdom-mcp) — platform → tmp, clone overlay wins

---

## Manual path

Prerequisites: repo access to Ringdom, clone slug chosen, FEATURE_ID matching `^[a-z][a-z0-9]*$`, MCP or local merge script available.

**Classify Mode** — New thin overlay (**A**), flat→`web/` migrate (**B**), or ringize existing Final-Split (**C**). Prefer **A/B** via **layer2-clone-operator** before endemic product.

**Tier-1 config** — Under `OVERLAY_ROOT` (`ring-/web`): set `ring-config.json` `clone.*`, `seo`, `home.preset`, entity/product presets. For Tier-3 add top-level `"": { "enabled": true, … }` — **not** under boolean `features.*`.

**Tier-2 presets** — Prefer platform catalogs (`agricultural`, `mvm-landing`, …). Only add clone `features/*/presets/.ts` + registry overlay when the niche is not upstream yet.

**Tier-3 package** — Create `features//` (`i18n.ts` → `appendOverlayMessages`, components, optional APIs). Overlay **maps-only** `lib/overlay/registry.ts` for i18n + home rail. Optional `components/pages/home-presets/-landing.tsx`.

**Reggie exclude** — At clone root `.reggie-propagate-exclude.json`: `files[]` + `directories[]` + `locale_strategy: "new_keys_only"`. Final-Split paths use **`web/`** prefixes. Always exclude the registry **plug**; never exclude `types.ts` / `runtime.ts` / whole `lib/overlay/`.

**Build verify** — `ringdom-clone-build({ project_name: "ring-", dry_run: true })`, then typecheck in the merge tmp / `.dev-merge`. Push forge `ringdom-clones/` only after dry-run review.

### Exclude skeleton (Final-Split)

```json
{
  "description": " feature-overlay — brand + Tier-3. Exclude registry.ts plug only.",
  "files": [
    ".reggie-propagate-exclude.json",
    "web/ring-config.json",
    "web/lib/overlay/registry.ts",
    "web/components/pages/home-presets/-landing.tsx"
  ],
  "directories": [
    "web/features/",
    "web/public/branding",
    "web/locales"
  ],
  "locale_strategy": "new_keys_only"
}
```

Allowlisted domain ids on Layer1 (`OVERLAY_FEATURE_IDS`): `n9life`, `connect`, `greenfood`, `ringdom`. New global ids need a separate platform PR to extend the allowlist; one-off clones still use the same id string + clone registry overlay.

---

### For founders

## Why this matters for your clone

You buy a **vertical Ring**, not a fork of the entire platform. Ringization keeps your brand and product modules in a thin overlay so platform upgrades (Auth.js, store, matcher, Lab) still flow via Reggie — without wiping Cosmic Mirror, Connect, or your logos.

  
- **[Pay → Project Config](/docs/features/owner-project-lab.md)** — Set name, slogan, logo, home.preset, and domainFeatureId after calculator checkout.

  
- **[Order Lab playbook tab](/docs/configuration/playbook.md)** — Per-order checklist beside secrets, wiki, and deploy gates.

  
- **[Vertical presets](/docs/customization/vertical-presets.md)** — Prefer agricultural / mvm-landing shared niches before asking for custom code.

  
- **[Customization guide](/docs/customization/customization-guide.md)** — Branding, feature flags, and thin-overlay exclude doctrine.

### Typical scenarios

| Scenario | What you ask for |
|----------|------------------|
| Logo + site name only | Tier-1 — `ring-config` + branding assets |
| Healthy-food marketplace like GreenFood | Tier-2 — `entities`/`productFields`/`productBadges` = `agricultural`, `home.preset` = `mvm-landing` |
| Unique product (Cosmic Mirror, Connect) | Tier-3 — `features//*` + registry plug + exclude |
| Flat legacy clone | Mode B Final-Split migrate before more endemic UI |

> **Warning**
> Empire Order Lab (`ring-platform-org`) is the **control plane** for paid clones — it is not the template to copy into your white-label. Your product lives under `ring-/web/`.

### For developers

## Implementation map

| Concern | Verified path |
|---------|----------------|
| In-app playbook SSOT | `ring-platform-org/web/features/crm/lab/ringization-playbook.ts` |
| Playbook UI panel | `…/ringization-playbook-panel.tsx` |
| Seed on assign | `seedRingizationPlaybookMessage` in `order-lab-chat-service.ts` |
| Project Config domain key | `domainFeatureId` → top-level overlay in `order-project-config.ts` |
| Layer1 empty registry | `ring/web/lib/overlay/registry.ts` |
| Socket SSOT | `ring/web/lib/overlay/types.ts`, `runtime.ts` |
| Feature id allowlist | `OVERLAY_FEATURE_IDS` in `lib/overlay/types.ts` |
| Agents | `.cursor/agents/ringization-implementer.md`, `layer2-clone-operator.md`, `clone-customization-with-implementer.md` |
| Exclude exemplar (empire) | `ring-platform-org/.reggie-propagate-exclude.json` (`web/…` + ops dirs) |
| Exclude exemplar (vertical) | `ring-n9life-com/.reggie-propagate-exclude.json` |

```mermaid
flowchart LR
  L1["ring/webtypes + runtimeempty registry"] --> Build["ringdom-clone-build"]
  Clone["ring-*/webregistry mapsfeatures/id"] --> Build
  Build --> Tmp["tmp mergeclone wins"]
  Reggie["reggie_ringdom_propagatesource=ring"] -.->|"skips exclude"| Clone
```

### Registry plug (clone only)

```ts
import type { OverlayHomeRailRegistry, OverlayI18nRegistry } from '@/lib/overlay/types'

export const OVERLAY_I18N_REGISTRY: OverlayI18nRegistry = {
  n9life: () => import('@/features/n9life/i18n'),
}

export const OVERLAY_HOME_RAIL_REGISTRY: OverlayHomeRailRegistry = {
  n9life: () => import('@/features/n9life/components/home-right-rail'),
}
```

Replace `n9life` with your `FEATURE_ID`. Do **not** define `loadOverlayMessages` / `resolveOverlayHomeRail` here — those stay in platform `runtime.ts`.

### MCP servers

| Tool | Server id |
|------|-----------|
| `legiox-knowledge` / agent-selector | `project-0-ringdom-legiox-mcp` |
| `reggie_autonomous_clone`, `reggie_ringdom_propagate` | `project-0-ringdom-reggie-mcp` |
| `ringdom-clone-build` | `project-0-ringdom-ringdom-mcp` |

---

## Frequently asked questions

### Impact

#### Will platform upgrades wipe my Cosmic Mirror / domain UI?

No — if those paths are listed in `.reggie-propagate-exclude.json`. Missing excludes are how Reggie overwrites vertical code. Always exclude the registry plug + `web/features//`.

#### Do I need Tier-3 for every clone?

No. Prefer Tier-1 brand + Tier-2 named presets. Tier-3 only when you need clone-only UI, locales, or APIs.

### Migration

#### Our clone is still flat (app/ at repo root). What first?

Run **layer2-clone-operator Mode B**: cut endemic files into `web/`, rewrite exclude with `web/…` prefixes, add `scripts/merge-dev.sh`, then Mode C ringize.

#### Can integrators edit `ring/web` to “fix” a missing brand string?

No. That is a hard ban. Fix via clone locales / overlay registry / home preset — or upstream a **shared** preset in a separate Layer1 PR.

### Ops

#### Who deploys — buyer, integrator, or Reggie?

Deploy is **integrator/admin** from Order Lab. Reggie plans in chat and may scaffold/propagate; it does **not** deploy. See [Owner Project Lab](/docs/features/owner-project-lab.md).

#### What is the factory for a new disk overlay?

`reggie_autonomous_clone` (thin overlay + optional merge). Not `reggie-ringize` plan artifacts.

#### Where do buyers see this playbook in-app?

`/my-orders/[id]?tab=playbook` (buyer) and `/my-jobs/[id]?tab=playbook` (integrator). Seeded chat uses `PLAYBOOK_SEED_MARKER` for idempotent re-assign.

---

## Related documentation

  
- [configuration/playbook](/docs/configuration/playbook.md) — Same-workflow: Order Lab playbook tab checklist for this settler order.

  
- [features/owner-project-lab](/docs/features/owner-project-lab.md) — Prerequisite: buyer My Projects and integrator Order Lab chrome.

  
- [customization/vertical-presets](/docs/customization/vertical-presets.md) — Depends-on: named preset catalogs before Tier-3 forks.

  
- [customization/customization-guide](/docs/customization/customization-guide.md) — Next-step: config-first branding and thin exclude hygiene.

  
- [customization/quick-start](/docs/customization/quick-start.md) — See-also: first local clone before ringizing a vertical.