qa-engineer 0.9.2 → 0.11.0

package/packages/installer/lib/commands/install.mjs

@@ -4,18 +4,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { BACKUP_DIR, LOCKFILE, EXIT } from '../constants.mjs';
-import { resolveSourceRoot, resolveProjectRoot, toPosix } from '../core/paths.mjs';
-import { listSkills, skillFiles } from '../core/manifest.mjs';
-import { bundleFilesForSkill } from '../core/bundle.mjs';
-import { hashBytes } from '../core/hash.mjs';
+import { resolveSourceRoot } from '../core/paths.mjs';
 import { detectConflicts } from '../core/conflict.mjs';
-import { Transaction } from '../core/fs-safe.mjs';
-import { buildLock, readLock, serializeLock, lockPath } from '../core/lockfile.mjs';
+import { Transaction, readLinkTarget, canLink } from '../core/fs-safe.mjs';
+import { buildLock, readLock, serializeLock, scopeLockPath } from '../core/lockfile.mjs';
+import { resolveScope } from '../core/scope.mjs';
+import { buildPlan, dedupePlan } from '../core/plan.mjs';
+import { resolveScopeTargets, describeUnservedAgents } from '../agents/targets.mjs';
 import { loadConfig } from '../core/config.mjs';
-import { readSkillMeta } from '../core/skill-meta.mjs';
-import { renderWrapper } from '../core/wrappers.mjs';
 import { conflictError, verifyError } from '../core/errors.mjs';
-import { resolveInstallTargets } from '../agents/registry.mjs';
 import { createLogger } from '../core/logger.mjs';
 import { parseCommonFlags } from '../cli/flags.mjs';
 import { validateInstall } from '../core/validate-install.mjs';
@@ -92,6 +89,19 @@ function reportFrameworkFit(root, logger) {
   logger.info('  → unit tests only (Jest, Vitest, Jasmine, pytest)? That is expected');
 }
 
+/**
+ * Name the hosts a global install could not serve, and what to do about them.
+ *
+ * Staying quiet here would leave a Cursor user waiting for slash commands that are never
+ * going to appear, with an install that reported success.
+ */
+function reportUnserved(unserved, logger) {
+  if (!unserved || unserved.length === 0) return;
+  logger.info(`  → not installed for ${unserved.map((entry) => entry.id).join(', ')}:`);
+  for (const entry of unserved) logger.info(`      ${entry.id} — ${entry.reason}`);
+  logger.info('  → run `qa install --project .` inside a repository to serve those hosts');
+}
+
 /**
  * Core install implementation shared by install / onboard / repair / update.
  *
@@ -108,7 +118,9 @@ function reportFrameworkFit(root, logger) {
  */
 export async function executeInstall({
   projectRoot,
+  scope: providedScope = null,
   agentIds = [],
+  allAgents = false,
   force = false,
   dryRun = false,
   skipValidate = false,
@@ -118,85 +130,58 @@ export async function executeInstall({
 } = {}) {
   const logger = log ?? createLogger();
   const sourceRoot = resolveSourceRoot();
-  const root = resolveProjectRoot(projectRoot);
+  // A caller that names a scope gets it; everything else is a project install at the
+  // path it asked for, which is what every pre-0.11 caller means.
+  const scope = providedScope ?? resolveScope({ project: projectRoot ?? process.cwd() });
+  const root = scope.root;
   const { config } = loadConfig(root);
   const explicit = agentIds.length > 0 ? agentIds : config.agents ?? [];
-  const agents = resolveInstallTargets(root, explicit);
-  const skills = listSkills(sourceRoot);
+  const agents = resolveScopeTargets(scope, { explicitIds: explicit, allAgents });
+  const unserved = describeUnservedAgents(scope, agents);
+
+  if (agents.length === 0) {
+    throw conflictError(
+      `no agent can be served by a ${scope.kind} install here`,
+      scope.kind === 'global'
+        ? 'no supported host has a user-level skills directory on this machine; ' +
+          'install per project with: qa install --project .'
+        : 'pass --agent <id> to name one explicitly',
+    );
+  }
+
+  // Probe once, before planning. A filesystem that cannot hold a directory link — FAT,
+  // some network and container mounts, Windows without junction support — gets copies
+  // instead of a failed install.
+  const linksSupported = scope.shareEngine ? canLink(scope.root) : false;
+  const { skills, files, links } = buildPlan({
+    sourceRoot,
+    scope,
+    targets: agents,
+    preferLinks: linksSupported,
+  });
 
   if (!json) {
     logger.step(`source: ${sourceRoot}`);
-    logger.step(`project: ${root}`);
+    logger.step(`scope: ${scope.label}`);
     logger.step(`agents: ${agents.map((a) => a.id).join(', ')}`);
     logger.step(`skills: ${skills.length}`);
-  }
-
-  /** @type {Array<{path:string, sha256:string, bytes:number, owner:string, skill?:string, agent?:string, content:Buffer}>} */
-  const planned = [];
-
-  for (const agent of agents) {
-    for (const skill of skills) {
-      const files = skillFiles(sourceRoot, skill);
-      for (const rel of files) {
-        if (rel.startsWith('tests/') || rel.includes('/tests/')) continue;
-        const abs = path.join(sourceRoot, 'skills', skill, rel);
-        const content = fs.readFileSync(abs);
-        const dest = toPosix(path.join(agent.skillsDir, skill, rel));
-        planned.push({
-          path: dest,
-          sha256: hashBytes(content),
-          bytes: content.length,
-          owner: 'skill',
-          skill,
-          agent: agent.id,
-          content,
-        });
-      }
-      for (const bundled of bundleFilesForSkill(sourceRoot, skill)) {
-        const dest = toPosix(path.join(agent.skillsDir, skill, bundled.rel));
-        planned.push({
-          path: dest,
-          sha256: hashBytes(bundled.content),
-          bytes: bundled.content.length,
-          owner: 'skill',
-          skill,
-          agent: agent.id,
-          content: bundled.content,
-        });
-      }
-    }
-
-    if (agent.wrapperFormat && agent.wrapperDir) {
-      for (const skill of skills) {
-        const meta = readSkillMeta(path.join(sourceRoot, 'skills', skill, 'SKILL.md'));
-        if (!meta.name) continue;
-        const { filename, content } = renderWrapper(agent.wrapperFormat, meta);
-        const buf = Buffer.from(content, 'utf8');
-        const dest = toPosix(path.join(agent.wrapperDir, filename));
-        planned.push({
-          path: dest,
-          sha256: hashBytes(buf),
-          bytes: buf.length,
-          owner: 'wrapper',
-          skill,
-          agent: agent.id,
-          content: buf,
-        });
+    if (scope.shareEngine) {
+      logger.step(`shared engine: ${path.join(scope.qaRoot, 'engine')}`);
+      if (!linksSupported) {
+        logger.warn('this filesystem does not support directory links — copying skills instead');
+        logger.info('  → the install works the same; it uses more disk and each agent gets its own copy');
       }
     }
   }
 
-  const byPath = new Map();
-  for (const entry of planned) {
-    const prev = byPath.get(entry.path);
-    if (prev && prev.sha256 !== entry.sha256) {
-      throw conflictError(`conflicting content for ${entry.path}`);
-    }
-    if (!prev) byPath.set(entry.path, entry);
+  const { unique: uniqueFiles, conflicts: contentConflicts } = dedupePlan(files);
+  if (contentConflicts.length > 0) {
+    throw conflictError(`conflicting content for ${contentConflicts[0]}`);
   }
-  const unique = [...byPath.values()];
+  const { unique: uniqueLinks } = dedupePlan(links);
+  const unique = [...uniqueFiles, ...uniqueLinks];
 
-  const priorLock = readLock(root);
+  const priorLock = readLock(root, scope.lockfile);
   const conflicts = detectConflicts({
     projectRoot: root,
     planned: unique,
@@ -220,10 +205,42 @@ export async function executeInstall({
   reportProgress(INSTALL_STEPS[0].label, 1);
 
   const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-  const backupDir = path.join(root, BACKUP_DIR, stamp);
+  // A scope that owns a directory keeps its backups inside it. Otherwise a global
+  // install writes them to `~/.qa/backups`, which is loose in the user's home — the
+  // exact thing owning a directory was meant to stop.
+  const backupRoot = scope.qaRootRelative ? path.join(scope.qaRootRelative, 'backups') : BACKUP_DIR;
+  const backupDir = path.join(root, backupRoot, stamp);
   const tx = new Transaction(root, backupDir, { dryRun });
   for (const entry of unique) {
-    tx.write(entry.path, entry.content);
+    if (entry.owner === 'link') tx.link(entry.path, entry.linkTarget);
+    else tx.write(entry.path, entry.content);
+  }
+
+  // Files the previous install owned that this one does not: remove them.
+  //
+  // Without this, anything that leaves the pack between versions stays on disk
+  // forever, and `verify` cannot see it — verify checks that lockfile entries are
+  // present and unmodified, and an orphan is in no lockfile. Upgrading 0.9.1 to
+  // 0.9.3, which replaced the Python engine with a Node one, left 154 dead Python
+  // files in the user's repository, reported as a clean install and ready to be
+  // committed.
+  //
+  // Only files the pack itself wrote are touched: the candidates come from the
+  // prior lockfile, which is the record of what this installer created. Each goes
+  // through the same Transaction as a write, so it is backed up first and restored
+  // if any later step fails.
+  const orphans = [];
+  if (priorLock && !dryRun) {
+    const stillOwned = new Set(unique.map((entry) => entry.path));
+    for (const previous of priorLock.files ?? []) {
+      if (previous.path === scope.lockfile || stillOwned.has(previous.path)) continue;
+      const absolute = path.join(root, previous.path);
+      // A stale link still counts as present even when its target is gone, so lstat
+      // rather than exists — otherwise a broken link survives every upgrade.
+      if (!fs.existsSync(absolute) && readLinkTarget(absolute) === null) continue;
+      orphans.push(previous.path);
+      tx.delete(previous.path);
+    }
   }
 
   reportProgress(INSTALL_STEPS[1].label, 2);
@@ -237,18 +254,24 @@ export async function executeInstall({
       skillsDir: a.skillsDir,
       detected: a.detected,
     })),
-    files: unique.map(({ path: p, sha256, bytes, owner, skill, agent }) => ({
+    // Shared entries — the engine, and the canonical skill tree — belong to no single
+    // agent, so the optional keys are omitted rather than set to undefined. The schema
+    // types them as strings, and a present-but-undefined key fails that as loudly as a
+    // wrong one.
+    files: unique.map(({ path: p, sha256, bytes, owner, skill, agent, linkTarget }) => ({
       path: p,
       sha256,
       bytes,
       owner,
-      skill,
-      agent,
+      ...(skill ? { skill } : {}),
+      ...(agent ? { agent } : {}),
+      ...(linkTarget ? { linkTarget } : {}),
     })),
     now: new Date().toISOString(),
+    scope,
   });
   if (!dryRun) {
-    tx.write(LOCKFILE, Buffer.from(serializeLock(lock), 'utf8'));
+    tx.write(scope.lockfile, Buffer.from(serializeLock(lock), 'utf8'));
   }
 
   const summary = tx.commit();
@@ -258,7 +281,7 @@ export async function executeInstall({
 
   let validation = null;
   if (!dryRun && !skipValidate) {
-    validation = validateInstall(root);
+    validation = validateInstall(root, { scope });
     if (!validation.ok) {
       const failed = validation.checks.filter((c) => c.hard && !c.ok);
       throw verifyError(
@@ -274,20 +297,38 @@ export async function executeInstall({
   if (dryRun) {
     if (!json) logger.ok(`dry run: would write ${summary.written} file(s)`);
   } else if (!json) {
-    logger.ok(`installed ${unique.length} file(s); lockfile ${lockPath(root)}`);
+    const linked = unique.filter((entry) => entry.owner === 'link').length;
+    logger.ok(
+      `installed ${unique.length - linked} file(s)` +
+        (linked > 0 ? ` and ${linked} link(s)` : '') +
+        `; lockfile ${scopeLockPath(scope)}`,
+    );
+    if (orphans.length > 0) {
+      logger.ok(`removed ${orphans.length} file(s) the previous version owned and this one does not`);
+    }
     for (const step of INSTALL_STEPS) logger.ok(step.label);
     reportInvocation(agents, logger);
-    reportFrameworkFit(root, logger);
+    // A global install has no project to inspect, and reporting "no framework detected"
+    // about the user's home directory would be noise pretending to be a diagnosis.
+    if (scope.kind !== 'global') reportFrameworkFit(root, logger);
+    reportUnserved(unserved, logger);
   }
 
   return {
     ok: true,
     dryRun,
+    scope: scope.kind,
+    root,
+    // Kept under its original name so every existing caller and test keeps working.
     projectRoot: root,
+    qaRoot: scope.qaRoot,
     agents: agents.map((a) => a.id),
+    unservedAgents: unserved,
     skills: skills.length,
-    files: unique.length,
-    lockfile: dryRun ? null : LOCKFILE,
+    files: unique.filter((entry) => entry.owner !== 'link').length,
+    links: unique.filter((entry) => entry.owner === 'link').length,
+    lockfile: dryRun ? null : scope.lockfile,
+    removed: orphans,
     validation,
   };
 }
@@ -296,17 +337,45 @@ export async function runInstall(argv, { log } = {}) {
   const opts = parseCommonFlags(argv);
   const logger = log ?? createLogger();
   if (opts.help) {
-    logger.result(`Usage: qa install [--agent <id>]... [--force] [--dry-run] [--yes] [--json] [--project <dir>]
+    logger.result(`Usage: qa install [scope] [--agent <id>]... [--all-agents]
+                  [--force] [--dry-run] [--yes] [--json]
+
+Scope — choose one; --project is the default:
+
+  --global, -g          Install once for this machine, in ~/.qa-engineer.
+                        One engine, one copy of the skills, linked into the
+                        user-level skills directory of every host that has one.
+                        Every project then works with no per-project install.
+                        Override the location with QA_ENGINEER_HOME.
+
+  --workspace, -w       Install once at the root of the monorepo containing the
+                        current directory, shared by every package in it.
+                        Detects pnpm, npm/yarn workspaces, Nx, Turborepo, Lerna,
+                        Rush, Go, and Cargo.
 
-Copy QA Engineer Pack skills into Agent Skills discovery paths
-(.agents/skills/ and .claude/skills/ when applicable), write qa-lock.json,
-and generate thin slash wrappers for agents that need them.`);
+  --project [dir], -C   Install into one project (default: this directory).
+                        Self-contained: the engine travels inside each skill, so
+                        the repository works on a machine with nothing installed.
+
+Other:
+  --all-agents          Install for every host that has a user-level directory,
+                        not just the ones detected here.
+  --agent <id>          Target a specific host; repeatable.
+  --force               Overwrite files a previous install does not own.
+  --dry-run             Report what would change and write nothing.`);
     return EXIT.OK;
   }
 
+  const scope = resolveScope({
+    global: opts.global,
+    workspace: opts.workspace,
+    project: opts.project,
+  });
+
   const result = await executeInstall({
-    projectRoot: opts.project ?? process.cwd(),
+    scope,
     agentIds: opts.agents,
+    allAgents: opts.allAgents,
     force: opts.force,
     dryRun: opts.dryRun,
     json: opts.json,

package/packages/installer/lib/commands/repair.mjs

@@ -1,7 +1,7 @@
 // `qa repair` — fix common install problems by reinstalling pack-owned files.
 
 import { EXIT, LOCKFILE } from '../constants.mjs';
-import { resolveProjectRoot } from '../core/paths.mjs';
+import { resolveOperatingScope } from '../core/scope.mjs';
 import { readLock } from '../core/lockfile.mjs';
 import { parseCommonFlags } from '../cli/flags.mjs';
 import { executeInstall } from './install.mjs';
@@ -21,9 +21,10 @@ Repair a broken or drifted installation:
     return EXIT.OK;
   }
 
-  const root = resolveProjectRoot(opts.project ?? process.cwd());
-  const prior = readLock(root);
-  const before = validateInstall(root);
+  const scope = resolveOperatingScope(opts);
+  const root = scope.root;
+  const prior = readLock(root, scope.lockfile);
+  const before = validateInstall(root, { scope });
 
   if (!opts.json) {
     logger.step(`repairing ${root}`);
@@ -40,7 +41,10 @@ Repair a broken or drifted installation:
     : (prior?.agents ?? []).map((a) => a.id).filter(Boolean);
 
   const result = await executeInstall({
-    projectRoot: root,
+    // The scope the command resolved, not just its root: without it the reinstall
+    // reverts a global install to a project-shaped one — 1225 files and a lockfile in
+    // the wrong place — while reporting success.
+    scope,
     agentIds,
     force: true,
     dryRun: opts.dryRun,
@@ -48,7 +52,7 @@ Repair a broken or drifted installation:
     log: logger,
   });
 
-  const after = opts.dryRun ? before : validateInstall(root);
+  const after = opts.dryRun ? before : validateInstall(root, { scope });
 
   if (!opts.json) {
     if (after.ok) logger.ok('repair complete — installation validated');

package/packages/installer/lib/commands/self-test.mjs

@@ -1,7 +1,7 @@
 // `qa self-test` — verify an installation is operational.
 
 import { EXIT } from '../constants.mjs';
-import { resolveProjectRoot } from '../core/paths.mjs';
+import { resolveOperatingScope } from '../core/scope.mjs';
 import { parseCommonFlags } from '../cli/flags.mjs';
 import { validateInstall } from '../core/validate-install.mjs';
 import { createLogger } from '../core/logger.mjs';
@@ -17,8 +17,9 @@ Prints PASS/FAIL per check. Does not invoke live AI agents.`);
     return EXIT.OK;
   }
 
-  const root = resolveProjectRoot(opts.project ?? process.cwd());
-  const { ok, checks } = validateInstall(root);
+  const scope = resolveOperatingScope(opts);
+  const root = scope.root;
+  const { ok, checks } = validateInstall(root, { scope });
 
   if (!opts.json) {
     logger.step(`self-test — ${root}`);

package/packages/installer/lib/commands/uninstall.mjs

@@ -16,9 +16,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { EXIT, LOCKFILE, BACKUP_DIR } from '../constants.mjs';
-import { resolveProjectRoot } from '../core/paths.mjs';
+import { resolveOperatingScope } from '../core/scope.mjs';
 import { readLock, lockPath } from '../core/lockfile.mjs';
-import { hashFile } from '../core/hash.mjs';
+import { entryDigest } from '../core/integrity.mjs';
 import { Transaction, pruneEmptyDirs } from '../core/fs-safe.mjs';
 import { conflictError, verifyError } from '../core/errors.mjs';
 import { createLogger } from '../core/logger.mjs';
@@ -40,7 +40,7 @@ function findPycache(dir) {
   return found;
 }
 
-export async function runUninstall(argv, { log } = {}) {
+export async function runUninstall(argv, { log, env = process.env } = {}) {
   const opts = parseCommonFlags(argv);
   const logger = log ?? createLogger();
   if (opts.help) {
@@ -54,8 +54,11 @@ Only pack-owned files are removed; anything else is left alone.
     return EXIT.OK;
   }
 
-  const root = resolveProjectRoot(opts.project ?? process.cwd());
-  const lock = readLock(root);
+  // `env` is injected by the test suite so a global uninstall can be exercised
+  // against a temporary home rather than the developer's own.
+  const scope = resolveOperatingScope({ ...opts, env });
+  const root = scope.root;
+  const lock = readLock(root, scope.lockfile);
   if (!lock) {
     if (!opts.json) {
       logger.error(`FAIL  no ${LOCKFILE} in ${root}`);
@@ -73,7 +76,7 @@ Only pack-owned files are removed; anything else is left alone.
       missing.push(entry.path);
       continue;
     }
-    if (hashFile(abs) !== entry.sha256) drifted.push(entry.path);
+    if (entryDigest(root, entry) !== entry.sha256) drifted.push(entry.path);
     present.push(entry.path);
   }
 
@@ -97,9 +100,12 @@ Only pack-owned files are removed; anything else is left alone.
   }
 
   const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-  const tx = new Transaction(root, path.join(root, BACKUP_DIR, stamp), { dryRun: opts.dryRun });
+  // Same rule as install: a scope that owns a directory keeps its backups inside it,
+  // rather than dropping `.qa/backups` into the user's home.
+  const backupRoot = scope.qaRootRelative ? path.join(scope.qaRootRelative, 'backups') : BACKUP_DIR;
+  const tx = new Transaction(root, path.join(root, backupRoot, stamp), { dryRun: opts.dryRun });
   for (const rel of present) tx.delete(rel);
-  if (fs.existsSync(lockPath(root))) tx.delete(LOCKFILE);
+  if (fs.existsSync(path.join(root, scope.lockfile))) tx.delete(scope.lockfile);
   const summary = tx.commit();
 
   // Byproducts of the pack's own bundled code: Python writes __pycache__ next to

package/packages/installer/lib/commands/update.mjs

@@ -1,7 +1,8 @@
 // `qa update` — refresh an install from the current pack source.
 
 import { EXIT } from '../constants.mjs';
-import { resolveProjectRoot, resolveSourceRoot } from '../core/paths.mjs';
+import { resolveSourceRoot } from '../core/paths.mjs';
+import { resolveOperatingScope } from '../core/scope.mjs';
 import { readLock } from '../core/lockfile.mjs';
 import { parseCommonFlags } from '../cli/flags.mjs';
 import { executeInstall } from './install.mjs';
@@ -20,9 +21,10 @@ Always re-validates after updating.`);
     return EXIT.OK;
   }
 
-  const root = resolveProjectRoot(opts.project ?? process.cwd());
+  const scope = resolveOperatingScope(opts);
+  const root = scope.root;
   const sourceRoot = resolveSourceRoot();
-  const lock = readLock(root);
+  const lock = readLock(root, scope.lockfile);
   const installedVersion = lock?.pack?.version ?? null;
 
   if (!opts.json) {
@@ -43,7 +45,10 @@ Always re-validates after updating.`);
     : (lock?.agents ?? []).map((a) => a.id).filter(Boolean);
 
   const result = await executeInstall({
-    projectRoot: root,
+    // The scope the command resolved, not just its root: without it the reinstall
+    // reverts a global install to a project-shaped one — 1225 files and a lockfile in
+    // the wrong place — while reporting success.
+    scope,
     agentIds,
     force: true,
     dryRun: opts.dryRun,

package/packages/installer/lib/commands/verify.mjs

@@ -3,9 +3,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { EXIT, LOCKFILE } from '../constants.mjs';
-import { resolveProjectRoot } from '../core/paths.mjs';
+import { resolveOperatingScope } from '../core/scope.mjs';
 import { readLock } from '../core/lockfile.mjs';
-import { hashFile } from '../core/hash.mjs';
+import { entryDigest } from '../core/integrity.mjs';
 import { verifyError } from '../core/errors.mjs';
 import { createLogger } from '../core/logger.mjs';
 import { parseCommonFlags } from '../cli/flags.mjs';
@@ -21,8 +21,9 @@ On failure: run qa repair`);
     return EXIT.OK;
   }
 
-  const root = resolveProjectRoot(opts.project ?? process.cwd());
-  const lock = readLock(root);
+  const scope = resolveOperatingScope(opts);
+  const root = scope.root;
+  const lock = readLock(root, scope.lockfile);
   if (!lock) {
     if (!opts.json) {
       logger.error(`FAIL  no ${LOCKFILE}`);
@@ -33,14 +34,14 @@ On failure: run qa repair`);
 
   const problems = [];
   for (const entry of lock.files) {
-    const abs = path.join(root, entry.path);
-    if (!fs.existsSync(abs)) {
-      problems.push({ path: entry.path, reason: 'missing' });
-      continue;
-    }
-    const actual = hashFile(abs);
-    if (actual !== entry.sha256) {
-      problems.push({ path: entry.path, reason: 'hash mismatch' });
+    const actual = entryDigest(root, entry);
+    if (actual === null) {
+      problems.push({ path: entry.path, reason: entry.owner === 'link' ? 'link missing' : 'missing' });
+    } else if (actual !== entry.sha256) {
+      problems.push({
+        path: entry.path,
+        reason: entry.owner === 'link' ? 'link points somewhere else' : 'hash mismatch',
+      });
     }
   }
 

package/packages/installer/lib/constants.mjs

@@ -11,6 +11,19 @@ export const LOCKFILE = 'qa-lock.json';
 export const QA_DIR = '.qa';
 export const BACKUP_DIR = `${QA_DIR}/backups`;
 
+// The directory QA Engineer owns. In a global install it sits in the user's home; in a
+// workspace install it sits at the monorepo root. Same name in both, so a developer who
+// has seen one recognises the other.
+export const QA_HOME_DIR_NAME = '.qa-engineer';
+
+// Full override for where the global install lives. Also what makes global installs
+// testable — the suite points it at a temporary directory instead of a real $HOME.
+export const QA_HOME_ENV = 'QA_ENGINEER_HOME';
+
+// Where the shared engine lands inside a qaRoot, and where the canonical skills live.
+export const SHARED_ENGINE_DIR = 'engine';
+export const SHARED_SKILLS_STORE = 'skills';
+
 // Marker line prepended to every generated invocation wrapper. Wrappers are
 // disposable build artifacts; this line tells humans and `verify` that the file
 // is pack-owned and regenerated, never hand-edited.