Customization Guide

Ring clones share one codebase (ring-platform.org). Customization is config-first (ring-config.json presets, env, locales). Vertical niches ship as in-repo presets — do not fork niche TypeScript into the clone. See Vertical presets.

Customization map

1. ring-config.json (install-time SSOT)

Created by ./install.sh or copied from ring-config.template.json. Merged with the template at runtime in lib/ring-config-core.ts (also exposed server-side via lib/ring-config.ts).

Clone identity

{
  "clone": {
    "name": "my-ring-clone",
    "displayName": "My Platform",
    "description": "Regional opportunities network",
    "organization": "Your Org",
    "contactEmail": "contact@example.com"
  },
  "domains": {
    "production": "https://example.com",
    "development": "http://localhost:3000"
  },
  "platform": {
    "baseUrl": "https://example.com"
  }
}

Used for SEO (lib/seo-metadata.ts), JSON-LD, and getSiteBaseUrl().

Vertical presets (preferred over code forks)

{
  "entities": { "preset": "platform" },
  "productFields": { "preset": "platform" },
  "productBadges": { "preset": "platform" }
}

Agricultural / GreenFood-style clones use "agricultural" for all three. Full registry: Vertical presets.

Branding block

branding.logo, branding.colors, branding.darkColors, branding.fonts in the template — place assets under public/images/ (see template paths).

Optional env overrides (lib/site-branding.ts):

Feature flags

Toggle modules without deleting code:

Server checks: isFeatureEnabled() in lib/ring-config-core.ts and whitelabel/features.ts. Disable routes in navigation when turning features off.

Matcher defaults

Install-time AI matcher thresholds live under matcher in ring-config.json (getMatcherInstallDefaults()). Runtime DB overlay may apply for production rings — see AI customization.

Sidebar and navigation metadata

sidebar and navigation.links in ring-config.json feed public instance config (getPublicInstanceConfig()). Primary chrome is implemented in:

• components/navigation/navigation.tsx
• components/navigation/desktop-sidebar.tsx
• components/navigation/bottom-navigation.tsx

For a custom desktop nav variant, follow Whitelabel navigation.

2. Home page (replaces deprecated portal)

Customize hero copy (fastest path)

Edit locales/en/pages.json (mirror uk, ru):

HomeContent reads via useTranslations('pages.home').

Customize home layout

• Right rail (OSS marketplace / Ringdom CTAs): HomeRightRail inside home-wrapper.tsx, strings in pages.home.rightRail
• Deeper UX — fork home-wrapper.tsx or home.tsx; add paths to .reggie-propagate-exclude.json

ring-config.json hero block remains for clones that read it elsewhere; the flagship home hero is i18n-driven as above.

3. Internationalization

• SSOT: lib/locale-config.ts
• Messages: locales/{locale}/**/*.json, loaded by lib/i18n.ts
• Routing: @/i18n/routing — never hand-strip locale prefixes in client code

Full guide: Localization.

Protected locale files (overlay deltas) are listed in .reggie-propagate-exclude.json — typically locales/*/config.json, vendor.json only.

4. Theme and visual polish

Ring uses Tailwind 4 with CSS variables for light/dark (next-themes).

1. Set branding.colors / darkColors in ring-config.json (template documents keys aligned to shadcn tokens)
2. Replace public/favicon.ico, public/images/logo-*.svg, apple-touch-icon.png
3. Theme default: ring-config.json → "theme": { "default": "system" }

Avoid editing generated design tokens in unrelated clones — prefer ring-config + env brand overrides.

5. Payments and store (clone-level)

• PaymentConductor processors: env vars — Payment integration
• Store currency / tax: features.store in ring-config.json
• WayForPay / Stripe: never commit secrets; use k8s secrets in production

6. Web3 and tokens (optional)

Contract addresses and treasury: env + Token economics. Set tokens.native in ring-config.json for display metadata.

7. Reggie propagation — thin overlay only

Source of truth: always propagate from ring-platform.org. Exclude protects brand/locale overlay — not vertical code.

File: .reggie-propagate-exclude.json at repo root. Do not exclude niche fields, entity catalogs, or home-wrapper forks — select presets instead. Details: Vertical presets.

8. Verification checklist

1. 1

   Branding — logo, favicon, NEXT_PUBLIC_BRAND_NAME, OG image on share previews

2. 2

   Home — / hero matches pages.home in each supported locale

3. 3

   Presets — entities / productFields / productBadges match the vertical

4. 4

   Features — disabled modules 404 or hide from nav; no dead sidebar links

5. 5

   Auth — login/logout, role-gated admin at /admin

6. 6

   Build — npm run build clean; smoke tests if payments enabled

Next steps

Customization Guide

Ring clones share one codebase (ring-platform.org). Customization is config-first (ring-config.json presets, env, locales). Vertical niches ship as in-repo presets — do not fork niche TypeScript into the clone. See Vertical presets.

Customization map

1. ring-config.json (install-time SSOT)

Created by ./install.sh or copied from ring-config.template.json. Merged with the template at runtime in lib/ring-config-core.ts (also exposed server-side via lib/ring-config.ts).

Clone identity

{
  "clone": {
    "name": "my-ring-clone",
    "displayName": "My Platform",
    "description": "Regional opportunities network",
    "organization": "Your Org",
    "contactEmail": "contact@example.com"
  },
  "domains": {
    "production": "https://example.com",
    "development": "http://localhost:3000"
  },
  "platform": {
    "baseUrl": "https://example.com"
  }
}

Used for SEO (lib/seo-metadata.ts), JSON-LD, and getSiteBaseUrl().

Vertical presets (preferred over code forks)

{
  "entities": { "preset": "platform" },
  "productFields": { "preset": "platform" },
  "productBadges": { "preset": "platform" }
}

Agricultural / GreenFood-style clones use "agricultural" for all three. Full registry: Vertical presets.

Branding block

branding.logo, branding.colors, branding.darkColors, branding.fonts in the template — place assets under public/images/ (see template paths).

Optional env overrides (lib/site-branding.ts):

Feature flags

Toggle modules without deleting code:

Server checks: isFeatureEnabled() in lib/ring-config-core.ts and whitelabel/features.ts. Disable routes in navigation when turning features off.

Matcher defaults

Install-time AI matcher thresholds live under matcher in ring-config.json (getMatcherInstallDefaults()). Runtime DB overlay may apply for production rings — see AI customization.

Sidebar and navigation metadata

sidebar and navigation.links in ring-config.json feed public instance config (getPublicInstanceConfig()). Primary chrome is implemented in:

• components/navigation/navigation.tsx
• components/navigation/desktop-sidebar.tsx
• components/navigation/bottom-navigation.tsx

For a custom desktop nav variant, follow Whitelabel navigation.

2. Home page (replaces deprecated portal)

Customize hero copy (fastest path)

Edit locales/en/pages.json (mirror uk, ru):

HomeContent reads via useTranslations('pages.home').

Customize home layout

• Right rail (OSS marketplace / Ringdom CTAs): HomeRightRail inside home-wrapper.tsx, strings in pages.home.rightRail
• Deeper UX — fork home-wrapper.tsx or home.tsx; add paths to .reggie-propagate-exclude.json

ring-config.json hero block remains for clones that read it elsewhere; the flagship home hero is i18n-driven as above.

3. Internationalization

• SSOT: lib/locale-config.ts
• Messages: locales/{locale}/**/*.json, loaded by lib/i18n.ts
• Routing: @/i18n/routing — never hand-strip locale prefixes in client code

Full guide: Localization.

Protected locale files (overlay deltas) are listed in .reggie-propagate-exclude.json — typically locales/*/config.json, vendor.json only.

4. Theme and visual polish

Ring uses Tailwind 4 with CSS variables for light/dark (next-themes).

1. Set branding.colors / darkColors in ring-config.json (template documents keys aligned to shadcn tokens)
2. Replace public/favicon.ico, public/images/logo-*.svg, apple-touch-icon.png
3. Theme default: ring-config.json → "theme": { "default": "system" }

Avoid editing generated design tokens in unrelated clones — prefer ring-config + env brand overrides.

5. Payments and store (clone-level)

• PaymentConductor processors: env vars — Payment integration
• Store currency / tax: features.store in ring-config.json
• WayForPay / Stripe: never commit secrets; use k8s secrets in production

6. Web3 and tokens (optional)

Contract addresses and treasury: env + Token economics. Set tokens.native in ring-config.json for display metadata.

7. Reggie propagation — thin overlay only

Source of truth: always propagate from ring-platform.org. Exclude protects brand/locale overlay — not vertical code.

File: .reggie-propagate-exclude.json at repo root. Do not exclude niche fields, entity catalogs, or home-wrapper forks — select presets instead. Details: Vertical presets.

8. Verification checklist

1. 1

   Branding — logo, favicon, NEXT_PUBLIC_BRAND_NAME, OG image on share previews

2. 2

   Home — / hero matches pages.home in each supported locale

3. 3

   Presets — entities / productFields / productBadges match the vertical

4. 4

   Features — disabled modules 404 or hide from nav; no dead sidebar links

5. 5

   Auth — login/logout, role-gated admin at /admin

6. 6

   Build — npm run build clean; smoke tests if payments enabled

Next steps

Customization Guide

Ring clones share one codebase (ring-platform.org). Customization is config-first (ring-config.json presets, env, locales). Vertical niches ship as in-repo presets — do not fork niche TypeScript into the clone. See Vertical presets.

Customization map

1. ring-config.json (install-time SSOT)

Created by ./install.sh or copied from ring-config.template.json. Merged with the template at runtime in lib/ring-config-core.ts (also exposed server-side via lib/ring-config.ts).

Clone identity

{
  "clone": {
    "name": "my-ring-clone",
    "displayName": "My Platform",
    "description": "Regional opportunities network",
    "organization": "Your Org",
    "contactEmail": "contact@example.com"
  },
  "domains": {
    "production": "https://example.com",
    "development": "http://localhost:3000"
  },
  "platform": {
    "baseUrl": "https://example.com"
  }
}

Used for SEO (lib/seo-metadata.ts), JSON-LD, and getSiteBaseUrl().

Vertical presets (preferred over code forks)

{
  "entities": { "preset": "platform" },
  "productFields": { "preset": "platform" },
  "productBadges": { "preset": "platform" }
}

Agricultural / GreenFood-style clones use "agricultural" for all three. Full registry: Vertical presets.

Branding block

branding.logo, branding.colors, branding.darkColors, branding.fonts in the template — place assets under public/images/ (see template paths).

Optional env overrides (lib/site-branding.ts):

Feature flags

Toggle modules without deleting code:

Server checks: isFeatureEnabled() in lib/ring-config-core.ts and whitelabel/features.ts. Disable routes in navigation when turning features off.

Matcher defaults

Install-time AI matcher thresholds live under matcher in ring-config.json (getMatcherInstallDefaults()). Runtime DB overlay may apply for production rings — see AI customization.

Sidebar and navigation metadata

sidebar and navigation.links in ring-config.json feed public instance config (getPublicInstanceConfig()). Primary chrome is implemented in:

• components/navigation/navigation.tsx
• components/navigation/desktop-sidebar.tsx
• components/navigation/bottom-navigation.tsx

For a custom desktop nav variant, follow Whitelabel navigation.

2. Home page (replaces deprecated portal)

Customize hero copy (fastest path)

Edit locales/en/pages.json (mirror uk, ru):

HomeContent reads via useTranslations('pages.home').

Customize home layout

• Right rail (OSS marketplace / Ringdom CTAs): HomeRightRail inside home-wrapper.tsx, strings in pages.home.rightRail
• Deeper UX — fork home-wrapper.tsx or home.tsx; add paths to .reggie-propagate-exclude.json

ring-config.json hero block remains for clones that read it elsewhere; the flagship home hero is i18n-driven as above.

3. Internationalization

• SSOT: lib/locale-config.ts
• Messages: locales/{locale}/**/*.json, loaded by lib/i18n.ts
• Routing: @/i18n/routing — never hand-strip locale prefixes in client code

Full guide: Localization.

Protected locale files (overlay deltas) are listed in .reggie-propagate-exclude.json — typically locales/*/config.json, vendor.json only.

4. Theme and visual polish

Ring uses Tailwind 4 with CSS variables for light/dark (next-themes).

1. Set branding.colors / darkColors in ring-config.json (template documents keys aligned to shadcn tokens)
2. Replace public/favicon.ico, public/images/logo-*.svg, apple-touch-icon.png
3. Theme default: ring-config.json → "theme": { "default": "system" }

Avoid editing generated design tokens in unrelated clones — prefer ring-config + env brand overrides.

5. Payments and store (clone-level)

• PaymentConductor processors: env vars — Payment integration
• Store currency / tax: features.store in ring-config.json
• WayForPay / Stripe: never commit secrets; use k8s secrets in production

6. Web3 and tokens (optional)

Contract addresses and treasury: env + Token economics. Set tokens.native in ring-config.json for display metadata.

7. Reggie propagation — thin overlay only

Source of truth: always propagate from ring-platform.org. Exclude protects brand/locale overlay — not vertical code.

File: .reggie-propagate-exclude.json at repo root. Do not exclude niche fields, entity catalogs, or home-wrapper forks — select presets instead. Details: Vertical presets.

8. Verification checklist

1. 1

   Branding — logo, favicon, NEXT_PUBLIC_BRAND_NAME, OG image on share previews

2. 2

   Home — / hero matches pages.home in each supported locale

3. 3

   Presets — entities / productFields / productBadges match the vertical

4. 4

   Features — disabled modules 404 or hide from nav; no dead sidebar links

5. 5

   Auth — login/logout, role-gated admin at /admin

6. 6

   Build — npm run build clean; smoke tests if payments enabled

Next steps

Quick Start (new clone)

Quick Start (new clone)

Quick Start (new clone)