docs(skills): describe flat Claude skill layout

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
fix(build): generate flat Claude skill directories
2026-10-01 11:02:07 +02:00 · 2026-10-01 11:02:07 +02:00 · 2026-10-01 11:02:06 +02:00 · 2026-10-01 11:02:06 +02:00 · 2026-10-01 11:02:05 +02:00 · 2026-10-01 11:01:55 +02:00
43 changed files with 1708 additions and 1641 deletions
@@ -142,10 +142,13 @@ jobs:
  client-smoke:
    name: Installed client configuration smoke tests
    runs-on: ubuntu-latest
-    timeout-minutes: 15
+    timeout-minutes: 20
    needs: [build]
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
      - name: Build packages
        run: bash scripts/commands/build.sh --summary
      - uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v22.16.0
@@ -153,6 +156,10 @@ jobs:
          node-version: '24'
      - name: Install current client CLIs
        run: npm install --global @openai/codex @anthropic-ai/claude-code
+      - name: Install Claude sandbox dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes --no-install-recommends bubblewrap socat
      - name: Validate current Codex and Claude settings
        run: |
          set -euo pipefail
@@ -160,6 +167,10 @@ jobs:
          cp generated/codex-powershell/config.toml "$schema_home/config.toml"
          CODEX_HOME="$schema_home" codex --strict-config --help >/dev/null
          claude --settings generated/claude-powershell/settings.json --help >/dev/null
+      - name: Run client behavior smoke tests
+        env:
+          AI_CONFIG_REQUIRE_CLIENTS: '1'
+        run: timeout 900 python scripts/tests/test-client-smoke.py -v

  retrieval:
    name: Qwen retrieval integration
@@ -6,7 +6,9 @@
  },
  "sandbox": __CLAUDE_SANDBOX__,
  "env": {
-    "CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY": "__CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY__"
+    "CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY": "__CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY__",
+    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "5",
+    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"
  },
  "statusLine": {
    "type": "command",
@@ -1 +1 @@
-Read skills/rules/rules-orchestration/SKILL.md from your installed configuration before acting as a subagent.
+Read skills/rules-orchestration/SKILL.md from your installed configuration before acting as a subagent.
@@ -1,6 +1,6 @@
 # Configuration

-Codex receives a generated global `AGENTS.md`, agent TOML files, skills, rule files, and a `config.toml` adapter. It sets workspace sandboxing with network access for shell commands (so MCPorter calls such as Context7 work without approval), automatic approval review, `agents.enabled = true`, `agents.max_concurrent_threads_per_session = 5`, and `agents.max_depth = 1`. Claude Code receives a generated global `CLAUDE.md`, agent Markdown files, skills, and `settings.json` with `auto` permissions, explicit `Agent` and `mcporter call context7.*` shell permissions, `mcp.context7.com` as the only allowed sandbox domain where the Claude sandbox is enabled, and a five-operation concurrency default. Installation resolves user paths at runtime; the repository contains no machine-specific paths.
+Codex receives a generated global `AGENTS.md`, agent TOML files, skills, rule files, and a `config.toml` adapter. It sets workspace sandboxing with network access for shell commands (so MCPorter calls such as Context7 work without approval), automatic approval review, `agents.enabled = true`, `agents.max_concurrent_threads_per_session = 5`, and `agents.max_depth = 1`. Claude Code receives a generated global `CLAUDE.md`, agent Markdown files, skills, and `settings.json` with `auto` permissions, explicit `Agent` and `mcporter call context7.*` shell permissions, `mcp.context7.com` as the only allowed sandbox domain where the Claude sandbox is enabled, a five-operation concurrency default, at most five concurrent subagents (`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`), and a subagent spawn depth of one (`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`), so subagents cannot start further subagents. Installation resolves user paths at runtime; the repository contains no machine-specific paths.

 Both clients embed `shared/rules/general.md` and the rule-loading conditions from `shared/global-instructions.md`. Rules for languages and frameworks live in their own directories, with an `index.md` entry point and focused Markdown rules under `references/`. Security has its own directory with a baseline entry point and focused rules for authentication, web, APIs, data, files, network, cryptography, and supply chains. Git, Microsoft, and cross-cutting rules remain directly under `shared/rules/`. Codex receives the full directory tree; Claude generates a skill for each rule and copies supporting references alongside the index skill.

@@ -50,7 +50,7 @@ Gitea Actions runs the repository checks from `.gitea/workflows/ci.yml`.
 | `tests/test-build-validation.ps1`, `tests/test-build-validation.sh` | Validate build failures and generated output. |
 | `tests/test-capabilities.ps1` | Guard PowerShell capability detection. |
 | `tests/test-install-guards.ps1`, `tests/test-install-guards.sh` | Validate install and update guard conditions. |
-| `tests/test-client-smoke.py` | Install a package into a temporary home with foreign settings and ask the installed Claude and Codex CLIs which skills, agents, and hooks they discover, without completing a model request. Skips a client whose CLI is unavailable. |
+| `tests/test-client-smoke.py` | Install a package into a temporary home with foreign settings and ask the installed Claude and Codex CLIs which skills, agents, and hooks they discover, without completing a model request. Skips a client whose CLI is unavailable unless `AI_CONFIG_REQUIRE_CLIENTS=1`, which the CI `client-smoke` job sets. |
 | `tests/test-install-options.py` | Validate interactive option handling and generated manifest changes. |
 | `tests/test-managed-extensions.py` | Validate plugin, skill, and CLI ownership handling. |
 | `tests/test-managed-install.ps1`, `tests/test-managed-install.sh` | Validate managed-file synchronization and backups. |
@@ -20,7 +20,7 @@ Each skill defines a focused workflow with the investigation, decision points, a

 The single catalog in `shared/skills/` includes development skills and focused skills for writing, images, content and site structure, positioning, psychology, and conversion. Builds include every retained skill for both clients. Updating a managed installation backs up and removes unchanged setup-owned skills deleted from the catalog; local changes are backed up and retained.

-Claude's generated package additionally has `skills/rules/`: one skill per focused rule file or directory in
+Claude discovers only `skills/<name>/SKILL.md`, so its generated package flattens the categorized catalog to one directory per skill name, together with the skill's `references/`; the build fails on duplicate names or a `name` that differs from its directory. Claude's package additionally has a `rules-*` skill for each focused rule file or directory in
 `shared/rules/`. The rule-to-skill loading conditions live in `shared/global-instructions.md`, so full rule text loads
 only when Claude invokes a matching skill instead of sitting permanently in context. Codex reads the matching rule
 files directly. Both clients embed the general rules in their global instructions.
@@ -94,7 +94,18 @@ foreach ($shell in @('powershell','bash')) {
    New-Item (Join-Path $output "codex-$shell") -ItemType Directory -Force | Out-Null
    New-Item (Join-Path $output "claude-$shell") -ItemType Directory -Force | Out-Null
    Copy-Directory (Join-Path $shared 'skills') (Join-Path $output "codex-$shell/skills")
-    Copy-Directory (Join-Path $shared 'skills') (Join-Path $output "claude-$shell/skills")
+    # Claude discovers only skills/<name>/SKILL.md, so flatten the categorized source tree.
+    $claudeSkills = Join-Path $output "claude-$shell/skills"
+    New-Item $claudeSkills -ItemType Directory -Force | Out-Null
+    Get-ChildItem (Join-Path $shared 'skills') -File | ForEach-Object { Copy-Item $_.FullName (Join-Path $claudeSkills $_.Name) -Force }
+    $claudeSkillNames = @{}
+    foreach ($skillFile in Get-ChildItem (Join-Path $shared 'skills') -File -Filter 'SKILL.md' -Recurse) {
+        $skillName = $skillFile.Directory.Name
+        if (@(Get-Content -LiteralPath $skillFile.FullName -TotalCount 6) -notcontains "name: $skillName") { throw "Skill name must match its directory: $($skillFile.FullName)" }
+        if ($claudeSkillNames.ContainsKey($skillName)) { throw "Duplicate Claude skill name: $skillName" }
+        $claudeSkillNames[$skillName] = $true
+        Copy-Directory $skillFile.DirectoryName (Join-Path $claudeSkills $skillName)
+    }
    Copy-Directory (Join-Path $shared 'rules') (Join-Path $output "codex-$shell/rules")
    Copy-Directory (Join-Path $shared 'hooks') (Join-Path $output "codex-$shell/hooks")
    Copy-Directory (Join-Path $shared 'hooks') (Join-Path $output "claude-$shell/hooks")
@@ -117,12 +128,12 @@ foreach ($shell in @('powershell','bash')) {
                $ruleName = "rules-$($ruleDirectory.Name)-$($ruleParts -join '-')"
                $references = $null
            }
-            if ($ruleSkills.Name -contains $ruleName) { throw "Duplicate generated rule skill name: $ruleName" }
+            if ($ruleSkills.Name -contains $ruleName -or $claudeSkillNames.ContainsKey($ruleName)) { throw "Duplicate generated rule skill name: $ruleName" }
            $ruleSkills += [pscustomobject]@{ Name = $ruleName; Body = $ruleFile.FullName; References = $references }
        }
    }
    foreach ($ruleSkill in $ruleSkills | Sort-Object Name) {
-        $skillDir = Join-Path $output "claude-$shell/skills/rules/$($ruleSkill.Name)"
+        $skillDir = Join-Path $claudeSkills $ruleSkill.Name
        New-Item $skillDir -ItemType Directory -Force | Out-Null
        $ruleContent = Get-Content $ruleSkill.Body -Raw
        $ruleTitle = (Get-Content $ruleSkill.Body | Where-Object { $_ -match '^#+\s+' } | Select-Object -First 1) -replace '^#+\s+', ''
@@ -79,7 +79,19 @@ done
 for shell in powershell bash; do
 mkdir -p "$output/codex-$shell" "$output/claude-$shell"
 copy_directory "$shared/skills" "$output/codex-$shell/skills"
-copy_directory "$shared/skills" "$output/claude-$shell/skills"
+# Claude discovers only skills/<name>/SKILL.md, so flatten the categorized source tree.
+claude_skills="$output/claude-$shell/skills"
+mkdir -p "$claude_skills"
+find "$shared/skills" -maxdepth 1 -type f -exec cp {} "$claude_skills"/ \;
+declare -A claude_skill_names=()
+while IFS= read -r skill_file; do
+  skill_source=$(dirname -- "$skill_file")
+  skill_name=$(basename -- "$skill_source")
+  head -n 6 "$skill_file" | grep -qx "name: $skill_name" || { printf 'Skill name must match its directory: %s\n' "$skill_file" >&2; exit 1; }
+  [ -z "${claude_skill_names[$skill_name]+x}" ] || { printf 'Duplicate Claude skill name: %s\n' "$skill_name" >&2; exit 1; }
+  claude_skill_names[$skill_name]=1
+  copy_directory "$skill_source" "$claude_skills/$skill_name"
+done < <(find "$shared/skills" -type f -name SKILL.md | sort)
 copy_directory "$shared/rules" "$output/codex-$shell/rules"
 copy_directory "$shared/hooks" "$output/codex-$shell/hooks"
 copy_directory "$shared/hooks" "$output/claude-$shell/hooks"
@@ -103,12 +115,12 @@ while IFS= read -r rule_path; do
    *.md) skill_name="rules-${rule_path%.md}"; rule_body="$shared/rules/$rule_path"; references_dir='' ;;
    *) continue ;;
  esac
-  if [[ -n "${rule_skill_names[$skill_name]:-}" ]]; then
+  if [[ -n "${rule_skill_names[$skill_name]:-}" || -n "${claude_skill_names[$skill_name]:-}" ]]; then
    printf 'Duplicate generated rule skill name: %s\n' "$skill_name" >&2
    exit 1
  fi
  rule_skill_names[$skill_name]=1
-  skill_dir="$output/claude-$shell/skills/rules/$skill_name"
+  skill_dir="$claude_skills/$skill_name"
  mkdir -p "$skill_dir"
  rule_title=$(sed -n 's/^#\{1,6\} *//p' "$rule_body" | head -n 1)
  if [ -z "$rule_title" ]; then printf 'Missing rule title in %s\n' "$rule_body" >&2; exit 1; fi
@@ -4,21 +4,67 @@ Each test installs a generated package into a temporary home that already holds
 foreign settings, then asks the real client CLI what it discovered. Claude runs
 with an invalid API key and is stopped at its init event; Codex is queried
 through `codex app-server`. No model request completes.
+
+Set AI_CONFIG_REQUIRE_CLIENTS=1 to fail instead of skip when a client CLI is missing.
 """
 import json
 import os
 from pathlib import Path
+import queue
 import re
 import shutil
 import subprocess
 import sys
 import tempfile
+import threading
 import unittest


 ROOT = Path(__file__).resolve().parent.parent.parent
 SHELL = 'powershell' if os.name == 'nt' else 'bash'
 MARKER_SCRIPT = "import sys; open(sys.argv[1], 'w').write('ok')"
+REQUIRE_CLIENTS = os.environ.get('AI_CONFIG_REQUIRE_CLIENTS') == '1'
+INSTALL_TIMEOUT = 300
+OUTPUT_TIMEOUT = 90
+
+
+def client_cli(test, name):
+    path = shutil.which(name)
+    if path:
+        return path
+    if REQUIRE_CLIENTS:
+        test.fail(f'{name} CLI unavailable but AI_CONFIG_REQUIRE_CLIENTS=1')
+    test.skipTest(f'{name} CLI unavailable')
+
+
+class LineReader:
+    """Read process output lines on a thread so every wait has a deadline."""
+
+    def __init__(self, stream):
+        self.lines = queue.Queue()
+        threading.Thread(target=self._pump, args=(stream,), daemon=True).start()
+
+    def _pump(self, stream):
+        for line in stream:
+            self.lines.put(line)
+        self.lines.put(None)
+
+    def next(self, what):
+        try:
+            line = self.lines.get(timeout=OUTPUT_TIMEOUT)
+        except queue.Empty:
+            raise AssertionError(f'no output for {OUTPUT_TIMEOUT}s while waiting for {what}') from None
+        if line is None:
+            raise AssertionError(f'client exited while waiting for {what}')
+        return line
+
+
+def stop(process):
+    process.kill()
+    for stream in (process.stdin, process.stdout):
+        if stream:
+            stream.close()
+    process.wait(timeout=30)


 def frontmatter_names(directory, pattern):
@@ -56,7 +102,7 @@ def install(client, home):
                  'while IFS="|" read -r source destination; do '
                  'sync_managed_destination "$source" "$destination" smoke "$destination" bash "pwsh -NoProfile -File" false true >/dev/null; done')
        args = ['bash', '-c', script]
-    result = subprocess.run(args, capture_output=True, text=True)
+    result = subprocess.run(args, capture_output=True, text=True, timeout=INSTALL_TIMEOUT)
    if result.returncode:
        raise RuntimeError(f"install failed: {result.stdout}{result.stderr}")

@@ -67,14 +113,14 @@ class ClientSmokeTests(unittest.TestCase):
        self.home = self.base / 'home'
        self.work = self.base / 'work'
        self.work.mkdir(parents=True)
-        subprocess.run(['git', 'init', '-q'], cwd=self.work, check=True)
+        subprocess.run(['git', 'init', '-q'], cwd=self.work, check=True, timeout=60)
        self.marker = self.base / 'foreign-hook.txt'

    def tearDown(self):
        shutil.rmtree(self.base, ignore_errors=True)

-    @unittest.skipUnless(shutil.which('claude'), 'Claude CLI unavailable')
    def test_claude_discovers_package_and_keeps_foreign_settings(self):
+        claude = client_cli(self, 'claude')
        package = ROOT / f'generated/claude-{SHELL}'
        config = self.home / '.claude'
        config.mkdir(parents=True)
@@ -82,23 +128,17 @@ class ClientSmokeTests(unittest.TestCase):
        (config / 'settings.json').write_text(json.dumps({'foreignSetting': 'keep', 'hooks': {'SessionStart': [foreign_hook]}}))
        install('Claude', self.home)

-        process = subprocess.Popen([shutil.which('claude'), '-p', 'smoke', '--output-format', 'stream-json', '--verbose', '--max-turns', '1'],
+        process = subprocess.Popen([claude, '-p', 'smoke', '--output-format', 'stream-json', '--verbose', '--max-turns', '1'],
                                   cwd=self.work, env=clean_env(CLAUDE_CONFIG_DIR=str(config), ANTHROPIC_API_KEY='sk-ant-invalid-smoke'),
                                   stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding='utf-8')
        events = []
        try:
-            for line in process.stdout:
-                events.append(json.loads(line))
-                if events[-1].get('subtype') == 'init':
-                    break
+            reader = LineReader(process.stdout)
+            while not events or events[-1].get('subtype') != 'init':
+                events.append(json.loads(reader.next('the Claude init event')))
        finally:
-            process.kill()
-            for stream in (process.stdin, process.stdout):
-                if stream:
-                    stream.close()
-            process.wait(timeout=30)
-        init = next((event for event in events if event.get('subtype') == 'init'), None)
-        self.assertIsNotNone(init, 'Claude emitted no init event')
+            stop(process)
+        init = events[-1]

        with self.subTest('skills'):
            self.assertEqual(sorted(frontmatter_names(package / 'skills', 'SKILL.md') - set(init['skills'])), [])
@@ -112,8 +152,8 @@ class ClientSmokeTests(unittest.TestCase):
        with self.subTest('foreign settings'):
            self.assertEqual(json.loads((config / 'settings.json').read_text(encoding='utf-8-sig')).get('foreignSetting'), 'keep')

-    @unittest.skipUnless(shutil.which('codex'), 'Codex CLI unavailable')
    def test_codex_discovers_package_and_keeps_foreign_settings(self):
+        codex = client_cli(self, 'codex')
        package = ROOT / f'generated/codex-{SHELL}'
        codex_home = self.home / '.codex'
        codex_home.mkdir(parents=True)
@@ -123,15 +163,16 @@ class ClientSmokeTests(unittest.TestCase):
            f'[[hooks.SessionStart]]\n[[hooks.SessionStart.hooks]]\ntype = "command"\ncommand = {command}\ntimeout = 10\n')
        install('Codex', self.home)

-        process = subprocess.Popen([shutil.which('codex'), 'app-server'], cwd=self.work,
+        process = subprocess.Popen([codex, 'app-server'], cwd=self.work,
                                   env=clean_env(CODEX_HOME=str(codex_home), OPENAI_API_KEY='sk-invalid-smoke'),
                                   stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding='utf-8')
+        reader = LineReader(process.stdout)

        def call(request_id, method, params):
            process.stdin.write(json.dumps({'jsonrpc': '2.0', 'id': request_id, 'method': method, 'params': params}) + '\n')
            process.stdin.flush()
            while True:
-                message = json.loads(process.stdout.readline())
+                message = json.loads(reader.next(method))
                if message.get('id') == request_id:
                    self.assertNotIn('error', message, method)
                    return message['result']
@@ -146,11 +187,7 @@ class ClientSmokeTests(unittest.TestCase):
            hooks = call(4, 'hooks/list', {'cwds': [str(self.work)]})['data'][0]['hooks']
            config = call(5, 'config/read', {})['config']
        finally:
-            process.kill()
-            for stream in (process.stdin, process.stdout):
-                if stream:
-                    stream.close()
-            process.wait(timeout=30)
+            stop(process)

        isolated = {skill['name'] for skill in skills if Path(skill['path']).resolve().is_relative_to(skills_root.resolve())}
        self.assertEqual(sorted(frontmatter_names(package / 'skills', 'SKILL.md') - isolated), [], 'skills not discovered')
@@ -48,7 +48,9 @@ foreach ($shell in @('powershell','bash')) {
        if ($client -eq 'claude' -and (Get-Content (Join-Path $package 'agents/reviewer.md') -Raw) -notmatch "(?m)^tools: Read,Grep,Glob,$expectedReviewerShellTool\r?`$") { throw "Reviewer capability profile is missing in $package" }
        $expectedSkillCount = if ($client -eq 'claude') { $sourceSkillCount + $ruleSkillCount } else { $sourceSkillCount }
        if (@(Get-ChildItem "$package/skills" -Filter SKILL.md -Recurse).Count -ne $expectedSkillCount) { throw "Missing skills in $package" }
-        if ((Test-Path "$package/skills/debugging/SKILL.md") -or -not (Test-Path "$package/skills/reviews/security-review/SKILL.md") -or -not (Test-Path "$package/skills/copywriting/SKILL.md") -or -not (Test-Path "$package/skills/marketing-psychology/SKILL.md") -or -not (Test-Path "$package/skills/image/SKILL.md") -or (Test-Path "$package/skills/marketing-plan/SKILL.md") -or (Test-Path "$package/skills/social/SKILL.md")) { throw "Incorrect skill catalog in $package" }
+        $securityReview = if ($client -eq 'claude') { 'skills/security-review/SKILL.md' } else { 'skills/reviews/security-review/SKILL.md' }
+        if ($client -eq 'claude' -and @(Get-ChildItem "$package/skills" -Filter SKILL.md -Recurse | Where-Object { $_.Directory.Parent.FullName -ne (Resolve-Path "$package/skills").Path }).Count) { throw "Nested Claude skills in $package" }
+        if ((Test-Path "$package/skills/debugging/SKILL.md") -or -not (Test-Path "$package/$securityReview") -or -not (Test-Path "$package/skills/copywriting/SKILL.md") -or -not (Test-Path "$package/skills/marketing-psychology/SKILL.md") -or -not (Test-Path "$package/skills/image/SKILL.md") -or (Test-Path "$package/skills/marketing-plan/SKILL.md") -or (Test-Path "$package/skills/social/SKILL.md")) { throw "Incorrect skill catalog in $package" }
        $expected = if ($shell -eq 'powershell') { '__POWERSHELL_COMMAND__ .*flashbang.ps1' } else { 'bash .*flashbang.sh' }
        if ($content -notmatch $expected -or $content -match '__HOOK_|__POWERSHELL_HOOK_') { throw "Incorrect shell command in $package" }
        if ($shell -eq 'powershell' -and $content -match 'WindowStyle\s+Hidden') { throw "PowerShell hook hides the terminal in $package" }
@@ -62,6 +64,8 @@ foreach ($shell in @('powershell','bash')) {
            throw "Claude finish hook is incorrect in $package"
        } elseif ($content -notmatch '"defaultMode"\s*:\s*"auto"') {
            throw "Claude auto permission mode is missing in $package"
+        } elseif ($settings.env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS -ne '5' -or $settings.env.CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH -ne '1') {
+            throw "Claude subagent limits are missing in $package"
        } elseif ($sandboxSupported -and ($settings.sandbox.enabled -ne $true -or $settings.sandbox.allowUnsandboxedCommands -ne $false -or $settings.sandbox.failIfUnavailable -ne $true -or (@($settings.sandbox.network.allowedDomains) -join ',') -ne 'mcp.context7.com' -or @($settings.sandbox.PSObject.Properties).Count -ne 4)) {
            throw "Claude strict sandbox is missing in $package"
        } elseif (-not $sandboxSupported -and ($settings.sandbox.enabled -ne $false -or @($settings.sandbox.PSObject.Properties).Count -ne 1)) {
@@ -74,7 +78,7 @@ foreach ($shell in @('powershell','bash')) {
        if ($docContent -notmatch [regex]::Escape('rules/security/index.md')) { throw "$package is missing common rule loading instructions." }
        if ($client -eq 'claude') {
            foreach ($ruleSource in $ruleSources) {
-                $skillPath = Join-Path $package "skills/rules/$($ruleSource.Skill)/SKILL.md"
+                $skillPath = Join-Path $package "skills/$($ruleSource.Skill)/SKILL.md"
                if (-not (Test-Path -LiteralPath $skillPath)) { throw "$package is missing generated skill $($ruleSource.Skill)." }
            }
        }
@@ -85,7 +89,7 @@ foreach ($shell in @('powershell','bash')) {
        if ($client -eq 'codex' -and $docContent -match 'Always load and apply `rules/general\.md`') { throw "$package must not still instruct loading general.md by path" }
        if ($client -eq 'claude' -and (Test-Path (Join-Path $package 'rules/general.md'))) { throw 'Claude must not automatically load a second copy of general rules.' }
        foreach ($splitRule in @('angular','wpf','ui-ux')) {
-            $referencesDir = if ($client -eq 'codex') { Join-Path $package "rules/$splitRule/references" } else { Join-Path $package "skills/rules/rules-$splitRule/references" }
+            $referencesDir = if ($client -eq 'codex') { Join-Path $package "rules/$splitRule/references" } else { Join-Path $package "skills/rules-$splitRule/references" }
            if (-not (Test-Path $referencesDir) -or (Get-ChildItem $referencesDir -Filter '*.md').Count -eq 0) { throw "$package is missing reference files for $splitRule" }
        }
    }
@@ -56,7 +56,12 @@ for shell in powershell bash; do
    [ "$client" != claude ] || expected_skill_count=$((source_skill_count + rule_skill_count))
    test "$(find "$package/skills" -name SKILL.md | wc -l)" -eq "$expected_skill_count"
    test ! -e "$package/skills/debugging/SKILL.md"
-    test -f "$package/skills/reviews/security-review/SKILL.md"
+    if [ "$client" = claude ]; then
+      test -f "$package/skills/security-review/SKILL.md"
+      test "$(find "$package/skills" -mindepth 3 -name SKILL.md | wc -l)" -eq 0
+    else
+      test -f "$package/skills/reviews/security-review/SKILL.md"
+    fi
    test -f "$package/skills/copywriting/SKILL.md"
    test -f "$package/skills/marketing-psychology/SKILL.md"
    test -f "$package/skills/image/SKILL.md"
@@ -80,6 +85,8 @@ for shell in powershell bash; do
      ! grep -q 'flashbang-if-input' "$package/$file"
      ! grep -q '"async"[[:space:]]*:[[:space:]]*true' "$package/$file"
      grep -q '"defaultMode"[[:space:]]*:[[:space:]]*"auto"' "$package/$file"
+      grep -q '"CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS"[[:space:]]*:[[:space:]]*"5"' "$package/$file"
+      grep -q '"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH"[[:space:]]*:[[:space:]]*"1"' "$package/$file"
      python3 -c 'import json,sys; settings=json.load(open(sys.argv[1], encoding="utf-8-sig")); expected={"enabled": True, "allowUnsandboxedCommands": False, "failIfUnavailable": True, "network": {"allowedDomains": ["mcp.context7.com"]}} if sys.argv[2] == "true" else {"enabled": False}; assert settings["sandbox"] == expected' "$package/$file" "$sandbox_supported"
      statusline_extension='sh'
      [ "$shell" != powershell ] || statusline_extension=ps1
@@ -94,7 +101,7 @@ for shell in powershell bash; do
    if [ "$client" = claude ]; then
      for rule_path in "${rule_paths[@]}"; do
        skill_name=$(rule_skill_name "$rule_path")
-        test -f "$package/skills/rules/$skill_name/SKILL.md"
+        test -f "$package/skills/$skill_name/SKILL.md"
      done
    fi
    printf '%s' "$doc_content" | grep -Fq 'Use the `mcporter` CLI for MCP servers this configuration registers there'
@@ -114,7 +121,7 @@ for shell in powershell bash; do
      if [ "$client" = codex ]; then
        references_dir="$package/rules/$split_rule/references"
      else
-        references_dir="$package/skills/rules/rules-$split_rule/references"
+        references_dir="$package/skills/rules-$split_rule/references"
      fi
      if [ ! -d "$references_dir" ] || [ -z "$(find "$references_dir" -maxdepth 1 -name '*.md' -print -quit)" ]; then
        printf '%s is missing reference files for %s\n' "$package" "$split_rule" >&2
@@ -4,13 +4,7 @@
 * Keep components small; move substantial business logic to a focused service or domain layer.
 * Keep dependencies explicit and follow the feature architecture. Avoid god components, god services, unnecessary wrappers, and abstractions without a concrete need.
 * Use `ChangeDetectionStrategy.OnPush` unless there is a concrete reason not to.
-* Prefer signal-based state for local component state.
-* Prefer `computed` for derived state.
-* Prefer `effect` only for actual side effects.
-* Do not use `effect` as a replacement for normal data flow.
-* Keep component state minimal.
-* Avoid duplicating derived state.
-* Prefer immutable state updates.
+* Keep component state minimal and prefer immutable state updates.
 * Avoid direct mutation of shared state.
 * Keep inputs and outputs strongly typed.
 * Prefer signal-based inputs and outputs when consistent with the project.
@@ -24,13 +18,9 @@
 ## Signals and State

 * Prefer signals for local and synchronous reactive state.
-* Prefer `computed` for derived values.
-* Keep signals private when external mutation is not intended.
-* Expose readonly state where practical.
-* Avoid storing values that can be derived from existing state.
+* Derive values with `computed` instead of storing or duplicating them; keep `computed` free of side effects.
+* Keep signals private when external mutation is not intended, and expose readonly state where practical.
 * Avoid circular signal dependencies.
-* Avoid side effects inside `computed`.
-* Keep effects small and deterministic.
-* Clean up resources created by effects.
+* Use `effect` only for actual side effects, not as a replacement for normal data flow. Keep effects small and deterministic, and clean up resources they create.
 * Do not use global state unless multiple unrelated parts of the application genuinely need it.
 * Do not introduce a state-management library without a clear requirement.
@@ -5,9 +5,7 @@
 * Prefer declarative observable pipelines.
 * Avoid nested `subscribe`.
 * Avoid manual subscriptions where `async`, signals or framework helpers are sufficient.
-* Prefer `takeUntilDestroyed` or equivalent Angular lifecycle integration for manual subscriptions.
-* Always consider subscription lifetime.
-* Avoid memory leaks from unmanaged subscriptions.
+* Bind every manual subscription's lifetime with `takeUntilDestroyed` or equivalent Angular lifecycle integration to avoid leaks.
 * Use the correct flattening operator for the required semantics.
 * Do not use `switchMap`, `mergeMap`, `concatMap` or `exhaustMap` interchangeably.
 * Avoid unnecessary `Subject` usage.
@@ -39,12 +39,6 @@ Gather this context (ask if not provided):

 ---

-## Treat Content Like a Product
-
-Every piece is its own launch. Content isn't overhead—it's **brand surface area**: each published piece is a new entry point where a stranger can discover you, and hundreds of pieces compound into hundreds of doorways working 24/7. Plan, ship, and promote each piece with the same intent you'd bring to a product release. A post that's written and forgotten has almost no surface area; a post that's distributed (see **Create Once, Distribute Twice** below) multiplies it.
-
-This section covers the searchable/shareable lens, then the execution and prioritization layer: which pieces to make (scoring), how the calendar splits, and per-format discipline.
-
 ## Searchable vs Shareable

 Every piece of content must be searchable, shareable, or both. Prioritize in that order—search traffic is the foundation.
@@ -53,337 +47,7 @@ Every piece of content must be searchable, shareable, or both. Prioritize in tha

 **Shareable content** creates demand. Spreads ideas and gets people talking.

-### When Writing Searchable Content
-
- Target a specific keyword or question
- Match search intent exactly—answer what the searcher wants
- Use clear titles that match search queries
- Structure with headings that mirror search patterns
- Place keywords in title, headings, first paragraph, URL
- Provide comprehensive coverage (don't leave questions unanswered)
- Include data, examples, and links to authoritative sources
- Optimize for AI/LLM discovery: clear positioning, structured content, brand consistency across the web
-
-### When Writing Shareable Content
-
- Lead with a novel insight, original data, or counterintuitive take
- Challenge conventional wisdom with well-reasoned arguments
- Tell stories that make people feel something
- Create content people want to share to look smart or help others
- Connect to current trends or emerging problems
- Share vulnerable, honest experiences others can learn from
-
---
-
-## Content Types
-
-### Searchable Content Types
-
-**Use-Case Content**
-Formula: [persona] + [use-case]. Targets long-tail keywords.
- "Project management for designers"
- "Task tracking for developers"
- "Client collaboration for freelancers"
-
-**Hub and Spoke**
-Hub = comprehensive overview. Spokes = related subtopics.
-```
-/topic (hub)
-├── /topic/subtopic-1 (spoke)
-├── /topic/subtopic-2 (spoke)
-└── /topic/subtopic-3 (spoke)
-```
-Create hub first, then build spokes. Interlink strategically.
-
-**Note:** Most content works fine under `/blog`. Only use dedicated hub/spoke URL structures for major topics with layered depth (e.g., Atlassian's `/agile` guide). For typical blog posts, `/blog/post-title` is sufficient.
-
-**Template Libraries**
-High-intent keywords + product adoption.
- Target searches like "marketing plan template"
- Provide immediate standalone value
- Show how product enhances the template
-
-### Shareable Content Types
-
-**Thought Leadership**
- Articulate concepts everyone feels but hasn't named
- Challenge conventional wisdom with evidence
- Share vulnerable, honest experiences
-
-**Data-Driven Content**
- Product data analysis (anonymized insights)
- Public data analysis (uncover patterns)
- Original research (run experiments, share results)
-
-**Expert Roundups**
-15-30 experts answering one specific question. Built-in distribution.
-
-**Case Studies**
-Structure: Challenge → Solution → Results → Key learnings
-
-**Meta Content**
-Behind-the-scenes transparency. "How We Got Our First $5k MRR," "Why We Chose Debt Over VC."
-
-### Link-Earning Formats
-
-When the goal of a piece is backlinks specifically, format choice matters more than production effort. Foundation Inc.'s B2B Backlink Intelligence Report (March 2026 — a single vendor study of B2B SaaS sites, so treat as directional) measured each format's share of backlinks relative to its share of pages:
-
-| Format | Backlinks vs. page share |
-|---|---|
-| Statistics / data roundups | **4.25x** |
-| Glossary / definition pages | 1.47x |
-| Interactive tools / calculators | 1.38x |
-| How-to / tutorials | 1.36x |
-| Original research / reports | 0.80x |
-| Ultimate guides | 0.77x |
-| Thought leadership | 0.74x |
-| Templates / frameworks | 0.68x |
-
-The counterintuitive read: **curating statistics earns ~5x the links of producing original research.** Writers link to whatever makes citation easiest — a maintained stat-roundup page is citation infrastructure, while original research often gets cited *via* the roundups that aggregate it. Implications: (1) publish a stats page for your category and keep it fresh — it's cheap and compounds, and citable one-line stats are also what LLMs lift, making it an AI-visibility play; (2) when you do run original research, pair it with your own stat-roundup page that presents the findings as citable one-liners, so you capture the links your data generates. The formats at the bottom aren't dead — guides, templates, and thought leadership earn their keep on rankings, conversions, and brand. Judge each piece by the job it's for, and don't expect links from formats that don't earn them.
-
-
---
-
-## Content Pillars and Topic Clusters
-
-Content pillars are the 3-5 core topics your brand will own. Each pillar spawns a cluster of related content.
-
-Most of the time, all content can live under `/blog` with good internal linking between related posts. Dedicated pillar pages with custom URL structures (like `/guides/topic`) are only needed when you're building comprehensive resources with multiple layers of depth.
-
-### How to Identify Pillars
-
-1. **Product-led**: What problems does your product solve?
-2. **Audience-led**: What does your ICP need to learn?
-3. **Search-led**: What topics have volume in your space?
-4. **Competitor-led**: What are competitors ranking for?
-
-### Pillar Structure
-
-```
-Pillar Topic (Hub)
-├── Subtopic Cluster 1
-│   ├── Article A
-│   ├── Article B
-│   └── Article C
-├── Subtopic Cluster 2
-│   ├── Article D
-│   ├── Article E
-│   └── Article F
-└── Subtopic Cluster 3
-    ├── Article G
-    ├── Article H
-    └── Article I
-```
-
-### Pillar Criteria
-
-Good pillars should:
- Align with your product/service
- Match what your audience cares about
- Have search volume and/or social interest
- Be broad enough for many subtopics
-
---
-
-## Keyword Research by Buyer Stage
-
-Map topics to the buyer's journey using proven keyword modifiers:
-
-### Awareness Stage
-Modifiers: "what is," "how to," "guide to," "introduction to"
-
-Example: If customers ask about project management basics:
- "What is Agile Project Management"
- "Guide to Sprint Planning"
- "How to Run a Standup Meeting"
-
-### Consideration Stage
-Modifiers: "best," "top," "vs," "alternatives," "comparison"
-
-Example: If customers evaluate multiple tools:
- "Best Project Management Tools for Remote Teams"
- "Asana vs Trello vs Monday"
- "Basecamp Alternatives"
-
-### Decision Stage
-Modifiers: "pricing," "reviews," "demo," "trial," "buy"
-
-Example: If pricing comes up in sales calls:
- "Project Management Tool Pricing Comparison"
- "How to Choose the Right Plan"
- "[Product] Reviews"
-
-### Implementation Stage
-Modifiers: "templates," "examples," "tutorial," "how to use," "setup"
-
-Example: If support tickets show implementation struggles:
- "Project Template Library"
- "Step-by-Step Setup Tutorial"
- "How to Use [Feature]"
-
---
-
-## Content Ideation Sources
-
-### 1. Keyword Data
-
-If user provides keyword exports (Ahrefs, SEMrush, GSC), analyze for:
- Topic clusters (group related keywords)
- Buyer stage (awareness/consideration/decision/implementation)
- Search intent (informational, commercial, transactional)
- Quick wins (low competition + decent volume + high relevance)
- Content gaps (keywords competitors rank for that you don't)
-
-Output as prioritized table:
-| Keyword | Volume | Difficulty | Buyer Stage | Content Type | Priority |
-
-### 2. Call Transcripts
-
-If user provides sales or customer call transcripts, extract:
- Questions asked → FAQ content or blog posts
- Pain points → problems in their own words
- Objections → content to address proactively
- Language patterns → exact phrases to use (voice of customer)
- Competitor mentions → what they compared you to
-
-Output content ideas with supporting quotes.
-
-### 3. Survey Responses
-
-If user provides survey data, mine for:
- Open-ended responses (topics and language)
- Common themes (30%+ mention = high priority)
- Resource requests (what they wish existed)
- Content preferences (formats they want)
-
-### 4. Forum Research
-
-Use web search to find content ideas:
-
-**Reddit:** `site:reddit.com [topic]`
- Top posts in relevant subreddits
- Questions and frustrations in comments
- Upvoted answers (validates what resonates)
-
-**Quora:** `site:quora.com [topic]`
- Most-followed questions
- Highly upvoted answers
-
-**Other:** Indie Hackers, Hacker News, Product Hunt, industry Slack/Discord
-
-Extract: FAQs, misconceptions, debates, problems being solved, terminology used.
-
-### 5. Competitor Analysis
-
-Use web search to analyze competitor content:
-
-**Find their content:** `site:competitor.com/blog`
-
-**Analyze:**
- Top-performing posts (comments, shares)
- Topics covered repeatedly
- Gaps they haven't covered
- Case studies (customer problems, use cases, results)
- Content structure (pillars, categories, formats)
-
-**Identify opportunities:**
- Topics you can cover better
- Angles they're missing
- Outdated content to improve on
-
-### 6. Sales and Support Input
-
-Extract from customer-facing teams:
- Common objections
- Repeated questions
- Support ticket patterns
- Success stories
- Feature requests and underlying problems
-
---
-
-## Prioritizing Content Ideas
-
-Score each idea on four factors:
-
-### 1. Customer Impact (40%)
- How frequently did this topic come up in research?
- What percentage of customers face this challenge?
- How emotionally charged was this pain point?
- What's the potential LTV of customers with this need?
-
-### 2. Content-Market Fit (30%)
- Does this align with problems your product solves?
- Can you offer unique insights from customer research?
- Do you have customer stories to support this?
- Will this naturally lead to product interest?
-
-### 3. Search Potential (20%)
- What's the monthly search volume?
- How competitive is this topic?
- Are there related long-tail opportunities?
- Is search interest growing or declining?
-
-### 4. Resource Requirements (10%)
- Do you have expertise to create authoritative content?
- What additional research is needed?
- What assets (graphics, data, examples) will you need?
-
-### Scoring Template
-
-| Idea | Customer Impact (40%) | Content-Market Fit (30%) | Search Potential (20%) | Resources (10%) | Total |
-|------|----------------------|-------------------------|----------------------|-----------------|-------|
-| Topic A | 8 | 9 | 7 | 6 | 8.0 |
-| Topic B | 6 | 7 | 9 | 8 | 7.1 |
-
-Score 1-10 per factor, multiply by the weight, sum for the total. Rank the list; make the top-scoring pieces first.
-
---
-
-## Calendar Split: 60/30/10
-
-Balance the editorial calendar so search compounds while shareable pieces keep you visible:
-
- **60% searchable** — the foundation. Demand you can capture predictably (use-case content, hub/spoke, how-tos).
- **30% shareable** — thought leadership, original data, opinion. Creates demand and earns links/mentions.
- **10% experimental** — new formats, channels, or bets. Cheap insurance against a stale mix.
-
-This is a starting ratio, not a rule. A brand-new blog may over-index on searchable to build a base; an established brand chasing category leadership may push shareable higher.
-
---
-
-## Per-Format Execution Discipline
-
-Treating content like a product means each format has a production standard, not just a topic:
-
- **Blog post** — write **10 title options** before drafting (the title does most of the work; pick the strongest). Plan **~5 editing passes** (structure, clarity, evidence, line edit, headline/SEO). For the writing itself, see **copywriting**.
- **Long-form guide** — the flagship of a pillar. Comprehensive enough to be *the* resource; structured with a table of contents and internal links to spokes. Build the hub before the spokes.
- **Video** — script the hook first; front-load the payoff.
- **Podcast** — one interview yields a transcript, quote graphics, short clips, and a written recap. Design the episode knowing it will be atomized.
- **Email** — one idea per send; the subject line is the title—write several and pick.
-
---
-
-## Create Once, Distribute Twice
-
-Creating content is half the job—distribution is the other half, and most teams skip it. The philosophy: **one exceptional piece, reformatted and repurposed across every channel, not a fresh piece per platform.** Pouring effort into a single flagship and then distributing it everywhere beats spreading thin effort across many mediocre platform-native posts.
-
-Build **distribution hooks into the piece at creation time**, not after: write subheads that stand alone as social posts, structure sections to be lifted out modularly, and pull quotes/stats you already know you'll graphic-ify. A well-designed guide is a distribution kit in disguise.
-
-**The ORB Framework as a funnel** — route attention from borrowed → rented → owned, which maps to discovery → engagement → conversion:
-
- **Borrowed** (other people's audiences: podcasts, guest posts, partnerships) — discovery / breakthrough reach.
- **Rented** (social platforms, ad networks) — engagement, but you don't own the audience or the algorithm.
- **Owned** (email list, blog, community) — conversion and the only durable asset. Everything upstream should funnel here.
-
-This skill covers the distribution side of content strategy.
-
-**Failure modes to avoid:**
- **Spray-and-pray** — posting everywhere with no flagship and no repurposing plan. Effort scatters, nothing compounds.
- **Platform dependency** — building on rented land. Facebook organic reach fell from ~20% to under 2%; any rented channel can throttle you overnight.
- **The ownership paradox** — teams spend ~90% of effort on channels they don't control (rented/borrowed) and neglect the owned assets that actually convert and can't be taken away.
-
-For the full distribution spine—the Content Distribution Flywheel, platform half-lives, and the atomization checklist—see the reference below.
+Prioritize roughly 60% searchable, 30% shareable, and 10% experimental content; adjust for the blog's maturity.

 ---

@@ -421,6 +85,9 @@ Visual or structured representation of how content interconnects.

 ## References

+- **[Content Types and Formats](references/content-types.md)**: read when choosing formats or writing a piece; treating content like a product, searchable and shareable writing checklists, searchable/shareable content types, link-earning formats, per-format execution discipline
+- **[Pillars and Keyword Research](references/pillars-and-keywords.md)**: read when defining pillars or mapping topics to buyer stages; pillar identification, structure, and criteria, keyword modifiers per stage
+- **[Ideation and Prioritization](references/ideation-and-prioritization.md)**: read when generating, scoring, or scheduling ideas; ideation sources (keywords, calls, surveys, forums, competitors, sales), the weighted scoring template, the 60/30/10 calendar split
 - **[Content Distribution Spine](references/content-distribution.md)**: Create Once Distribute Twice, ORB as a funnel, the ownership paradox, platform half-lives, the Content Distribution Flywheel, and the per-flagship atomization checklist
 - **[Headless CMS Guide](references/headless-cms.md)**: CMS selection, content modeling for marketing, editorial workflows, platform comparison (Sanity, Contentful, Strapi)

@@ -81,3 +81,26 @@ For each major piece, produce:
 - **social** — atomization/repurposing workflows and platform-native execution
 - **emails** — the owned channel that converts distributed attention
 - **ai-seo** — making owned content citable by LLMs (another distribution surface)
+
+---
+
+## Skill Overview: Create Once, Distribute Twice
+
+Creating content is half the job—distribution is the other half, and most teams skip it. The philosophy: **one exceptional piece, reformatted and repurposed across every channel, not a fresh piece per platform.** Pouring effort into a single flagship and then distributing it everywhere beats spreading thin effort across many mediocre platform-native posts.
+
+Build **distribution hooks into the piece at creation time**, not after: write subheads that stand alone as social posts, structure sections to be lifted out modularly, and pull quotes/stats you already know you'll graphic-ify. A well-designed guide is a distribution kit in disguise.
+
+**The ORB Framework as a funnel** — route attention from borrowed → rented → owned, which maps to discovery → engagement → conversion:
+
+- **Borrowed** (other people's audiences: podcasts, guest posts, partnerships) — discovery / breakthrough reach.
+- **Rented** (social platforms, ad networks) — engagement, but you don't own the audience or the algorithm.
+- **Owned** (email list, blog, community) — conversion and the only durable asset. Everything upstream should funnel here.
+
+This skill covers the distribution side of content strategy.
+
+**Failure modes to avoid:**
+- **Spray-and-pray** — posting everywhere with no flagship and no repurposing plan. Effort scatters, nothing compounds.
+- **Platform dependency** — building on rented land. Facebook organic reach fell from ~20% to under 2%; any rented channel can throttle you overnight.
+- **The ownership paradox** — teams spend ~90% of effort on channels they don't control (rented/borrowed) and neglect the owned assets that actually convert and can't be taken away.
+
+For the full distribution spine—the Content Distribution Flywheel, platform half-lives, and the atomization checklist—see the sections above in this file.
@@ -0,0 +1,103 @@
+# Content Types and Formats
+
+## Treat Content Like a Product
+
+Every piece is its own launch. Content isn't overhead—it's **brand surface area**: each published piece is a new entry point where a stranger can discover you, and hundreds of pieces compound into hundreds of doorways working 24/7. Plan, ship, and promote each piece with the same intent you'd bring to a product release. A post that's written and forgotten has almost no surface area; a post that's distributed (see **Create Once, Distribute Twice** in [content-distribution.md](content-distribution.md)) multiplies it.
+
+This reference covers the searchable/shareable lens and per-format discipline. Scoring and the calendar split are in [ideation-and-prioritization.md](ideation-and-prioritization.md).
+
+## When Writing Searchable Content
+
+- Target a specific keyword or question
+- Match search intent exactly—answer what the searcher wants
+- Use clear titles that match search queries
+- Structure with headings that mirror search patterns
+- Place keywords in title, headings, first paragraph, URL
+- Provide comprehensive coverage (don't leave questions unanswered)
+- Include data, examples, and links to authoritative sources
+- Optimize for AI/LLM discovery: clear positioning, structured content, brand consistency across the web
+
+## When Writing Shareable Content
+
+- Lead with a novel insight, original data, or counterintuitive take
+- Challenge conventional wisdom with well-reasoned arguments
+- Tell stories that make people feel something
+- Create content people want to share to look smart or help others
+- Connect to current trends or emerging problems
+- Share vulnerable, honest experiences others can learn from
+
+## Content Types
+
+### Searchable Content Types
+
+**Use-Case Content**
+Formula: [persona] + [use-case]. Targets long-tail keywords.
+- "Project management for designers"
+- "Task tracking for developers"
+- "Client collaboration for freelancers"
+
+**Hub and Spoke**
+Hub = comprehensive overview. Spokes = related subtopics.
+```
+/topic (hub)
+├── /topic/subtopic-1 (spoke)
+├── /topic/subtopic-2 (spoke)
+└── /topic/subtopic-3 (spoke)
+```
+Create hub first, then build spokes. Interlink strategically.
+
+**Note:** Most content works fine under `/blog`. Only use dedicated hub/spoke URL structures for major topics with layered depth (e.g., Atlassian's `/agile` guide). For typical blog posts, `/blog/post-title` is sufficient.
+
+**Template Libraries**
+High-intent keywords + product adoption.
+- Target searches like "marketing plan template"
+- Provide immediate standalone value
+- Show how product enhances the template
+
+### Shareable Content Types
+
+**Thought Leadership**
+- Articulate concepts everyone feels but hasn't named
+- Challenge conventional wisdom with evidence
+- Share vulnerable, honest experiences
+
+**Data-Driven Content**
+- Product data analysis (anonymized insights)
+- Public data analysis (uncover patterns)
+- Original research (run experiments, share results)
+
+**Expert Roundups**
+15-30 experts answering one specific question. Built-in distribution.
+
+**Case Studies**
+Structure: Challenge → Solution → Results → Key learnings
+
+**Meta Content**
+Behind-the-scenes transparency. "How We Got Our First $5k MRR," "Why We Chose Debt Over VC."
+
+### Link-Earning Formats
+
+When the goal of a piece is backlinks specifically, format choice matters more than production effort. Foundation Inc.'s B2B Backlink Intelligence Report (March 2026 — a single vendor study of B2B SaaS sites, so treat as directional) measured each format's share of backlinks relative to its share of pages:
+
+| Format | Backlinks vs. page share |
+|---|---|
+| Statistics / data roundups | **4.25x** |
+| Glossary / definition pages | 1.47x |
+| Interactive tools / calculators | 1.38x |
+| How-to / tutorials | 1.36x |
+| Original research / reports | 0.80x |
+| Ultimate guides | 0.77x |
+| Thought leadership | 0.74x |
+| Templates / frameworks | 0.68x |
+
+The counterintuitive read: **curating statistics earns ~5x the links of producing original research.** Writers link to whatever makes citation easiest — a maintained stat-roundup page is citation infrastructure, while original research often gets cited *via* the roundups that aggregate it. Implications: (1) publish a stats page for your category and keep it fresh — it's cheap and compounds, and citable one-line stats are also what LLMs lift, making it an AI-visibility play; (2) when you do run original research, pair it with your own stat-roundup page that presents the findings as citable one-liners, so you capture the links your data generates. The formats at the bottom aren't dead — guides, templates, and thought leadership earn their keep on rankings, conversions, and brand. Judge each piece by the job it's for, and don't expect links from formats that don't earn them.
+
+## Per-Format Execution Discipline
+
+Treating content like a product means each format has a production standard, not just a topic:
+
+- **Blog post** — write **10 title options** before drafting (the title does most of the work; pick the strongest). Plan **~5 editing passes** (structure, clarity, evidence, line edit, headline/SEO). For the writing itself, see **copywriting**.
+- **Long-form guide** — the flagship of a pillar. Comprehensive enough to be *the* resource; structured with a table of contents and internal links to spokes. Build the hub before the spokes.
+- **Video** — script the hook first; front-load the payoff.
+- **Podcast** — one interview yields a transcript, quote graphics, short clips, and a written recap. Design the episode knowing it will be atomized.
+- **Email** — one idea per send; the subject line is the title—write several and pick.
@@ -0,0 +1,124 @@
+# Content Ideation and Prioritization
+
+## Content Ideation Sources
+
+### 1. Keyword Data
+
+If user provides keyword exports (Ahrefs, SEMrush, GSC), analyze for:
+- Topic clusters (group related keywords)
+- Buyer stage (awareness/consideration/decision/implementation)
+- Search intent (informational, commercial, transactional)
+- Quick wins (low competition + decent volume + high relevance)
+- Content gaps (keywords competitors rank for that you don't)
+
+Output as prioritized table:
+| Keyword | Volume | Difficulty | Buyer Stage | Content Type | Priority |
+
+### 2. Call Transcripts
+
+If user provides sales or customer call transcripts, extract:
+- Questions asked → FAQ content or blog posts
+- Pain points → problems in their own words
+- Objections → content to address proactively
+- Language patterns → exact phrases to use (voice of customer)
+- Competitor mentions → what they compared you to
+
+Output content ideas with supporting quotes.
+
+### 3. Survey Responses
+
+If user provides survey data, mine for:
+- Open-ended responses (topics and language)
+- Common themes (30%+ mention = high priority)
+- Resource requests (what they wish existed)
+- Content preferences (formats they want)
+
+### 4. Forum Research
+
+Use web search to find content ideas:
+
+**Reddit:** `site:reddit.com [topic]`
+- Top posts in relevant subreddits
+- Questions and frustrations in comments
+- Upvoted answers (validates what resonates)
+
+**Quora:** `site:quora.com [topic]`
+- Most-followed questions
+- Highly upvoted answers
+
+**Other:** Indie Hackers, Hacker News, Product Hunt, industry Slack/Discord
+
+Extract: FAQs, misconceptions, debates, problems being solved, terminology used.
+
+### 5. Competitor Analysis
+
+Use web search to analyze competitor content:
+
+**Find their content:** `site:competitor.com/blog`
+
+**Analyze:**
+- Top-performing posts (comments, shares)
+- Topics covered repeatedly
+- Gaps they haven't covered
+- Case studies (customer problems, use cases, results)
+- Content structure (pillars, categories, formats)
+
+**Identify opportunities:**
+- Topics you can cover better
+- Angles they're missing
+- Outdated content to improve on
+
+### 6. Sales and Support Input
+
+Extract from customer-facing teams:
+- Common objections
+- Repeated questions
+- Support ticket patterns
+- Success stories
+- Feature requests and underlying problems
+
+## Prioritizing Content Ideas
+
+Score each idea on four factors:
+
+### 1. Customer Impact (40%)
+- How frequently did this topic come up in research?
+- What percentage of customers face this challenge?
+- How emotionally charged was this pain point?
+- What's the potential LTV of customers with this need?
+
+### 2. Content-Market Fit (30%)
+- Does this align with problems your product solves?
+- Can you offer unique insights from customer research?
+- Do you have customer stories to support this?
+- Will this naturally lead to product interest?
+
+### 3. Search Potential (20%)
+- What's the monthly search volume?
+- How competitive is this topic?
+- Are there related long-tail opportunities?
+- Is search interest growing or declining?
+
+### 4. Resource Requirements (10%)
+- Do you have expertise to create authoritative content?
+- What additional research is needed?
+- What assets (graphics, data, examples) will you need?
+
+### Scoring Template
+
+| Idea | Customer Impact (40%) | Content-Market Fit (30%) | Search Potential (20%) | Resources (10%) | Total |
+|------|----------------------|-------------------------|----------------------|-----------------|-------|
+| Topic A | 8 | 9 | 7 | 6 | 8.0 |
+| Topic B | 6 | 7 | 9 | 8 | 7.1 |
+
+Score 1-10 per factor, multiply by the weight, sum for the total. Rank the list; make the top-scoring pieces first.
+
+## Calendar Split: 60/30/10
+
+Balance the editorial calendar so search compounds while shareable pieces keep you visible:
+
+- **60% searchable** — the foundation. Demand you can capture predictably (use-case content, hub/spoke, how-tos).
+- **30% shareable** — thought leadership, original data, opinion. Creates demand and earns links/mentions.
+- **10% experimental** — new formats, channels, or bets. Cheap insurance against a stale mix.
+
+This is a starting ratio, not a rule. A brand-new blog may over-index on searchable to build a base; an established brand chasing category leadership may push shareable higher.
@@ -0,0 +1,78 @@
+# Content Pillars and Keyword Research
+
+## Content Pillars and Topic Clusters
+
+Content pillars are the 3-5 core topics your brand will own. Each pillar spawns a cluster of related content.
+
+Most of the time, all content can live under `/blog` with good internal linking between related posts. Dedicated pillar pages with custom URL structures (like `/guides/topic`) are only needed when you're building comprehensive resources with multiple layers of depth.
+
+### How to Identify Pillars
+
+1. **Product-led**: What problems does your product solve?
+2. **Audience-led**: What does your ICP need to learn?
+3. **Search-led**: What topics have volume in your space?
+4. **Competitor-led**: What are competitors ranking for?
+
+### Pillar Structure
+
+```
+Pillar Topic (Hub)
+├── Subtopic Cluster 1
+│   ├── Article A
+│   ├── Article B
+│   └── Article C
+├── Subtopic Cluster 2
+│   ├── Article D
+│   ├── Article E
+│   └── Article F
+└── Subtopic Cluster 3
+    ├── Article G
+    ├── Article H
+    └── Article I
+```
+
+### Pillar Criteria
+
+Good pillars should:
+- Align with your product/service
+- Match what your audience cares about
+- Have search volume and/or social interest
+- Be broad enough for many subtopics
+
+---
+
+## Keyword Research by Buyer Stage
+
+Map topics to the buyer's journey using proven keyword modifiers:
+
+### Awareness Stage
+Modifiers: "what is," "how to," "guide to," "introduction to"
+
+Example: If customers ask about project management basics:
+- "What is Agile Project Management"
+- "Guide to Sprint Planning"
+- "How to Run a Standup Meeting"
+
+### Consideration Stage
+Modifiers: "best," "top," "vs," "alternatives," "comparison"
+
+Example: If customers evaluate multiple tools:
+- "Best Project Management Tools for Remote Teams"
+- "Asana vs Trello vs Monday"
+- "Basecamp Alternatives"
+
+### Decision Stage
+Modifiers: "pricing," "reviews," "demo," "trial," "buy"
+
+Example: If pricing comes up in sales calls:
+- "Project Management Tool Pricing Comparison"
+- "How to Choose the Right Plan"
+- "[Product] Reviews"
+
+### Implementation Stage
+Modifiers: "templates," "examples," "tutorial," "how to use," "setup"
+
+Example: If support tickets show implementation struggles:
+- "Project Template Library"
+- "Step-by-Step Setup Tutorial"
+- "How to Use [Feature]"
@@ -28,231 +28,7 @@ Good copy editing isn't about rewriting—it's about enhancing. Each pass focuse

 Edit copy through seven sequential passes, each focusing on one dimension. After each sweep, loop back to check previous sweeps aren't compromised.

-### Sweep 1: Clarity
-
-**Focus:** Can the reader understand what you're saying?
-
-**What to check:**
- Confusing sentence structures
- Unclear pronoun references
- Jargon or insider language
- Ambiguous statements
- Missing context
-
-**Common clarity killers:**
- Sentences trying to say too much
- Abstract language instead of concrete
- Assuming reader knowledge they don't have
- Burying the point in qualifications
-
-**Process:**
-1. Read through quickly, highlighting unclear parts
-2. Don't correct yet—just note problem areas
-3. After marking issues, recommend specific edits
-4. Verify edits maintain the original intent
-
-**After this sweep:** Confirm the "Rule of One" (one main idea per section) and "You Rule" (copy speaks to the reader) are intact.
-
---
-
-### Sweep 2: Voice and Tone
-
-**Focus:** Is the copy consistent in how it sounds?
-
-**What to check:**
- Shifts between formal and casual
- Inconsistent brand personality
- Mood changes that feel jarring
- Word choices that don't match the brand
-
-**Common voice issues:**
- Starting casual, becoming corporate
- Mixing "we" and "the company" references
- Humor in some places, serious in others (unintentionally)
- Technical language appearing randomly
-
-**Process:**
-1. Read aloud to hear inconsistencies
-2. Mark where tone shifts unexpectedly
-3. Recommend edits that smooth transitions
-4. Ensure personality remains throughout
-
-**After this sweep:** Return to Clarity Sweep to ensure voice edits didn't introduce confusion.
-
---
-
-### Sweep 3: So What
-
-**Focus:** Does every claim answer "why should I care?"
-
-**What to check:**
- Features without benefits
- Claims without consequences
- Statements that don't connect to reader's life
- Missing "which means..." bridges
-
-**The So What test:**
-For every statement, ask "Okay, so what?" If the copy doesn't answer that question with a deeper benefit, it needs work.
-
-❌ "Our platform uses AI-powered analytics"
-*So what?*
-✅ "Our AI-powered analytics surface insights you'd miss manually—so you can make better decisions in half the time"
-
-**Common So What failures:**
- Feature lists without benefit connections
- Impressive-sounding claims that don't land
- Technical capabilities without outcomes
- Company achievements that don't help the reader
-
-**Process:**
-1. Read each claim and literally ask "so what?"
-2. Highlight claims missing the answer
-3. Add the benefit bridge or deeper meaning
-4. Ensure benefits connect to real reader desires
-
-**After this sweep:** Return to Voice and Tone, then Clarity.
-
---
-
-### Sweep 4: Prove It
-
-**Focus:** Is every claim supported with evidence?
-
-**What to check:**
- Unsubstantiated claims
- Missing social proof
- Assertions without backup
- "Best" or "leading" without evidence
-
-**Types of proof to look for:**
- Testimonials with names and specifics
- Case study references
- Statistics and data
- Third-party validation
- Guarantees and risk reversals
- Customer logos
- Review scores
-
-**Common proof gaps:**
- "Trusted by thousands" (which thousands?)
- "Industry-leading" (according to whom?)
- "Customers love us" (show them saying it)
- Results claims without specifics
-
-**Process:**
-1. Identify every claim that needs proof
-2. Check if proof exists nearby
-3. Flag unsupported assertions
-4. Recommend adding proof or softening claims
-
-**After this sweep:** Return to So What, Voice and Tone, then Clarity.
-
---
-
-### Sweep 5: Specificity
-
-**Focus:** Is the copy concrete enough to be compelling?
-
-**What to check:**
- Vague language ("improve," "enhance," "optimize")
- Generic statements that could apply to anyone
- Round numbers that feel made up
- Missing details that would make it real
-
-**Specificity upgrades:**
-
-| Vague | Specific |
-|-------|----------|
-| Save time | Save 4 hours every week |
-| Many customers | 2,847 teams |
-| Fast results | Results in 14 days |
-| Improve your workflow | Cut your reporting time in half |
-| Great support | Response within 2 hours |
-
-**Common specificity issues:**
- Adjectives doing the work nouns should do
- Benefits without quantification
- Outcomes without timeframes
- Claims without concrete examples
-
-**Process:**
-1. Highlight vague words and phrases
-2. Ask "Can this be more specific?"
-3. Add numbers, timeframes, or examples
-4. Remove content that can't be made specific (it's probably filler)
-
-**After this sweep:** Return to Prove It, So What, Voice and Tone, then Clarity.
-
---
-
-### Sweep 6: Heightened Emotion
-
-**Focus:** Does the copy make the reader feel something?
-
-**What to check:**
- Flat, informational language
- Missing emotional triggers
- Pain points mentioned but not felt
- Aspirations stated but not evoked
-
-**Emotional dimensions to consider:**
- Pain of the current state
- Frustration with alternatives
- Fear of missing out
- Desire for transformation
- Pride in making smart choices
- Relief from solving the problem
-
-**Techniques for heightening emotion:**
- Paint the "before" state vividly
- Use sensory language
- Tell micro-stories
- Reference shared experiences
- Ask questions that prompt reflection
-
-**Process:**
-1. Read for emotional impact—does it move you?
-2. Identify flat sections that should resonate
-3. Add emotional texture while staying authentic
-4. Ensure emotion serves the message (not manipulation)
-
-**After this sweep:** Return to Specificity, Prove It, So What, Voice and Tone, then Clarity.
-
---
-
-### Sweep 7: Zero Risk
-
-**Focus:** Have we removed every barrier to action?
-
-**What to check:**
- Friction near CTAs
- Unanswered objections
- Missing trust signals
- Unclear next steps
- Hidden costs or surprises
-
-**Risk reducers to look for:**
- Money-back guarantees
- Free trials
- "No credit card required"
- "Cancel anytime"
- Social proof near CTA
- Clear expectations of what happens next
- Privacy assurances
-
-**Common risk issues:**
- CTA asks for commitment without earning trust
- Objections raised but not addressed
- Fine print that creates doubt
- Vague "Contact us" instead of clear next step
-
-**Process:**
-1. Focus on sections near CTAs
-2. List every reason someone might hesitate
-3. Check if the copy addresses each concern
-4. Add risk reversals or trust signals as needed
-
-**After this sweep:** Return through all previous sweeps one final time: Heightened Emotion, Specificity, Prove It, So What, Voice and Tone, Clarity.
+Read [references/seven-sweeps.md](references/seven-sweeps.md) for the focus, checks, process, and loop-back of each sweep: Clarity, Voice and Tone, So What, Prove It, Specificity, Heightened Emotion, Zero Risk.

 ---

@@ -260,50 +36,7 @@ For every statement, ask "Okay, so what?" If the copy doesn't answer that questi

 Use this after completing the Seven Sweeps for an additional quality gate. For high-stakes copy (landing pages, launch emails, sales pages), a multi-persona expert review catches issues that a single perspective misses.

-### How It Works
-
-1. **Assemble 3-5 expert personas** relevant to the copy type
-2. **Each persona scores the copy 1-10** on their area of expertise
-3. **Collect specific critiques** — not just scores, but what to fix
-4. **Revise based on feedback** — address the lowest-scoring areas first
-5. **Re-score after revisions** — iterate until all personas score 7+, with an average of 8+ across the panel
-
-### Recommended Expert Panels
-
-**Landing page copy:**
- Conversion copywriter (clarity, CTA strength, benefit hierarchy)
- UX writer (scannability, cognitive load, user flow)
- Target customer persona (does this speak to me? do I trust it?)
- Brand strategist (voice consistency, positioning accuracy)
-
-**Email sequence:**
- Email marketing specialist (subject lines, open/click optimization)
- Copywriter (hooks, storytelling, persuasion)
- Spam filter analyst (deliverability red flags, trigger words)
- Target customer persona (relevance, value, unsubscribe risk)
-
-**Sales page / long-form:**
- Direct response copywriter (offer structure, objection handling, urgency)
- Skeptical buyer persona (proof gaps, trust issues, red flags)
- Editor (flow, readability, conciseness)
- SEO specialist (keyword coverage, search intent alignment)
-
-### Scoring Rubric
-
-| Score | Meaning |
-|-------|---------|
-| 9-10 | Publish-ready. No meaningful improvements. |
-| 7-8 | Strong. Minor tweaks only. |
-| 5-6 | Functional but has clear gaps. Needs another pass. |
-| 3-4 | Significant issues. Major revision needed. |
-| 1-2 | Fundamentally broken. Rethink approach. |
-
-### When to Use
-
- **Always** for launch copy, pricing pages, and high-traffic landing pages
- **Recommended** for email sequences, sales pages, and ad copy
- **Optional** for blog posts, social content, and internal docs
- **Skip** for quick updates, minor edits, and low-stakes content
+Read [references/expert-panel-scoring.md](references/expert-panel-scoring.md) for how it works, recommended panels, the scoring rubric, and when to use it.

 ---

@@ -311,48 +44,7 @@ Use this after completing the Seven Sweeps for an additional quality gate. For h

 Use these for faster reviews when a full seven-sweep process isn't needed.

-### Word-Level Checks
-
-**Cut these words:**
- Very, really, extremely, incredibly (weak intensifiers)
- Just, actually, basically (filler)
- In order to (use "to")
- That (often unnecessary)
- Things, stuff (vague)
-
-**Replace these:**
-
-| Weak | Strong |
-|------|--------|
-| Utilize | Use |
-| Implement | Set up |
-| Leverage | Use |
-| Facilitate | Help |
-| Innovative | New |
-| Robust | Strong |
-| Seamless | Smooth |
-| Cutting-edge | New/Modern |
-
-**Watch for:**
- Adverbs (usually unnecessary)
- Passive voice (switch to active)
- Nominalizations (verb → noun: "make a decision" → "decide")
-
-### Sentence-Level Checks
-
- One idea per sentence
- Vary sentence length (mix short and long)
- Front-load important information
- Max 3 conjunctions per sentence
- No more than 25 words (usually)
-
-### Paragraph-Level Checks
-
- One topic per paragraph
- Short paragraphs (2-4 sentences for web)
- Strong opening sentences
- Logical flow between paragraphs
- White space for scannability
+Read [references/quick-pass-checks.md](references/quick-pass-checks.md) for word-, sentence-, and paragraph-level checks.

 ---

@@ -364,51 +56,13 @@ For a final QA pass before delivering edits, work through the full checklist in

 ## Common Copy Problems & Fixes

-### Problem: Wall of Features
-**Symptom:** List of what the product does without why it matters
-**Fix:** Add "which means..." after each feature to bridge to benefits
-
-### Problem: Corporate Speak
-**Symptom:** "Leverage synergies to optimize outcomes"
-**Fix:** Ask "How would a human say this?" and use those words
-
-### Problem: Weak Opening
-**Symptom:** Starting with company history or vague statements
-**Fix:** Lead with the reader's problem or desired outcome
-
-### Problem: Buried CTA
-**Symptom:** The ask comes after too much buildup, or isn't clear
-**Fix:** Make the CTA obvious, early, and repeated
-
-### Problem: No Proof
-**Symptom:** "Customers love us" with no evidence
-**Fix:** Add specific testimonials, numbers, or case references
-
-### Problem: Generic Claims
-**Symptom:** "We help businesses grow"
-**Fix:** Specify who, how, and by how much
-
-### Problem: Mixed Audiences
-**Symptom:** Copy tries to speak to everyone, resonates with no one
-**Fix:** Pick one audience and write directly to them
-
-### Problem: Feature Overload
-**Symptom:** Listing every capability, overwhelming the reader
-**Fix:** Focus on 3-5 key benefits that matter most to the audience
+Read [references/common-copy-problems.md](references/common-copy-problems.md) for symptoms and fixes of frequent copy problems (wall of features, corporate speak, weak opening, buried CTA, and more).

 ---

 ## Working with Copy Sweeps

-When editing collaboratively:
-
-1. **Run a sweep and present findings** - Show what you found, why it's an issue
-2. **Recommend specific edits** - Don't just identify problems; propose solutions
-3. **Request the updated copy** - Let the author make final decisions
-4. **Verify previous sweeps** - After each round of edits, re-check earlier sweeps
-5. **Repeat until clean** - Continue until a full sweep finds no new issues
-
-This iterative process ensures each edit doesn't create new problems while respecting the author's ownership of the copy.
+When editing collaboratively, follow the iterative sweep loop in [references/seven-sweeps.md](references/seven-sweeps.md).

 ---

@@ -0,0 +1,33 @@
+# Common Copy Problems & Fixes
+
+## Problem: Wall of Features
+**Symptom:** List of what the product does without why it matters
+**Fix:** Add "which means..." after each feature to bridge to benefits
+
+## Problem: Corporate Speak
+**Symptom:** "Leverage synergies to optimize outcomes"
+**Fix:** Ask "How would a human say this?" and use those words
+
+## Problem: Weak Opening
+**Symptom:** Starting with company history or vague statements
+**Fix:** Lead with the reader's problem or desired outcome
+
+## Problem: Buried CTA
+**Symptom:** The ask comes after too much buildup, or isn't clear
+**Fix:** Make the CTA obvious, early, and repeated
+
+## Problem: No Proof
+**Symptom:** "Customers love us" with no evidence
+**Fix:** Add specific testimonials, numbers, or case references
+
+## Problem: Generic Claims
+**Symptom:** "We help businesses grow"
+**Fix:** Specify who, how, and by how much
+
+## Problem: Mixed Audiences
+**Symptom:** Copy tries to speak to everyone, resonates with no one
+**Fix:** Pick one audience and write directly to them
+
+## Problem: Feature Overload
+**Symptom:** Listing every capability, overwhelming the reader
+**Fix:** Focus on 3-5 key benefits that matter most to the audience
@@ -0,0 +1,46 @@
+# Expert Panel Scoring
+
+## How It Works
+
+1. **Assemble 3-5 expert personas** relevant to the copy type
+2. **Each persona scores the copy 1-10** on their area of expertise
+3. **Collect specific critiques** — not just scores, but what to fix
+4. **Revise based on feedback** — address the lowest-scoring areas first
+5. **Re-score after revisions** — iterate until all personas score 7+, with an average of 8+ across the panel
+
+## Recommended Expert Panels
+
+**Landing page copy:**
+- Conversion copywriter (clarity, CTA strength, benefit hierarchy)
+- UX writer (scannability, cognitive load, user flow)
+- Target customer persona (does this speak to me? do I trust it?)
+- Brand strategist (voice consistency, positioning accuracy)
+
+**Email sequence:**
+- Email marketing specialist (subject lines, open/click optimization)
+- Copywriter (hooks, storytelling, persuasion)
+- Spam filter analyst (deliverability red flags, trigger words)
+- Target customer persona (relevance, value, unsubscribe risk)
+
+**Sales page / long-form:**
+- Direct response copywriter (offer structure, objection handling, urgency)
+- Skeptical buyer persona (proof gaps, trust issues, red flags)
+- Editor (flow, readability, conciseness)
+- SEO specialist (keyword coverage, search intent alignment)
+
+## Scoring Rubric
+
+| Score | Meaning |
+|-------|---------|
+| 9-10 | Publish-ready. No meaningful improvements. |
+| 7-8 | Strong. Minor tweaks only. |
+| 5-6 | Functional but has clear gaps. Needs another pass. |
+| 3-4 | Significant issues. Major revision needed. |
+| 1-2 | Fundamentally broken. Rethink approach. |
+
+## When to Use
+
+- **Always** for launch copy, pricing pages, and high-traffic landing pages
+- **Recommended** for email sequences, sales pages, and ad copy
+- **Optional** for blog posts, social content, and internal docs
+- **Skip** for quick updates, minor edits, and low-stakes content
@@ -0,0 +1,44 @@
+# Quick-Pass Editing Checks
+
+## Word-Level Checks
+
+**Cut these words:**
+- Very, really, extremely, incredibly (weak intensifiers)
+- Just, actually, basically (filler)
+- In order to (use "to")
+- That (often unnecessary)
+- Things, stuff (vague)
+
+**Replace these:**
+
+| Weak | Strong |
+|------|--------|
+| Utilize | Use |
+| Implement | Set up |
+| Leverage | Use |
+| Facilitate | Help |
+| Innovative | New |
+| Robust | Strong |
+| Seamless | Smooth |
+| Cutting-edge | New/Modern |
+
+**Watch for:**
+- Adverbs (usually unnecessary)
+- Passive voice (switch to active)
+- Nominalizations (verb → noun: "make a decision" → "decide")
+
+## Sentence-Level Checks
+
+- One idea per sentence
+- Vary sentence length (mix short and long)
+- Front-load important information
+- Max 3 conjunctions per sentence
+- No more than 25 words (usually)
+
+## Paragraph-Level Checks
+
+- One topic per paragraph
+- Short paragraphs (2-4 sentences for web)
+- Strong opening sentences
+- Logical flow between paragraphs
+- White space for scannability
@@ -0,0 +1,240 @@
+# The Seven Sweeps Framework
+
+## Sweep 1: Clarity
+
+**Focus:** Can the reader understand what you're saying?
+
+**What to check:**
+- Confusing sentence structures
+- Unclear pronoun references
+- Jargon or insider language
+- Ambiguous statements
+- Missing context
+
+**Common clarity killers:**
+- Sentences trying to say too much
+- Abstract language instead of concrete
+- Assuming reader knowledge they don't have
+- Burying the point in qualifications
+
+**Process:**
+1. Read through quickly, highlighting unclear parts
+2. Don't correct yet—just note problem areas
+3. After marking issues, recommend specific edits
+4. Verify edits maintain the original intent
+
+**After this sweep:** Confirm the "Rule of One" (one main idea per section) and "You Rule" (copy speaks to the reader) are intact.
+
+---
+
+## Sweep 2: Voice and Tone
+
+**Focus:** Is the copy consistent in how it sounds?
+
+**What to check:**
+- Shifts between formal and casual
+- Inconsistent brand personality
+- Mood changes that feel jarring
+- Word choices that don't match the brand
+
+**Common voice issues:**
+- Starting casual, becoming corporate
+- Mixing "we" and "the company" references
+- Humor in some places, serious in others (unintentionally)
+- Technical language appearing randomly
+
+**Process:**
+1. Read aloud to hear inconsistencies
+2. Mark where tone shifts unexpectedly
+3. Recommend edits that smooth transitions
+4. Ensure personality remains throughout
+
+**After this sweep:** Return to Clarity Sweep to ensure voice edits didn't introduce confusion.
+
+---
+
+## Sweep 3: So What
+
+**Focus:** Does every claim answer "why should I care?"
+
+**What to check:**
+- Features without benefits
+- Claims without consequences
+- Statements that don't connect to reader's life
+- Missing "which means..." bridges
+
+**The So What test:**
+For every statement, ask "Okay, so what?" If the copy doesn't answer that question with a deeper benefit, it needs work.
+
+❌ "Our platform uses AI-powered analytics"
+*So what?*
+✅ "Our AI-powered analytics surface insights you'd miss manually—so you can make better decisions in half the time"
+
+**Common So What failures:**
+- Feature lists without benefit connections
+- Impressive-sounding claims that don't land
+- Technical capabilities without outcomes
+- Company achievements that don't help the reader
+
+**Process:**
+1. Read each claim and literally ask "so what?"
+2. Highlight claims missing the answer
+3. Add the benefit bridge or deeper meaning
+4. Ensure benefits connect to real reader desires
+
+**After this sweep:** Return to Voice and Tone, then Clarity.
+
+---
+
+## Sweep 4: Prove It
+
+**Focus:** Is every claim supported with evidence?
+
+**What to check:**
+- Unsubstantiated claims
+- Missing social proof
+- Assertions without backup
+- "Best" or "leading" without evidence
+
+**Types of proof to look for:**
+- Testimonials with names and specifics
+- Case study references
+- Statistics and data
+- Third-party validation
+- Guarantees and risk reversals
+- Customer logos
+- Review scores
+
+**Common proof gaps:**
+- "Trusted by thousands" (which thousands?)
+- "Industry-leading" (according to whom?)
+- "Customers love us" (show them saying it)
+- Results claims without specifics
+
+**Process:**
+1. Identify every claim that needs proof
+2. Check if proof exists nearby
+3. Flag unsupported assertions
+4. Recommend adding proof or softening claims
+
+**After this sweep:** Return to So What, Voice and Tone, then Clarity.
+
+---
+
+## Sweep 5: Specificity
+
+**Focus:** Is the copy concrete enough to be compelling?
+
+**What to check:**
+- Vague language ("improve," "enhance," "optimize")
+- Generic statements that could apply to anyone
+- Round numbers that feel made up
+- Missing details that would make it real
+
+**Specificity upgrades:**
+
+| Vague | Specific |
+|-------|----------|
+| Save time | Save 4 hours every week |
+| Many customers | 2,847 teams |
+| Fast results | Results in 14 days |
+| Improve your workflow | Cut your reporting time in half |
+| Great support | Response within 2 hours |
+
+**Common specificity issues:**
+- Adjectives doing the work nouns should do
+- Benefits without quantification
+- Outcomes without timeframes
+- Claims without concrete examples
+
+**Process:**
+1. Highlight vague words and phrases
+2. Ask "Can this be more specific?"
+3. Add numbers, timeframes, or examples
+4. Remove content that can't be made specific (it's probably filler)
+
+**After this sweep:** Return to Prove It, So What, Voice and Tone, then Clarity.
+
+---
+
+## Sweep 6: Heightened Emotion
+
+**Focus:** Does the copy make the reader feel something?
+
+**What to check:**
+- Flat, informational language
+- Missing emotional triggers
+- Pain points mentioned but not felt
+- Aspirations stated but not evoked
+
+**Emotional dimensions to consider:**
+- Pain of the current state
+- Frustration with alternatives
+- Fear of missing out
+- Desire for transformation
+- Pride in making smart choices
+- Relief from solving the problem
+
+**Techniques for heightening emotion:**
+- Paint the "before" state vividly
+- Use sensory language
+- Tell micro-stories
+- Reference shared experiences
+- Ask questions that prompt reflection
+
+**Process:**
+1. Read for emotional impact—does it move you?
+2. Identify flat sections that should resonate
+3. Add emotional texture while staying authentic
+4. Ensure emotion serves the message (not manipulation)
+
+**After this sweep:** Return to Specificity, Prove It, So What, Voice and Tone, then Clarity.
+
+---
+
+## Sweep 7: Zero Risk
+
+**Focus:** Have we removed every barrier to action?
+
+**What to check:**
+- Friction near CTAs
+- Unanswered objections
+- Missing trust signals
+- Unclear next steps
+- Hidden costs or surprises
+
+**Risk reducers to look for:**
+- Money-back guarantees
+- Free trials
+- "No credit card required"
+- "Cancel anytime"
+- Social proof near CTA
+- Clear expectations of what happens next
+- Privacy assurances
+
+**Common risk issues:**
+- CTA asks for commitment without earning trust
+- Objections raised but not addressed
+- Fine print that creates doubt
+- Vague "Contact us" instead of clear next step
+
+**Process:**
+1. Focus on sections near CTAs
+2. List every reason someone might hesitate
+3. Check if the copy addresses each concern
+4. Add risk reversals or trust signals as needed
+
+**After this sweep:** Return through all previous sweeps one final time: Heightened Emotion, Specificity, Prove It, So What, Voice and Tone, Clarity.
+
+---
+# Working with Copy Sweeps
+
+When editing collaboratively:
+
+1. **Run a sweep and present findings** - Show what you found, why it's an issue
+2. **Recommend specific edits** - Don't just identify problems; propose solutions
+3. **Request the updated copy** - Let the author make final decisions
+4. **Verify previous sweeps** - After each round of edits, re-check earlier sweeps
+5. **Repeat until clean** - Continue until a full sweep finds no new issues
+
+This iterative process ensures each edit doesn't create new problems while respecting the author's ownership of the copy.
@@ -47,277 +47,19 @@ Pick the right tool for the job:

 ---

-## AI Image Generation
+## References

-Generate original images from text prompts. The fastest way to create unique marketing visuals.
-
-### Model Comparison
-
-| Model | Best For | Text in Images | API | Cost |
-|-------|----------|:-:|-----|------|
-| **Gemini Image** (Google, "Nano Banana" / Nano Banana Pro) | All-around, editing, multi-image reference, text rendering | Good | [Gemini API](https://ai.google.dev/gemini-api/docs/image-generation) | Check [pricing](https://ai.google.dev/gemini-api/docs/pricing) |
-| **Flux** (Black Forest Labs — Pro 1.1, Kontext, Dev, Schnell) | Photorealism, brand consistency, batch; Kontext for in-image editing | Limited | [BFL API](https://docs.bfl.ai/), Replicate, fal.ai | Check [pricing](https://docs.bfl.ai/quick_start/pricing) |
-| **Ideogram 3.0** | Typography, branded graphics, accurate text rendering | Best | [Ideogram API](https://developer.ideogram.ai/) | Check [pricing](https://about.ideogram.ai/api-pricing) |
-| **ChatGPT Images 2.0 / GPT Image** (OpenAI) | General purpose, ChatGPT integration, native editing | Good | [OpenAI API](https://platform.openai.com/docs/guides/image-generation) | Check [pricing](https://platform.openai.com/docs/pricing) |
-| **Midjourney v7** | Artistic, high-aesthetic, art-directed visuals | Improved | No official API; Discord + Web | Subscription-based |
-| **Recraft V3** | Vector + brand-consistent illustrations, design assets | Strong | [Recraft API](https://www.recraft.ai/docs) | Per-credit |
-| **Stable Diffusion 3.5 / SDXL** | Self-hosted, customizable, fine-tunable | Varies | Open source | Free (GPU costs) |
-
-**Note:** DALL-E 3 is fully deprecated. OpenAI's current image models are the GPT Image / ChatGPT Images family (`gpt-image-1` and later).
-
-### When to Use Which
-
-```
-Need text/headlines in the image?
-├── Yes → Ideogram 3.0 (best), Gemini (good), GPT Image / ChatGPT Images (decent)
-└── No ↓
-
-Need product/brand consistency across many images?
-├── Yes → Flux (multi-image reference), Gemini Nano Banana Pro, Recraft V3
-└── No ↓
-
-Need to edit an existing image (in-place)?
-├── Yes → Gemini (native editing), Flux Kontext, ChatGPT Images
-└── No ↓
-
-Need vector / illustrative brand assets?
-├── Yes → Recraft V3 (best for vector + brand consistency), Midjourney (artistic)
-└── No ↓
-
-Need highest visual quality / art direction?
-├── Yes → Flux Pro 1.1, Midjourney v7
-└── No ↓
-
-Need volume at low cost?
-└── Flux Schnell, Gemini Flash, Stable Diffusion (self-hosted)
-```
-
-### Prompting Basics
-
-A strong image prompt follows: **Subject + Setting + Style + Lighting + Composition + Technical**
-
-```
-A laptop on a minimal white desk showing a dashboard UI,
-soft directional lighting from the left, shallow depth of field,
-clean commercial photography style, 16:9 aspect ratio, 4K
-```
-
-**Common mistakes:**
- Too vague ("a business image") — add specific details
- Forgetting aspect ratio — always specify dimensions
- Requesting complex text — use overlays instead for anything beyond short headlines
- No style direction — "photorealistic," "flat illustration," "3D render"
+- [references/ai-image-generation.md](references/ai-image-generation.md): Read when generating images with AI: model comparison, model choice decision tree, prompting basics
+- [references/design-tools.md](references/design-tools.md): Read when using Canva or Figma, or deciding between design tools and AI generation
+- [references/marketing-image-workflows.md](references/marketing-image-workflows.md): Read when producing blog heroes, social graphics, product mockups, profile/listing banners, or brand assets (includes platform sizes)
+- [references/image-optimization.md](references/image-optimization.md): Read when optimizing images for web performance: formats, checklist, commands
+- [references/og-social-preview-images.md](references/og-social-preview-images.md): Read when setting up OG/social preview images and meta tags
+- [references/common-mistakes.md](references/common-mistakes.md): Read before delivering, to check against common image mistakes

 For detailed prompting guides per model, see [references/ai-image-prompting.md](references/ai-image-prompting.md).

 ---

-## Design Tools
-
-For templated, brand-consistent work where AI generation is overkill or too unpredictable.
-
-### Canva
-
-Best for non-designers who need polished output fast.
-
- **Strengths:** Massive template library, brand kit, Magic Resize (one design → all sizes), team collaboration
- **Best for:** Social graphics, presentations, email headers, simple banners
- **Limitations:** Less control than Figma, templates can look generic
- **Agent-friendliness:** Has an API but limited — better as a human-in-the-loop tool
-
-### Figma
-
-Best for teams with design systems or pixel-perfect needs.
-
- **Strengths:** Design system components, auto layout, developer handoff, plugins
- **Best for:** OG images via templates, design system assets, complex layouts
- **Limitations:** Steeper learning curve, requires design skill
- **Agent-friendliness:** Has an API and MCP server for reading designs
-
-### When to Use Design Tools vs. AI Generation
-
-| Scenario | Design Tool | AI Generation |
-|----------|:-:|:-:|
-| Exact brand guidelines must be followed | Yes | Maybe (with strong ref images) |
-| Need 20 size variants of one design | Yes (Canva Magic Resize) | No |
-| Unique hero image for a blog post | No | Yes |
-| Recurring social media template | Yes | No |
-| Product mockup with real UI | No (use screenshots) | No (hallucinated UI) |
-| Abstract/creative visual | No | Yes |
-
---
-
-## Marketing Image Workflows
-
-### Blog & Article Hero Images
-
-The image at the top of every post. Sets tone, improves shareability, required for OG/social previews.
-
-1. **Define the concept** — what visual metaphor represents the topic?
-2. **Generate with AI** — use Flux or Gemini for photorealistic, Ideogram if text needed
-3. **Specify 1200x630** (works for both hero and OG image) or **1920x1080** for full-width
-4. **Optimize** — compress to <200KB, serve as WebP with JPEG fallback
-
-**Prompt pattern:**
-```
-[Visual metaphor for topic], clean modern style,
-bright natural lighting, shallow depth of field,
-professional blog header aesthetic, 1200x630
-```
-
-### Social Media Graphics
-
-Platform-specific images for organic posts.
-
-| Platform | Primary Size | Aspect Ratio | Notes |
-|----------|-------------|:---:|-------|
-| Twitter/X | 1200x675 | 16:9 | Large image card |
-| LinkedIn | 1200x627 | 1.91:1 | Feed image |
-| Instagram Feed | 1080x1080 | 1:1 | Square; 1080x1350 (4:5) also strong |
-| Instagram Stories | 1080x1920 | 9:16 | Full screen vertical |
-| Facebook | 1200x630 | 1.91:1 | Link share image |
-
-**Workflow:**
-1. Create the hero concept at highest resolution needed
-2. Use Canva Magic Resize or manual crop for platform variants
-3. Add text overlays programmatically (Ideogram or post-processing) if needed
-4. Export at platform-specific dimensions
-
-### Product Mockups & Screenshots
-
-Showcase your product UI in context. AI models hallucinate UI — don't use them for this.
-
-1. **Capture real screenshots** of your product at 2x resolution
-2. **Frame in device mockups** — use browser frame, laptop, or phone templates
-3. **Add context** — callout arrows, feature labels, before/after comparisons
-4. **Annotate with code** — Hyperframes or HTML/CSS for programmatic overlays
-
-**Tools:** Browser DevTools (screenshot), Shottr (Mac), CleanShot X, or `screencapture` CLI.
-
-### Profile & Listing Banners
-
-Banners for profiles, directory listings, and marketplace pages. Often the first visual impression.
-
-| Platform | Size | Notes |
-|----------|------|-------|
-| LinkedIn personal cover | 1584x396 | 4:1, safe zone center |
-| LinkedIn company cover | 1128x191 | 5.9:1; LinkedIn recommends up to 4200x700 |
-| Twitter/X header | 1500x500 | 3:1, partially obscured by avatar |
-| Product Hunt gallery | 1270x760 | 5:3, up to 6 images |
-| G2 profile | 1280x720 | 16:9, product screenshots preferred |
-| GitHub social preview | 1280x640 | 2:1, shows in link cards |
-| App Store screenshots | Varies by device | Check current platform specifications |
-| Google Play feature graphic | 1024x500 | ~2:1, required for store listing |
-
-**Best practices:**
- **Keep text minimal** — banners are seen at small sizes on mobile
- **Center critical content** — edges get cropped differently per device
- **Show the product** — real UI screenshots outperform abstract graphics on directory listings
- **Match your brand** — use consistent colors, fonts, logo placement
- **Update seasonally** — stale banners signal an inactive product
-
-**Workflow:**
-1. Pick the platform(s) and note exact dimensions
-2. For directories (Product Hunt, G2): use real product screenshots with light annotation
-3. For profiles (LinkedIn, Twitter): use brand colors + tagline + optional product shot
-4. Generate with Canva/Figma templates or Ideogram (if text-heavy)
-5. Test at actual display size — zoom out to check readability
-
-### Brand Assets
-
-Logos, icons, and illustrations. AI generation has limits here.
-
-| Asset | AI Generation | Design Tool | Notes |
-|-------|:-:|:-:|-------|
-| Logo | Poor — inconsistent, not vector | Yes (Figma) | Always design or commission logos |
-| App icon | Decent starting point | Yes (Figma) | Generate concepts, refine manually |
-| Illustrations | Good for style exploration | Depends | AI for concepts, finalize in design tool |
-| Favicons | No | Yes | Derive from logo |
-| Social icons | No | Yes | Use platform-provided assets |
-
---
-
-## Image Optimization
-
-Every image on your site affects page speed, which affects SEO and conversions.
-
-### Format Guide
-
-| Format | Best For | Compression | Browser Support |
-|--------|----------|-------------|:---:|
-| **WebP** | Photos, graphics — default choice | Lossy + lossless | ~96% |
-| **AVIF** | Highest compression, newest | Better than WebP | ~94% |
-| **JPEG** | Fallback for older browsers | Lossy only | Universal |
-| **PNG** | Transparency, screenshots | Lossless | Universal |
-| **SVG** | Logos, icons, illustrations | Vector (scales) | Universal |
-
-### Optimization Checklist
-
- [ ] **Serve WebP** with JPEG/PNG fallback (`<picture>` element or CDN auto-format)
- [ ] **Resize to display size** — don't serve 4000px images in 800px containers
- [ ] **Compress** — target quality 75-85% for photos, near-lossless for screenshots
- [ ] **Lazy load** below-the-fold images (`loading="lazy"`)
- [ ] **Set explicit dimensions** — `width` and `height` attributes prevent layout shift (CLS)
- [ ] **Use a CDN** with auto-optimization (Cloudflare, Vercel, Imgix, Cloudinary)
- [ ] **Add alt text** — descriptive, keyword-relevant, not stuffed
-
-### Quick Optimization Commands
-
-```bash
-# Convert to WebP (using cwebp)
-cwebp -q 80 input.png -o output.webp
-
-# Batch convert with ImageMagick
-mogrify -format webp -quality 80 *.png
-
-# Optimize JPEG (using jpegoptim)
-jpegoptim --max=80 --strip-all *.jpg
-
-# Check image sizes on a page
-curl -s https://yoursite.com | grep -oP 'src="[^"]+\.(jpg|png|webp)"' | head -20
-```
-
---
-
-## OG & Social Preview Images
-
-The image that appears when your URL is shared on social media, Slack, Discord, etc.
-
-### Required Meta Tags
-
-```html
-<meta property="og:image" content="https://yoursite.com/og/page-name.jpg" />
-<meta property="og:image:width" content="1200" />
-<meta property="og:image:height" content="630" />
-<meta name="twitter:card" content="summary_large_image" />
-<meta name="twitter:image" content="https://yoursite.com/og/page-name.jpg" />
-```
-
-### Dynamic OG Images
-
-Generate OG images programmatically for pages with dynamic content (blog posts, user profiles):
-
- **Vercel OG** (`@vercel/og`) — generates images at the edge using JSX
- **Satori** — converts HTML/CSS to SVG (powers Vercel OG)
- **Cloudinary** — URL-based text overlay on template images
-
-**Best for programmatic SEO:** Generate unique OG images per page using templates + dynamic data.
-
---
-
-## Common Mistakes
-
-1. **Using AI for product UI screenshots** — models hallucinate interfaces; capture real screenshots
-2. **Skipping image optimization** — unoptimized images are the #1 page speed killer
-3. **No OG image** — shared links look broken without a preview image
-4. **Wrong aspect ratio** — always check platform specs before generating
-5. **Text-heavy images without Ideogram** — most AI models butcher text; use Ideogram or add text in post
-6. **Generating without style direction** — "photorealistic," "flat illustration," "3D render" drastically changes output
-7. **Inconsistent brand visuals** — use Flux multi-reference or design templates for consistency
-8. **Huge images on landing pages** — compress, resize, lazy load
-
---
-
 ## Task-Specific Questions

 1. What type of image do you need? (Blog hero, social graphic, mockup, banner, brand asset)
@@ -0,0 +1,60 @@
+# AI Image Generation
+
+Generate original images from text prompts. The fastest way to create unique marketing visuals.
+
+## Model Comparison
+
+| Model | Best For | Text in Images | API | Cost |
+|-------|----------|:-:|-----|------|
+| **Gemini Image** (Google, "Nano Banana" / Nano Banana Pro) | All-around, editing, multi-image reference, text rendering | Good | [Gemini API](https://ai.google.dev/gemini-api/docs/image-generation) | Check [pricing](https://ai.google.dev/gemini-api/docs/pricing) |
+| **Flux** (Black Forest Labs — Pro 1.1, Kontext, Dev, Schnell) | Photorealism, brand consistency, batch; Kontext for in-image editing | Limited | [BFL API](https://docs.bfl.ai/), Replicate, fal.ai | Check [pricing](https://docs.bfl.ai/quick_start/pricing) |
+| **Ideogram 3.0** | Typography, branded graphics, accurate text rendering | Best | [Ideogram API](https://developer.ideogram.ai/) | Check [pricing](https://about.ideogram.ai/api-pricing) |
+| **ChatGPT Images 2.0 / GPT Image** (OpenAI) | General purpose, ChatGPT integration, native editing | Good | [OpenAI API](https://platform.openai.com/docs/guides/image-generation) | Check [pricing](https://platform.openai.com/docs/pricing) |
+| **Midjourney v7** | Artistic, high-aesthetic, art-directed visuals | Improved | No official API; Discord + Web | Subscription-based |
+| **Recraft V3** | Vector + brand-consistent illustrations, design assets | Strong | [Recraft API](https://www.recraft.ai/docs) | Per-credit |
+| **Stable Diffusion 3.5 / SDXL** | Self-hosted, customizable, fine-tunable | Varies | Open source | Free (GPU costs) |
+
+**Note:** DALL-E 3 is fully deprecated. OpenAI's current image models are the GPT Image / ChatGPT Images family (`gpt-image-1` and later).
+
+## When to Use Which
+
+```
+Need text/headlines in the image?
+├── Yes → Ideogram 3.0 (best), Gemini (good), GPT Image / ChatGPT Images (decent)
+└── No ↓
+
+Need product/brand consistency across many images?
+├── Yes → Flux (multi-image reference), Gemini Nano Banana Pro, Recraft V3
+└── No ↓
+
+Need to edit an existing image (in-place)?
+├── Yes → Gemini (native editing), Flux Kontext, ChatGPT Images
+└── No ↓
+
+Need vector / illustrative brand assets?
+├── Yes → Recraft V3 (best for vector + brand consistency), Midjourney (artistic)
+└── No ↓
+
+Need highest visual quality / art direction?
+├── Yes → Flux Pro 1.1, Midjourney v7
+└── No ↓
+
+Need volume at low cost?
+└── Flux Schnell, Gemini Flash, Stable Diffusion (self-hosted)
+```
+
+## Prompting Basics
+
+A strong image prompt follows: **Subject + Setting + Style + Lighting + Composition + Technical**
+
+```
+A laptop on a minimal white desk showing a dashboard UI,
+soft directional lighting from the left, shallow depth of field,
+clean commercial photography style, 16:9 aspect ratio, 4K
+```
+
+**Common mistakes:**
+- Too vague ("a business image") — add specific details
+- Forgetting aspect ratio — always specify dimensions
+- Requesting complex text — use overlays instead for anything beyond short headlines
+- No style direction — "photorealistic," "flat illustration," "3D render"
@@ -0,0 +1,10 @@
+# Common Mistakes
+
+1. **Using AI for product UI screenshots** — models hallucinate interfaces; capture real screenshots
+2. **Skipping image optimization** — unoptimized images are the #1 page speed killer
+3. **No OG image** — shared links look broken without a preview image
+4. **Wrong aspect ratio** — always check platform specs before generating
+5. **Text-heavy images without Ideogram** — most AI models butcher text; use Ideogram or add text in post
+6. **Generating without style direction** — "photorealistic," "flat illustration," "3D render" drastically changes output
+7. **Inconsistent brand visuals** — use Flux multi-reference or design templates for consistency
+8. **Huge images on landing pages** — compress, resize, lazy load
@@ -0,0 +1,32 @@
+# Design Tools
+
+For templated, brand-consistent work where AI generation is overkill or too unpredictable.
+
+## Canva
+
+Best for non-designers who need polished output fast.
+
+- **Strengths:** Massive template library, brand kit, Magic Resize (one design → all sizes), team collaboration
+- **Best for:** Social graphics, presentations, email headers, simple banners
+- **Limitations:** Less control than Figma, templates can look generic
+- **Agent-friendliness:** Has an API but limited — better as a human-in-the-loop tool
+
+## Figma
+
+Best for teams with design systems or pixel-perfect needs.
+
+- **Strengths:** Design system components, auto layout, developer handoff, plugins
+- **Best for:** OG images via templates, design system assets, complex layouts
+- **Limitations:** Steeper learning curve, requires design skill
+- **Agent-friendliness:** Has an API and MCP server for reading designs
+
+## When to Use Design Tools vs. AI Generation
+
+| Scenario | Design Tool | AI Generation |
+|----------|:-:|:-:|
+| Exact brand guidelines must be followed | Yes | Maybe (with strong ref images) |
+| Need 20 size variants of one design | Yes (Canva Magic Resize) | No |
+| Unique hero image for a blog post | No | Yes |
+| Recurring social media template | Yes | No |
+| Product mockup with real UI | No (use screenshots) | No (hallucinated UI) |
+| Abstract/creative visual | No | Yes |
@@ -0,0 +1,39 @@
+# Image Optimization
+
+Every image on your site affects page speed, which affects SEO and conversions.
+
+## Format Guide
+
+| Format | Best For | Compression | Browser Support |
+|--------|----------|-------------|:---:|
+| **WebP** | Photos, graphics — default choice | Lossy + lossless | ~96% |
+| **AVIF** | Highest compression, newest | Better than WebP | ~94% |
+| **JPEG** | Fallback for older browsers | Lossy only | Universal |
+| **PNG** | Transparency, screenshots | Lossless | Universal |
+| **SVG** | Logos, icons, illustrations | Vector (scales) | Universal |
+
+## Optimization Checklist
+
+- [ ] **Serve WebP** with JPEG/PNG fallback (`<picture>` element or CDN auto-format)
+- [ ] **Resize to display size** — don't serve 4000px images in 800px containers
+- [ ] **Compress** — target quality 75-85% for photos, near-lossless for screenshots
+- [ ] **Lazy load** below-the-fold images (`loading="lazy"`)
+- [ ] **Set explicit dimensions** — `width` and `height` attributes prevent layout shift (CLS)
+- [ ] **Use a CDN** with auto-optimization (Cloudflare, Vercel, Imgix, Cloudinary)
+- [ ] **Add alt text** — descriptive, keyword-relevant, not stuffed
+
+## Quick Optimization Commands
+
+```bash
+# Convert to WebP (using cwebp)
+cwebp -q 80 input.png -o output.webp
+
+# Batch convert with ImageMagick
+mogrify -format webp -quality 80 *.png
+
+# Optimize JPEG (using jpegoptim)
+jpegoptim --max=80 --strip-all *.jpg
+
+# Check image sizes on a page
+curl -s https://yoursite.com | grep -oP 'src="[^"]+\.(jpg|png|webp)"' | head -20
+```
@@ -0,0 +1,87 @@
+# Marketing Image Workflows
+
+## Blog & Article Hero Images
+
+The image at the top of every post. Sets tone, improves shareability, required for OG/social previews.
+
+1. **Define the concept** — what visual metaphor represents the topic?
+2. **Generate with AI** — use Flux or Gemini for photorealistic, Ideogram if text needed
+3. **Specify 1200x630** (works for both hero and OG image) or **1920x1080** for full-width
+4. **Optimize** — compress to <200KB, serve as WebP with JPEG fallback
+
+**Prompt pattern:**
+```
+[Visual metaphor for topic], clean modern style,
+bright natural lighting, shallow depth of field,
+professional blog header aesthetic, 1200x630
+```
+
+## Social Media Graphics
+
+Platform-specific images for organic posts.
+
+| Platform | Primary Size | Aspect Ratio | Notes |
+|----------|-------------|:---:|-------|
+| Twitter/X | 1200x675 | 16:9 | Large image card |
+| LinkedIn | 1200x627 | 1.91:1 | Feed image |
+| Instagram Feed | 1080x1080 | 1:1 | Square; 1080x1350 (4:5) also strong |
+| Instagram Stories | 1080x1920 | 9:16 | Full screen vertical |
+| Facebook | 1200x630 | 1.91:1 | Link share image |
+
+**Workflow:**
+1. Create the hero concept at highest resolution needed
+2. Use Canva Magic Resize or manual crop for platform variants
+3. Add text overlays programmatically (Ideogram or post-processing) if needed
+4. Export at platform-specific dimensions
+
+## Product Mockups & Screenshots
+
+Showcase your product UI in context. AI models hallucinate UI — don't use them for this.
+
+1. **Capture real screenshots** of your product at 2x resolution
+2. **Frame in device mockups** — use browser frame, laptop, or phone templates
+3. **Add context** — callout arrows, feature labels, before/after comparisons
+4. **Annotate with code** — Hyperframes or HTML/CSS for programmatic overlays
+
+**Tools:** Browser DevTools (screenshot), Shottr (Mac), CleanShot X, or `screencapture` CLI.
+
+## Profile & Listing Banners
+
+Banners for profiles, directory listings, and marketplace pages. Often the first visual impression.
+
+| Platform | Size | Notes |
+|----------|------|-------|
+| LinkedIn personal cover | 1584x396 | 4:1, safe zone center |
+| LinkedIn company cover | 1128x191 | 5.9:1; LinkedIn recommends up to 4200x700 |
+| Twitter/X header | 1500x500 | 3:1, partially obscured by avatar |
+| Product Hunt gallery | 1270x760 | 5:3, up to 6 images |
+| G2 profile | 1280x720 | 16:9, product screenshots preferred |
+| GitHub social preview | 1280x640 | 2:1, shows in link cards |
+| App Store screenshots | Varies by device | Check current platform specifications |
+| Google Play feature graphic | 1024x500 | ~2:1, required for store listing |
+
+**Best practices:**
+- **Keep text minimal** — banners are seen at small sizes on mobile
+- **Center critical content** — edges get cropped differently per device
+- **Show the product** — real UI screenshots outperform abstract graphics on directory listings
+- **Match your brand** — use consistent colors, fonts, logo placement
+- **Update seasonally** — stale banners signal an inactive product
+
+**Workflow:**
+1. Pick the platform(s) and note exact dimensions
+2. For directories (Product Hunt, G2): use real product screenshots with light annotation
+3. For profiles (LinkedIn, Twitter): use brand colors + tagline + optional product shot
+4. Generate with Canva/Figma templates or Ideogram (if text-heavy)
+5. Test at actual display size — zoom out to check readability
+
+## Brand Assets
+
+Logos, icons, and illustrations. AI generation has limits here.
+
+| Asset | AI Generation | Design Tool | Notes |
+|-------|:-:|:-:|-------|
+| Logo | Poor — inconsistent, not vector | Yes (Figma) | Always design or commission logos |
+| App icon | Decent starting point | Yes (Figma) | Generate concepts, refine manually |
+| Illustrations | Good for style exploration | Depends | AI for concepts, finalize in design tool |
+| Favicons | No | Yes | Derive from logo |
+| Social icons | No | Yes | Use platform-provided assets |
@@ -0,0 +1,23 @@
+# OG & Social Preview Images
+
+The image that appears when your URL is shared on social media, Slack, Discord, etc.
+
+## Required Meta Tags
+
+```html
+<meta property="og:image" content="https://yoursite.com/og/page-name.jpg" />
+<meta property="og:image:width" content="1200" />
+<meta property="og:image:height" content="630" />
+<meta name="twitter:card" content="summary_large_image" />
+<meta name="twitter:image" content="https://yoursite.com/og/page-name.jpg" />
+```
+
+## Dynamic OG Images
+
+Generate OG images programmatically for pages with dynamic content (blog posts, user profiles):
+
+- **Vercel OG** (`@vercel/og`) — generates images at the edge using JSX
+- **Satori** — converts HTML/CSS to SVG (powers Vercel OG)
+- **Cloudinary** — URL-based text overlay on template images
+
+**Best for programmatic SEO:** Generate unique OG images per page using templates + dynamic data.
@@ -23,399 +23,16 @@ Mental models are thinking tools that help you make better decisions, understand

 ---

-## Foundational Thinking Models
+## Model Categories

-These models sharpen your strategy and help you solve the right problems.
+Pick the category that matches the challenge, then read only that file for the model explanations and marketing applications:

-### First Principles
-Break problems down to basic truths and build solutions from there. Instead of copying competitors, ask "why" repeatedly to find root causes. Use the 5 Whys technique to tunnel down to what really matters.
-
-**Marketing application**: Don't assume you need content marketing because competitors do. Ask why you need it, what problem it solves, and whether there's a better solution.
-
-### Jobs to Be Done
-People don't buy products—they "hire" them to get a job done. Focus on the outcome customers want, not features.
-
-**Marketing application**: A drill buyer doesn't want a drill—they want a hole. Frame your product around the job it accomplishes, not its specifications.
-
-### Circle of Competence
-Know what you're good at and stay within it. Venture outside only with proper learning or expert help.
-
-**Marketing application**: Don't chase every channel. Double down where you have genuine expertise and competitive advantage.
-
-### Inversion
-Instead of asking "How do I succeed?", ask "What would guarantee failure?" Then avoid those things.
-
-**Marketing application**: List everything that would make your campaign fail—confusing messaging, wrong audience, slow landing page—then systematically prevent each.
-
-### Occam's Razor
-The simplest explanation is usually correct. Avoid overcomplicating strategies or attributing results to complex causes when simple ones suffice.
-
-**Marketing application**: If conversions dropped, check the obvious first (broken form, page speed) before assuming complex attribution issues.
-
-### Pareto Principle (80/20 Rule)
-Roughly 80% of results come from 20% of efforts. Identify and focus on the vital few.
-
-**Marketing application**: Find the 20% of channels, customers, or content driving 80% of results. Cut or reduce the rest.
-
-### Local vs. Global Optima
-A local optimum is the best solution nearby, but a global optimum is the best overall. Don't get stuck optimizing the wrong thing.
-
-**Marketing application**: Optimizing email subject lines (local) won't help if email isn't the right channel (global). Zoom out before zooming in.
-
-### Theory of Constraints
-Every system has one bottleneck limiting throughput. Find and fix that constraint before optimizing elsewhere.
-
-**Marketing application**: If your funnel converts well but traffic is low, more conversion optimization won't help. Fix the traffic bottleneck first.
-
-### Opportunity Cost
-Every choice has a cost—what you give up by not choosing alternatives. Consider what you're saying no to.
-
-**Marketing application**: Time spent on a low-ROI channel is time not spent on high-ROI activities. Always compare against alternatives.
-
-### Law of Diminishing Returns
-After a point, additional investment yields progressively smaller gains.
-
-**Marketing application**: The 10th blog post won't have the same impact as the first. Know when to diversify rather than double down.
-
-### Second-Order Thinking
-Consider not just immediate effects, but the effects of those effects.
-
-**Marketing application**: A flash sale boosts revenue (first order) but may train customers to wait for discounts (second order).
-
-### Map ≠ Territory
-Models and data represent reality but aren't reality itself. Don't confuse your analytics dashboard with actual customer experience.
-
-**Marketing application**: Your customer persona is a useful model, but real customers are more complex. Stay in touch with actual users.
-
-### Probabilistic Thinking
-Think in probabilities, not certainties. Estimate likelihoods and plan for multiple outcomes.
-
-**Marketing application**: Don't bet everything on one campaign. Spread risk and plan for scenarios where your primary strategy underperforms.
-
-### Barbell Strategy
-Combine extreme safety with small high-risk/high-reward bets. Avoid the mediocre middle.
-
-**Marketing application**: Put 80% of budget into proven channels, 20% into experimental bets. Avoid moderate-risk, moderate-reward middle.
-
---
-
-## Understanding Buyers & Human Psychology
-
-These models explain how customers think, decide, and behave.
-
-### Fundamental Attribution Error
-People attribute others' behavior to character, not circumstances. "They didn't buy because they're not serious" vs. "The checkout was confusing."
-
-**Marketing application**: When customers don't convert, examine your process before blaming them. The problem is usually situational, not personal.
-
-### Mere Exposure Effect
-People prefer things they've seen before. Familiarity breeds liking.
-
-**Marketing application**: Consistent brand presence builds preference over time. Repetition across channels creates comfort and trust.
-
-### Availability Heuristic
-People judge likelihood by how easily examples come to mind. Recent or vivid events seem more common.
-
-**Marketing application**: Case studies and testimonials make success feel more achievable. Make positive outcomes easy to imagine.
-
-### Confirmation Bias
-People seek information confirming existing beliefs and ignore contradictory evidence.
-
-**Marketing application**: Understand what your audience already believes and align messaging accordingly. Fighting beliefs head-on rarely works.
-
-### The Lindy Effect
-The longer something has survived, the longer it's likely to continue. Old ideas often outlast new ones.
-
-**Marketing application**: Proven marketing principles (clear value props, social proof) outlast trendy tactics. Don't abandon fundamentals for fads.
-
-### Mimetic Desire
-People want things because others want them. Desire is socially contagious.
-
-**Marketing application**: Show that desirable people want your product. Waitlists, exclusivity, and social proof trigger mimetic desire.
-
-### Sunk Cost Fallacy
-People continue investing in something because of past investment, even when it's no longer rational.
-
-**Marketing application**: Know when to kill underperforming campaigns. Past spend shouldn't justify future spend if results aren't there.
-
-### Endowment Effect
-People value things more once they own them.
-
-**Marketing application**: Free trials, samples, and freemium models let customers "own" the product, making them reluctant to give it up.
-
-### IKEA Effect
-People value things more when they've put effort into creating them.
-
-**Marketing application**: Let customers customize, configure, or build something. Their investment increases perceived value and commitment.
-
-### Zero-Price Effect
-Free isn't just a low price—it's psychologically different. "Free" triggers irrational preference.
-
-**Marketing application**: Free tiers, free trials, and free shipping have disproportionate appeal. The jump from $1 to $0 is bigger than $2 to $1.
-
-### Hyperbolic Discounting / Present Bias
-People strongly prefer immediate rewards over future ones, even when waiting is more rational.
-
-**Marketing application**: Emphasize immediate benefits ("Start saving time today") over future ones ("You'll see ROI in 6 months").
-
-### Status-Quo Bias
-People prefer the current state of affairs. Change requires effort and feels risky.
-
-**Marketing application**: Reduce friction to switch. Make the transition feel safe and easy. "Import your data in one click."
-
-### Default Effect
-People tend to accept pre-selected options. Defaults are powerful.
-
-**Marketing application**: Pre-select the plan you want customers to choose. Opt-out beats opt-in for subscriptions (ethically applied).
-
-### Paradox of Choice
-Too many options overwhelm and paralyze. Fewer choices often lead to more decisions.
-
-**Marketing application**: Limit options. Three pricing tiers beat seven. Recommend a single "best for most" option.
-
-### Goal-Gradient Effect
-People accelerate effort as they approach a goal. Progress visualization motivates action.
-
-**Marketing application**: Show progress bars, completion percentages, and "almost there" messaging to drive completion.
-
-### Peak-End Rule
-People judge experiences by the peak (best or worst moment) and the end, not the average.
-
-**Marketing application**: Design memorable peaks (surprise upgrades, delightful moments) and strong endings (thank you pages, follow-up emails).
-
-### Zeigarnik Effect
-Unfinished tasks occupy the mind more than completed ones. Open loops create tension.
-
-**Marketing application**: "You're 80% done" creates pull to finish. Incomplete profiles, abandoned carts, and cliffhangers leverage this.
-
-### Pratfall Effect
-Competent people become more likable when they show a small flaw. Perfection is less relatable.
-
-**Marketing application**: Admitting a weakness ("We're not the cheapest, but...") can increase trust and differentiation.
-
-### Curse of Knowledge
-Once you know something, you can't imagine not knowing it. Experts struggle to explain simply.
-
-**Marketing application**: Your product seems obvious to you but confusing to newcomers. Test copy with people unfamiliar with your space.
-
-### Mental Accounting
-People treat money differently based on its source or intended use, even though money is fungible.
-
-**Marketing application**: Frame costs in favorable mental accounts. "$3/day" feels different than "$90/month" even though it's the same.
-
-### Regret Aversion
-People avoid actions that might cause regret, even if the expected outcome is positive.
-
-**Marketing application**: Address regret directly. Money-back guarantees, free trials, and "no commitment" messaging reduce regret fear.
-
-### Bandwagon Effect / Social Proof
-People follow what others are doing. Popularity signals quality and safety.
-
-**Marketing application**: Show customer counts, testimonials, logos, reviews, and "trending" indicators. Numbers create confidence.
-
---
-
-## Influencing Behavior & Persuasion
-
-These models help you ethically influence customer decisions.
-
-### Reciprocity Principle
-People feel obligated to return favors. Give first, and people want to give back.
-
-**Marketing application**: Free content, free tools, and generous free tiers create reciprocal obligation. Give value before asking for anything.
-
-### Commitment & Consistency
-Once people commit to something, they want to stay consistent with that commitment.
-
-**Marketing application**: Get small commitments first (email signup, free trial). People who've taken one step are more likely to take the next.
-
-### Authority Bias
-People defer to experts and authority figures. Credentials and expertise create trust.
-
-**Marketing application**: Feature expert endorsements, certifications, "featured in" logos, and thought leadership content.
-
-### Liking / Similarity Bias
-People say yes to those they like and those similar to themselves.
-
-**Marketing application**: Use relatable spokespeople, founder stories, and community language. "Built by marketers for marketers" signals similarity.
-
-### Unity Principle
-Shared identity drives influence. "One of us" is powerful.
-
-**Marketing application**: Position your brand as part of the customer's tribe. Use insider language and shared values.
-
-### Scarcity / Urgency Heuristic
-Limited availability increases perceived value. Scarcity signals desirability.
-
-**Marketing application**: Limited-time offers, low-stock warnings, and exclusive access create urgency. Only use when genuine.
-
-### Foot-in-the-Door Technique
-Start with a small request, then escalate. Compliance with small requests leads to compliance with larger ones.
-
-**Marketing application**: Free trial → paid plan → annual plan → enterprise. Each step builds on the last.
-
-### Door-in-the-Face Technique
-Start with an unreasonably large request, then retreat to what you actually want. The contrast makes the second request seem reasonable.
-
-**Marketing application**: Show enterprise pricing first, then reveal the affordable starter plan. The contrast makes it feel like a deal.
-
-### Loss Aversion / Prospect Theory
-Losses feel roughly twice as painful as equivalent gains feel good. People will work harder to avoid losing than to gain.
-
-**Marketing application**: Frame in terms of what they'll lose by not acting. "Don't miss out" beats "You could gain."
-
-### Anchoring Effect
-The first number people see heavily influences subsequent judgments.
-
-**Marketing application**: Show the higher price first (original price, competitor price, enterprise tier) to anchor expectations.
-
-### Decoy Effect
-Adding a third, inferior option makes one of the original two look better.
-
-**Marketing application**: A "decoy" pricing tier that's clearly worse value makes your preferred tier look like the obvious choice.
-
-### Framing Effect
-How something is presented changes how it's perceived. Same facts, different frames.
-
-**Marketing application**: "90% success rate" vs. "10% failure rate" are identical but feel different. Frame positively.
-
-### Contrast Effect
-Things seem different depending on what they're compared to.
-
-**Marketing application**: Show the "before" state clearly. The contrast with your "after" makes improvements vivid.
-
---
-
-## Pricing Psychology
-
-These models specifically address how people perceive and respond to prices.
-
-### Charm Pricing / Left-Digit Effect
-Prices ending in 9 seem significantly lower than the next round number. $99 feels much cheaper than $100.
-
-**Marketing application**: Use .99 or .95 endings for value-focused products. The left digit dominates perception.
-
-### Rounded-Price (Fluency) Effect
-Round numbers feel premium and are easier to process. $100 signals quality; $99 signals value.
-
-**Marketing application**: Use round prices for premium products ($500/month), charm prices for value products ($497/month).
-
-### Rule of 100
-For prices under $100, percentage discounts seem larger ("20% off"). For prices over $100, absolute discounts seem larger ("$50 off").
-
-**Marketing application**: $80 product: "20% off" beats "$16 off." $500 product: "$100 off" beats "20% off."
-
-### Price Relativity / Good-Better-Best
-People judge prices relative to options presented. A middle tier seems reasonable between cheap and expensive.
-
-**Marketing application**: Three tiers where the middle is your target. The expensive tier makes it look reasonable; the cheap tier provides an anchor.
-
-### Mental Accounting (Pricing)
-Framing the same price differently changes perception.
-
-**Marketing application**: "$1/day" feels cheaper than "$30/month." "Less than your morning coffee" reframes the expense.
-
---
-
-## Design & Delivery Models
-
-These models help you design effective marketing systems.
-
-### Hick's Law
-Decision time increases with the number and complexity of choices. More options = slower decisions = more abandonment.
-
-**Marketing application**: Simplify choices. One clear CTA beats three. Fewer form fields beat more.
-
-### AIDA Funnel
-Attention → Interest → Desire → Action. The classic customer journey model.
-
-**Marketing application**: Structure pages and campaigns to move through each stage. Capture attention before building desire.
-
-### Rule of 7
-Prospects need roughly 7 touchpoints before converting. One ad rarely converts; sustained presence does.
-
-**Marketing application**: Build multi-touch campaigns across channels. Retargeting, email sequences, and consistent presence compound.
-
-### Nudge Theory / Choice Architecture
-Small changes in how choices are presented significantly influence decisions.
-
-**Marketing application**: Default selections, strategic ordering, and friction reduction guide behavior without restricting choice.
-
-### BJ Fogg Behavior Model
-Behavior = Motivation × Ability × Prompt. All three must be present for action.
-
-**Marketing application**: High motivation but hard to do = won't happen. Easy to do but no prompt = won't happen. Design for all three.
-
-### EAST Framework
-Make desired behaviors: Easy, Attractive, Social, Timely.
-
-**Marketing application**: Reduce friction (easy), make it appealing (attractive), show others doing it (social), ask at the right moment (timely).
-
-### COM-B Model
-Behavior requires: Capability, Opportunity, Motivation.
-
-**Marketing application**: Can they do it (capability)? Is the path clear (opportunity)? Do they want to (motivation)? Address all three.
-
-### Activation Energy
-The initial energy required to start something. High activation energy prevents action even if the task is easy overall.
-
-**Marketing application**: Reduce starting friction. Pre-fill forms, offer templates, show quick wins. Make the first step trivially easy.
-
-### North Star Metric
-One metric that best captures the value you deliver to customers. Focus creates alignment.
-
-**Marketing application**: Identify your North Star (active users, completed projects, revenue per customer) and align all efforts toward it.
-
-### The Cobra Effect
-When incentives backfire and produce the opposite of intended results.
-
-**Marketing application**: Test incentive structures. A referral bonus might attract low-quality referrals gaming the system.
-
---
-
-## Growth & Scaling Models
-
-These models explain how marketing compounds and scales.
-
-### Feedback Loops
-Output becomes input, creating cycles. Positive loops accelerate growth; negative loops create decline.
-
-**Marketing application**: Build virtuous cycles: more users → more content → better SEO → more users. Identify and strengthen positive loops.
-
-### Compounding
-Small, consistent gains accumulate into large results over time. Early gains matter most.
-
-**Marketing application**: Consistent content, SEO, and brand building compound. Start early; benefits accumulate exponentially.
-
-### Network Effects
-A product becomes more valuable as more people use it.
-
-**Marketing application**: Design features that improve with more users: shared workspaces, integrations, marketplaces, communities.
-
-### Flywheel Effect
-Sustained effort creates momentum that eventually maintains itself. Hard to start, easy to maintain.
-
-**Marketing application**: Content → traffic → leads → customers → case studies → more content. Each element powers the next.
-
-### Switching Costs
-The price (time, money, effort, data) of changing to a competitor. High switching costs create retention.
-
-**Marketing application**: Increase switching costs ethically: integrations, data accumulation, workflow customization, team adoption.
-
-### Exploration vs. Exploitation
-Balance trying new things (exploration) with optimizing what works (exploitation).
-
-**Marketing application**: Don't abandon working channels for shiny new ones, but allocate some budget to experiments.
-
-### Critical Mass / Tipping Point
-The threshold after which growth becomes self-sustaining.
-
-**Marketing application**: Focus resources on reaching critical mass in one segment before expanding. Depth before breadth.
-
-### Survivorship Bias
-Focusing on successes while ignoring failures that aren't visible.
-
-**Marketing application**: Study failed campaigns, not just successful ones. The viral hit you're copying had 99 failures you didn't see.
+- [Foundational Thinking Models](references/thinking-models.md): read for strategy, prioritization, or diagnosing the real problem (First Principles, Inversion, Pareto, Theory of Constraints, Second-Order Thinking, Barbell Strategy, and more).
+- [Understanding Buyers & Human Psychology](references/buyer-psychology.md): read for explaining how customers think, decide, and resist change (biases, heuristics, Endowment, Default Effect, Paradox of Choice, Peak-End, Social Proof, and more).
+- [Influencing Behavior & Persuasion](references/persuasion.md): read for ethically influencing a decision (Reciprocity, Commitment, Authority, Scarcity, Loss Aversion, Anchoring, Decoy, Framing, and more).
+- [Pricing Psychology](references/pricing-psychology.md): read for price presentation, discounts, and tiers (Charm Pricing, Rounded Prices, Rule of 100, Good-Better-Best, Mental Accounting).
+- [Design & Delivery Models](references/design-delivery.md): read for designing pages, flows, CTAs, and incentive systems (Hick's Law, AIDA, Fogg, EAST, COM-B, Activation Energy, North Star, Cobra Effect, and more).
+- [Growth & Scaling Models](references/growth-scaling.md): read for compounding, retention, and scaling (Feedback Loops, Flywheel, Network Effects, Switching Costs, Critical Mass, Survivorship Bias, and more).

 ---

@@ -0,0 +1,113 @@
+# Understanding Buyers & Human Psychology
+
+These models explain how customers think, decide, and behave.
+
+## Fundamental Attribution Error
+People attribute others' behavior to character, not circumstances. "They didn't buy because they're not serious" vs. "The checkout was confusing."
+
+**Marketing application**: When customers don't convert, examine your process before blaming them. The problem is usually situational, not personal.
+
+## Mere Exposure Effect
+People prefer things they've seen before. Familiarity breeds liking.
+
+**Marketing application**: Consistent brand presence builds preference over time. Repetition across channels creates comfort and trust.
+
+## Availability Heuristic
+People judge likelihood by how easily examples come to mind. Recent or vivid events seem more common.
+
+**Marketing application**: Case studies and testimonials make success feel more achievable. Make positive outcomes easy to imagine.
+
+## Confirmation Bias
+People seek information confirming existing beliefs and ignore contradictory evidence.
+
+**Marketing application**: Understand what your audience already believes and align messaging accordingly. Fighting beliefs head-on rarely works.
+
+## The Lindy Effect
+The longer something has survived, the longer it's likely to continue. Old ideas often outlast new ones.
+
+**Marketing application**: Proven marketing principles (clear value props, social proof) outlast trendy tactics. Don't abandon fundamentals for fads.
+
+## Mimetic Desire
+People want things because others want them. Desire is socially contagious.
+
+**Marketing application**: Show that desirable people want your product. Waitlists, exclusivity, and social proof trigger mimetic desire.
+
+## Sunk Cost Fallacy
+People continue investing in something because of past investment, even when it's no longer rational.
+
+**Marketing application**: Know when to kill underperforming campaigns. Past spend shouldn't justify future spend if results aren't there.
+
+## Endowment Effect
+People value things more once they own them.
+
+**Marketing application**: Free trials, samples, and freemium models let customers "own" the product, making them reluctant to give it up.
+
+## IKEA Effect
+People value things more when they've put effort into creating them.
+
+**Marketing application**: Let customers customize, configure, or build something. Their investment increases perceived value and commitment.
+
+## Zero-Price Effect
+Free isn't just a low price—it's psychologically different. "Free" triggers irrational preference.
+
+**Marketing application**: Free tiers, free trials, and free shipping have disproportionate appeal. The jump from $1 to $0 is bigger than $2 to $1.
+
+## Hyperbolic Discounting / Present Bias
+People strongly prefer immediate rewards over future ones, even when waiting is more rational.
+
+**Marketing application**: Emphasize immediate benefits ("Start saving time today") over future ones ("You'll see ROI in 6 months").
+
+## Status-Quo Bias
+People prefer the current state of affairs. Change requires effort and feels risky.
+
+**Marketing application**: Reduce friction to switch. Make the transition feel safe and easy. "Import your data in one click."
+
+## Default Effect
+People tend to accept pre-selected options. Defaults are powerful.
+
+**Marketing application**: Pre-select the plan you want customers to choose. Opt-out beats opt-in for subscriptions (ethically applied).
+
+## Paradox of Choice
+Too many options overwhelm and paralyze. Fewer choices often lead to more decisions.
+
+**Marketing application**: Limit options. Three pricing tiers beat seven. Recommend a single "best for most" option.
+
+## Goal-Gradient Effect
+People accelerate effort as they approach a goal. Progress visualization motivates action.
+
+**Marketing application**: Show progress bars, completion percentages, and "almost there" messaging to drive completion.
+
+## Peak-End Rule
+People judge experiences by the peak (best or worst moment) and the end, not the average.
+
+**Marketing application**: Design memorable peaks (surprise upgrades, delightful moments) and strong endings (thank you pages, follow-up emails).
+
+## Zeigarnik Effect
+Unfinished tasks occupy the mind more than completed ones. Open loops create tension.
+
+**Marketing application**: "You're 80% done" creates pull to finish. Incomplete profiles, abandoned carts, and cliffhangers leverage this.
+
+## Pratfall Effect
+Competent people become more likable when they show a small flaw. Perfection is less relatable.
+
+**Marketing application**: Admitting a weakness ("We're not the cheapest, but...") can increase trust and differentiation.
+
+## Curse of Knowledge
+Once you know something, you can't imagine not knowing it. Experts struggle to explain simply.
+
+**Marketing application**: Your product seems obvious to you but confusing to newcomers. Test copy with people unfamiliar with your space.
+
+## Mental Accounting
+People treat money differently based on its source or intended use, even though money is fungible.
+
+**Marketing application**: Frame costs in favorable mental accounts. "$3/day" feels different than "$90/month" even though it's the same.
+
+## Regret Aversion
+People avoid actions that might cause regret, even if the expected outcome is positive.
+
+**Marketing application**: Address regret directly. Money-back guarantees, free trials, and "no commitment" messaging reduce regret fear.
+
+## Bandwagon Effect / Social Proof
+People follow what others are doing. Popularity signals quality and safety.
+
+**Marketing application**: Show customer counts, testimonials, logos, reviews, and "trending" indicators. Numbers create confidence.
@@ -0,0 +1,53 @@
+# Design & Delivery Models
+
+These models help you design effective marketing systems.
+
+## Hick's Law
+Decision time increases with the number and complexity of choices. More options = slower decisions = more abandonment.
+
+**Marketing application**: Simplify choices. One clear CTA beats three. Fewer form fields beat more.
+
+## AIDA Funnel
+Attention → Interest → Desire → Action. The classic customer journey model.
+
+**Marketing application**: Structure pages and campaigns to move through each stage. Capture attention before building desire.
+
+## Rule of 7
+Prospects need roughly 7 touchpoints before converting. One ad rarely converts; sustained presence does.
+
+**Marketing application**: Build multi-touch campaigns across channels. Retargeting, email sequences, and consistent presence compound.
+
+## Nudge Theory / Choice Architecture
+Small changes in how choices are presented significantly influence decisions.
+
+**Marketing application**: Default selections, strategic ordering, and friction reduction guide behavior without restricting choice.
+
+## BJ Fogg Behavior Model
+Behavior = Motivation × Ability × Prompt. All three must be present for action.
+
+**Marketing application**: High motivation but hard to do = won't happen. Easy to do but no prompt = won't happen. Design for all three.
+
+## EAST Framework
+Make desired behaviors: Easy, Attractive, Social, Timely.
+
+**Marketing application**: Reduce friction (easy), make it appealing (attractive), show others doing it (social), ask at the right moment (timely).
+
+## COM-B Model
+Behavior requires: Capability, Opportunity, Motivation.
+
+**Marketing application**: Can they do it (capability)? Is the path clear (opportunity)? Do they want to (motivation)? Address all three.
+
+## Activation Energy
+The initial energy required to start something. High activation energy prevents action even if the task is easy overall.
+
+**Marketing application**: Reduce starting friction. Pre-fill forms, offer templates, show quick wins. Make the first step trivially easy.
+
+## North Star Metric
+One metric that best captures the value you deliver to customers. Focus creates alignment.
+
+**Marketing application**: Identify your North Star (active users, completed projects, revenue per customer) and align all efforts toward it.
+
+## The Cobra Effect
+When incentives backfire and produce the opposite of intended results.
+
+**Marketing application**: Test incentive structures. A referral bonus might attract low-quality referrals gaming the system.
@@ -0,0 +1,43 @@
+# Growth & Scaling Models
+
+These models explain how marketing compounds and scales.
+
+## Feedback Loops
+Output becomes input, creating cycles. Positive loops accelerate growth; negative loops create decline.
+
+**Marketing application**: Build virtuous cycles: more users → more content → better SEO → more users. Identify and strengthen positive loops.
+
+## Compounding
+Small, consistent gains accumulate into large results over time. Early gains matter most.
+
+**Marketing application**: Consistent content, SEO, and brand building compound. Start early; benefits accumulate exponentially.
+
+## Network Effects
+A product becomes more valuable as more people use it.
+
+**Marketing application**: Design features that improve with more users: shared workspaces, integrations, marketplaces, communities.
+
+## Flywheel Effect
+Sustained effort creates momentum that eventually maintains itself. Hard to start, easy to maintain.
+
+**Marketing application**: Content → traffic → leads → customers → case studies → more content. Each element powers the next.
+
+## Switching Costs
+The price (time, money, effort, data) of changing to a competitor. High switching costs create retention.
+
+**Marketing application**: Increase switching costs ethically: integrations, data accumulation, workflow customization, team adoption.
+
+## Exploration vs. Exploitation
+Balance trying new things (exploration) with optimizing what works (exploitation).
+
+**Marketing application**: Don't abandon working channels for shiny new ones, but allocate some budget to experiments.
+
+## Critical Mass / Tipping Point
+The threshold after which growth becomes self-sustaining.
+
+**Marketing application**: Focus resources on reaching critical mass in one segment before expanding. Depth before breadth.
+
+## Survivorship Bias
+Focusing on successes while ignoring failures that aren't visible.
+
+**Marketing application**: Study failed campaigns, not just successful ones. The viral hit you're copying had 99 failures you didn't see.
@@ -0,0 +1,68 @@
+# Influencing Behavior & Persuasion
+
+These models help you ethically influence customer decisions.
+
+## Reciprocity Principle
+People feel obligated to return favors. Give first, and people want to give back.
+
+**Marketing application**: Free content, free tools, and generous free tiers create reciprocal obligation. Give value before asking for anything.
+
+## Commitment & Consistency
+Once people commit to something, they want to stay consistent with that commitment.
+
+**Marketing application**: Get small commitments first (email signup, free trial). People who've taken one step are more likely to take the next.
+
+## Authority Bias
+People defer to experts and authority figures. Credentials and expertise create trust.
+
+**Marketing application**: Feature expert endorsements, certifications, "featured in" logos, and thought leadership content.
+
+## Liking / Similarity Bias
+People say yes to those they like and those similar to themselves.
+
+**Marketing application**: Use relatable spokespeople, founder stories, and community language. "Built by marketers for marketers" signals similarity.
+
+## Unity Principle
+Shared identity drives influence. "One of us" is powerful.
+
+**Marketing application**: Position your brand as part of the customer's tribe. Use insider language and shared values.
+
+## Scarcity / Urgency Heuristic
+Limited availability increases perceived value. Scarcity signals desirability.
+
+**Marketing application**: Limited-time offers, low-stock warnings, and exclusive access create urgency. Only use when genuine.
+
+## Foot-in-the-Door Technique
+Start with a small request, then escalate. Compliance with small requests leads to compliance with larger ones.
+
+**Marketing application**: Free trial → paid plan → annual plan → enterprise. Each step builds on the last.
+
+## Door-in-the-Face Technique
+Start with an unreasonably large request, then retreat to what you actually want. The contrast makes the second request seem reasonable.
+
+**Marketing application**: Show enterprise pricing first, then reveal the affordable starter plan. The contrast makes it feel like a deal.
+
+## Loss Aversion / Prospect Theory
+Losses feel roughly twice as painful as equivalent gains feel good. People will work harder to avoid losing than to gain.
+
+**Marketing application**: Frame in terms of what they'll lose by not acting. "Don't miss out" beats "You could gain."
+
+## Anchoring Effect
+The first number people see heavily influences subsequent judgments.
+
+**Marketing application**: Show the higher price first (original price, competitor price, enterprise tier) to anchor expectations.
+
+## Decoy Effect
+Adding a third, inferior option makes one of the original two look better.
+
+**Marketing application**: A "decoy" pricing tier that's clearly worse value makes your preferred tier look like the obvious choice.
+
+## Framing Effect
+How something is presented changes how it's perceived. Same facts, different frames.
+
+**Marketing application**: "90% success rate" vs. "10% failure rate" are identical but feel different. Frame positively.
+
+## Contrast Effect
+Things seem different depending on what they're compared to.
+
+**Marketing application**: Show the "before" state clearly. The contrast with your "after" makes improvements vivid.
@@ -0,0 +1,28 @@
+# Pricing Psychology
+
+These models specifically address how people perceive and respond to prices.
+
+## Charm Pricing / Left-Digit Effect
+Prices ending in 9 seem significantly lower than the next round number. $99 feels much cheaper than $100.
+
+**Marketing application**: Use .99 or .95 endings for value-focused products. The left digit dominates perception.
+
+## Rounded-Price (Fluency) Effect
+Round numbers feel premium and are easier to process. $100 signals quality; $99 signals value.
+
+**Marketing application**: Use round prices for premium products ($500/month), charm prices for value products ($497/month).
+
+## Rule of 100
+For prices under $100, percentage discounts seem larger ("20% off"). For prices over $100, absolute discounts seem larger ("$50 off").
+
+**Marketing application**: $80 product: "20% off" beats "$16 off." $500 product: "$100 off" beats "20% off."
+
+## Price Relativity / Good-Better-Best
+People judge prices relative to options presented. A middle tier seems reasonable between cheap and expensive.
+
+**Marketing application**: Three tiers where the middle is your target. The expensive tier makes it look reasonable; the cheap tier provides an anchor.
+
+## Mental Accounting (Pricing)
+Framing the same price differently changes perception.
+
+**Marketing application**: "$1/day" feels cheaper than "$30/month." "Less than your morning coffee" reframes the expense.
@@ -0,0 +1,73 @@
+# Foundational Thinking Models
+
+These models sharpen your strategy and help you solve the right problems.
+
+## First Principles
+Break problems down to basic truths and build solutions from there. Instead of copying competitors, ask "why" repeatedly to find root causes. Use the 5 Whys technique to tunnel down to what really matters.
+
+**Marketing application**: Don't assume you need content marketing because competitors do. Ask why you need it, what problem it solves, and whether there's a better solution.
+
+## Jobs to Be Done
+People don't buy products—they "hire" them to get a job done. Focus on the outcome customers want, not features.
+
+**Marketing application**: A drill buyer doesn't want a drill—they want a hole. Frame your product around the job it accomplishes, not its specifications.
+
+## Circle of Competence
+Know what you're good at and stay within it. Venture outside only with proper learning or expert help.
+
+**Marketing application**: Don't chase every channel. Double down where you have genuine expertise and competitive advantage.
+
+## Inversion
+Instead of asking "How do I succeed?", ask "What would guarantee failure?" Then avoid those things.
+
+**Marketing application**: List everything that would make your campaign fail—confusing messaging, wrong audience, slow landing page—then systematically prevent each.
+
+## Occam's Razor
+The simplest explanation is usually correct. Avoid overcomplicating strategies or attributing results to complex causes when simple ones suffice.
+
+**Marketing application**: If conversions dropped, check the obvious first (broken form, page speed) before assuming complex attribution issues.
+
+## Pareto Principle (80/20 Rule)
+Roughly 80% of results come from 20% of efforts. Identify and focus on the vital few.
+
+**Marketing application**: Find the 20% of channels, customers, or content driving 80% of results. Cut or reduce the rest.
+
+## Local vs. Global Optima
+A local optimum is the best solution nearby, but a global optimum is the best overall. Don't get stuck optimizing the wrong thing.
+
+**Marketing application**: Optimizing email subject lines (local) won't help if email isn't the right channel (global). Zoom out before zooming in.
+
+## Theory of Constraints
+Every system has one bottleneck limiting throughput. Find and fix that constraint before optimizing elsewhere.
+
+**Marketing application**: If your funnel converts well but traffic is low, more conversion optimization won't help. Fix the traffic bottleneck first.
+
+## Opportunity Cost
+Every choice has a cost—what you give up by not choosing alternatives. Consider what you're saying no to.
+
+**Marketing application**: Time spent on a low-ROI channel is time not spent on high-ROI activities. Always compare against alternatives.
+
+## Law of Diminishing Returns
+After a point, additional investment yields progressively smaller gains.
+
+**Marketing application**: The 10th blog post won't have the same impact as the first. Know when to diversify rather than double down.
+
+## Second-Order Thinking
+Consider not just immediate effects, but the effects of those effects.
+
+**Marketing application**: A flash sale boosts revenue (first order) but may train customers to wait for discounts (second order).
+
+## Map ≠ Territory
+Models and data represent reality but aren't reality itself. Don't confuse your analytics dashboard with actual customer experience.
+
+**Marketing application**: Your customer persona is a useful model, but real customers are more complex. Stay in touch with actual users.
+
+## Probabilistic Thinking
+Think in probabilities, not certainties. Estimate likelihoods and plan for multiple outcomes.
+
+**Marketing application**: Don't bet everything on one campaign. Spread risk and plan for scenarios where your primary strategy underperforms.
+
+## Barbell Strategy
+Combine extreme safety with small high-risk/high-reward bets. Avoid the mediocre middle.
+
+**Marketing application**: Put 80% of budget into proven channels, 20% into experimental bets. Avoid moderate-risk, moderate-reward middle.
@@ -56,258 +56,26 @@ Gather this context (ask if not provided):

 ---

-## Page Hierarchy Design
+## References

-### The 3-Click Rule
-
-Users should reach any important page within 3 clicks from the homepage. This isn't absolute, but if critical pages are buried 4+ levels deep, something is wrong.
-
-### Flat vs Deep
-
-| Approach | Best For | Tradeoff |
-|----------|----------|----------|
-| Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale |
-| Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability |
-| Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content |
-
-**Rule of thumb**: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy.
-
-### Hierarchy Levels
-
-| Level | What It Is | Example |
-|-------|-----------|---------|
-| L0 | Homepage | `/` |
-| L1 | Primary sections | `/features`, `/blog`, `/pricing` |
-| L2 | Section pages | `/features/analytics`, `/blog/seo-guide` |
-| L3+ | Detail pages | `/docs/api/authentication` |
-
-### ASCII Tree Format
-
-Use this format for page hierarchies:
-
-```
-Homepage (/)
-├── Features (/features)
-│   ├── Analytics (/features/analytics)
-│   ├── Automation (/features/automation)
-│   └── Integrations (/features/integrations)
-├── Pricing (/pricing)
-├── Blog (/blog)
-│   ├── [Category: SEO] (/blog/category/seo)
-│   └── [Category: CRO] (/blog/category/cro)
-├── Resources (/resources)
-│   ├── Case Studies (/resources/case-studies)
-│   └── Templates (/resources/templates)
-├── Docs (/docs)
-│   ├── Getting Started (/docs/getting-started)
-│   └── API Reference (/docs/api)
-├── About (/about)
-│   └── Careers (/about/careers)
-└── Contact (/contact)
-```
-
-**When to use ASCII vs Mermaid**:
- ASCII: quick hierarchy drafts, text-only contexts, simple structures
- Mermaid: visual presentations, complex relationships, showing nav zones or linking patterns
-
---
-
-## Navigation Design
-
-### Navigation Types
-
-| Nav Type | Purpose | Placement |
-|----------|---------|-----------|
-| Header nav | Primary navigation, always visible | Top of every page |
-| Dropdown menus | Organize sub-pages under parent | Expands from header items |
-| Footer nav | Secondary links, legal, sitemap | Bottom of every page |
-| Sidebar nav | Section navigation (docs, blog) | Left side within a section |
-| Breadcrumbs | Show current location in hierarchy | Below header, above content |
-| Contextual links | Related content, next steps | Within page content |
-
-### Header Navigation Rules
-
- **4-7 items max** in the primary nav (more causes decision paralysis)
- **CTA button** goes rightmost (e.g., "Start Free Trial," "Get Started")
- **Logo** links to homepage (left side)
- **Order by priority**: most important/visited pages first
- If you have a mega menu, limit to 3-4 columns
-
-### Footer Organization
-
-Group footer links into columns:
- **Product**: Features, Pricing, Integrations, Changelog
- **Resources**: Blog, Case Studies, Templates, Docs
- **Company**: About, Careers, Contact, Press
- **Legal**: Privacy, Terms, Security
-
-### Breadcrumb Format
-
-```
-Home > Features > Analytics
-Home > Blog > SEO Category > Post Title
-```
-
-Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page.
+- [references/page-hierarchy.md](references/page-hierarchy.md): Read when designing hierarchy depth, levels, or the ASCII tree
+- [references/navigation-design.md](references/navigation-design.md): Read when designing header, footer, sidebar, or breadcrumb navigation
+- [references/url-structure.md](references/url-structure.md): Read when designing URL patterns and redirects
+- [references/visual-sitemaps.md](references/visual-sitemaps.md): Read when producing the Mermaid visual sitemap
+- [references/internal-linking.md](references/internal-linking.md): Read when planning internal links or a link audit

 **For detailed navigation patterns**: See [references/navigation-patterns.md](references/navigation-patterns.md)

---
-
-## URL Structure
-
-### Design Principles
-
-1. **Readable by humans** — `/features/analytics` not `/f/a123`
-2. **Hyphens, not underscores** — `/blog/seo-guide` not `/blog/seo_guide`
-3. **Reflect the hierarchy** — URL path should match site structure
-4. **Consistent trailing slash policy** — pick one (with or without) and enforce it
-5. **Lowercase always** — `/About` should redirect to `/about`
-6. **Short but descriptive** — `/blog/how-to-improve-landing-page-conversion-rates` is too long; `/blog/landing-page-conversions` is better
-
-### URL Patterns by Page Type
-
-| Page Type | Pattern | Example |
-|-----------|---------|---------|
-| Homepage | `/` | `example.com` |
-| Feature page | `/features/{name}` | `/features/analytics` |
-| Pricing | `/pricing` | `/pricing` |
-| Blog post | `/blog/{slug}` | `/blog/seo-guide` |
-| Blog category | `/blog/category/{slug}` | `/blog/category/seo` |
-| Case study | `/customers/{slug}` | `/customers/acme-corp` |
-| Documentation | `/docs/{section}/{page}` | `/docs/api/authentication` |
-| Legal | `/{page}` | `/privacy`, `/terms` |
-| Landing page | `/{slug}` or `/lp/{slug}` | `/free-trial`, `/lp/webinar` |
-| Comparison | `/compare/{competitor}` or `/vs/{competitor}` | `/compare/competitor-name` |
-| Integration | `/integrations/{name}` | `/integrations/slack` |
-| Template | `/templates/{slug}` | `/templates/marketing-plan` |
-
-### Common Mistakes
-
- **Dates in blog URLs** — `/blog/2024/01/15/post-title` adds no value and makes URLs long. Use `/blog/post-title`.
- **Over-nesting** — `/products/category/subcategory/item/detail` is too deep. Flatten where possible.
- **Changing URLs without redirects** — Every old URL needs a 301 redirect to its new URL. Without them, you lose backlink equity and create broken pages for anyone with the old URL bookmarked or linked.
- **IDs in URLs** — `/product/12345` is not human-readable. Use slugs.
- **Query parameters for content** — `/blog?id=123` should be `/blog/post-title`.
- **Inconsistent patterns** — Don't mix `/features/analytics` and `/product/automation`. Pick one parent.
-
-### Breadcrumb-URL Alignment
-
-The breadcrumb trail should mirror the URL path:
-
-| URL | Breadcrumb |
-|-----|-----------|
-| `/features/analytics` | Home > Features > Analytics |
-| `/blog/seo-guide` | Home > Blog > SEO Guide |
-| `/docs/api/auth` | Home > Docs > API > Authentication |
-
---
-
-## Visual Sitemap Output (Mermaid)
-
-Use Mermaid `graph TD` for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones.
-
-### Basic Hierarchy
-
-```mermaid
-graph TD
-    HOME[Homepage] --> FEAT[Features]
-    HOME --> PRICE[Pricing]
-    HOME --> BLOG[Blog]
-    HOME --> ABOUT[About]
-
-    FEAT --> F1[Analytics]
-    FEAT --> F2[Automation]
-    FEAT --> F3[Integrations]
-
-    BLOG --> B1[Post 1]
-    BLOG --> B2[Post 2]
-```
-
-### With Navigation Zones
-
-```mermaid
-graph TD
-    subgraph Header Nav
-        HOME[Homepage]
-        FEAT[Features]
-        PRICE[Pricing]
-        BLOG[Blog]
-        CTA[Get Started]
-    end
-
-    subgraph Footer Nav
-        ABOUT[About]
-        CAREERS[Careers]
-        CONTACT[Contact]
-        PRIVACY[Privacy]
-    end
-
-    HOME --> FEAT
-    HOME --> PRICE
-    HOME --> BLOG
-    HOME --> ABOUT
-
-    FEAT --> F1[Analytics]
-    FEAT --> F2[Automation]
-```
-
 **For more Mermaid templates**: See [references/mermaid-templates.md](references/mermaid-templates.md)

 ---

-## Internal Linking Strategy
-
-### Link Types
-
-| Type | Purpose | Example |
-|------|---------|---------|
-| Navigational | Move between sections | Header, footer, sidebar links |
-| Contextual | Related content within text | "Learn more about [analytics](/features/analytics)" |
-| Hub-and-spoke | Connect cluster content to hub | Blog posts linking to pillar page |
-| Cross-section | Connect related pages across sections | Feature page linking to related case study |
-
-### Internal Linking Rules
-
-1. **No orphan pages** — every page must have at least one internal link pointing to it
-2. **Descriptive anchor text** — "our analytics features" not "click here"
-3. **5-10 internal links per 1000 words** of content (approximate guideline)
-4. **Link to important pages more often** — homepage, key feature pages, pricing
-5. **Use breadcrumbs** — free internal links on every page
-6. **Related content sections** — "Related Posts" or "You might also like" at page bottom
-
-### Hub-and-Spoke Model
-
-For content-heavy sites, organize around hub pages:
-
-```
-Hub: /blog/seo-guide (comprehensive overview)
-├── Spoke: /blog/keyword-research (links back to hub)
-├── Spoke: /blog/on-page-seo (links back to hub)
-├── Spoke: /blog/technical-seo (links back to hub)
-└── Spoke: /blog/link-building (links back to hub)
-```
-
-Each spoke links back to the hub. The hub links to all spokes. Spokes link to each other where relevant.
-
-### Link Audit Checklist
-
- [ ] Every page has at least one inbound internal link
- [ ] No broken internal links (404s)
- [ ] Anchor text is descriptive (not "click here" or "read more")
- [ ] Important pages have the most inbound internal links
- [ ] Breadcrumbs are implemented on all pages
- [ ] Related content links exist on blog posts
- [ ] Cross-section links connect features to case studies, blog to product pages
-
---
-
 ## Output Format

 When creating a site architecture plan, provide these deliverables:

 ### 1. Page Hierarchy (ASCII Tree)
-Full site structure with URLs at each node. Use the ASCII tree format from the Page Hierarchy Design section.
+Full site structure with URLs at each node. Use the ASCII tree format from [references/page-hierarchy.md](references/page-hierarchy.md).

 ### 2. Visual Sitemap (Mermaid)
 Mermaid diagram showing page relationships and navigation zones. Use `graph TD` with subgraphs for nav zones where helpful.
@@ -0,0 +1,43 @@
+# Internal Linking Strategy
+
+## Link Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| Navigational | Move between sections | Header, footer, sidebar links |
+| Contextual | Related content within text | "Learn more about [analytics](/features/analytics)" |
+| Hub-and-spoke | Connect cluster content to hub | Blog posts linking to pillar page |
+| Cross-section | Connect related pages across sections | Feature page linking to related case study |
+
+## Internal Linking Rules
+
+1. **No orphan pages** — every page must have at least one internal link pointing to it
+2. **Descriptive anchor text** — "our analytics features" not "click here"
+3. **5-10 internal links per 1000 words** of content (approximate guideline)
+4. **Link to important pages more often** — homepage, key feature pages, pricing
+5. **Use breadcrumbs** — free internal links on every page
+6. **Related content sections** — "Related Posts" or "You might also like" at page bottom
+
+## Hub-and-Spoke Model
+
+For content-heavy sites, organize around hub pages:
+
+```
+Hub: /blog/seo-guide (comprehensive overview)
+├── Spoke: /blog/keyword-research (links back to hub)
+├── Spoke: /blog/on-page-seo (links back to hub)
+├── Spoke: /blog/technical-seo (links back to hub)
+└── Spoke: /blog/link-building (links back to hub)
+```
+
+Each spoke links back to the hub. The hub links to all spokes. Spokes link to each other where relevant.
+
+## Link Audit Checklist
+
+- [ ] Every page has at least one inbound internal link
+- [ ] No broken internal links (404s)
+- [ ] Anchor text is descriptive (not "click here" or "read more")
+- [ ] Important pages have the most inbound internal links
+- [ ] Breadcrumbs are implemented on all pages
+- [ ] Related content links exist on blog posts
+- [ ] Cross-section links connect features to case studies, blog to product pages
@@ -0,0 +1,37 @@
+# Navigation Design
+
+## Navigation Types
+
+| Nav Type | Purpose | Placement |
+|----------|---------|-----------|
+| Header nav | Primary navigation, always visible | Top of every page |
+| Dropdown menus | Organize sub-pages under parent | Expands from header items |
+| Footer nav | Secondary links, legal, sitemap | Bottom of every page |
+| Sidebar nav | Section navigation (docs, blog) | Left side within a section |
+| Breadcrumbs | Show current location in hierarchy | Below header, above content |
+| Contextual links | Related content, next steps | Within page content |
+
+## Header Navigation Rules
+
+- **4-7 items max** in the primary nav (more causes decision paralysis)
+- **CTA button** goes rightmost (e.g., "Start Free Trial," "Get Started")
+- **Logo** links to homepage (left side)
+- **Order by priority**: most important/visited pages first
+- If you have a mega menu, limit to 3-4 columns
+
+## Footer Organization
+
+Group footer links into columns:
+- **Product**: Features, Pricing, Integrations, Changelog
+- **Resources**: Blog, Case Studies, Templates, Docs
+- **Company**: About, Careers, Contact, Press
+- **Legal**: Privacy, Terms, Security
+
+## Breadcrumb Format
+
+```
+Home > Features > Analytics
+Home > Blog > SEO Category > Post Title
+```
+
+Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page.
@@ -0,0 +1,53 @@
+# Page Hierarchy Design
+
+## The 3-Click Rule
+
+Users should reach any important page within 3 clicks from the homepage. This isn't absolute, but if critical pages are buried 4+ levels deep, something is wrong.
+
+## Flat vs Deep
+
+| Approach | Best For | Tradeoff |
+|----------|----------|----------|
+| Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale |
+| Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability |
+| Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content |
+
+**Rule of thumb**: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy.
+
+## Hierarchy Levels
+
+| Level | What It Is | Example |
+|-------|-----------|---------|
+| L0 | Homepage | `/` |
+| L1 | Primary sections | `/features`, `/blog`, `/pricing` |
+| L2 | Section pages | `/features/analytics`, `/blog/seo-guide` |
+| L3+ | Detail pages | `/docs/api/authentication` |
+
+## ASCII Tree Format
+
+Use this format for page hierarchies:
+
+```
+Homepage (/)
+├── Features (/features)
+│   ├── Analytics (/features/analytics)
+│   ├── Automation (/features/automation)
+│   └── Integrations (/features/integrations)
+├── Pricing (/pricing)
+├── Blog (/blog)
+│   ├── [Category: SEO] (/blog/category/seo)
+│   └── [Category: CRO] (/blog/category/cro)
+├── Resources (/resources)
+│   ├── Case Studies (/resources/case-studies)
+│   └── Templates (/resources/templates)
+├── Docs (/docs)
+│   ├── Getting Started (/docs/getting-started)
+│   └── API Reference (/docs/api)
+├── About (/about)
+│   └── Careers (/about/careers)
+└── Contact (/contact)
+```
+
+**When to use ASCII vs Mermaid**:
+- ASCII: quick hierarchy drafts, text-only contexts, simple structures
+- Mermaid: visual presentations, complex relationships, showing nav zones or linking patterns
@@ -0,0 +1,46 @@
+# URL Structure
+
+## Design Principles
+
+1. **Readable by humans** — `/features/analytics` not `/f/a123`
+2. **Hyphens, not underscores** — `/blog/seo-guide` not `/blog/seo_guide`
+3. **Reflect the hierarchy** — URL path should match site structure
+4. **Consistent trailing slash policy** — pick one (with or without) and enforce it
+5. **Lowercase always** — `/About` should redirect to `/about`
+6. **Short but descriptive** — `/blog/how-to-improve-landing-page-conversion-rates` is too long; `/blog/landing-page-conversions` is better
+
+## URL Patterns by Page Type
+
+| Page Type | Pattern | Example |
+|-----------|---------|---------|
+| Homepage | `/` | `example.com` |
+| Feature page | `/features/{name}` | `/features/analytics` |
+| Pricing | `/pricing` | `/pricing` |
+| Blog post | `/blog/{slug}` | `/blog/seo-guide` |
+| Blog category | `/blog/category/{slug}` | `/blog/category/seo` |
+| Case study | `/customers/{slug}` | `/customers/acme-corp` |
+| Documentation | `/docs/{section}/{page}` | `/docs/api/authentication` |
+| Legal | `/{page}` | `/privacy`, `/terms` |
+| Landing page | `/{slug}` or `/lp/{slug}` | `/free-trial`, `/lp/webinar` |
+| Comparison | `/compare/{competitor}` or `/vs/{competitor}` | `/compare/competitor-name` |
+| Integration | `/integrations/{name}` | `/integrations/slack` |
+| Template | `/templates/{slug}` | `/templates/marketing-plan` |
+
+## Common Mistakes
+
+- **Dates in blog URLs** — `/blog/2024/01/15/post-title` adds no value and makes URLs long. Use `/blog/post-title`.
+- **Over-nesting** — `/products/category/subcategory/item/detail` is too deep. Flatten where possible.
+- **Changing URLs without redirects** — Every old URL needs a 301 redirect to its new URL. Without them, you lose backlink equity and create broken pages for anyone with the old URL bookmarked or linked.
+- **IDs in URLs** — `/product/12345` is not human-readable. Use slugs.
+- **Query parameters for content** — `/blog?id=123` should be `/blog/post-title`.
+- **Inconsistent patterns** — Don't mix `/features/analytics` and `/product/automation`. Pick one parent.
+
+## Breadcrumb-URL Alignment
+
+The breadcrumb trail should mirror the URL path:
+
+| URL | Breadcrumb |
+|-----|-----------|
+| `/features/analytics` | Home > Features > Analytics |
+| `/blog/seo-guide` | Home > Blog > SEO Guide |
+| `/docs/api/auth` | Home > Docs > API > Authentication |
@@ -0,0 +1,48 @@
+# Visual Sitemap Output (Mermaid)
+
+Use Mermaid `graph TD` for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones.
+
+## Basic Hierarchy
+
+```mermaid
+graph TD
+    HOME[Homepage] --> FEAT[Features]
+    HOME --> PRICE[Pricing]
+    HOME --> BLOG[Blog]
+    HOME --> ABOUT[About]
+
+    FEAT --> F1[Analytics]
+    FEAT --> F2[Automation]
+    FEAT --> F3[Integrations]
+
+    BLOG --> B1[Post 1]
+    BLOG --> B2[Post 2]
+```
+
+## With Navigation Zones
+
+```mermaid
+graph TD
+    subgraph Header Nav
+        HOME[Homepage]
+        FEAT[Features]
+        PRICE[Pricing]
+        BLOG[Blog]
+        CTA[Get Started]
+    end
+
+    subgraph Footer Nav
+        ABOUT[About]
+        CAREERS[Careers]
+        CONTACT[Contact]
+        PRIVACY[Privacy]
+    end
+
+    HOME --> FEAT
+    HOME --> PRICE
+    HOME --> BLOG
+    HOME --> ABOUT
+
+    FEAT --> F1[Analytics]
+    FEAT --> F2[Automation]
+```
Author	SHA1	Message	Date
Julian lechnerandClaude Opus 5.5	f83b0add58	docs(skills): describe flat Claude skill layout CI / CI configuration security checks (push) Successful in 5s Details CI / Capabilities and shell quality (push) Successful in 17s Details CI / Python tests and compilation (push) Successful in 24s Details CI / Build and inspect generated packages (push) Successful in 17s Details CI / PowerShell tests on Ubuntu (push) Successful in 54s Details CI / Bash integration and installation guards (push) Failing after 59s Details CI / Installed client configuration smoke tests (push) Successful in 1m2s Details CI / Qwen retrieval integration (push) Canceled after 5m28s Details Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:02:07 +02:00
Julian lechnerandClaude Opus 5.5	3203e4ed67	fix(build): generate flat Claude skill directories Claude discovers only skills/<name>/SKILL.md, so 84 nested skills, including all rule skills, were invisible. Flatten the categorized catalog for Claude, keep references, and fail the build on duplicate names or a name that differs from its directory. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:02:07 +02:00
Julian lechnerandClaude Opus 5.5	5c1bee043d	docs(scripts): document required client mode Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:02:06 +02:00
Julian lechnerandClaude Opus 5.5	e49dd3f4bc	ci: run client behavior smoke tests Run scripts/tests/test-client-smoke.py in the client-smoke job with required clients, Python, and Claude sandbox dependencies. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:02:06 +02:00
Julian lechnerandClaude Opus 5.5	82391bdfbf	test(clients): add smoke test timeouts and required-client mode Read client output on a thread with a deadline so a silent or exited client fails instead of hanging, and fail on a missing CLI when AI_CONFIG_REQUIRE_CLIENTS=1. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:02:05 +02:00
Julian lechnerandClaude Opus 5.5	c14101e60d	refactor(skills): move site-architecture catalogs to references Keep the decision steps in SKILL.md and move catalogs, examples, and checklists verbatim to references/ to reduce the context cost of loading the skill. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:01:55 +02:00
Julian lechnerandClaude Opus 5.5	c8b00584d9	refactor(skills): move copy-editing catalogs to references Keep the decision steps in SKILL.md and move catalogs, examples, and checklists verbatim to references/ to reduce the context cost of loading the skill. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:01:55 +02:00
Julian lechnerandClaude Opus 5.5	d841ce6ead	refactor(skills): move image catalogs to references Keep the decision steps in SKILL.md and move catalogs, examples, and checklists verbatim to references/ to reduce the context cost of loading the skill. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:01:55 +02:00
Julian lechnerandClaude Opus 5.5	310876a466	refactor(skills): move content-strategy catalogs to references Keep the decision steps in SKILL.md and move catalogs, examples, and checklists verbatim to references/ to reduce the context cost of loading the skill. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:01:54 +02:00
Julian lechnerandClaude Opus 5.5	4c93437e59	refactor(skills): move marketing-psychology catalogs to references Keep the decision steps in SKILL.md and move catalogs, examples, and checklists verbatim to references/ to reduce the context cost of loading the skill. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:01:54 +02:00
Julian lechnerandClaude Opus 5.5	569f55dd0d	refactor(rules): merge Angular subscription lifetime rules Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:01:46 +02:00
Julian lechnerandClaude Opus 5.5	e8cdcec629	refactor(rules): deduplicate Angular signal state rules Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:01:46 +02:00
Julian lechnerandClaude Opus 5.5	85221f6c97	docs(config): document Claude subagent limits Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:01:45 +02:00
Julian lechnerandClaude Opus 5.5	a30440f55d	feat(claude): limit concurrent subagents and spawn depth Set CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=5 and CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 so Claude matches the Codex agent limits and subagents cannot start further subagents. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-01 11:01:45 +02:00