@jstn-sdk/ma 0.1.13 → 0.14.0

package/scripts/install.sh

@@ -1,8 +1,20 @@
 #!/usr/bin/env sh
 set -eu
 
-MA_PACKAGE="${MA_PACKAGE:-@jstn-sdk/ma@latest}"
+MA_PACKAGE="${MA_PACKAGE:-@jstn-sdk/ma@0.14.0}"
 CODEX_PACKAGE="${CODEX_PACKAGE:-@openai/codex@latest}"
+NO_SETUP=0
+NO_SKILLS=0
+DRY_RUN=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --no-setup) NO_SETUP=1 ;;
+    --no-skills) NO_SKILLS=1 ;;
+    --dry-run) DRY_RUN=1 ;;
+    *) echo "meta-architect install: unknown option: $arg" >&2; exit 2 ;;
+  esac
+done
 
 need_cmd() {
   command -v "$1" >/dev/null 2>&1 || {
@@ -14,14 +26,31 @@ need_cmd() {
 need_cmd npm
 need_cmd node
 
-echo "meta-architect install: installing Codex + Meta-Architect"
+echo "meta-architect install: plan"
+echo "  install: $CODEX_PACKAGE $MA_PACKAGE"
+echo "  setup: $([ "$NO_SETUP" -eq 1 ] && echo disabled || echo enabled)"
+echo "  skills: $([ "$NO_SKILLS" -eq 1 ] && echo disabled || echo enabled)"
+echo "  undo: npm uninstall -g $MA_PACKAGE $CODEX_PACKAGE"
+
+if [ "$DRY_RUN" -eq 1 ]; then
+  echo "meta-architect install: dry-run complete"
+  exit 0
+fi
+
+if [ "$NO_SKILLS" -eq 1 ]; then export MA_SKIP_SKILLS=1; fi
 npm i -g "$CODEX_PACKAGE" "$MA_PACKAGE"
+echo "meta-architect install: versions"
+node --version
+npm --version
+command -v codex >/dev/null 2>&1 && codex --version || echo "codex: unavailable"
 
-if command -v ma >/dev/null 2>&1; then
+if command -v ma >/dev/null 2>&1 && [ "$NO_SETUP" -eq 0 ]; then
   echo "meta-architect install: seeding local MA runtime"
-  ma setup >/dev/null
+  ma setup
   echo "meta-architect install: ready"
   echo "start: ma --madmax --high"
+elif [ "$NO_SETUP" -eq 1 ]; then
+  echo "meta-architect install: setup disabled by --no-setup"
 else
   echo "meta-architect install: ma command not found after npm install" >&2
   exit 1

package/scripts/install.sh.sha256

@@ -0,0 +1 @@
+0a18d94ded8872eae750cd2cc4a5b6ab05a6c48796def3634bc2414b3d48f7f7  scripts/install.sh

package/scripts/linux-package-smoke.mjs

@@ -3,9 +3,9 @@
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import process from "node:process";
+import { createTestNamespace } from "../src/test-fixtures.js";
 import {
   getDebArtifactPath,
   getPacmanArtifactPath,
@@ -61,7 +61,7 @@ async function main() {
     throw new Error("Native Linux package smoke validation is supported only on Linux hosts");
   }
 
-  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "meta-architect-linux-smoke-"));
+  const tempRoot = createTestNamespace("meta-architect-linux-smoke");
   const debExtractRoot = path.join(tempRoot, "deb");
   const pacmanExtractRoot = path.join(tempRoot, "pacman");
   const rpmExtractRoot = path.join(tempRoot, "rpm");

package/scripts/package-size-check.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+
+const budget = Number(process.env.MA_PACKAGE_SIZE_BUDGET ?? 5 * 1024 * 1024);
+const result = spawnSync("npm", ["pack", "--dry-run", "--json", "--ignore-scripts"], {
+  encoding: "utf8",
+});
+if (result.status !== 0) throw new Error(result.stderr || "npm pack inspection failed");
+const pack = JSON.parse(result.stdout)[0];
+const excludedMedia = pack.files.filter((file) => /docs\/assets\//.test(file.path));
+if (excludedMedia.length > 0)
+  throw new Error(
+    `Heavy demo media included: ${excludedMedia.map((file) => file.path).join(", ")}`,
+  );
+const unexpectedExecutables = pack.files.filter(
+  (file) =>
+    file.mode === 493 && !file.path.startsWith("bin/") && !/^scripts\/[^/]+\.sh$/.test(file.path),
+);
+if (unexpectedExecutables.length > 0) {
+  throw new Error(
+    `Unexpected executable package files: ${unexpectedExecutables.map((file) => file.path).join(", ")}`,
+  );
+}
+console.log(`package size: ${pack.size} bytes (budget ${budget})`);
+if (pack.size > budget) throw new Error(`Package exceeds ${budget} byte budget`);

package/scripts/plugin-sync.js

@@ -3,6 +3,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
+import { fileURLToPath } from "node:url";
 
 const repoRoot = process.cwd();
 const skillsRoot = path.join(repoRoot, "skills");
@@ -30,10 +31,23 @@ async function copyDir(src, dest) {
   }
 }
 
+async function linkOrCopyDir(src, dest) {
+  if (process.env.MA_PLUGIN_SYNC_MODE !== "copy") {
+    try {
+      await fs.symlink(path.relative(path.dirname(dest), src), dest, "dir");
+      return "symlink";
+    } catch {
+      // Restricted worktrees and Windows may reject directory links.
+    }
+  }
+  await copyDir(src, dest);
+  return "copy";
+}
+
 async function listSkillDirs(root) {
-  const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+  const entries = await fs.readdir(root, { withFileTypes: true });
   return entries
-    .filter((entry) => entry.isDirectory())
+    .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
     .map((entry) => entry.name)
     .sort();
 }
@@ -53,24 +67,74 @@ async function syncPluginSkills() {
     const src = path.join(skillsRoot, name);
     const dest = path.join(pluginSkillsRoot, name);
     await fs.rm(dest, { recursive: true, force: true });
-    await copyDir(src, dest);
+    await linkOrCopyDir(src, dest);
   }
 
   return skillDirs;
 }
 
-async function verifyPluginSkills() {
-  const skillDirs = await listSkillDirs(skillsRoot);
-  const pluginDirs = await listSkillDirs(pluginSkillsRoot);
-  if (skillDirs.length !== pluginDirs.length) {
-    throw new Error("Plugin skill mirror drift: directory count mismatch");
+async function listFiles(root, current = root, files = []) {
+  const entries = await fs.readdir(current, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = path.join(current, entry.name);
+    if (entry.isDirectory() || entry.isSymbolicLink()) {
+      await listFiles(root, absolutePath, files);
+    } else if (entry.isFile()) {
+      files.push(path.relative(root, absolutePath));
+    }
+  }
+  return files.sort();
+}
+
+export async function verifyPluginSkills(sourceRoot = skillsRoot, mirrorRoot = pluginSkillsRoot) {
+  await fs.access(sourceRoot);
+  await fs.access(mirrorRoot);
+  const sourceSkillDirs = await listSkillDirs(sourceRoot);
+  const mirrorSkillDirs = await listSkillDirs(mirrorRoot);
+  const filesForSkillDirs = async (root, skillDirs) => {
+    const files = [];
+    for (const skillDir of skillDirs) {
+      for (const relativePath of await listFiles(path.join(root, skillDir))) {
+        files.push(path.join(skillDir, relativePath));
+      }
+    }
+    return files.sort();
+  };
+  const sourceFiles = await filesForSkillDirs(sourceRoot, sourceSkillDirs);
+  const mirrorFiles = await filesForSkillDirs(mirrorRoot, mirrorSkillDirs);
+  if (JSON.stringify(sourceFiles) !== JSON.stringify(mirrorFiles)) {
+    throw new Error("Plugin skill mirror drift: file set mismatch");
   }
 
-  for (let index = 0; index < skillDirs.length; index += 1) {
-    if (skillDirs[index] !== pluginDirs[index]) {
-      throw new Error(
-        `Plugin skill mirror drift: expected ${skillDirs[index]}, found ${pluginDirs[index]}`,
-      );
+  for (const relativePath of sourceFiles) {
+    const sourcePath = path.join(sourceRoot, relativePath);
+    const mirrorPath = path.join(mirrorRoot, relativePath);
+    const [source, mirror, sourceStat, mirrorStat] = await Promise.all([
+      fs.readFile(sourcePath),
+      fs.readFile(mirrorPath),
+      fs.stat(sourcePath),
+      fs.stat(mirrorPath),
+    ]);
+    if (!source.equals(mirror)) {
+      throw new Error(`Plugin skill mirror drift: content mismatch at ${relativePath}`);
+    }
+    if ((sourceStat.mode & 0o777) !== (mirrorStat.mode & 0o777)) {
+      throw new Error(`Plugin skill mirror drift: mode mismatch at ${relativePath}`);
+    }
+  }
+  for (const skillDir of sourceSkillDirs) {
+    const mirrorPath = path.join(mirrorRoot, skillDir);
+    const mirrorStat = await fs.lstat(mirrorPath);
+    if (mirrorStat.isSymbolicLink()) {
+      const [sourceRealPath, mirrorRealPath] = await Promise.all([
+        fs.realpath(path.join(sourceRoot, skillDir)),
+        fs.realpath(mirrorPath),
+      ]);
+      if (sourceRealPath !== mirrorRealPath) {
+        throw new Error(`Plugin skill mirror drift: invalid symlink target at ${skillDir}`);
+      }
+    } else if (!mirrorStat.isDirectory()) {
+      throw new Error(`Plugin skill mirror drift: invalid mirror entry at ${skillDir}`);
     }
   }
 }
@@ -87,7 +151,9 @@ async function main() {
   console.log(pluginSkillsRoot);
 }
 
-main().catch((error) => {
-  console.error(error.message);
-  process.exitCode = 1;
-});
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/scripts/postinstall.js

@@ -1,20 +1,27 @@
 #!/usr/bin/env node
 
+import fs from "node:fs/promises";
 import process from "node:process";
-import { installSkills, installSupportBundle } from "../src/skill-installer.js";
 
 async function main() {
-  if (process.env.MA_SKIP_AUTO_INSTALL === "1") {
-    console.log("meta-architect: skipped Codex skill auto-install");
+  const dryRun = process.env.MA_POSTINSTALL_DRY_RUN === "1";
+  const skipSkills = process.env.MA_SKIP_SKILLS === "1";
+  const receiptPath = process.env.MA_POSTINSTALL_RECEIPT;
+  console.log(
+    `meta-architect: postinstall skills=${skipSkills ? "disabled" : "enabled"} dry-run=${dryRun ? "yes" : "no"}`,
+  );
+  if (dryRun || skipSkills || process.env.MA_SKIP_AUTO_INSTALL === "1") {
+    console.log("meta-architect: deferred host selection until first interactive launch");
     return;
   }
-
-  const [
-    { targetRoot: skillRoot, installed: skills },
-    { targetRoot: bundleRoot, installed: assets },
-  ] = await Promise.all([installSkills(), installSupportBundle()]);
-  console.log(`meta-architect: installed ${skills.length} Codex skills into ${skillRoot}`);
-  console.log(`meta-architect: installed ${assets.length} support assets into ${bundleRoot}`);
+  console.log("meta-architect: host selection deferred until first interactive launch");
+  if (receiptPath) {
+    await fs.writeFile(
+      receiptPath,
+      `${JSON.stringify({ schemaVersion: "0.1.0", deferred: true }, null, 2)}\n`,
+    );
+    console.log(`meta-architect: receipt ${receiptPath}`);
+  }
 }
 
 main().catch((error) => {

package/scripts/prepack.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+
+execFileSync(process.execPath, ["./scripts/plugin-sync.js"], {
+  stdio: "inherit",
+  env: { ...process.env, MA_PLUGIN_SYNC_MODE: "copy" },
+});

package/scripts/release-sync.js

@@ -31,6 +31,8 @@ const WATCHED_FILES = new Set([
 function parseArgs(argv) {
   const args = {
     bump: "",
+    version: "",
+    refreshFrom: "",
     fromRef: "",
     toRef: "",
     githubOutput: "",
@@ -44,6 +46,16 @@ function parseArgs(argv) {
       index += 1;
       continue;
     }
+    if (token === "--version") {
+      args.version = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+    if (token === "--refresh-from") {
+      args.refreshFrom = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
     if (token === "--from-ref") {
       args.fromRef = argv[index + 1] ?? "";
       index += 1;
@@ -184,6 +196,12 @@ function updateCurrentSurfaceFile(file, oldVersion, nextVersion) {
   writeText(file, content);
 }
 
+function syncReadmeReleaseSurface(_nextVersion) {
+  const readmePath = "README.md";
+  // The README uses a dynamic GitHub release badge; no version replacement is needed.
+  writeText(readmePath, readText(readmePath));
+}
+
 function syncPackageVersion(nextVersion) {
   const pkg = readJson("package.json");
   const lock = readJson("package-lock.json");
@@ -196,6 +214,14 @@ function syncPackageVersion(nextVersion) {
   writeJson("package-lock.json", lock);
 }
 
+function syncSupportBundleVersion(nextVersion) {
+  const manifestPath = "support-bundle.json";
+  if (!fs.existsSync(manifestPath)) return;
+  const manifest = readJson(manifestPath);
+  manifest.bundleVersion = nextVersion;
+  writeJson(manifestPath, manifest);
+}
+
 function syncPluginVersions(nextVersion) {
   for (const file of [
     path.join("plugins", "meta-architect", ".app.json"),
@@ -215,9 +241,13 @@ function syncPluginVersions(nextVersion) {
 function syncCurrentReleaseFiles(oldVersion, nextVersion) {
   for (const file of [
     "README.md",
+    "DEMO.md",
+    "COVERAGE.md",
     "RELEASE.md",
     path.join("docs", "README.md"),
     path.join("docs", "getting-started.md"),
+    path.join("docs", "onboarding.md"),
+    path.join("docs", "skills.md"),
     path.join("docs", "release-spec.md"),
     path.join("plugins", "meta-architect", "README.md"),
   ]) {
@@ -228,16 +258,17 @@ function syncCurrentReleaseFiles(oldVersion, nextVersion) {
   const nextQa = path.join("docs", "qa", `release-readiness-${nextVersion}.md`);
   fs.renameSync(oldQa, nextQa);
   updateCurrentSurfaceFile(nextQa, oldVersion, nextVersion);
+
+  const oldIssueGates = path.join("docs", "qa", `release-issue-gates-${oldVersion}.json`);
+  const nextIssueGates = path.join("docs", "qa", `release-issue-gates-${nextVersion}.json`);
+  if (fs.existsSync(oldIssueGates)) {
+    fs.renameSync(oldIssueGates, nextIssueGates);
+    updateCurrentSurfaceFile(nextIssueGates, oldVersion, nextVersion);
+  }
 }
 
 function syncSupportingCode(oldVersion, nextVersion) {
   const replacements = [
-    {
-      file: path.join("src", "skills.js"),
-      search: `release-readiness-${oldVersion}.md`,
-      replacement: `release-readiness-${nextVersion}.md`,
-      label: "skills QA path",
-    },
     {
       file: path.join("test", "package-install-smoke.test.js"),
       search: `jstn-sdk-ma-${oldVersion}.tgz`,
@@ -259,6 +290,9 @@ function syncSupportingCode(oldVersion, nextVersion) {
 
   const mcpLiveClientFile = path.join("src", "mcp-live-client.js");
   const mcpLiveClient = readText(mcpLiveClientFile);
+  if (/resolveMcpClientVersion\(packageMetadata\)/.test(mcpLiveClient)) {
+    return;
+  }
   if (!/version: "[0-9]+\.[0-9]+\.[0-9]+(?:-dev)?"/.test(mcpLiveClient)) {
     throw new Error("Expected to find mcp live client version declaration");
   }
@@ -271,6 +305,27 @@ function syncSupportingCode(oldVersion, nextVersion) {
   );
 }
 
+function refreshCurrentReleaseFiles(oldVersion, currentVersion) {
+  for (const file of [
+    "README.md",
+    "DEMO.md",
+    "COVERAGE.md",
+    "RELEASE.md",
+    path.join("docs", "README.md"),
+    path.join("docs", "getting-started.md"),
+    path.join("docs", "onboarding.md"),
+    path.join("docs", "skills.md"),
+    path.join("docs", "release-spec.md"),
+    path.join("plugins", "meta-architect", "README.md"),
+    path.join("docs", "qa", `release-readiness-${currentVersion}.md`),
+    path.join("docs", "qa", `release-issue-gates-${currentVersion}.json`),
+    path.join("scripts", "install.sh"),
+    path.join("plugins", "meta-architect", "obsidian", "manifest.json"),
+  ]) {
+    if (fs.existsSync(file)) updateCurrentSurfaceFile(file, oldVersion, currentVersion);
+  }
+}
+
 function rewriteReleaseState(nextVersion, previousVersion) {
   const releasePath = "RELEASE.md";
   const qaPath = path.join("docs", "qa", `release-readiness-${nextVersion}.md`);
@@ -319,6 +374,13 @@ function main() {
   const args = parseArgs(process.argv.slice(2));
   const pkg = readJson("package.json");
   const currentVersion = pkg.version;
+  if (args.refreshFrom) {
+    refreshCurrentReleaseFiles(args.refreshFrom, currentVersion);
+    console.log(
+      JSON.stringify({ updated: true, refreshed: true, version: currentVersion }, null, 2),
+    );
+    return;
+  }
   const changedFiles = getChangedFiles(args);
   const relevantChanges = args.force ? ["<forced>"] : changedFiles.filter(isWatchedPath);
 
@@ -342,12 +404,15 @@ function main() {
   }
 
   const bumpKind = args.bump || "patch";
-  const nextVersion = bumpVersion(currentVersion, bumpKind);
+  const nextVersion = args.version || bumpVersion(currentVersion, bumpKind);
+  parseVersion(nextVersion);
 
   syncPackageVersion(nextVersion);
+  syncSupportBundleVersion(nextVersion);
   syncPluginVersions(nextVersion);
   prependChangelog(nextVersion);
   syncCurrentReleaseFiles(currentVersion, nextVersion);
+  syncReadmeReleaseSurface(nextVersion);
   syncSupportingCode(currentVersion, nextVersion);
   rewriteReleaseState(nextVersion, currentVersion);
 

package/scripts/release-verify.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
@@ -7,8 +9,6 @@ import { validateReleaseIssueGates } from "../src/release-issue-gates.js";
 
 const CANONICAL_PACKAGE = "@jstn-sdk/ma";
 const CANONICAL_INSTALL = "npm i -g @openai/codex@latest @jstn-sdk/ma@latest";
-const CDN_INSTALL =
-  "curl -fsSL https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@main/scripts/install.sh | sh";
 const CANONICAL_LAUNCH = "ma --madmax --high";
 const UNINSTALL_MA = "npm uninstall -g @jstn-sdk/ma";
 const UNINSTALL_BOTH = "npm uninstall -g @jstn-sdk/ma @openai/codex";
@@ -41,13 +41,18 @@ function parseVersion(version) {
   return match.groups;
 }
 
+function latestCdnInstall() {
+  return "curl -fsSLo install.sh https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh && curl -fsSLo install.sh.sha256 https://cdn.jsdelivr.net/gh/JustineDevs/meta-architect@latest/scripts/install.sh.sha256 && sed 's#scripts/install.sh#install.sh#' install.sh.sha256 | sha256sum -c - && sh install.sh";
+}
+
 function verifyInstallBlock(file) {
   const content = readText(file);
-  if (!content.includes(CANONICAL_INSTALL) && !content.includes(CDN_INSTALL)) {
+  const cdnInstall = latestCdnInstall();
+  if (!content.includes(CANONICAL_INSTALL) && !content.includes(cdnInstall)) {
     return;
   }
 
-  assert(content.includes(CDN_INSTALL), `${file}: missing jsDelivr POSIX installer command`);
+  assert(content.includes(cdnInstall), `${file}: missing jsDelivr POSIX installer command`);
   assert(content.includes(CANONICAL_INSTALL), `${file}: missing canonical npm install command`);
   assert(content.includes(CANONICAL_LAUNCH), `${file}: missing canonical launch command`);
   assert(content.includes(UNINSTALL_MA), `${file}: missing uninstall Meta-Architect command`);
@@ -77,12 +82,29 @@ function verifyNpmIgnore() {
   }
 }
 
+function verifyDistPolicy() {
+  const tracked = execFileSync("git", ["ls-files", "dist/"], { encoding: "utf8" }).trim();
+  assert(!tracked, `dist/: generated release artifacts must not be tracked:\n${tracked}`);
+}
+
+function verifyInstallerIntegrity() {
+  const installer = readText("scripts/install.sh");
+  const checksum = readText("scripts/install.sh.sha256").trim().split(/\s+/)[0];
+  const actual = crypto.createHash("sha256").update(installer).digest("hex");
+  assert(checksum === actual, "scripts/install.sh.sha256: checksum does not match installer");
+  assert(
+    !installer.includes("raw.githubusercontent.com") && !installer.includes("jsdelivr"),
+    "scripts/install.sh: must not fetch mutable installer sources at runtime",
+  );
+}
+
 function verifyDemoDoc({ version, gitTag }) {
+  const cdnInstall = latestCdnInstall();
   assert(fs.existsSync("DEMO.md"), "DEMO.md: missing demo guide");
   const content = readText("DEMO.md");
   assert(content.includes(`Release line: \`${gitTag}\``), "DEMO.md: wrong release line");
   assert(content.includes("Package: `@jstn-sdk/ma`"), "DEMO.md: missing package name");
-  assert(content.includes(CDN_INSTALL), "DEMO.md: missing jsDelivr installer");
+  assert(content.includes(cdnInstall), "DEMO.md: missing versioned installer");
   assert(content.includes(CANONICAL_INSTALL), "DEMO.md: missing canonical npm install");
   assert(content.includes(CANONICAL_LAUNCH), "DEMO.md: missing canonical launch");
   assert(content.includes(UNINSTALL_MA), "DEMO.md: missing MA uninstall command");
@@ -131,6 +153,73 @@ function verifyCoverageDoc({ version, gitTag }) {
   assert(!content.includes("v0.1.0 release bar"), "COVERAGE.md: stale release bar");
 }
 
+function verifyReadmeReleaseSurface({ gitTag }) {
+  const content = readText("README.md");
+  const demoImage = `<img src="https://raw.githubusercontent.com/JustineDevs/meta-architect/${gitTag}/docs/assets/DEMO_VIDEO.gif" alt="Meta-Architect demo video" width="800">`;
+  const logoImage = `<img src="https://raw.githubusercontent.com/JustineDevs/meta-architect/${gitTag}/docs/assets/meta-architect-logo.svg" alt="Meta-Architect: quality gates and evidence verification for AI coding agents" width="1024" height="240">`;
+  assert(content.includes("> [!NOTE]"), "README.md: missing product-positioning note admonition");
+  assert(
+    content.includes(
+      "> Meta-Architect is a workflow layer for teams that want architecture, evidence, review, and release discipline before build execution.",
+    ),
+    "README.md: missing workflow-layer positioning note",
+  );
+  assert(
+    content.includes("> Meta-Architect does not replace your coding runtime."),
+    "README.md: missing runtime-wrapper boundary note",
+  );
+  assert(
+    content.includes(
+      "> It wraps that runtime with architecture, evidence, gate enforcement, and release-sensitive workflow control.",
+    ),
+    "README.md: missing runtime-wrapper behavior note",
+  );
+  assert(content.includes(demoImage), "README.md: missing requested 800px demo GIF");
+  assert(
+    content.includes("<summary><strong>🔌 All 33 plugins & features</strong></summary>"),
+    "README.md: missing all 33 plugins/features toggle",
+  );
+  assert(
+    content.includes(
+      "https://img.shields.io/github/v/release/JustineDevs/meta-architect?display_name=tag&sort=semver",
+    ),
+    "README.md: missing GitHub release badge",
+  );
+  assert(content.includes(logoImage), "README.md: release-pinned logo missing");
+  assert(
+    !content.includes("raw.githubusercontent.com/JustineDevs/meta-architect/main/"),
+    "README.md: stable docs must not reference mutable main",
+  );
+}
+
+function verifyRealDemoKit() {
+  const runbook = readText(path.join("docs", "demo", "REAL_DEMO_RUNBOOK.md"));
+  const story = readText(path.join("docs", "demo", "DEMO_STORY.md"));
+  const checklist = readText(path.join("docs", "demo", "PROSPECT_CHECKLIST.md"));
+  assert(fs.existsSync(path.join("scripts", "demo-smoke.js")), "scripts/demo-smoke.js: missing");
+  assert(
+    runbook.includes("npm run demo:smoke"),
+    "REAL_DEMO_RUNBOOK.md: missing demo smoke command",
+  );
+  assert(runbook.includes("$maestro"), "REAL_DEMO_RUNBOOK.md: missing maestro scenario");
+  assert(
+    runbook.includes("vault_context"),
+    "REAL_DEMO_RUNBOOK.md: missing Obsidian context boundary",
+  );
+  assert(story.includes("Northstar Logistics"), "DEMO_STORY.md: missing realistic buyer story");
+  assert(story.includes("npm run release:verify"), "DEMO_STORY.md: missing release proof close");
+  assert(
+    checklist.includes("Remove `Demo Account`, `Test Company`, `Sample Co`"),
+    "PROSPECT_CHECKLIST.md: missing no-test-branding check",
+  );
+  for (const forbidden of ["Demo Account", "Test Company", "Sample Co"]) {
+    assert(
+      !runbook.includes(forbidden) && !story.includes(forbidden),
+      `demo docs: forbidden visible demo branding ${forbidden}`,
+    );
+  }
+}
+
 function verifyCanonicalSemanticSurfaces({ version, gitTag }) {
   const usageWorkflow = readText(path.join("example", "usage-workflow.md"));
   assert(
@@ -178,7 +267,7 @@ function verifyCanonicalSemanticSurfaces({ version, gitTag }) {
 
   const currentQa = readText(path.join("docs", "qa", `release-readiness-${version}.md`));
   assert(
-    currentQa.includes("Harden Meta-Architect v0.1.13 semantic core"),
+    currentQa.includes(`Harden Meta-Architect ${gitTag} semantic core`),
     `docs/qa/release-readiness-${version}.md: missing realistic semantic smoke idea`,
   );
   assert(
@@ -217,8 +306,12 @@ function main() {
   assert(pkg.files?.includes("COVERAGE.md"), "package.json: files must include COVERAGE.md");
 
   verifyNpmIgnore();
+  verifyDistPolicy();
+  verifyInstallerIntegrity();
   verifyDemoDoc({ version, gitTag });
   verifyCoverageDoc({ version, gitTag });
+  verifyReadmeReleaseSurface({ gitTag });
+  verifyRealDemoKit();
   verifyCanonicalSemanticSurfaces({ version, gitTag });
 
   const changelog = readText("CHANGELOG.md");
@@ -279,7 +372,7 @@ function main() {
     path.join("docs", "skills.md"),
     path.join("plugins", "meta-architect", "README.md"),
   ]) {
-    verifyInstallBlock(file);
+    verifyInstallBlock(file, gitTag);
   }
 
   const envTag =