Brand Generation & Governance

Status: Draft (stub) — documents scripts/generate-brand-app.sh capabilities.

Purpose

Deterministic, guarded creation of brand application shells with validation, tagging, and idempotency.

Features

Registry key validation (jq)
Idempotency guard (--force to overwrite)
Dry run mode (--dry-run)
Dynamic tag injection (brand:<key> + extras)
Post-generation Nx project registration check

Usage

./scripts/generate-brand-app.sh <brand-id> <platform:web|mobile> [options]

Options

Flag	Description
—dry-run	Show actions without writing
—family `<name>`	Set family folder under apps/ (default: generated)
—tags `<csv>`	Append extra tags (comma separated)
—force	Overwrite existing directory
—skip-validate	Skip registry brand key lookup

Example

./scripts/generate-brand-app.sh orangeGuest web --tags "status:experimental,owner:team-a"

Output Structure

apps/<family>/<brand>/<platform>/
  project.json
  src/
    App.tsx
  (template files)

Post-Generation Checklist

Commit scaffold
Run verify gate (./scripts/verify-repo.sh)
Implement brand-specific customizations

Failure Modes

Scenario	Exit Code	Mitigation
Brand not in registry	2	Add to registry.json or —skip-validate
Target exists	3	Use —force if intentional
jq missing	(warn)	Install jq for validation
nx missing	(warn)	Ensure Nx CLI available

Roadmap

Phase 1 (Complete)

✅ Registry key validation (jq)
✅ Idempotency guard (--force to overwrite)
✅ Dry run mode (--dry-run)
✅ Dynamic tag injection (brand:<key> + extras)
✅ Post-generation Nx project registration check

Phase 2 (Complete - M3)

✅ Auto-generate brand README template per scaffold
✅ Protected regions for custom content preservation
✅ Batch generation mode (matrix input)
✅ Post-generation summary table output

Phase 2 Features (M3)

Brand README Generation

Script: scripts/generate-brand-readme.mjs

Automatically generates per-brand README files with dual sections:

Auto-generated section: Registry-driven metadata (regenerated on every run)
Custom section: Team-specific content preserved across regenerations

Usage:

# Generate/update all brand READMEs
node scripts/generate-brand-readme.mjs

# Check mode (dry-run, shows what would change)
node scripts/generate-brand-readme.mjs --check

# Force overwrite (for initial migration)
node scripts/generate-brand-readme.mjs --force-overwrite

Protected Regions:

<!-- AUTO-GENERATED -->
...generated content...
<!-- END AUTO-GENERATED SECTION -->

<!-- CUSTOM CONTENT BELOW - Edit freely, this section is preserved -->
...team-specific notes, architecture diagrams, etc....

Features:

✅ Registry-driven content (brand name, description, platforms, features)
✅ Automatic sections: Overview, Features, Platforms, Development
✅ Protected custom content region (preserved on regeneration)
✅ Idempotent: safe to run multiple times
✅ Summary table output (brands processed, created, updated, errors)

Output Location:

apps/<family>/<brand>/mobile/README.md

Example Summary:

╔══════════════════════════════════════════════════════════════╗
║                   Brand README Summary                       ║
╚══════════════════════════════════════════════════════════════╝

  Total Brands: 2
  Created:      1
  Updated:      1
  Errors:       0

  Duration: 0.234s

Batch Generation Mode

Capability: Generate READMEs for all brands in the registry at once.

Default behavior: The script processes all brands by default, making batch mode implicit.

Use cases:

Initial migration (add READMEs to all existing brands)
Periodic refresh after registry schema changes
CI automation (ensure READMEs stay in sync with registry)

Post-Generation Summary

Output format: Structured table with status, counts, and timing

Example:

$ node scripts/generate-brand-readme.mjs

[readme-generator] Reading brand registry...
[readme-generator] Found 2 brands

Processing: pinkGuest
  ✓ README updated: apps/stay_match/pinkguest/mobile/README.md

Processing: orangeGuest
  ✓ README created: apps/stay_match/orangeguest/mobile/README.md

╔══════════════════════════════════════════════════════════════╗
║                   Brand README Summary                       ║
╚══════════════════════════════════════════════════════════════╝

  Total Brands: 2
  Created:      1
  Updated:      1
  Errors:       0

  Duration: 0.234s

Protected Content Preservation

Workflow:

First Run (No README exists):
- Creates README with auto-generated section
- Adds custom content placeholder
Subsequent Runs (README exists):
- Regenerates auto-generated section (updates brand metadata)
- Preserves everything after 
- Maintains team notes, architecture decisions, troubleshooting guides
Migration (Existing README, no markers):
- Use --force-overwrite to establish protected regions
- Manually restore custom content from git history
- Future runs will preserve custom section

Safety Guarantees:

Custom content is never overwritten (unless --force-overwrite used)
Auto-generated section always reflects current registry state
Regeneration is idempotent (safe to run repeatedly)

Check Mode (—check)

Purpose: Preview changes without writing files