@friedbotstudio/create-baseline 0.4.0 → 0.5.0

package/bin/cli.js

@@ -7,7 +7,7 @@ import { existsSync } from 'node:fs';
 
 import * as io from '../src/cli/io.js';
 import { scanSentinels } from '../src/cli/conflict.js';
-import { freshInstall, forceInstall } from '../src/cli/install.js';
+import { freshInstall, forceInstall, COPY_EXCLUDE } from '../src/cli/install.js';
 import { threeWayMerge } from '../src/cli/merge.js';
 import { loadManifest, buildManifestFromDir } from '../src/cli/manifest.js';
 import { fetchPlantumlIfMissing, FETCH_OUTCOMES } from '../src/cli/plantuml.js';
@@ -100,7 +100,13 @@ function getTemplateDir() {
 async function listShippedFiles(templateDir) {
   const out = [];
   await walkFiles(templateDir, templateDir, out);
-  return out;
+  // COPY_EXCLUDE was used to keep the legacy `manifest.json` at the template
+  // root from being copied to the consumer target root. The manifest now
+  // ships at `.claude/manifest.json` so no path-level exclusion is needed;
+  // COPY_EXCLUDE is currently empty but the filter stays so future entries
+  // (e.g., dev-only artifacts that accidentally leak into obj/template) can
+  // be added in one place. See src/cli/install.js → COPY_EXCLUDE.
+  return out.filter((p) => !COPY_EXCLUDE.includes(p));
 }
 
 async function walkFiles(dir, base, acc) {
@@ -111,6 +117,34 @@ async function walkFiles(dir, base, acc) {
   }
 }
 
+// Renders a usage error and the canonical HELP_TEXT through the branded TUI
+// when stderr is a TTY, falling back to plain `Error: <msg>` + help body
+// otherwise. Every non-success exit from `main()` flows through here so the
+// user always sees usage guidance alongside the failure.
+async function usageError(msg) {
+  const version = await readPackageVersion();
+  const meta = await import('../src/cli/tui/meta.js');
+  meta.renderUsageError(msg, HELP_TEXT, version);
+}
+
+// Translates Node's parseArgs error noise into a short, branded message.
+// Node emits e.g. `Unknown option '--upgrade'. To specify a positional ...`
+// which leaks library implementation detail; we collapse it and, where we
+// can identify the user's likely intent (typing `--upgrade` for the
+// `upgrade` subcommand), we hint at the correct shape.
+function friendlyParseArgsMessage(rawMessage) {
+  const firstLine = (rawMessage || '').split('\n')[0];
+  if (/Unknown option ['"]?--upgrade['"]?/.test(firstLine)) {
+    return 'Did you mean `create-baseline upgrade <target>`? `upgrade` is a subcommand, not a flag.';
+  }
+  if (/Unknown option ['"]?--doctor['"]?/.test(firstLine)) {
+    return 'Did you mean `create-baseline doctor <target>`? `doctor` is a subcommand, not a flag.';
+  }
+  const unknown = /Unknown option ['"]?([^'"]+?)['"]?(?:\.|$)/.exec(firstLine);
+  if (unknown) return `Unknown option '${unknown[1]}'.`;
+  return firstLine;
+}
+
 async function dispatchInstall(target, values, templateDir) {
   const dryRun = !!values['dry-run'];
   if (process.stdout.isTTY && !values.force && !dryRun) {
@@ -136,13 +170,13 @@ async function runPlainInstall(target, values, templateDir) {
   const dryRun = !!values['dry-run'];
   if (values.force) {
     if (!process.stdin.isTTY) {
-      io.error('--force requires an interactive TTY for the confirmation prompt');
+      await usageError('--force requires an interactive TTY for the confirmation prompt');
       return 2;
     }
     if (!dryRun) {
       const answer = await io.ask("type 'overwrite' to proceed: ");
       if (answer.toLowerCase() !== 'overwrite') {
-        io.error('confirmation declined');
+        await usageError('confirmation declined');
         return 1;
       }
     }
@@ -157,7 +191,7 @@ async function runPlainInstall(target, values, templateDir) {
       else await freshInstall(templateDir, target, { withNpmrc: !!values['with-npmrc'] });
     }
   } catch (err) {
-    io.error(`install failed: ${err.message}`);
+    await usageError(`install failed: ${err.message}`);
     return 1;
   }
 
@@ -181,7 +215,7 @@ async function fetchPlantumlPlain(target, values) {
     return 0;
   }
   if (result.outcome === FETCH_OUTCOMES.ERRORED_REQUIRE_PLANTUML) {
-    io.error(`--require-plantuml: ${result.reason}`);
+    await usageError(`--require-plantuml: ${result.reason}`);
     return 4;
   }
   return 0;
@@ -190,7 +224,7 @@ async function fetchPlantumlPlain(target, values) {
 async function dispatchUpgrade(target, values, templateDir) {
   const manifestPath = join(target, '.claude/.baseline-manifest.json');
   if (!existsSync(manifestPath)) {
-    io.error(`No baseline manifest at ${manifestPath}. Run a fresh install first.`);
+    await usageError(`No baseline manifest at ${manifestPath}. Run a fresh install first.`);
     return 2;
   }
   if (process.stdout.isTTY) {
@@ -245,10 +279,10 @@ async function main(argv) {
     });
   } catch (err) {
     if (/--merge/.test(err.message)) {
-      io.error('--merge has been removed; use `create-baseline upgrade <target>` instead.');
+      await usageError('--merge has been removed; use `create-baseline upgrade <target>` instead.');
       return 2;
     }
-    io.error(err.message);
+    await usageError(friendlyParseArgsMessage(err.message));
     return 2;
   }
 
@@ -285,23 +319,34 @@ async function main(argv) {
     try {
       templateDir = getTemplateDir();
     } catch (err) {
-      io.error(err.message);
+      await usageError(err.message);
       return 2;
     }
     return await dispatchUpgrade(target, values, templateDir);
   }
 
   if (values['no-plantuml'] && values['require-plantuml']) {
-    io.error('--no-plantuml and --require-plantuml are mutually exclusive');
+    await usageError('--no-plantuml and --require-plantuml are mutually exclusive');
     return 2;
   }
   if (positionals.length === 0) {
-    io.error('missing required <target> argument');
-    io.error(HELP_TEXT);
+    // TTY landing: render the branded splash (skills.sh-style marquee) so the
+    // empty invocation reads as "here's what this tool does" instead of an
+    // angry error. Non-TTY keeps the strict error+help+exit-2 contract so
+    // scripts and CI still detect the missing argument.
+    if (process.stdout.isTTY) {
+      const splash = await import('../src/cli/tui/splash.js');
+      process.stdout.write(splash.renderSplash({
+        tryLine: 'npx @friedbotstudio/create-baseline ./my-project',
+        discoverUrl: 'https://baseline.friedbotstudio.com/',
+      }));
+      return 0;
+    }
+    await usageError('missing required <target> argument');
     return 2;
   }
   if (positionals.length > 1) {
-    io.error(`unexpected positional arguments: ${positionals.slice(1).join(', ')}`);
+    await usageError(`unexpected positional arguments: ${positionals.slice(1).join(', ')}`);
     return 2;
   }
 
@@ -310,15 +355,17 @@ async function main(argv) {
   try {
     templateDir = getTemplateDir();
   } catch (err) {
-    io.error(err.message);
+    await usageError(err.message);
     return 2;
   }
 
   const sentinels = await scanSentinels(target);
   const hasConflict = sentinels.length > 0;
   if (hasConflict && !values.force) {
-    io.error(`existing baseline detected at ${target}: ${sentinels.join(', ')}`);
-    io.error('pass --force to overwrite or use `create-baseline upgrade <target>` to three-way merge');
+    await usageError(
+      `existing baseline detected at ${target}: ${sentinels.join(', ')}. ` +
+        'Pass --force to overwrite or use `create-baseline upgrade <target>` to three-way merge.'
+    );
     return 1;
   }
 

package/obj/template/{manifest.json → .claude/manifest.json}

@@ -1,6 +1,6 @@
 {
   "manifest_version": 2,
-  "generated_at": "2026-05-18T19:07:49.408Z",
+  "generated_at": "2026-05-20T09:13:44.485Z",
   "files": {
     ".claude/agents/swarm-worker.md": "1735a220f268c9765cb22e0567b728803f2edd7776cbde51dd017a9f062ae41f",
     ".claude/bin/LICENSE": "a8dcf2775ab71a58c7d4cc935e3a8e9974e87bb7d6082ee25ef52f8140be8e07",
@@ -56,7 +56,7 @@
     ".claude/skills/archive/SKILL.md": "5174e8b72ab1e830912c231052d1e535023d58f0808434fe1d4abce305b80318",
     ".claude/skills/archive/archive.sh": "29f5b3c8870d0665ce624c6d1b5770f691f1d19f82a201767d5685fc3b0a0b58",
     ".claude/skills/audit-baseline/SKILL.md": "86e9955a99ade89074571320b2b9b0780bc033d201968f62edcca35d9e25f7cb",
-    ".claude/skills/audit-baseline/audit.sh": "8b8a7db4db2aba0e0dd9948e4472feabe568e06a5f4e752c10dcd3da655bedf3",
+    ".claude/skills/audit-baseline/audit.sh": "bd95803bc27cc398564e6df1b89521ead94f3cff458b50497e78fefcced2958e",
     ".claude/skills/audit-baseline/tests/fixtures/_pending_opener_only.md": "9c64d7ef0b3be48b3e87acd89f9ac638db956f2c7cc5adf569d9d97d16f18163",
     ".claude/skills/audit-baseline/tests/fixtures/preamble_full_empty_body.md": "b757223c9b4954882b7f4ac828de7d83a105f74ba0cdf0951fbbe19c07ae892d",
     ".claude/skills/audit-baseline/tests/fixtures/preamble_full_with_entries.md": "9fcd049b006a7474d182a04420df6b3af08e3b6777a2ec5b4031d661ba2f4c82",
@@ -227,8 +227,8 @@
     ".claude/skills/triage/SKILL.md": "499f82a26d77c60af827dd89a7fcb3eae0cd903e34c70740c297bc260aeed38e",
     ".claude/skills/verify/SKILL.md": "fcddba67cf7f3623fc8f8ae142303b16b9db0c9fc1652bc920e16c56fe4c7864",
     ".mcp.json": "8ebb7966045486187bbdf9bac643e690c4fbc7a9a70a8345e3665ba72fa19b96",
-    "CLAUDE.md": "5aff9bb3534792961b3e5c79a23f7ae3a859bb22efc3553c62847f555c61a08d",
-    "docs/init/seed.md": "e0d708ccf06ae1ae124e0a3ada3e77bfbdbb9f2899a548a1729c9270a12f3e98"
+    "CLAUDE.md": "1d87311fa1b177944afe69f060b0ddd31359e5391445034d10dc51ced1503ada",
+    "docs/init/seed.md": "63f3a0c09895f2040f7fdc188cb0e759bd6a47d615759ec7c83671798504a71d"
   },
   "owners": {
     "skills": {
@@ -271,5 +271,5 @@
       "verify": "baseline"
     }
   },
-  "build_id": "gha-26054481720"
+  "build_id": "gha-26153025904"
 }

package/obj/template/.claude/skills/audit-baseline/audit.sh

@@ -49,18 +49,25 @@ EXPECTED_AGENTS = {
     # from main context; they never make decisions.
     "swarm-worker",
 }
-# Skill provenance comes from the shipped manifest at obj/template/manifest.json.
+# Skill provenance comes from the shipped manifest. Two possible locations,
+# tried in order:
+#   1. <root>/.claude/manifest.json — present in consumer projects after the
+#      CLI installs the baseline (the recursive cp puts it there directly).
+#   2. <root>/obj/template/.claude/manifest.json — present in the baseline
+#      dev repo, where `npm run build` writes the manifest before publishing.
 # The build (scripts/build-manifest.mjs) reads owner: frontmatter from every
 # .claude/skills/<slug>/SKILL.md and emits the canonical baseline-skill set as
 # manifest.owners.skills. See CLAUDE.md Article XI and seed.md §17.
 def load_manifest():
-    path = root / "obj/template/manifest.json"
-    if not path.exists():
-        return None
-    try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except Exception:
-        return None
+    for rel in (".claude/manifest.json", "obj/template/.claude/manifest.json"):
+        path = root / rel
+        if not path.exists():
+            continue
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            return None
+    return None
 
 def read_skill_owner(slug):
     p = root / f".claude/skills/{slug}/SKILL.md"
@@ -245,7 +252,7 @@ def check_skill_ownership():
     # Manifest-driven baseline-skill presence + per-file hash check.
     manifest = load_manifest()
     if manifest is None:
-        add("skill ownership: manifest", "WARN", "obj/template/manifest.json missing — run npm run build")
+        add("skill ownership: manifest", "WARN", ".claude/manifest.json (or obj/template/.claude/manifest.json) missing — run npm run build")
         return
     owners_skills = (manifest.get("owners") or {}).get("skills", {}) or {}
     files_map = manifest.get("files") or {}

package/obj/template/CLAUDE.md

@@ -272,13 +272,13 @@ The vendored `impeccable` skill stays untouched (Article IX). `design-ui` is the
 
 ## Article XI — Skill provenance and the baseline manifest
 
-A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project with pre-existing skills can install the baseline without annotating any of its own files. The build script `scripts/build-manifest.mjs` reads each `owner:` value and emits the canonical baseline-skill set into `obj/template/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The CLI mirrors this manifest verbatim to `<target>/.claude/.baseline-manifest.json` on install. The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` as the canonical baseline-skill enumeration — the previous hard-coded `EXPECTED_SKILLS` set is removed.
+A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project with pre-existing skills can install the baseline without annotating any of its own files. The build script `scripts/build-manifest.mjs` reads each `owner:` value and emits the canonical baseline-skill set into the shipped manifest at `obj/template/.claude/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The recursive install copies the manifest straight to `<target>/.claude/manifest.json` (same path inside the `.claude/` subtree, no special-case). The CLI separately writes `<target>/.claude/.baseline-manifest.json` post-install as a runtime sha256 table of the target's actual on-disk contents (used by `doctor` and `upgrade`). The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` from the shipped `.claude/manifest.json` as the canonical baseline-skill enumeration — the previous hard-coded `EXPECTED_SKILLS` set is removed.
 
 You SHALL:
 
 1. **Declare baseline ownership only.** A SKILL.md that ships in the baseline SHALL declare `owner: baseline` in its frontmatter directly after `name:`. Authoring a user/third-party skill does NOT require any `owner:` annotation — absence is the default. Explicit `owner: user` is permitted but never required. The only frontmatter-related FAIL the audit emits is `invalid owner=<value>` (a present-but-malformed `owner:` field, e.g. typo). Missing-`owner:` is silently skipped.
-2. **Trust the manifest.** The shipped `obj/template/manifest.json` (mirrored to `<target>/.claude/.baseline-manifest.json` on install) is the canonical record of baseline-owned skills and their content hashes. You SHALL NOT maintain a separate hard-coded list of baseline-skill slugs anywhere in the codebase.
-3. **Re-derive on drift.** The audit re-derives sha256 hashes from `manifest.files` for every path under `.claude/skills/<slug>/` whose slug appears in `owners.skills`, and compares against on-disk content. Mismatches surface as `hash mismatch at <path>`. A baseline-listed slug missing from disk surfaces as `baseline skill missing`. These are hard FAIL — drift detection has no opt-out.
+2. **Trust the manifest.** The shipped manifest at `obj/template/.claude/manifest.json` (delivered to `<target>/.claude/manifest.json` by the recursive install copy) is the canonical record of baseline-owned skills and their content hashes. The runtime `<target>/.claude/.baseline-manifest.json` written by the CLI post-install is a separate file that captures the target's actual on-disk hashes for `doctor`/`upgrade` — do not conflate the two. You SHALL NOT maintain a separate hard-coded list of baseline-skill slugs anywhere in the codebase.
+3. **Re-derive on drift.** The audit reads the manifest from `<root>/.claude/manifest.json` (consumer projects) with a fallback to `<root>/obj/template/.claude/manifest.json` (the baseline dev repo). It re-derives sha256 hashes from `manifest.files` for every path under `.claude/skills/<slug>/` whose slug appears in `owners.skills`, and compares against on-disk content. Mismatches surface as `hash mismatch at <path>`. A baseline-listed slug missing from disk surfaces as `baseline skill missing`. These are hard FAIL — drift detection has no opt-out.
 4. **Preserve constitutional citation.** This Article XI SHALL remain in CLAUDE.md AND in `src/CLAUDE.template.md` (byte-equal mirror). The genesis §17 in `docs/init/seed.md` SHALL remain present, with `src/seed.template.md` mirroring it. The audit verifies both citations and reports `CLAUDE.md missing Article XI citation` or `seed.md missing §17 citation` on absence.
 5. **Out-of-scope skills don't break the audit.** Any skill on disk that doesn't declare `owner: baseline` is out-of-scope: excluded from the baseline count, the names-match check, and the hash-drift check. Installing the baseline into a project that already has its own skills is zero-friction — no per-file annotation required. Maintenance of those skills is the user's responsibility.
 

package/obj/template/docs/init/seed.md

@@ -591,9 +591,9 @@ Until `/init-project` runs, this section stays empty. Once populated, every fiel
 
 ## §17 — Skill provenance and the baseline manifest
 
-A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Baseline-owned skills are those that ship with the baseline; every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project that already has its own skills can install the baseline without annotating any of those files. The build script `scripts/build-manifest.mjs` reads each `owner:` value at release time and emits the canonical baseline-skill set into `obj/template/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The CLI mirrors this manifest verbatim to `<target>/.claude/.baseline-manifest.json` on `freshInstall`/`forceInstall`/`merge`.
+A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Baseline-owned skills are those that ship with the baseline; every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project that already has its own skills can install the baseline without annotating any of those files. The build script `scripts/build-manifest.mjs` reads each `owner:` value at release time and emits the canonical baseline-skill set into the shipped manifest at `obj/template/.claude/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The recursive install copies the manifest into the consumer target at `<target>/.claude/manifest.json` (same in-tree path, no special-case). The CLI separately writes `<target>/.claude/.baseline-manifest.json` post-install on `freshInstall`/`forceInstall`/`merge` — that file is the runtime snapshot of the target's actual on-disk hashes, consumed by `doctor` and `upgrade`. The two files coexist by design: the shipped manifest is frozen at release time and carries `owners.skills`; the runtime manifest is generated at install time and is hash-only.
 
-The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` as the canonical baseline-skill enumeration (replacing the previous hard-coded `EXPECTED_SKILLS` set). For every baseline-owned skill, the audit re-derives sha256 hashes from `manifest.files` and compares against on-disk content; a mismatch is reported as `hash mismatch at <path>` against the named slug. A baseline skill present in the manifest but absent from disk is reported as `baseline skill missing`. A SKILL.md whose `owner:` field is present but carries an invalid value (anything other than `baseline` or `user`) is reported as `invalid owner=<value>`. SKILL.md files without an `owner:` field are treated as user/third-party and silently skipped — they are excluded from the baseline count, the names-match check, and the hash-drift check, so installing the baseline into a project that already has its own skills never breaks the audit.
+The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` as the canonical baseline-skill enumeration (replacing the previous hard-coded `EXPECTED_SKILLS` set). It reads the manifest from `<root>/.claude/manifest.json` first (consumer projects) and falls back to `<root>/obj/template/.claude/manifest.json` (the baseline dev repo where `npm run build` writes the manifest). For every baseline-owned skill, the audit re-derives sha256 hashes from `manifest.files` and compares against on-disk content; a mismatch is reported as `hash mismatch at <path>` against the named slug. A baseline skill present in the manifest but absent from disk is reported as `baseline skill missing`. A SKILL.md whose `owner:` field is present but carries an invalid value (anything other than `baseline` or `user`) is reported as `invalid owner=<value>`. SKILL.md files without an `owner:` field are treated as user/third-party and silently skipped — they are excluded from the baseline count, the names-match check, and the hash-drift check, so installing the baseline into a project that already has its own skills never breaks the audit.
 
 The audit also verifies constitutional citation: CLAUDE.md SHALL contain the literal string "Article XI" and a reference to the manifest, and `docs/init/seed.md` SHALL contain "§17" and a manifest reference. Missing citations trigger FAIL with `CLAUDE.md missing Article XI citation` or `seed.md missing §17 citation`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@friedbotstudio/create-baseline",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Node CLI scaffolder that materializes the Claude Code baseline (hooks, skills, commands, MCP servers, governance docs) into a target project, with branded interactive install / upgrade / doctor flows. Run via `npx @friedbotstudio/create-baseline <target>`.",
   "type": "module",
   "bin": {

package/src/CLAUDE.template.md

@@ -272,13 +272,13 @@ The vendored `impeccable` skill stays untouched (Article IX). `design-ui` is the
 
 ## Article XI — Skill provenance and the baseline manifest
 
-A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project with pre-existing skills can install the baseline without annotating any of its own files. The build script `scripts/build-manifest.mjs` reads each `owner:` value and emits the canonical baseline-skill set into `obj/template/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The CLI mirrors this manifest verbatim to `<target>/.claude/.baseline-manifest.json` on install. The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` as the canonical baseline-skill enumeration — the previous hard-coded `EXPECTED_SKILLS` set is removed.
+A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project with pre-existing skills can install the baseline without annotating any of its own files. The build script `scripts/build-manifest.mjs` reads each `owner:` value and emits the canonical baseline-skill set into the shipped manifest at `obj/template/.claude/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The recursive install copies the manifest straight to `<target>/.claude/manifest.json` (same path inside the `.claude/` subtree, no special-case). The CLI separately writes `<target>/.claude/.baseline-manifest.json` post-install as a runtime sha256 table of the target's actual on-disk contents (used by `doctor` and `upgrade`). The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` from the shipped `.claude/manifest.json` as the canonical baseline-skill enumeration — the previous hard-coded `EXPECTED_SKILLS` set is removed.
 
 You SHALL:
 
 1. **Declare baseline ownership only.** A SKILL.md that ships in the baseline SHALL declare `owner: baseline` in its frontmatter directly after `name:`. Authoring a user/third-party skill does NOT require any `owner:` annotation — absence is the default. Explicit `owner: user` is permitted but never required. The only frontmatter-related FAIL the audit emits is `invalid owner=<value>` (a present-but-malformed `owner:` field, e.g. typo). Missing-`owner:` is silently skipped.
-2. **Trust the manifest.** The shipped `obj/template/manifest.json` (mirrored to `<target>/.claude/.baseline-manifest.json` on install) is the canonical record of baseline-owned skills and their content hashes. You SHALL NOT maintain a separate hard-coded list of baseline-skill slugs anywhere in the codebase.
-3. **Re-derive on drift.** The audit re-derives sha256 hashes from `manifest.files` for every path under `.claude/skills/<slug>/` whose slug appears in `owners.skills`, and compares against on-disk content. Mismatches surface as `hash mismatch at <path>`. A baseline-listed slug missing from disk surfaces as `baseline skill missing`. These are hard FAIL — drift detection has no opt-out.
+2. **Trust the manifest.** The shipped manifest at `obj/template/.claude/manifest.json` (delivered to `<target>/.claude/manifest.json` by the recursive install copy) is the canonical record of baseline-owned skills and their content hashes. The runtime `<target>/.claude/.baseline-manifest.json` written by the CLI post-install is a separate file that captures the target's actual on-disk hashes for `doctor`/`upgrade` — do not conflate the two. You SHALL NOT maintain a separate hard-coded list of baseline-skill slugs anywhere in the codebase.
+3. **Re-derive on drift.** The audit reads the manifest from `<root>/.claude/manifest.json` (consumer projects) with a fallback to `<root>/obj/template/.claude/manifest.json` (the baseline dev repo). It re-derives sha256 hashes from `manifest.files` for every path under `.claude/skills/<slug>/` whose slug appears in `owners.skills`, and compares against on-disk content. Mismatches surface as `hash mismatch at <path>`. A baseline-listed slug missing from disk surfaces as `baseline skill missing`. These are hard FAIL — drift detection has no opt-out.
 4. **Preserve constitutional citation.** This Article XI SHALL remain in CLAUDE.md AND in `src/CLAUDE.template.md` (byte-equal mirror). The genesis §17 in `docs/init/seed.md` SHALL remain present, with `src/seed.template.md` mirroring it. The audit verifies both citations and reports `CLAUDE.md missing Article XI citation` or `seed.md missing §17 citation` on absence.
 5. **Out-of-scope skills don't break the audit.** Any skill on disk that doesn't declare `owner: baseline` is out-of-scope: excluded from the baseline count, the names-match check, and the hash-drift check. Installing the baseline into a project that already has its own skills is zero-friction — no per-file annotation required. Maintenance of those skills is the user's responsibility.
 

package/src/cli/install.js

@@ -12,15 +12,13 @@ const NPMRC_TEMPLATE_PATH = join(PACKAGE_ROOT, 'src/.npmrc.template');
 
 export const NEVER_TOUCH = Object.freeze(['.claude/project.json']);
 export const SPECIAL_MERGE = Object.freeze(['.mcp.json']);
-// Files present in the shipped template that must NOT be cp'd to target. These
-// are reference artifacts the CLI consults from templateDir (or that ship for
-// inspection-time provenance), never materialized at consumer project root.
-// `manifest.json`: the shipped sha256 table. The CLI's runtime manifest lives
-// at `target/.claude/.baseline-manifest.json` (written by writeBaselineManifest);
-// `target/manifest.json` would be a confusing duplicate. Keep the file in the
-// published tarball so anyone inspecting `node_modules/<pkg>/obj/template/` can
-// see what shipped, but exclude it from the fresh/force install copy.
-export const COPY_EXCLUDE = Object.freeze(['manifest.json']);
+// The shipped manifest now lives at `.claude/manifest.json` (inside the
+// template's .claude/ subtree), so the recursive cp drops it at the correct
+// consumer path without any special-case filtering. The consumer-side audit
+// (`.claude/skills/audit-baseline/audit.sh`) reads it from there for
+// hash-drift detection. COPY_EXCLUDE stays as a list (currently empty) so
+// future never-copy artifacts can be added without API churn at the callers.
+export const COPY_EXCLUDE = Object.freeze([]);
 
 async function listFiles(root, base = root, acc = []) {
   for (const entry of await readdir(root, { withFileTypes: true })) {

package/src/cli/tui/install.js

@@ -6,6 +6,7 @@ import * as clackModule from '@clack/prompts';
 import { readFile } from 'node:fs/promises';
 import { freshInstall, forceInstall } from '../install.js';
 import { fetchPlantumlIfMissing, FETCH_OUTCOMES } from '../plantuml.js';
+import { renderBrandStrip } from './splash.js';
 
 const SUCCESS = 0;
 const ERR_INSTALL_FAILED = 1;
@@ -20,7 +21,8 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
   }
 
   const version = await readPackageVersion();
-  prompts.intro(`create-baseline v${version}`);
+  process.stdout.write(renderBrandStrip({ version, subtitle: 'install' }));
+  prompts.intro('create-baseline');
 
   const spinner = prompts.spinner();
   spinner.start('Copying baseline files');

package/src/cli/tui/meta.js

@@ -1,24 +1,30 @@
-// Domain — branded renderers for the meta commands (--help, --version).
-// In a TTY, a brand banner frames the canonical body; in non-TTY the body is
-// emitted unchanged so that piped consumers (`$(cli --version)`, `cli --help |
-// grep ...`) keep working byte-clean.
+// Domain — branded renderers for the meta commands (--help, --version) and
+// for usage-class errors. In a TTY, the splash marquee (wordmark + brand
+// strip from splash.js) frames the canonical body; in non-TTY the body is
+// emitted unchanged so that piped consumers (`$(cli --version)`,
+// `cli --help | grep ...`) keep working byte-clean.
 
-import { accent, muted, rule } from './tokens.js';
+import { accent, muted, rule, error as errorPaint } from './tokens.js';
+import {
+  renderSplash,
+  renderBrandStrip,
+  renderVersionMarquee,
+  wordmarkFits,
+} from './splash.js';
 
-export function renderHelp(helpText, version) {
-  if (!process.stdout.isTTY) {
-    process.stdout.write(helpText.endsWith('\n') ? helpText : helpText + '\n');
+const DISCOVER_URL = 'https://baseline.friedbotstudio.com/';
+
+export function renderHelp(helpText, _version) {
+  const body = helpText.endsWith('\n') ? helpText : helpText + '\n';
+  if (!process.stdout.isTTY || !wordmarkFits()) {
+    process.stdout.write(body);
     return;
   }
-  const banner = [
-    '',
-    `  ${accent('Baseline CLI')}  ${muted(`v${version}`)}`,
-    `  ${muted('@friedbotstudio/create-baseline')}`,
-    `  ${rule('─'.repeat(48))}`,
-    '',
-  ].join('\n');
-  process.stdout.write(banner + '\n');
-  process.stdout.write(helpText.endsWith('\n') ? helpText : helpText + '\n');
+  process.stdout.write(renderSplash({
+    tryLine: 'npx @friedbotstudio/create-baseline ./my-project',
+    discoverUrl: DISCOVER_URL,
+  }));
+  process.stdout.write(body);
 }
 
 export function renderVersion(version) {
@@ -26,5 +32,32 @@ export function renderVersion(version) {
     process.stdout.write(`${version}\n`);
     return;
   }
-  process.stdout.write(`${accent('baseline')} ${muted('v')}${version}\n`);
+  if (wordmarkFits()) {
+    process.stdout.write(renderVersionMarquee(version));
+    return;
+  }
+  process.stdout.write(renderBrandStrip({ version }));
+}
+
+// Usage errors always print to stderr (so a `cli ... 2>/dev/null` pipeline
+// can still consume stdout cleanly). In a TTY we wrap the message and the
+// HELP_TEXT body in the same brand banner used by --help, with the error
+// label painted in --mac-red. In non-TTY we emit a plain `Error: <msg>`
+// line followed by the canonical help body — same body, no ANSI.
+export function renderUsageError(msg, helpText, version) {
+  const body = helpText.endsWith('\n') ? helpText : helpText + '\n';
+  if (!process.stderr.isTTY) {
+    process.stderr.write(`Error: ${msg}\n`);
+    process.stderr.write(body);
+    return;
+  }
+  const banner = [
+    '',
+    `  ${errorPaint('Error')}  ${msg}`,
+    `  ${muted(`@friedbotstudio/create-baseline v${version}`)}`,
+    `  ${rule('─'.repeat(48))}`,
+    '',
+  ].join('\n');
+  process.stderr.write(banner + '\n');
+  process.stderr.write(body);
 }

package/src/cli/tui/splash.js

@@ -0,0 +1,111 @@
+// Domain — branded splash surfaces for the CLI. Renders a chunky pixel-art
+// "BASELINE" wordmark in three bands of FBS orange (bevel: shadow / mid /
+// highlight / mid / shadow) so the marquee surfaces (--help, --version,
+// no-arg landing) share a single visual identity. Slimmer brand strip is
+// reused by install / upgrade intros and inside the usage-error renderer.
+//
+// All renderers degrade cleanly when stdout is not a TTY or NO_COLOR is set
+// (paintRGB short-circuits to plain text). When the terminal is narrower
+// than the wordmark, callers should fall through to the plain banner via
+// `wordmarkFits(width)` instead of letting the glyphs wrap.
+
+import { paintRGB, PALETTE, accent, muted } from './tokens.js';
+
+// ANSI-Shadow style block-letter wordmark for "BASELINE". 5 rows × ~60 cols.
+// Kept as raw strings (not paint-wrapped) so renderWordmark can apply a
+// per-row shade. Trailing spaces matter — they're part of the glyph shape.
+const WORDMARK = [
+  '██████   █████  ███████ ███████ ██      ██ ███    ██ ███████',
+  '██   ██ ██   ██ ██      ██      ██      ██ ████   ██ ██     ',
+  '██████  ███████ ███████ █████   ██      ██ ██ ██  ██ █████  ',
+  '██   ██ ██   ██      ██ ██      ██      ██ ██  ██ ██ ██     ',
+  '██████  ██   ██ ███████ ███████ ███████ ██ ██   ████ ███████',
+];
+
+// Outline trace — mirrors the bottom row of the wordmark using the upper
+// one-eighth block (▔) so it visually kisses the base of every letter,
+// producing the subtle "letters are sitting on a baseline" shadow from
+// the skills.sh reference. Painted in accentShadow so it reads as a
+// trace, not a fifth band of the letter body.
+const WORDMARK_OUTLINE = WORDMARK[4].replace(/█/g, '▔');
+
+// Bevel banding: dim → mid → bright → mid → dim. Produces the chiseled
+// pixel-art look of the skills.sh reference (substituting FBS oranges for
+// the reference's grayscale palette).
+const SHADES = [
+  PALETTE.accentShadow,
+  PALETTE.accent,
+  PALETTE.accentLight,
+  PALETTE.accent,
+  PALETTE.accentShadow,
+];
+
+const WORDMARK_WIDTH = Math.max(...WORDMARK.map((row) => row.length));
+
+export const SPLASH_COMMANDS = Object.freeze([
+  ['$ npx @friedbotstudio/create-baseline <target>', 'Install the baseline'],
+  ['$ npx @friedbotstudio/create-baseline upgrade',  'Three-way merge upgrade'],
+  ['$ npx @friedbotstudio/create-baseline doctor',   'Drift report'],
+]);
+
+// `process.stdout.columns` is 0 (not undefined) under `script(1)` and some
+// CI ptys; treat any falsy value as "unknown, assume wide enough" so the
+// marquee renders rather than silently degrading to the plain banner.
+export function wordmarkFits(columns) {
+  const cols = columns ?? process.stdout.columns;
+  if (!cols) return true;
+  return cols >= WORDMARK_WIDTH;
+}
+
+export function renderWordmark() {
+  const bands = WORDMARK.map((row, i) => paintRGB(SHADES[i], row));
+  bands.push(paintRGB(PALETTE.accentShadow, WORDMARK_OUTLINE));
+  return bands.join('\n');
+}
+
+// Full marquee splash. Used by --help in TTY and the no-arg landing. The
+// version is intentionally NOT rendered here — `--version` already surfaces
+// it via renderVersionMarquee, and embedding it in the splash would force
+// docs-site screenshots to re-render every release.
+export function renderSplash({ tagline, tryLine, discoverUrl } = {}) {
+  const lines = [
+    '',
+    `${muted('▲')} ${muted('~/')} ${muted('npx @friedbotstudio/create-baseline@latest')}`,
+    '',
+    renderWordmark(),
+    '',
+    muted(tagline ?? 'The Claude Code baseline — hooks, skills, MCP, governance.'),
+    '',
+  ];
+  for (const [cmd, desc] of SPLASH_COMMANDS) {
+    const left = `  ${cmd}`;
+    lines.push(`${left.padEnd(54)}${muted(desc)}`);
+  }
+  if (tryLine) {
+    lines.push('');
+    lines.push(`${muted('try:')} ${tryLine}`);
+  }
+  if (discoverUrl) {
+    lines.push('');
+    lines.push(`${muted('Discover more at')} ${discoverUrl}`);
+  }
+  lines.push('');
+  lines.push(`${muted('▲')} ${muted('~/')}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+// Slim two-line brand strip. Used by install / upgrade intros, --version,
+// and the top of the usage-error renderer. Cheap and width-safe (~32 cols).
+export function renderBrandStrip({ version, subtitle } = {}) {
+  const left = `${accent('▲ BASELINE')}`;
+  const right = version ? `  ${muted(`v${version}`)}` : '';
+  const sub = subtitle ? `\n  ${muted(subtitle)}` : '';
+  return ['', `${left}${right}${sub}`, ''].join('\n');
+}
+
+// --version flourish: the wordmark + a version line. Wider than the strip;
+// callers should fall back to renderBrandStrip when the terminal is narrow.
+export function renderVersionMarquee(version) {
+  return ['', renderWordmark(), '', `  ${muted(`v${version}`)}`, ''].join('\n');
+}

package/src/cli/tui/tokens.js

@@ -6,6 +6,7 @@
 const NO_COLOR = process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '';
 
 // oklch -> approximate sRGB hex used in the rendered docs site:
+//   --accent-shadow oklch(35% 0.15 41.5)   ~ #7a2907   (dark band of the wordmark bevel)
 //   --accent       oklch(55.8% 0.187 41.5) ~ #c2410c   (orange-700)
 //   --accent-light oklch(70.3% 0.187 41.5) ~ #ea6a25   (orange-500)
 //   --muted        oklch(45% 0.026 257)    ~ #6b7280
@@ -14,6 +15,7 @@ const NO_COLOR = process.env.NO_COLOR !== undefined && process.env.NO_COLOR !==
 //   --mac-red      oklch(70% 0.21 24)      ~ #ef4444
 //   --rule         oklch(89% 0.013 257)    ~ #d1d5db
 const RGB = {
+  accentShadow: [122, 41, 7],
   accent: [194, 65, 12],
   accentLight: [234, 106, 37],
   muted: [107, 114, 128],
@@ -23,16 +25,21 @@ const RGB = {
   rule: [209, 213, 219],
 };
 
-function paint(rgb, text) {
+// Exposed for the splash wordmark, which paints individual rows in their own
+// shade. All other UI tokens funnel through the named helpers below.
+export function paintRGB(rgb, text) {
   if (NO_COLOR || !process.stdout.isTTY) return text;
   const [r, g, b] = rgb;
   return `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`;
 }
 
-export const accent = (text) => paint(RGB.accent, text);
-export const accentLight = (text) => paint(RGB.accentLight, text);
-export const muted = (text) => paint(RGB.muted, text);
-export const success = (text) => paint(RGB.success, text);
-export const warn = (text) => paint(RGB.warn, text);
-export const error = (text) => paint(RGB.error, text);
-export const rule = (text) => paint(RGB.rule, text);
+export const PALETTE = Object.freeze(RGB);
+
+export const accentShadow = (text) => paintRGB(RGB.accentShadow, text);
+export const accent = (text) => paintRGB(RGB.accent, text);
+export const accentLight = (text) => paintRGB(RGB.accentLight, text);
+export const muted = (text) => paintRGB(RGB.muted, text);
+export const success = (text) => paintRGB(RGB.success, text);
+export const warn = (text) => paintRGB(RGB.warn, text);
+export const error = (text) => paintRGB(RGB.error, text);
+export const rule = (text) => paintRGB(RGB.rule, text);

package/src/cli/tui/upgrade.js

@@ -7,10 +7,12 @@
 
 import * as clackModule from '@clack/prompts';
 import { existsSync } from 'node:fs';
-import { readdir } from 'node:fs/promises';
+import { readdir, readFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 import { threeWayMerge, ACTION_KINDS } from '../merge.js';
 import { loadManifest, buildManifestFromDir } from '../manifest.js';
+import { COPY_EXCLUDE } from '../install.js';
+import { renderBrandStrip } from './splash.js';
 
 const SUCCESS = 0;
 const ERR_ABORT = 1;
@@ -37,6 +39,8 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
     return ERR_NO_MANIFEST;
   }
 
+  const version = await readPackageVersion();
+  process.stdout.write(renderBrandStrip({ version, subtitle: 'upgrade' }));
   prompts.intro('create-baseline upgrade');
 
   const { oldManifest, newManifest } = await loadManifests(opts.templateDir, manifestPath);
@@ -90,11 +94,26 @@ async function loadManifests(templateDir, manifestPath) {
   return { oldManifest, newManifest };
 }
 
+async function readPackageVersion() {
+  try {
+    const url = new URL('../../../package.json', import.meta.url);
+    const pkg = JSON.parse(await readFile(url, 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
 async function listShippedFiles(root, base = root, acc = []) {
   for (const entry of await readdir(root, { withFileTypes: true })) {
     const full = join(root, entry.name);
     if (entry.isDirectory()) await listShippedFiles(full, base, acc);
     else if (entry.isFile()) acc.push(relative(base, full).split(sep).join('/'));
   }
-  return acc;
+  // COPY_EXCLUDE (single source of truth in install.js) now lists no paths —
+  // the shipped manifest moved into `.claude/manifest.json` so the recursive
+  // walk picks it up at the same path the consumer expects. The filter stays
+  // for forward-compat; if a future path needs to be kept out of the merge,
+  // add it to install.js → COPY_EXCLUDE in one place.
+  return acc.filter((p) => !COPY_EXCLUDE.includes(p));
 }

package/src/seed.template.md

@@ -591,9 +591,9 @@ Until `/init-project` runs, this section stays empty. Once populated, every fiel
 
 ## §17 — Skill provenance and the baseline manifest
 
-A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Baseline-owned skills are those that ship with the baseline; every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project that already has its own skills can install the baseline without annotating any of those files. The build script `scripts/build-manifest.mjs` reads each `owner:` value at release time and emits the canonical baseline-skill set into `obj/template/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The CLI mirrors this manifest verbatim to `<target>/.claude/.baseline-manifest.json` on `freshInstall`/`forceInstall`/`merge`.
+A skill at `.claude/skills/<slug>/SKILL.md` is **baseline-owned** iff its YAML frontmatter declares `owner: baseline`. Baseline-owned skills are those that ship with the baseline; every other skill on disk — those without an `owner:` field, or those declaring `owner: user` — is user/third-party and out-of-scope of baseline audit checks. Absence-of-`owner` is the deliberate default so a project that already has its own skills can install the baseline without annotating any of those files. The build script `scripts/build-manifest.mjs` reads each `owner:` value at release time and emits the canonical baseline-skill set into the shipped manifest at `obj/template/.claude/manifest.json` under `owners.skills` (a JSON object mapping slug → `"baseline"`). The recursive install copies the manifest into the consumer target at `<target>/.claude/manifest.json` (same in-tree path, no special-case). The CLI separately writes `<target>/.claude/.baseline-manifest.json` post-install on `freshInstall`/`forceInstall`/`merge` — that file is the runtime snapshot of the target's actual on-disk hashes, consumed by `doctor` and `upgrade`. The two files coexist by design: the shipped manifest is frozen at release time and carries `owners.skills`; the runtime manifest is generated at install time and is hash-only.
 
-The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` as the canonical baseline-skill enumeration (replacing the previous hard-coded `EXPECTED_SKILLS` set). For every baseline-owned skill, the audit re-derives sha256 hashes from `manifest.files` and compares against on-disk content; a mismatch is reported as `hash mismatch at <path>` against the named slug. A baseline skill present in the manifest but absent from disk is reported as `baseline skill missing`. A SKILL.md whose `owner:` field is present but carries an invalid value (anything other than `baseline` or `user`) is reported as `invalid owner=<value>`. SKILL.md files without an `owner:` field are treated as user/third-party and silently skipped — they are excluded from the baseline count, the names-match check, and the hash-drift check, so installing the baseline into a project that already has its own skills never breaks the audit.
+The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.skills` as the canonical baseline-skill enumeration (replacing the previous hard-coded `EXPECTED_SKILLS` set). It reads the manifest from `<root>/.claude/manifest.json` first (consumer projects) and falls back to `<root>/obj/template/.claude/manifest.json` (the baseline dev repo where `npm run build` writes the manifest). For every baseline-owned skill, the audit re-derives sha256 hashes from `manifest.files` and compares against on-disk content; a mismatch is reported as `hash mismatch at <path>` against the named slug. A baseline skill present in the manifest but absent from disk is reported as `baseline skill missing`. A SKILL.md whose `owner:` field is present but carries an invalid value (anything other than `baseline` or `user`) is reported as `invalid owner=<value>`. SKILL.md files without an `owner:` field are treated as user/third-party and silently skipped — they are excluded from the baseline count, the names-match check, and the hash-drift check, so installing the baseline into a project that already has its own skills never breaks the audit.
 
 The audit also verifies constitutional citation: CLAUDE.md SHALL contain the literal string "Article XI" and a reference to the manifest, and `docs/init/seed.md` SHALL contain "§17" and a manifest reference. Missing citations trigger FAIL with `CLAUDE.md missing Article XI citation` or `seed.md missing §17 citation`.