PR: Set up comprehensive branding automation scaffolds and workflows

.github/automation/badges.schema.yml

@@ -0,0 +1,33 @@
+# Canonical badge definitions and mapping rules
+version: 1
+badges:
+  workflow:
+    front-matter-schema:
+      label: "Front-Matter"
+      icon: "🧩"
+      source: "github-actions"
+      job: "front-matter-validate"
+      success_text: "Schema OK"
+      failure_text: "Schema Fail"
+  meta:
+    license:
+      label: "License"
+      icon: "📄"
+      values:
+        mit: "MIT"
+        gpl-2.0: "GPL-2.0"
+mapping:
+  # Deterministic mapping from front matter and repo state to badges
+  - when:
+      has_front_matter: true
+    add:
+      - workflow.front-matter-schema
+  - when:
+      front_matter.license: ["mit","gpl-2.0"]
+    add:
+      - meta.license
+render:
+  order:
+    - title
+    - badges
+    - description

.github/automation/emoji.schema.yml

@@ -0,0 +1,15 @@
+version: 1
+apply_to: ["h1","h2"]
+skip:
+  # formal docs where emojis are not used
+  - "CHANGELOG.md"
+  - "CODE_OF_CONDUCT.md"
+map:
+  # keyword -> emoji (first match wins)
+  design: "🎨"
+  workflow: "🛠"
+  release: "🚀"
+  governance: "🏛"
+fallbacks:
+  generic: "✨"     # used only if no keyword matched and page not in skip
+notes: "Conservative: 0–1 emoji per heading; never on h3+."

.github/automation/footers.yml

@@ -0,0 +1,31 @@
+version: 1
+categories:
+  docs:
+    phrases:
+      - "Made with ❤️ by the LightSpeed team."
+      - "Questions? Open an issue; we're listening."
+      - "Prefer a guided setup? Book a consult."
+      - "Clarity first, then code. Thanks for reading."
+      - "Improvements welcome—PRs encouraged."
+  prompts:
+    phrases:
+      - "Copy, adapt, and keep shipping."
+      - "Tweak the variables, get results fast."
+      - "Your feedback shapes the next iteration."
+      - "Reuse beats rework. Share improvements."
+      - "Keep prompts versioned for sanity."
+  saved-replies:
+    phrases:
+      - "Use responsibly; tailor to the thread."
+      - "Keep tone human, clear, and kind."
+      - "Update when guidance changes."
+      - "Link policies; avoid assumptions."
+      - "Thanks for helping contributors."
+default:
+  phrases:
+    - "Made with ❤️ by the LightSpeed team."
+    - "Need help? Say hi—work with us."
+selection:
+  strategy: "seeded"
+  seed: "file.path_slug"   # stable per file
+  # Deterministic selection algorithm not yet implemented. This section is non-functional.

.github/automation/front-matter.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Front Matter",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "title": { "type": "string" },
+    "slug":  { "type": "string" },
+    "series": { "type": ["object","string"] },
+    "tags":  { "type": "array", "items": { "type": "string" } },
+    "no_branding": { "type": "boolean" },
+    "category": { "type": "string" }
+  }
+}

.github/metrics/branding-log.md

@@ -0,0 +1,9 @@
+---
+title: 'Branding Metrics Log'
+description: 'Historical log of branding automation metrics'
+---
+
+# Branding Metrics Log
+
+| timestamp | coverage | changes | errors | optouts |
+|---|---:|---:|---:|---:|

.github/metrics/branding.json

@@ -0,0 +1,7 @@
+{
+  "ts": null,
+  "coverage": 0,
+  "changes": 0,
+  "errors": 0,
+  "optouts": 0
+}

.github/workflows/branding.yml

@@ -0,0 +1,142 @@
+---
+name: Branding Agent
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: [develop]
+    paths:
+      - "**/*.md"
+      - ".github/automation/**"
+      - ".github/agents/**"
+  push:
+    branches: [develop]
+    paths:
+      - "**/*.md"
+      - ".github/automation/**"
+      - ".github/agents/**"
+  schedule:
+    - cron: "0 3 * * 1" # weekly metrics roll-up (Mon 03:00 UTC)
+
+concurrency:
+  group: "branding-${{ github.ref }}"
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  front-matter-validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Validate Front Matter
+        run: |
+          npm i -g ajv-cli
+          if [ "${GITHUB_EVENT_NAME}" = "pull_request" ]; then
+            BASE_REF="${{ github.base_ref }}"
+            HEAD_REF="${{ github.sha }}"
+          elif [ "${GITHUB_EVENT_NAME}" = "push" ]; then
+            BASE_REF="${{ github.event.before }}"
+            HEAD_REF="${{ github.sha }}"
+          else
+            BASE_REF="HEAD~1"
+            HEAD_REF="${{ github.sha }}"
+          npm install --prefix .github/scripts js-yaml ajv
+          FILES=$(git diff --name-only ${{ github.sha }} ${{ github.base_ref || 'HEAD~1' }} | grep -E '\.md$' || true)
+          for f in $FILES; do
+            node .github/scripts/validate-frontmatter.js "$f"
+          done
+
+  lint-and-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: avto-dev/markdown-lint@v1
+        with:
+          config: 'markdownlint.config.js'
+          args: '**/*.md'
+
+      - name: Check Links
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --no-progress --verbose './**/*.md' --exclude-mail
+
+  apply-branding:
+    if: ${{ github.event_name != 'pull_request' }}
+    needs: [front-matter-validate, lint-and-links]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Run Branding Agent
+        run: |
+          node .github/agents/branding.agent.js
+
+      - name: Commit changes (content-only)
+        run: |
+          git config user.name "lightspeed-bot"
+          git config user.email "[email protected]"
+          git add -A
+          if ! git diff --cached --quiet; then
+            git commit -m "chore(branding): apply header/badges/refs/banner/footer [skip ci]"
+            git push
+          fi
+
+  metrics-update:
+    needs: [apply-branding]
+    if: ${{ success() || failure() }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Update Metrics Snapshot
+        run: |
+          mkdir -p .github/metrics
+          # Read metrics from branding agent output (branding-metrics.json)
+          if [ -f .github/metrics/branding-metrics.json ]; then
+            node -e "
+              const fs = require('fs');
+              const m = JSON.parse(fs.readFileSync('.github/metrics/branding-metrics.json', 'utf8'));
+              m.ts = new Date().toISOString();
+              fs.writeFileSync('.github/metrics/branding.json', JSON.stringify(m, null, 2));
+              const logLine = \`| \${m.ts} | coverage:\${m.coverage} | changes:\${m.changes} | errors:\${m.errors} | optouts:\${m.optouts} |\n\`;
+              fs.appendFileSync('.github/metrics/branding-log.md', logLine);
+            "
+          else
+            echo "Warning: .github/metrics/branding-metrics.json not found. Writing zeroed metrics."
+            node -e "
+              const fs = require('fs');
+              let m = { ts: new Date().toISOString(), coverage: 0, changes: 0, errors: 0, optouts: 0 };
+              fs.writeFileSync('.github/metrics/branding.json', JSON.stringify(m, null, 2));
+              const logLine = \`| \${m.ts} | coverage:0 | changes:0 | errors:0 | optouts:0 |\n\`;
+              fs.appendFileSync('.github/metrics/branding-log.md', logLine);
+            "
+          fi
+      - name: Commit metrics
+        run: |
+          git config user.name "lightspeed-bot"
+          git config user.email "[email protected]"
+          git add .github/metrics/branding.json .github/metrics/branding-log.md
+          if ! git diff --cached --quiet; then
+            git commit -m "chore(branding): update metrics snapshot [skip ci]"
+            git push
+          fi