cgallic · cgallic · Jul 5, 2026 · Jul 5, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -0,0 +1,17 @@
+{
+  "name": "kai-marketing-os",
+  "owner": {
+    "name": "Connor Gallic",
+    "email": "me@connorgallic.com"
+  },
+  "description": "Kai Marketing OS — marketing skills, knowledge base, and quality gates for Claude Code.",
+  "plugins": [
+    {
+      "name": "kai",
+      "source": "./plugins/kai-marketing-os",
+      "description": "A marketing team in your terminal: 45+ /kai skills, a full marketing knowledge base, and quality gates. Type /kai:kai-start after install.",
+      "category": "marketing",
+      "keywords": ["marketing", "growth", "seo", "ads", "copywriting", "cmo"]
+    }
+  ]
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,28 @@
 # Changelog
 
+## Unreleased — 2026-07-05
+
+### Install UX overhaul — plugin marketplace + installer v2
+
+**Claude Code plugin (new hero install path)**
+- Repo is now a plugin marketplace: `/plugin marketplace add cgallic/kai-cmo-harness` then `/plugin install kai@kai-marketing-os` — two lines inside Claude Code, no terminal
+- `plugins/kai-marketing-os/` packages skills + knowledge + references + contracts + quality gates (~7 MB) via symlinks, dereferenced at install; workspace/site/media junk never ships
+- `version` intentionally omitted from plugin.json → SHA-based auto-updates on every push
+
+**install.sh v2.0.0**
+- Now installs the knowledge base to `~/.claude/kai/` (v1 shipped skills whose referenced frameworks/contracts/gates were never installed)
+- `kaicalls-design` is optional (warn, not fail); uses local checkout when run from one
+- Executable bits fixed on `install.sh`, `setup.sh`, `deploy.sh`, `setup`, `bin/*` (previously `./install.sh` failed on every fresh clone)
+
+**Skills**
+- 34 skills gained a "Kai root note" so `knowledge/`/`harness/`/`scripts/` paths resolve in all three install modes (repo, plugin cache, `~/.claude/kai`) and missing `scripts/` commands are skipped-and-declared, never fabricated
+- `/kai-start`: goal-loop step auto-skips without `scripts/harness_cli.py`; first recommendation is now `/kai-growth-plan` (works anywhere) instead of `/kai-audit` (repo-only collectors)
+- `/kai-audit`: explicit qualitative mode when collectors are unavailable — unmeasured numbers go to `_data-gaps.md`, never estimated
+- Fixed `kai-growth-hacker` YAML frontmatter (unquoted `:` silently dropped all skill metadata)
+
+**Docs**
+- README + Quick Start lead with the plugin path; manual install now includes the knowledge payload; research + design decisions in `docs/install-ux-research.md`
+
 ## v0.2.0 — 2026-03-25
 
 ### Taste, Creative Production & Component Architecture

diff --git a/README.md b/README.md
@@ -32,20 +32,27 @@ See pre-generated examples in `demo/examples/`.
 
 ## Quick Start
 
-Install the skills:
+Inside Claude Code, type two lines — no terminal, no clone, no config:
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/cgallic/kai-cmo-harness/main/install.sh | bash
+```text
+/plugin marketplace add cgallic/kai-cmo-harness
+/plugin install kai@kai-marketing-os
 ```
 
-Open Claude Code in a product repo and run:
+That installs every skill **plus the knowledge base they run on** (frameworks, checklists, channel guides, policy references, quality gates — ~7 MB) and keeps them updated. Then open any product repo and run:
 
 ```text
 /kai-start
 /kai-growth-plan
 ```
 
-`/kai-start` creates or refreshes `MARKETING.md` from the repo. `/kai-growth-plan` turns that context into a stage-specific plan, recommended workflows, metrics, budget notes, and anti-patterns.
+`/kai-start` reads your repo, plays back what your product is, and writes `MARKETING.md` — once, in about 2 minutes. `/kai-growth-plan` turns that context into a stage-specific plan, recommended workflows, metrics, budget notes, and anti-patterns.
+
+Prefer a shell one-liner? Same result:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/cgallic/kai-cmo-harness/main/install.sh | bash
+```
 
 Want the short setup guide? Read [Quick Start](docs/QUICK_START.md).
 
@@ -83,22 +90,23 @@ Autonomous campaign management is a guarded phase, not the starting promise. Kai
 
 ## Install Options
 
-**One-liner:**
+**Plugin (recommended — Claude Code CLI or desktop):** two lines inside Claude Code. Auto-updating, includes the knowledge base, nothing touches your shell.
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/cgallic/kai-cmo-harness/main/install.sh | bash
+```text
+/plugin marketplace add cgallic/kai-cmo-harness
+/plugin install kai@kai-marketing-os
 ```
 
-**Manual:**
+Plugin skills are namespaced: type `/kai:kai-start`, `/kai:kai-growth-plan`, and so on.
+
+**Shell one-liner:** installs skills to `~/.claude/skills/` and the knowledge base to `~/.claude/kai/`. Use this if you prefer un-namespaced commands (`/kai-start`) or want to read the script first.
 
 ```bash
-git clone https://github.com/cgallic/kai-cmo-harness.git /tmp/kai-install \
-  && mkdir -p ~/.claude/skills \
-  && cp -r /tmp/kai-install/harness/skills/kai /tmp/kai-install/harness/skills/kai-* /tmp/kai-install/harness/skills/kaicalls-design ~/.claude/skills/ \
-  && rm -rf /tmp/kai-install \
-  && echo "Installed. Type /kai-start in Claude Code."
+curl -fsSL https://raw.githubusercontent.com/cgallic/kai-cmo-harness/main/install.sh | bash
 ```
 
+**Repo copy (Cursor, Codex, claude.ai/code web, client repos):** these surfaces don't persist `~/.claude/skills`, so put Kai in the repo itself. Clone this repo and copy `AGENTS.md`, `knowledge/`, `harness/`, `memory/`, and `scripts/quality_gates/` into your project root — the agent picks it up from `AGENTS.md` on the next session. Details in [Quick Start](docs/QUICK_START.md).
+
 ## Repository Structure
 
 ```

diff --git a/bin/kai-ab b/bin/kai-ab
diff --git a/bin/kai-brief b/bin/kai-brief
diff --git a/bin/kai-config b/bin/kai-config
diff --git a/bin/kai-gate b/bin/kai-gate
diff --git a/bin/kai-render b/bin/kai-render
diff --git a/bin/kai-report b/bin/kai-report
diff --git a/bin/kai-voice-gate b/bin/kai-voice-gate
diff --git a/deploy.sh b/deploy.sh
diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md
@@ -6,18 +6,23 @@ Kai Marketing OS gives Claude Code a marketing operating surface inside any prod
 
 ### 1. Install
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/cgallic/kai-cmo-harness/main/install.sh | bash
+The fastest path is the plugin — two lines typed inside Claude Code (CLI or desktop):
+
+```text
+/plugin marketplace add cgallic/kai-cmo-harness
+/plugin install kai@kai-marketing-os
 ```
 
-Manual install:
+This installs all skills plus the knowledge base they load (frameworks, checklists, policy references, skill contracts, quality gates) and auto-updates with the repo. Plugin skills are namespaced: `/kai:kai-start`, `/kai:kai-growth-plan`.
+
+Or use the shell installer, which puts skills in `~/.claude/skills/` (un-namespaced: `/kai-start`) and the knowledge base in `~/.claude/kai/`:
 
 ```bash
-git clone https://github.com/cgallic/kai-cmo-harness.git /tmp/kai-install
-cp -r /tmp/kai-install/harness/skills/kai* ~/.claude/skills/
-rm -rf /tmp/kai-install
+curl -fsSL https://raw.githubusercontent.com/cgallic/kai-cmo-harness/main/install.sh | bash
 ```
 
+Skills without the knowledge base run hollow — they load frameworks, contracts, and policy files by path. Both install paths above ship the two together; if you copy skills manually, copy `knowledge/`, `harness/references/`, `harness/skill-contracts/`, `harness/brief-schema.md`, and `scripts/quality_gates/` into `~/.claude/kai/` as well (the same layout `install.sh` produces).
+
 ### 2. Open A Product Repo
 
 ```bash
@@ -79,7 +84,7 @@ Claude Code will read `AGENTS.md` and use Kai's framework map, contracts, refere
 
 | Surface | Count | Examples |
 |---|---:|---|
-| Skill directories | 48 | `/kai`, `/kai-growth-plan`, `/kai-growth-hacker`, `/kai-landing-page`, `/kai-gate` |
+| Skill directories | 49 | `/kai`, `/kai-growth-plan`, `/kai-growth-hacker`, `/kai-landing-page`, `/kai-gate` |
 | Canonical `kai-*` docs | 45 | API-style skill docs with triggers, inputs, outputs, gates |
 | Public router commands | 42 | The commands shown by `/kai` |
 | Playbooks | 54 | CRO, experiments, growth hacker OS, pricing, SEO ops, content repurposing |
@@ -95,7 +100,7 @@ Run these before sharing publishable work:
 ```bash
 python scripts/quality_gates/banned_word_check.py --file draft.md
 python scripts/quality_gates/four_us_score.py --file draft.md
-python scripts/quality_gates/seo_lint.py --file draft.md
+python scripts/quality_gates/seo_lint.py --file draft.md --keyword "target keyword"
 python scripts/quality_gates/mutation_risk_lint.py draft.md
 python scripts/security/sanitize.py draft.md
 ```

diff --git a/docs/install-ux-research.md b/docs/install-ux-research.md
@@ -0,0 +1,66 @@
+# Install UX — Research & Design Decisions (2026-07-05)
+
+Findings from a 5-agent research pass (current-install audit, ICP profile, best-in-class installer research, technical-constraints audit, completeness critic) and the design decisions that came out of it. This doc is the provenance for the plugin packaging, `install.sh` v2, and the skill "Kai root note".
+
+## Who installs Kai
+
+Per `docs/icp-evaluation-prompt.md`, the primary installer is the **terminal-native solo technical founder** (1-5 people, can run Python, manages API keys); secondary: agency operators embedding Kai in client repos, and product engineers who want CI/CD-for-content. Non-technical marketers are explicitly out of scope for the repo funnel (meetkai.xyz routes them to the hosted app instead).
+
+Doctrine that follows: first value in ≤3 minutes, zero API keys or config before value, "cheat code" register not wizard register, curl|bash acceptable, SaaS signup unacceptable.
+
+## What was broken (pre-2.0 install)
+
+1. **Hollow installs.** `install.sh` v1 copied only `harness/skills/` (848K). 34 of 49 skills reference `knowledge/`, `harness/references/`, `harness/skill-contracts/` paths, and 14 invoke `scripts/` Python — none of it installed. The installer verified green while most skills were functionally broken.
+2. **Dead-end first command.** `/kai-start` and the installer both recommended `/kai-audit`, which hard-requires `python -m scripts.audit.collect` — guaranteed failure outside the repo.
+3. **Hard-fail on optional assets.** The installer aborted entirely if `kaicalls-design` reference files were missing.
+4. **No executable bits.** Every installer script was committed mode 644, so the documented `./install.sh`, `./deploy.sh`, `./setup` all failed on fresh clones.
+5. **7+ overlapping install paths** (curl, manual cp, setup.sh A/B, legacy `setup`, repo copy ×2 variants, OpenClaw) that disagree on what to copy and never reference each other.
+6. **Broken frontmatter.** `kai-growth-hacker/SKILL.md` had an unquoted `:` in its description — YAML parse failure, all metadata silently dropped at runtime.
+
+## The design (what shipped)
+
+### Hero path: Claude Code plugin (the "cheat")
+
+The repo is now a **plugin marketplace** (`.claude-plugin/marketplace.json`). Install is two lines typed inside Claude Code, zero terminal:
+
+```text
+/plugin marketplace add cgallic/kai-cmo-harness
+/plugin install kai@kai-marketing-os
+```
+
+Packaging mechanics (verified against code.claude.com/docs/en/plugins-reference and empirically with `claude` CLI v2.1.201):
+
+- Installed plugins are **copied to `~/.claude/plugins/cache`**; paths outside the plugin root break. But **symlinks inside the marketplace are dereferenced at install** — so `plugins/kai-marketing-os/` is a curated directory of symlinks (`skills/` → `harness/skills`, plus `knowledge/`, `harness/references`, `harness/skill-contracts`, `harness/brief-schema.md`, `scripts/quality_gates`). The cache copy materializes ~7 MB of real files and excludes the repo's other ~106 MB (workspace/, .git, site/, mp3s…). Verified locally: 0 symlinks in cache, full payload present, no junk leaked, 49 skills registered, ~7.7k always-on tokens.
+- `version` is intentionally **omitted** from `plugin.json`: version falls back to the git commit SHA, so every push is an update (docs-recommended for actively developed plugins). If we later adopt semver, remember: pushing commits without bumping the string ships nothing.
+- A `CLAUDE.md`/`AGENTS.md` at plugin root is **not** loaded as context from plugins — doctrine must flow through the skills themselves.
+- Plugin skills are namespaced `/kai:kai-start`. The shell-installer path keeps un-namespaced `/kai-start`.
+- Validate with `claude plugin validate ./plugins/kai-marketing-os` (passes; the only warning is the intentional missing version).
+
+### Path resolution: the "Kai root note"
+
+Skills now carry a short note telling the agent to resolve `knowledge/`, `harness/`, `scripts/` paths against the first ancestor directory of the SKILL.md that contains `knowledge/` — which is the plugin cache root, `~/.claude/kai`, or the repo checkout, in all three install modes — and to skip-and-say-so (never fabricate) when a `scripts/` command isn't shipped. `MARKETING.md` and `memory/` always resolve to the user's project.
+
+### install.sh v2
+
+Ships the knowledge base (to `~/.claude/kai/`) alongside the skills, uses a local checkout when run from one, verifies knowledge + gates + skills, treats `kaicalls-design` as optional (warn, not fail), and exits onto `/kai-start` + three commands with time promises. `/kai-audit` is no longer promoted on skills-only installs.
+
+### First-run flow fixes
+
+- `/kai-start` Step 4 (goal loop CLI) is skipped silently when `scripts/harness_cli.py` isn't present; the goal goes into `MARKETING.md` instead.
+- `/kai-start` Step 5 recommends `/kai-growth-plan` (works anywhere) and only recommends `/kai-audit` when the audit collectors exist.
+- `/kai-audit` gained an explicit **qualitative mode** for installs without collectors: cite-what-you-browse, all unmeasured numbers go to `_data-gaps.md`, never estimate what the collector would have measured.
+
+## Verified alternatives considered and rejected
+
+- **`source: "./"` (repo root = plugin):** copies the entire 113 MB working tree into every user's plugin cache; no exclude/ignore mechanism exists in the plugin spec. Rejected for the symlinked curated subdir.
+- **Checked-in copy of the payload under `plugins/`:** ~7 MB duplicated in git, guaranteed drift. Symlinks keep a single source of truth.
+- **`${CLAUDE_PLUGIN_ROOT}` in SKILL.md prose:** documented for hooks/MCP/monitors, not confirmed for skill body text. The root-note convention avoids depending on it.
+
+## Open items (owner decisions / future work)
+
+1. **Windows checkouts without symlink support** materialize git symlinks as text files; a plugin install from such a clone would be broken. Claude Code fetches marketplaces itself (its git), so this mainly affects contributors on Windows. Watch for reports; fallback is `install.sh` under Git Bash/WSL.
+2. **Four U's gate** still requires `google-genai` + `GEMINI_API_KEY` (hardcoded `gemini-2.0-flash`, dotenv path `/opt/cmo-analytics/.env`). Decide: model-self-scored fallback (needs new golden cases per the gate-change rule) vs. keeping it opt-in. The offline gates (banned words, SEO lint, provenance, agent-readiness) work with zero setup.
+3. **Marketplace listing**: consider submitting to `anthropics/claude-plugins-community` (platform.claude.com/plugins/submit) for discovery + Anthropic safety-screening trust signal. Decide first whether `kaicalls-design` and the KaiCalls fit rule belong in a public listing.
+4. **`npx skills add cgallic/kai-cmo-harness`** (Vercel skills CLI, agentskills.io standard) would reach Cursor/Codex/Copilot users; skills already conform. Low effort, separate PR.
+5. **Team onboarding**: committing `extraKnownMarketplaces` + `enabledPlugins` in a client repo's `.claude/settings.json` prompts every collaborator to install Kai on folder-trust — the zero-command agency path.
+6. **Legacy paths to retire**: the root `setup` script (registers the old `/content-*` family), the three conflicting config templates, `kai-upgrade`'s pointer at the wrong repo URL (`kai-marketing.git`), and README's `kai-harness` CLI references (no such wrapper exists — real invocation is `python scripts/harness_cli.py`). Deliberately left out of this change to keep it reviewable.
diff --git a/harness/skills/kai-ad-campaign/SKILL.md b/harness/skills/kai-ad-campaign/SKILL.md
@@ -72,6 +72,8 @@ Output to `workspace/ads/_evaluation-report.md`:
 ```markdown
 # Ad Evaluation Report — [Date]
 
+> **Kai root note:** `knowledge/`, `harness/`, and `scripts/` paths in this skill live in the Kai install, not the user's project. Resolve them against the first ancestor directory of this SKILL.md that contains a `knowledge/` folder (the Kai plugin root, `~/.claude/kai`, or the kai-cmo-harness repo). `MARKETING.md`, `memory/`, and any output files live in the current project. If a referenced `scripts/` command is not available in this install, say so, skip it, and continue with the file-based guidance — never fabricate its output.
+
 ## Summary
 - Active campaigns: [N]
 - Active ads: [N]

diff --git a/harness/skills/kai-audit/SKILL.md b/harness/skills/kai-audit/SKILL.md
@@ -3,6 +3,8 @@ name: kai-audit
 description: Full marketing audit — runs all relevant checklists against your product, site, and marketing in one go. Covers SEO, content, email, ads, social media, CRO, landing pages, technical SEO, and creative production. Produces a "state of your marketing" report with health scores per area and a prioritized fix list. Use when "marketing audit", "full audit", "audit everything", "marketing health check", "what's broken", "state of marketing", or any request to comprehensively assess marketing across all channels.
 ---
 
+> **Kai root note:** `knowledge/`, `harness/`, and `scripts/` paths in this skill live in the Kai install, not the user's project. Resolve them against the first ancestor directory of this SKILL.md that contains a `knowledge/` folder (the Kai plugin root, `~/.claude/kai`, or the kai-cmo-harness repo). `MARKETING.md`, `memory/`, and any output files live in the current project. If a referenced `scripts/` command is not available in this install, say so, skip it, and continue with the file-based guidance — never fabricate its output.
+
 One-click full marketing audit. Runs all relevant harness checklists and produces a health report.
 
 ## Non-Negotiable: Kai Data Provenance
@@ -35,6 +37,8 @@ python scripts/quality_gates/audit_provenance_lint.py workspace/marketing-audit
 
 ## Phase 0.5: Source-Backed Data Acquisition
 
+**If the collector scripts are not available in this install** (skills-only or plugin install — no `scripts/audit/` in the Kai root), run the audit in **qualitative mode**: browse the target's public pages directly, cite the URL and retrieval date for every observation, put every quantitative claim you could not measure into `_data-gaps.md`, and say plainly in the report header that collector-backed metrics require the full harness (github.com/cgallic/kai-cmo-harness). Never estimate a number the collector would have measured.
+
 Before writing the audit, run the source-backed Kai collector. The collector is shared by all Kai workflows, not audit-only; this audit must consume its `audit-data.json` alias. Existing audit automations may keep using `python -m scripts.audit.collect`; non-audit Kai workflows should prefer `python -m kai.source_data.collect` and read `kai-data.json`.
 
 ```bash

diff --git a/harness/skills/kai-brand-pulse/SKILL.md b/harness/skills/kai-brand-pulse/SKILL.md
@@ -5,6 +5,8 @@ description: Multi-platform brand intelligence pulse - collect cited public repu
 
 # kai-brand-pulse - Multi-Platform Brand Intelligence
 
+> **Kai root note:** `knowledge/`, `harness/`, and `scripts/` paths in this skill live in the Kai install, not the user's project. Resolve them against the first ancestor directory of this SKILL.md that contains a `knowledge/` folder (the Kai plugin root, `~/.claude/kai`, or the kai-cmo-harness repo). `MARKETING.md`, `memory/`, and any output files live in the current project. If a referenced `scripts/` command is not available in this install, say so, skip it, and continue with the file-based guidance — never fabricate its output.
+
 Run a cited brand pulse across public reputation surfaces. This is the Kai-native version of the Brand Monitor Agent pattern: collect evidence first, analyze each platform separately, then synthesize into marketing actions.
 
 ## When to Use