@jstn-sdk/ma 0.1.11 → 0.1.12

package/plugins/meta-architect/skills/vet/SKILL.md

@@ -5,7 +5,7 @@ description: "Use when the user wants a security and trust-boundary review of th
 
 # Vet
 
-Use this skill inside Codex to review security posture before the build lane.
+Use this skill inside Codex to review security posture before the build lane. `$vet` remains the sole security gate even as Meta-Architect ships deeper native security playbooks.
 
 ## Output
 
@@ -21,5 +21,7 @@ Produce:
 ## Rules
 
 - Prioritize material risks over exhaustive but low-value checklists.
+- Use `references/security-playbooks.md` when you need the native security playbook set for common trust-boundary reviews.
+- Keep security guidance product-owned and lane-aware. Do not introduce a second umbrella or a separate security release gate.
 - Call out missing assumptions that affect security posture.
 - Distinguish between must-fix blockers and documented accepted risk.

package/plugins/meta-architect/skills/vet/references/security-playbooks.md

@@ -0,0 +1,23 @@
+# Security Playbooks
+
+Use this reference pack inside `$vet` for repeatable trust-boundary reviews that stay native to Meta-Architect.
+
+## Core review slices
+
+- identity and session boundaries
+- authorization and tenancy boundaries
+- secret handling and key rotation assumptions
+- dependency and supply-chain trust
+- inbound data validation and outbound data exposure
+- operational abuse cases and failure modes
+
+## How to use the playbooks
+
+- Start with the architecture and evidence already approved by `$arch` and `$sage`.
+- Focus on the highest-risk boundary first.
+- Distinguish blockers from accepted risk.
+- Route remediation back to the owning lane rather than creating a parallel security workflow.
+
+## Product boundary
+
+This pack deepens `$vet`; it does not create a new security skill family. Security patterns are packaged as Meta-Architect guidance, not as mirrored external catalogs or branded upstream surfaces.

package/scripts/build-linux-packages.mjs

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import {
+  getDebArtifactPath,
+  getLinuxPackageManifestPath,
+  getPackArtifactPath,
+  getPacmanArtifactPath,
+  getRpmArtifactPath,
+  LINUX_PACKAGE_NAME,
+  LINUX_PACKAGE_REVISION,
+} from "./linux-package-lib.mjs";
+
+const repoRoot = process.cwd();
+const distRoot = path.join(repoRoot, "dist");
+const packageJson = JSON.parse(await fsp.readFile(path.join(repoRoot, "package.json"), "utf8"));
+const version = packageJson.version;
+const packageName = packageJson.name;
+const maintainer = packageJson.author;
+const homepage = packageJson.homepage;
+const description = packageJson.description;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: "pipe",
+    ...options,
+  });
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+  if (result.status !== 0) {
+    fail(`${command} ${args.join(" ")} failed with status ${result.status ?? 1}`);
+  }
+}
+
+async function copyDir(src, dest) {
+  await fsp.mkdir(dest, { recursive: true });
+  const entries = await fsp.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      await fsp.copyFile(srcPath, destPath);
+    }
+  }
+}
+
+async function writeExecutable(filePath, content) {
+  await fsp.writeFile(filePath, content, { mode: 0o755 });
+  await fsp.chmod(filePath, 0o755);
+}
+
+async function getInstalledSizeBytes(root) {
+  let total = 0;
+  const entries = await fsp.readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      total += await getInstalledSizeBytes(entryPath);
+      continue;
+    }
+    const stat = await fsp.stat(entryPath);
+    total += stat.size;
+  }
+  return total;
+}
+
+async function createCommonRoot(root, packArtifactPath) {
+  const libRoot = path.join(root, "usr", "lib", LINUX_PACKAGE_NAME);
+  const binRoot = path.join(root, "usr", "bin");
+  await fsp.mkdir(libRoot, { recursive: true });
+  await fsp.mkdir(binRoot, { recursive: true });
+  run("tar", ["-xzf", packArtifactPath, "-C", libRoot, "--strip-components=1", "package"], {
+    cwd: repoRoot,
+  });
+
+  const wrapper = `#!/bin/sh
+PREFIX="\${META_ARCHITECT_PREFIX:-}"
+NODE_BIN="\${META_ARCHITECT_NODE_BIN:-node}"
+if ! command -v "$NODE_BIN" >/dev/null 2>&1; then
+  echo "meta-architect requires nodejs >= 20 on the host system." >&2
+  exit 127
+fi
+if ! command -v git >/dev/null 2>&1; then
+  echo "meta-architect requires git on the host system." >&2
+  exit 127
+fi
+exec "$NODE_BIN" "\${PREFIX}/usr/lib/${LINUX_PACKAGE_NAME}/bin/ma.js" "$@"
+`;
+  await writeExecutable(path.join(binRoot, "ma"), wrapper);
+  await writeExecutable(path.join(binRoot, "meta-architect"), wrapper);
+}
+
+async function buildDeb(commonRoot, artifactPath) {
+  const debRoot = `${commonRoot}-deb`;
+  await fsp.rm(debRoot, { recursive: true, force: true });
+  await copyDir(commonRoot, debRoot);
+  const controlRoot = path.join(debRoot, "DEBIAN");
+  await fsp.mkdir(controlRoot, { recursive: true });
+  await fsp.writeFile(
+    path.join(controlRoot, "control"),
+    `Package: ${LINUX_PACKAGE_NAME}
+Version: ${version}
+Section: devel
+Priority: optional
+Architecture: all
+Maintainer: ${maintainer}
+Depends: nodejs (>= 20), git
+Description: ${description}
+ Meta-Architect installs the Codex-native Meta-Architect workflow surface
+ without requiring npm package installation first.
+Homepage: ${homepage}
+`,
+  );
+  await fsp.rm(artifactPath, { force: true });
+  run("dpkg-deb", ["--root-owner-group", "--build", debRoot, artifactPath], { cwd: repoRoot });
+}
+
+async function buildPacman(commonRoot, artifactPath) {
+  const pacmanRoot = `${commonRoot}-pacman`;
+  await fsp.rm(pacmanRoot, { recursive: true, force: true });
+  await copyDir(commonRoot, pacmanRoot);
+  const installedSize = await getInstalledSizeBytes(path.join(pacmanRoot, "usr"));
+  const buildDate = Math.floor(Date.now() / 1000);
+  await fsp.writeFile(
+    path.join(pacmanRoot, ".PKGINFO"),
+    `pkgname = ${LINUX_PACKAGE_NAME}
+pkgbase = ${LINUX_PACKAGE_NAME}
+pkgver = ${version}-${LINUX_PACKAGE_REVISION}
+pkgdesc = ${description}
+url = ${homepage}
+builddate = ${buildDate}
+packager = ${maintainer}
+size = ${installedSize}
+arch = any
+license = MIT
+depend = nodejs
+depend = git
+`,
+  );
+  await fsp.writeFile(
+    path.join(pacmanRoot, ".BUILDINFO"),
+    `format = 2
+pkgname = ${LINUX_PACKAGE_NAME}
+pkgbase = ${LINUX_PACKAGE_NAME}
+pkgver = ${version}-${LINUX_PACKAGE_REVISION}
+pkgarch = any
+packager = ${maintainer}
+builddate = ${buildDate}
+`,
+  );
+  await fsp.rm(artifactPath, { force: true });
+  run(
+    "tar",
+    [
+      "--sort=name",
+      "--mtime=@0",
+      "--owner=0",
+      "--group=0",
+      "--numeric-owner",
+      "-cJf",
+      artifactPath,
+      "-C",
+      pacmanRoot,
+      ".PKGINFO",
+      ".BUILDINFO",
+      "usr",
+    ],
+    { cwd: repoRoot },
+  );
+}
+
+async function buildRpm(commonRoot, artifactPath) {
+  const rpmRoot = `${commonRoot}-rpmbuild`;
+  const topDir = path.join(rpmRoot, "topdir");
+  for (const dirName of ["BUILD", "BUILDROOT", "RPMS", "SOURCES", "SPECS", "SRPMS", "TMP", "DB"]) {
+    await fsp.mkdir(path.join(topDir, dirName), { recursive: true });
+  }
+
+  const sourceRootName = `${LINUX_PACKAGE_NAME}-${version}`;
+  const sourceRoot = path.join(rpmRoot, sourceRootName);
+  await fsp.rm(sourceRoot, { recursive: true, force: true });
+  await copyDir(commonRoot, sourceRoot);
+  const sourceTarPath = path.join(topDir, "SOURCES", `${sourceRootName}.tar.gz`);
+  run("tar", ["-czf", sourceTarPath, "-C", rpmRoot, sourceRootName], { cwd: repoRoot });
+
+  const specPath = path.join(topDir, "SPECS", `${LINUX_PACKAGE_NAME}.spec`);
+  await fsp.writeFile(
+    specPath,
+    `Name: ${LINUX_PACKAGE_NAME}
+Version: ${version}
+Release: ${LINUX_PACKAGE_REVISION}%{?dist}
+Summary: ${description}
+License: MIT
+URL: ${homepage}
+BuildArch: noarch
+Requires: nodejs >= 20
+Requires: git
+Source0: %{name}-%{version}.tar.gz
+
+%description
+Meta-Architect installs the Codex-native Meta-Architect workflow surface
+without requiring npm package installation first.
+
+%prep
+%setup -q
+
+%build
+
+%install
+rm -rf %{buildroot}
+mkdir -p %{buildroot}
+cp -a usr %{buildroot}/
+
+%files
+/usr/bin/ma
+/usr/bin/meta-architect
+/usr/lib/${LINUX_PACKAGE_NAME}
+`,
+  );
+
+  await fsp.rm(artifactPath, { force: true });
+  run(
+    "rpmbuild",
+    [
+      "--define",
+      `_topdir ${topDir}`,
+      "--define",
+      `_tmppath ${path.join(topDir, "TMP")}`,
+      "--define",
+      `_dbpath ${path.join(topDir, "DB")}`,
+      "-bb",
+      specPath,
+    ],
+    {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        HOME: rpmRoot,
+        TMPDIR: path.join(topDir, "TMP"),
+        QA_RPATHS: "0x0000",
+      },
+    },
+  );
+  const builtRpmPath = path.join(topDir, "RPMS", "noarch", path.basename(artifactPath));
+  await fsp.copyFile(builtRpmPath, artifactPath);
+}
+
+async function main() {
+  if (process.platform !== "linux") {
+    fail("Native Linux package builds are supported only on Linux hosts");
+  }
+
+  await fsp.mkdir(distRoot, { recursive: true });
+  const packArtifactPath = getPackArtifactPath(distRoot, packageName, version);
+  await fsp.rm(packArtifactPath, { force: true });
+  run(
+    "npm",
+    [
+      "pack",
+      ".",
+      "--ignore-scripts",
+      "--cache",
+      path.join(distRoot, ".npm-cache"),
+      "--pack-destination",
+      distRoot,
+    ],
+    { cwd: repoRoot },
+  );
+
+  const workRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "meta-architect-linux-packages-"));
+  const commonRoot = path.join(workRoot, "root");
+  await createCommonRoot(commonRoot, packArtifactPath);
+
+  const debArtifactPath = getDebArtifactPath(distRoot, version);
+  const pacmanArtifactPath = getPacmanArtifactPath(distRoot, version);
+  const rpmArtifactPath = getRpmArtifactPath(distRoot, version);
+  await buildDeb(commonRoot, debArtifactPath);
+  await buildPacman(commonRoot, pacmanArtifactPath);
+  await buildRpm(commonRoot, rpmArtifactPath);
+
+  await fsp.writeFile(
+    getLinuxPackageManifestPath(distRoot),
+    `${JSON.stringify(
+      {
+        version,
+        packageName,
+        linuxPackageName: LINUX_PACKAGE_NAME,
+        revision: LINUX_PACKAGE_REVISION,
+        artifacts: {
+          deb: path.basename(debArtifactPath),
+          pacman: path.basename(pacmanArtifactPath),
+          rpm: path.basename(rpmArtifactPath),
+        },
+        install: {
+          debian: `sudo apt install ./${path.basename(debArtifactPath)}`,
+          arch: `sudo pacman -U ./${path.basename(pacmanArtifactPath)}`,
+          rpm: `sudo dnf install ./${path.basename(rpmArtifactPath)}`,
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  console.log(debArtifactPath);
+  console.log(pacmanArtifactPath);
+  console.log(rpmArtifactPath);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/scripts/doctor.js

@@ -1,11 +1,30 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import {
+  getDebArtifactName,
+  getPacmanArtifactName,
+  getRpmArtifactName,
+} from "./linux-package-lib.mjs";
+
+const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
 
 const checks = [
   ["package.json", fs.existsSync("package.json")],
   ["skills/index.json", fs.existsSync("skills/index.json")],
   ["dist/meta-architect-skills.tgz", fs.existsSync("dist/meta-architect-skills.tgz")],
+  [
+    `dist/${getDebArtifactName(pkg.version)}`,
+    fs.existsSync(`dist/${getDebArtifactName(pkg.version)}`),
+  ],
+  [
+    `dist/${getPacmanArtifactName(pkg.version)}`,
+    fs.existsSync(`dist/${getPacmanArtifactName(pkg.version)}`),
+  ],
+  [
+    `dist/${getRpmArtifactName(pkg.version)}`,
+    fs.existsSync(`dist/${getRpmArtifactName(pkg.version)}`),
+  ],
   [".codex/hooks.json", fs.existsSync(".codex/hooks.json")],
   [".ma/decisions.json", fs.existsSync(".ma/decisions.json")],
   [".ma/release.json", fs.existsSync(".ma/release.json")],

package/scripts/linux-package-lib.mjs

@@ -0,0 +1,40 @@
+import path from "node:path";
+
+export const LINUX_PACKAGE_NAME = "meta-architect";
+export const LINUX_PACKAGE_REVISION = "1";
+
+export function getPackArtifactName(packageName, version) {
+  return `${packageName.replace(/^@/, "").replace("/", "-")}-${version}.tgz`;
+}
+
+export function getPackArtifactPath(distRoot, packageName, version) {
+  return path.join(distRoot, getPackArtifactName(packageName, version));
+}
+
+export function getDebArtifactName(version) {
+  return `${LINUX_PACKAGE_NAME}_${version}_all.deb`;
+}
+
+export function getDebArtifactPath(distRoot, version) {
+  return path.join(distRoot, getDebArtifactName(version));
+}
+
+export function getPacmanArtifactName(version) {
+  return `${LINUX_PACKAGE_NAME}-${version}-${LINUX_PACKAGE_REVISION}-any.pkg.tar.xz`;
+}
+
+export function getPacmanArtifactPath(distRoot, version) {
+  return path.join(distRoot, getPacmanArtifactName(version));
+}
+
+export function getRpmArtifactName(version) {
+  return `${LINUX_PACKAGE_NAME}-${version}-${LINUX_PACKAGE_REVISION}.noarch.rpm`;
+}
+
+export function getRpmArtifactPath(distRoot, version) {
+  return path.join(distRoot, getRpmArtifactName(version));
+}
+
+export function getLinuxPackageManifestPath(distRoot) {
+  return path.join(distRoot, "linux-package-manifest.json");
+}

package/scripts/linux-package-smoke.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+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 {
+  getDebArtifactPath,
+  getPacmanArtifactPath,
+  getRpmArtifactPath,
+  LINUX_PACKAGE_NAME,
+} from "./linux-package-lib.mjs";
+
+const repoRoot = process.cwd();
+const pkg = JSON.parse(await fs.readFile(path.join(repoRoot, "package.json"), "utf8"));
+const version = pkg.version;
+const distRoot = path.join(repoRoot, "dist");
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: "pipe",
+    ...options,
+  });
+}
+
+function runBinary(command, args, options = {}) {
+  return spawnSync(command, args, {
+    encoding: null,
+    maxBuffer: 32 * 1024 * 1024,
+    stdio: "pipe",
+    ...options,
+  });
+}
+
+async function smokeExtractedRoot(extractRoot, label) {
+  const workRoot = path.join(extractRoot, `${label}-project`);
+  const codexHome = path.join(extractRoot, `${label}-codex-home`);
+  await fs.mkdir(workRoot, { recursive: true });
+  await fs.mkdir(codexHome, { recursive: true });
+  const maBin = path.join(extractRoot, "usr", "bin", "ma");
+  const env = {
+    ...process.env,
+    CODEX_HOME: codexHome,
+    MA_DISABLE_LIVE_MCP: "1",
+    META_ARCHITECT_PREFIX: extractRoot,
+  };
+  const setupResult = run(maBin, ["setup"], { cwd: workRoot, env });
+  assert.equal(setupResult.status, 0, setupResult.stderr || setupResult.stdout);
+  await fs.access(path.join(workRoot, ".ma", "release.json"));
+  await fs.access(path.join(workRoot, ".ma", "decisions.json"));
+  await fs.access(path.join(extractRoot, "usr", "bin", "meta-architect"));
+  const statusResult = run(maBin, ["status"], { cwd: workRoot, env });
+  assert.equal(statusResult.status, 0, statusResult.stderr || statusResult.stdout);
+}
+
+async function main() {
+  if (process.platform !== "linux") {
+    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 debExtractRoot = path.join(tempRoot, "deb");
+  const pacmanExtractRoot = path.join(tempRoot, "pacman");
+  const rpmExtractRoot = path.join(tempRoot, "rpm");
+  await fs.mkdir(debExtractRoot, { recursive: true });
+  await fs.mkdir(pacmanExtractRoot, { recursive: true });
+  await fs.mkdir(rpmExtractRoot, { recursive: true });
+
+  const debArtifactPath = getDebArtifactPath(distRoot, version);
+  const pacmanArtifactPath = getPacmanArtifactPath(distRoot, version);
+  const rpmArtifactPath = getRpmArtifactPath(distRoot, version);
+  const extractDeb = run("dpkg-deb", ["-x", debArtifactPath, debExtractRoot], { cwd: repoRoot });
+  assert.equal(extractDeb.status, 0, extractDeb.stderr || extractDeb.stdout);
+  const extractPacman = run("tar", ["-xJf", pacmanArtifactPath, "-C", pacmanExtractRoot], {
+    cwd: repoRoot,
+  });
+  assert.equal(extractPacman.status, 0, extractPacman.stderr || extractPacman.stdout);
+  const archiveConversion = runBinary("rpm2archive", [rpmArtifactPath], { cwd: rpmExtractRoot });
+  assert.equal(
+    archiveConversion.status,
+    0,
+    archiveConversion.stderr?.toString("utf8") || archiveConversion.stdout?.toString("utf8"),
+  );
+  const rpmArchivePath = path.join(rpmExtractRoot, `${path.basename(rpmArtifactPath)}.tgz`);
+  await fs.writeFile(rpmArchivePath, archiveConversion.stdout);
+  const extractRpm = run("tar", ["-xzf", rpmArchivePath, "-C", rpmExtractRoot], { cwd: repoRoot });
+  assert.equal(extractRpm.status, 0, extractRpm.stderr || extractRpm.stdout);
+  await fs.access(path.join(pacmanExtractRoot, ".PKGINFO"));
+  await fs.access(path.join(pacmanExtractRoot, "usr", "lib", LINUX_PACKAGE_NAME, "bin", "ma.js"));
+  await fs.access(path.join(rpmExtractRoot, "usr", "lib", LINUX_PACKAGE_NAME, "bin", "ma.js"));
+
+  await smokeExtractedRoot(debExtractRoot, "deb");
+  await smokeExtractedRoot(pacmanExtractRoot, "pacman");
+  await smokeExtractedRoot(rpmExtractRoot, "rpm");
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/scripts/release-sync.js

@@ -238,12 +238,6 @@ function syncSupportingCode(oldVersion, nextVersion) {
       replacement: `release-readiness-${nextVersion}.md`,
       label: "skills QA path",
     },
-    {
-      file: path.join("src", "mcp-live-client.js"),
-      search: `version: "${oldVersion}"`,
-      replacement: `version: "${nextVersion}"`,
-      label: "mcp live client version",
-    },
     {
       file: path.join("test", "package-install-smoke.test.js"),
       search: `jstn-sdk-ma-${oldVersion}.tgz`,
@@ -262,6 +256,19 @@ function syncSupportingCode(oldVersion, nextVersion) {
     const content = readText(entry.file);
     writeText(entry.file, replaceRequired(content, entry.search, entry.replacement, entry.label));
   }
+
+  const mcpLiveClientFile = path.join("src", "mcp-live-client.js");
+  const mcpLiveClient = readText(mcpLiveClientFile);
+  if (!/version: "[0-9]+\.[0-9]+\.[0-9]+(?:-dev)?"/.test(mcpLiveClient)) {
+    throw new Error("Expected to find mcp live client version declaration");
+  }
+  writeText(
+    mcpLiveClientFile,
+    mcpLiveClient.replace(
+      /version: "[0-9]+\.[0-9]+\.[0-9]+(?:-dev)?"/,
+      `version: "${nextVersion}-dev"`,
+    ),
+  );
 }
 
 function rewriteReleaseState(nextVersion, previousVersion) {

package/skills/align/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: align
+description: "Use when the user needs scope alignment, shared language, or docs clarity before or between gated lanes."
+---
+
+# Align
+
+Use this skill inside Codex when the problem is ambiguity, drift, or mismatched language rather than missing implementation. `align` is a non-gating helper skill.
+
+## Output
+
+Produce:
+- current ambiguity or mismatch
+- normalized terminology
+- scope boundary and exclusions
+- acceptance checks or rewritten prompts
+- exact next trigger, usually `$maestro` or the lane that owns the next decision
+
+## Rules
+
+- Align language and scope without creating a new release gate.
+- Prefer tightening existing artifacts over inventing parallel docs.
+- Keep terminology Meta-Architect-native for user-facing surfaces.
+- Use `references/shared-language.md` for naming, taxonomy, and docs-clarity patterns.

package/skills/align/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "$align"
+  short_description: "Scope alignment and shared language helper"
+  default_prompt: "Use $align to resolve scope drift, normalize terminology, and tighten prompts or docs before handing work back to the owning gated lane."

package/skills/align/references/shared-language.md

@@ -0,0 +1,24 @@
+# Shared Language
+
+Use this reference pack with `align` when terminology, scope, or docs are drifting.
+
+## Naming rules
+
+- `$maestro` is the only umbrella surface.
+- `$arch -> $sage -> $flow -> $vet -> $vibe -> $build` remains the fixed gated sequence.
+- `align`, `diagnose`, `tdd`, and `cleanup` are helper skills only.
+- User-facing guidance stays Meta-Architect-native; external source names may appear as evidence, not as product surfaces.
+
+## Alignment checklist
+
+- Name the current artifact, lane, and decision owner.
+- Replace vague nouns with one stable term.
+- Separate what is in scope, out of scope, and not yet decided.
+- Rewrite prompts or docs so the next trigger is obvious.
+
+## Docs-clarity patterns
+
+- Put the next trigger in one line.
+- Distinguish terminal helper commands from in-session skills.
+- Distinguish gated lanes from helper skills.
+- Prefer concise, high-signal wording over long catalogs or branding-heavy lists.