@xgent-ai/skills 0.5.0 → 0.7.0

package/vendor/phoenix-ui/bundle/blobs/8b1723fb51e6aad9bfc0bc5ba8e09b5a373b0e33c251331f6ca14ff6b1c261ef

@@ -0,0 +1,372 @@
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const http = require('node:http');
+const https = require('node:https');
+const tls = require('node:tls');
+const { spawn, spawnSync } = require('node:child_process');
+
+const TARGETS = ['darwin-arm64', 'darwin-x64', 'linux-x64', 'linux-arm64', 'windows-x64'];
+const HOOKS = new Set(['hook', 'hook-before-edit']);
+const sha256 = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+const failure = (message, code = 4) => Object.assign(new Error(message), { code });
+
+function platformTarget(platform = process.platform, arch = process.arch) {
+  if (platform === 'win32' && ['x64', 'arm64'].includes(arch)) return 'windows-x64';
+  const target = `${platform}-${arch}`;
+  if (!TARGETS.includes(target)) throw failure(`Unsupported Phoenix platform ${platform}/${arch}; use xgent-skills install --no-phoenix-ui for other features.`);
+  return target;
+}
+
+function manifestAt(file) {
+  const bytes = fs.readFileSync(file);
+  const data = JSON.parse(bytes);
+  if (data.schemaVersion !== 1 || data.bundleSchema !== 1 || data.reviewSchema !== 1
+      || !/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(data.toolVersion || '')
+      || !/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(data.npmPackageVersion || '')
+      || !/^[a-f0-9]{40}$/.test(data.sourceCommit || '') || !/^[a-f0-9]{64}$/.test(data.bundleSha256 || '')) {
+    throw failure('Invalid Phoenix package manifest. Reinstall the matching npm package.');
+  }
+  const targets = Object.keys(data.engines || {});
+  if (!targets.length || targets.some(target => !TARGETS.includes(target))) throw failure('Invalid engine target manifest.');
+  if (data.distribution !== 'development' && TARGETS.some(target => target !== 'windows-x64' && !targets.includes(target))) throw failure('Release manifest is missing a supported platform.');
+  for (const [target, engine] of Object.entries(data.engines)) {
+    const asset = `phoenix-ui-${target}${target.startsWith('windows-') ? '.exe' : ''}`;
+    if (engine.asset !== asset || !/^[a-f0-9]{64}$/.test(engine.sha256 || '')
+        || !Number.isSafeInteger(engine.size) || engine.size <= 0 || engine.size > 256 * 1024 * 1024) {
+      throw failure(`Invalid engine metadata for ${target}.`);
+    }
+    if (data.distribution !== 'development' && !engine.url) throw failure(`Release engine URL is missing for ${target}.`);
+    if (engine.url) checkedUrl(engine.url);
+  }
+  return { data, hash: sha256(bytes), bytes };
+}
+
+function checkedUrl(value) {
+  const url = new URL(value);
+  if (url.username || url.password || (url.protocol !== 'https:'
+      && !(url.protocol === 'http:' && ['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)))) {
+    throw failure('Engine download requires HTTPS (loopback HTTP is allowed for local verification).');
+  }
+  return url;
+}
+
+function cacheRoot(env = process.env) {
+  return path.resolve(env.PHOENIX_UI_HOME || path.join(os.homedir(), '.phoenix-ui'));
+}
+
+function enginePath(manifest, target, env = process.env) {
+  return path.join(cacheRoot(env), 'bin', manifest.data.toolVersion, target, target.startsWith('windows-') ? 'phoenix-ui.exe' : 'phoenix-ui');
+}
+
+function projectRoot(start) {
+  const initial = fs.realpathSync(path.resolve(start));
+  let dir = initial;
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.phoenix-ui/install/active.json')) || fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return initial;
+    dir = parent;
+  }
+}
+
+// The transactional installer writes this receipt last. It names the package and
+// bundle, not a platform, so one project serves every supported engine target.
+function verifyReceipt(project, manifest) {
+  const file = path.join(project, '.phoenix-ui/install/active.json');
+  if (!fs.existsSync(file)) return;
+  const receipt = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (receipt.schema_version !== 1 || receipt.manifest?.version !== manifest.data.npmPackageVersion
+      || receipt.manifest?.sha256 !== manifest.data.bundleSha256) {
+    throw failure(`Project receipt requires a different Phoenix package. Run @xgent-ai/skills@${receipt.manifest?.version || manifest.data.npmPackageVersion} for this project.`);
+  }
+}
+
+function verifyEngine(file, manifest, target, env = process.env) {
+  const meta = manifest.data.engines[target];
+  if (!meta) throw failure(`This development package has no verified engine for ${target}.`);
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.size !== meta.size || sha256(fs.readFileSync(file)) !== meta.sha256) throw failure('Phoenix binary digest or size differs from the package manifest.');
+  const probe = spawnSync(file, ['engine-probe'], { env, encoding: 'utf8', timeout: 3000, maxBuffer: 4096, windowsHide: true });
+  if (probe.error || probe.status !== 0 || probe.stdout.trim() !== `phoenix-ui-engine ${manifest.data.toolVersion}`) {
+    throw failure(`Phoenix engine identity or version differs from the package manifest. Probe: ${JSON.stringify({ error: probe.error?.code || null, status: probe.status, signal: probe.signal, stdout: probe.stdout, stderr: probe.stderr })}`);
+  }
+  return file;
+}
+
+function setupCommand(manifest, project) {
+  return `npm exec --package=@xgent-ai/skills@${manifest.data.npmPackageVersion} -- phoenix-ui engine install --project ${shellQuote(project)}`;
+}
+
+function shellQuote(value) {
+  return process.platform === 'win32' ? `'${value.replaceAll("'", "''")}'` : `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+
+function proxyFor(url, env) {
+  const noProxy = env.no_proxy || env.NO_PROXY || '';
+  const hostname = url.hostname.replace(/^\[|\]$/g, '');
+  if (noProxy.split(',').some(value => {
+    const item = value.trim().toLowerCase();
+    const [host, port] = item.split(':');
+    return item === '*' || ((!port || port === (url.port || (url.protocol === 'https:' ? '443' : '80')))
+      && (hostname === host || (host?.startsWith('.') && hostname.endsWith(host))));
+  })) return null;
+  const value = url.protocol === 'https:'
+    ? env.https_proxy || env.HTTPS_PROXY || env.all_proxy || env.ALL_PROXY || env.http_proxy || env.HTTP_PROXY
+    : env.http_proxy || env.HTTP_PROXY || env.all_proxy || env.ALL_PROXY;
+  if (!value) return null;
+  const proxy = new URL(value);
+  if (!['http:', 'https:'].includes(proxy.protocol)) throw failure('Phoenix engine install supports HTTP or HTTPS proxies.');
+  return proxy;
+}
+
+async function responseFor(url, env) {
+  const proxy = proxyFor(url, env);
+  const authorization = proxy?.username ? `Basic ${Buffer.from(`${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`).toString('base64')}` : null;
+  const transport = url.protocol === 'https:' ? https : http;
+  let connection;
+  if (proxy && url.protocol === 'https:') {
+    connection = await new Promise((resolve, reject) => {
+      const request = (proxy.protocol === 'https:' ? https : http).request(proxy, {
+        method: 'CONNECT', path: `${url.hostname}:${url.port || 443}`,
+        headers: authorization ? { 'Proxy-Authorization': authorization } : {},
+      });
+      request.setTimeout(60000, () => request.destroy(failure('Engine proxy timed out.')));
+      request.on('connect', (res, socket, head) => {
+        if (res.statusCode !== 200) { socket.destroy(); reject(failure(`Engine proxy HTTP ${res.statusCode}.`)); return; }
+        if (head.length) socket.unshift(head);
+        const secure = tls.connect({ socket, servername: url.hostname });
+        secure.once('secureConnect', () => resolve(secure));
+        secure.once('error', reject);
+      });
+      request.once('error', reject);
+      request.end();
+    });
+  }
+  return new Promise((resolve, reject) => {
+    const options = connection ? { agent: false, createConnection: () => connection } : {};
+    const destination = proxy && url.protocol === 'http:' ? proxy : url;
+    const client = proxy && url.protocol === 'http:' ? (proxy.protocol === 'https:' ? https : http) : transport;
+    if (proxy && url.protocol === 'http:') Object.assign(options, { path: url.href, headers: { Host: url.host, ...(authorization ? { 'Proxy-Authorization': authorization } : {}) } });
+    const request = client.get(destination, options, resolve);
+    request.setTimeout(60000, () => request.destroy(failure('Engine download timed out.')));
+    request.once('error', reject);
+  });
+}
+
+async function download(meta, env) {
+  let url = checkedUrl(meta.url);
+  for (let redirects = 0; redirects <= 5; redirects++) {
+    const res = await responseFor(url, env);
+    if ([301, 302, 303, 307, 308].includes(res.statusCode)) {
+      res.resume();
+      if (!res.headers.location || redirects === 5) throw failure('Invalid engine download redirect.');
+      const next = checkedUrl(new URL(res.headers.location, url).href);
+      if (url.protocol === 'https:' && next.protocol !== 'https:') throw failure('Engine download refused an HTTPS downgrade.');
+      url = next;
+      continue;
+    }
+    if (res.statusCode !== 200) { res.resume(); throw failure(`Engine download HTTP ${res.statusCode}.`); }
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of res) {
+      length += chunk.length;
+      if (length > meta.size) { res.destroy(); throw failure('Engine download exceeded the pinned size.'); }
+      chunks.push(chunk);
+    }
+    const bytes = Buffer.concat(chunks);
+    if (bytes.length !== meta.size || sha256(bytes) !== meta.sha256) throw failure('Engine download failed the pinned digest/size check.');
+    return bytes;
+  }
+  throw failure('Engine redirect limit exceeded.');
+}
+
+function reminderFile(project, version, event, env) {
+  const session = event.session_id || event.sessionId || env.CODEX_SESSION_ID || env.CLAUDE_SESSION_ID || '';
+  const provider = hookProvider(env, event);
+  const key = sha256(JSON.stringify([project, version, provider, session]));
+  return path.join(cacheRoot(env), 'unavailable', `${key}.json`);
+}
+
+function hookProvider(env, event) {
+  const provider = env.PHOENIX_UI_PROVIDER_ID || event.harness || 'source';
+  return provider === 'claude-code' ? 'claude' : provider === 'agents' ? 'codex' : provider;
+}
+
+function unavailableHook(project, manifest, event, env, message, version = manifest?.data.toolVersion || 'missing-manifest') {
+  const marker = reminderFile(project, version, event, env);
+  try {
+    fs.mkdirSync(path.dirname(marker), { recursive: true });
+    fs.writeFileSync(marker, JSON.stringify({ project, version, provider: hookProvider(env, event) }), { flag: 'wx', mode: 0o600 });
+  } catch (error) {
+    if (error.code === 'EEXIST') return;
+    // A read-only cache still permits the edit; it cannot persist deduplication.
+  }
+  const text = `Phoenix UI unavailable: ${message} ${manifest ? setupCommand(manifest, project) : 'Reinstall the pinned @xgent-ai/skills package.'}`;
+  const eventName = [event.hook_event_name, event.hookEventName].find(name => typeof name === 'string' && name) || 'PostToolUse';
+  const provider = hookProvider(env, event);
+  if (eventName.toLowerCase() === 'stop') { process.stderr.write(`${text}\n`); return; }
+  const output = provider === 'cursor' ? { additional_context: text }
+    : provider === 'github' ? { additionalContext: text }
+      : { hookSpecificOutput: { hookEventName: eventName, additionalContext: text } };
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+}
+
+function clearReminders(project, manifest, env) {
+  const dir = path.join(cacheRoot(env), 'unavailable');
+  if (!fs.existsSync(dir)) return;
+  for (const name of fs.readdirSync(dir)) {
+    const file = path.join(dir, name);
+    try {
+      const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (record.project === project && record.version === manifest.data.toolVersion) fs.unlinkSync(file);
+    } catch { /* An unrelated marker does not affect the installed engine. */ }
+  }
+}
+
+async function retryStagedFile(operation) {
+  for (let attempt = 0;; attempt++) {
+    try { return operation(); } catch (error) {
+      if (!['EBUSY', 'EPERM'].includes(error.code) || attempt === 5) throw error;
+      await new Promise(resolve => setTimeout(resolve, 25 * 2 ** attempt));
+    }
+  }
+}
+
+async function installEngine(manifest, target, project, releaseDir, env) {
+  const meta = manifest.data.engines[target];
+  if (!meta) throw failure(`No ${target} engine in this package manifest.`);
+  const dest = enginePath(manifest, target, env);
+  try { verifyEngine(dest, manifest, target, env); clearReminders(project, manifest, env); return dest; } catch { /* Explicit install repairs a missing or corrupt cache. */ }
+  let bytes;
+  if (releaseDir) {
+    const release = manifestAt(path.join(releaseDir, 'VERSION.json'));
+    if (release.hash !== manifest.hash) throw failure('Offline release manifest differs from this npm package.');
+    for (const name of ['THIRD-PARTY.json', 'THIRD-PARTY-NOTICES.md', 'THIRD-PARTY-LICENSES']) {
+      if (!fs.existsSync(path.join(releaseDir, name))) throw failure(`Offline release is missing ${name}.`);
+    }
+    bytes = fs.readFileSync(path.join(releaseDir, meta.asset));
+  } else {
+    if (!meta.url) throw failure('Development engine has no download URL; use --release-dir with its verified local artifacts.');
+    bytes = await download(meta, env);
+  }
+  if (bytes.length !== meta.size || sha256(bytes) !== meta.sha256) throw failure('Engine digest/size differs from the fixed package manifest.');
+  fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+  const temp = `${dest}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.part${process.platform === 'win32' ? '.exe' : ''}`;
+  let created = false;
+  let installError;
+  try {
+    fs.writeFileSync(temp, bytes, { flag: 'wx', mode: 0o700 });
+    created = true;
+    verifyEngine(temp, manifest, target, env);
+    await retryStagedFile(() => fs.renameSync(temp, dest));
+  } catch (error) {
+    installError = error;
+    throw error;
+  } finally {
+    if (created && fs.existsSync(temp)) {
+      try { await retryStagedFile(() => fs.unlinkSync(temp)); } catch (error) {
+        if (!installError) throw error;
+        installError.message += ` Cleanup of the staged engine failed: ${error.message}`;
+      }
+    }
+  }
+  clearReminders(project, manifest, env);
+  return dest;
+}
+
+async function main(args, options = {}) {
+  const env = { ...process.env, ...options.env };
+  const hook = HOOKS.has(args[0]);
+  let input;
+  let event = {};
+  if (hook) {
+    input = fs.readFileSync(0);
+    try {
+      const parsed = JSON.parse(input.toString('utf8') || '{}');
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) event = parsed;
+    } catch { /* The native hook owns malformed event handling. */ }
+  }
+  let manifest;
+  let target;
+  let project = process.cwd();
+  const manifestPath = options.manifestPath || path.join(__dirname, 'ENGINE.json');
+  const json = args.includes('--json');
+  try {
+    manifest = manifestAt(manifestPath);
+    project = projectRoot(env.CLAUDE_PROJECT_DIR || event.cwd || project);
+    target = platformTarget();
+    if (args[0] === 'engine' && args[1] === 'install') {
+      let releaseDir;
+      for (let i = 2; i < args.length; i++) {
+        if (args[i] === '--json') continue;
+        if (!['--project', '--release-dir'].includes(args[i]) || !args[i + 1]) throw failure('Usage: phoenix-ui engine install [--project DIR] [--release-dir DIR] [--json]', 2);
+        const flag = args[i++];
+        if (flag === '--project') {
+          const requested = path.resolve(args[i]);
+          if (!fs.existsSync(requested) || !fs.statSync(requested).isDirectory()) throw failure(`Project directory does not exist: ${requested}`, 2);
+          project = projectRoot(requested);
+        }
+        else releaseDir = path.resolve(args[i]);
+      }
+      verifyReceipt(project, manifest);
+      const binary = await installEngine(manifest, target, project, releaseDir, env);
+      process.stdout.write(json ? `${JSON.stringify({ status: 'installed', toolVersion: manifest.data.toolVersion, target, binary })}\n` : `Phoenix UI ${manifest.data.toolVersion} ready: ${binary}\n`);
+      return 0;
+    }
+    // Installer verbs replace or roll back the installed package themselves.
+    if (!['install', 'migrate'].includes(args[0])) verifyReceipt(project, manifest);
+    const binary = verifyEngine(enginePath(manifest, target, env), manifest, target, env);
+    clearReminders(project, manifest, env);
+    const childEnv = { ...env, PHOENIX_UI_SELF: options.self || process.argv[1], PHOENIX_UI_SKILL_DIR: options.skillDir || path.resolve(__dirname, '..') };
+    const childArgs = [...args];
+    const skillsVerb = args[0] === 'skills' ? args[1] : args[0];
+    if (options.bundleRoot && ['install', 'update', 'link', 'check'].includes(skillsVerb) && !args.some(a => a === '--bundle-root' || a.startsWith('--bundle-root='))) childArgs.push('--bundle-root', options.bundleRoot);
+    // Project installs also carry the auxiliary skills shipped beside phoenix-ui.
+    const userLevel = args.some((a, i) => ['--user', '--global', '--scope=global', '--help', '-h'].includes(a) || (a === '--scope' && args[i + 1] === 'global'));
+    if (options.bundleRoot && options.skillDir && ['install', 'update'].includes(args[0]) && !userLevel
+        && !args.some(a => a === '--auxiliary-root' || a.startsWith('--auxiliary-root='))) childArgs.push('--auxiliary-root', path.dirname(options.skillDir));
+    return await new Promise((resolve, reject) => {
+      const child = spawn(binary, childArgs, { env: childEnv, stdio: hook ? ['pipe', 'inherit', 'inherit'] : 'inherit', windowsHide: true });
+      if (hook) {
+        // The engine may answer before reading the whole event; its exit code decides.
+        child.stdin.on('error', error => { if (error.code !== 'EPIPE') reject(error); });
+        child.stdin.end(input);
+      }
+      const interrupt = () => child.kill('SIGINT');
+      const terminate = () => child.kill('SIGTERM');
+      process.on('SIGINT', interrupt);
+      process.on('SIGTERM', terminate);
+      child.once('error', reject);
+      child.once('close', (code, signal) => {
+        process.removeListener('SIGINT', interrupt);
+        process.removeListener('SIGTERM', terminate);
+        resolve(code ?? (signal === 'SIGINT' ? 130 : 143));
+      });
+    });
+  } catch (error) {
+    if (hook) {
+      let version = manifest?.data.toolVersion || 'missing-manifest';
+      if (!manifest) {
+        try { project = projectRoot(env.CLAUDE_PROJECT_DIR || event.cwd || project); } catch { /* Keep the original cwd when unavailable. */ }
+        try {
+          // VERSION only identifies the reminder; it never authorizes an engine.
+          const pinned = fs.readFileSync(path.join(path.dirname(manifestPath), 'VERSION'), 'utf8').trim();
+          if (/^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(pinned)) version = pinned;
+        } catch { /* An incomplete install may lack both metadata files. */ }
+      }
+      unavailableHook(project, manifest, event, env, error.message, version);
+      return 0;
+    }
+    const command = manifest ? setupCommand(manifest, project) : 'Reinstall the pinned @xgent-ai/skills package.';
+    process.stderr.write(`Phoenix UI: ${error.message}\n${command}\n`);
+    if (json) process.stdout.write(`${JSON.stringify({ status: 'unavailable', toolVersion: manifest?.data.toolVersion, target, message: error.message, setupCommand: command })}\n`);
+    return error.code === 2 || error.code === 3 ? error.code : 4;
+  }
+}
+
+module.exports = { TARGETS, platformTarget, manifestAt, enginePath, verifyEngine, verifyReceipt, setupCommand, shellQuote, proxyFor, installEngine, sha256, main };
+if (require.main === module) main(process.argv.slice(2)).then(code => { process.exitCode = code; }).catch(error => { process.stderr.write(`${error.message}\n`); process.exitCode = 4; });

package/vendor/phoenix-ui/bundle/blobs/8b93fd638213e11723dc10d0cdc5a3499314f8528330007028eb58573cddcd41

@@ -0,0 +1,54 @@
+Report and repair drift between this project's Phoenix UI artifacts and what the installed version reads: PRODUCT.md, DESIGN.md and its `.phoenix-ui/design.json` sidecar, `.phoenix-ui/config.json`, persisted surface briefs, and the design hook.
+
+This is maintenance, not design. Do not redesign anything, do not open files outside the ones the report names, and do not run any other command as a side effect.
+
+## What this owns, and what it does not
+
+Three kinds of drift travel under "out of date". Keep them apart:
+
+- **Tool version.** The installed skill is older than the published one. `phoenix-ui context` reports that at boot as `UPDATE_AVAILABLE` and `npx phoenix-ui update` fixes it. Not this command's job.
+- **Schema drift.** An artifact was written by an older Phoenix UI: fields nothing reads, fields now expected, files in retired locations. Mechanical, and this command repairs most of it.
+- **Truth drift.** The code moved on and the document no longer describes it. No file comparison settles this. `document` owns DESIGN.md, `init` owns PRODUCT.md, and this command's job is to hand them a specific gap rather than a vague suspicion.
+
+## Step 1: Run the pass
+
+```
+.agents/skills/phoenix-ui/scripts/phoenix-ui doctor --json
+```
+
+Add `--target <path>` when the user named a workspace, file, or route in a monorepo. Without it the report describes the repo root, and in a monorepo that is often the wrong project.
+
+The output carries `findings` (each with `id`, `artifact`, `path`, `severity`, `summary`, `fix`) and, in a monorepo, `workspaces` with each app's product and design resolution. `ruleRegistryAvailable: false` means ignored rule ids could not be validated; say so rather than implying that list is clean.
+
+An empty `findings` array is the good outcome. Say so in one line and stop.
+
+## Step 2: Act by severity
+
+The severity says what should happen, not how bad it is.
+
+- **`auto`** carries no decision. Run `.agents/skills/phoenix-ui/scripts/phoenix-ui doctor --fix` once to apply these, then report what it moved in one line. Do not ask permission first, and do not ask about them afterward.
+- **`mention`** needs the user to know but not to decide anything now. State each one in a sentence with its offered fix.
+- **`route`** needs a specific command. Name the command and the gap it would close. Run it only if the user asks in this turn; `init` and `document` are conversations, not repairs you perform unattended.
+
+Report all three groups in one pass. Findings are not errors and the command does not fail on them.
+
+## Step 3: Deprecated fields are binding
+
+A finding that reports a deprecated field (`## Register` is the current one) is not a style note. Treat that field as absent for every decision from here on, whatever value it holds, and offer to delete the section. Preserving it "just in case" is how a retired axis keeps steering current output.
+
+## Step 4: Do not overclaim on truth drift
+
+`design-md-drift` counts commits to the visual source directories since DESIGN.md was last edited. A commit count is not a contradiction. Report the number, say what it measures, and if the user wants to know whether the document is actually wrong, read DESIGN.md against the current tokens and components and answer from that. Never assert that DESIGN.md is stale because the number is large.
+
+The same restraint applies to `workspace-context-inherited`. Inheritance is a designed behavior. Whether one product record truthfully describes several apps is a question for the user, not a defect to fix.
+
+## Monorepo notes
+
+- `workspace-platform-native-evidence` is the finding that matters most here: a workspace carrying native build files while inheriting a root record that resolves to web gets web guidance for its whole life and never loads [ios.md](ios.md) or [android.md](android.md). The repair is a child PRODUCT.md in that workspace, because one inherited record cannot hold two platforms.
+- `config-project-roots-match-nothing` means every `projectRoots` glob missed, so the repo root is silently standing in as the active project. A renamed workspace directory is the usual cause. Report the patterns and ask which directories they should name.
+- `config-invalid-build-path` and `config-build-path-unset` both concern one key, `buildPath` in `.phoenix-ui/config.json` (or the gitignored `.phoenix-ui/config.local.json`, which wins for that developer). It holds `comp` or `code` and sets whether new surfaces are built from a generated comp or straight in code. An unread value does not fall back to the opposite path, so a project meaning `code` has been building comp-led; report the exact value. The unset finding fires only where a project has done direction work and never recorded a preference, and the offer belongs in it only when image generation exists in your tool surface. Without image generation there is nothing to choose and nothing to say.
+- Use the `workspaces` table to show the user which apps carry their own context, which inherit, and which have none, before proposing any change.
+
+## Opting out of the boot check
+
+`phoenix-ui context` reports the cheap subset of these findings at session start, throttled to once a week per project. Set `"stalenessCheck": false` in `.phoenix-ui/config.json` to silence that, or `PHOENIX_UI_NO_STALENESS_CHECK=1` for one session. This command still works with the check disabled, and that is the combination to suggest for a user who wants the report only when they ask for it.

package/vendor/phoenix-ui/bundle/blobs/8be043afdb409130c6e5050b8d979ce1abb60f38ed2af0137d17eabdd7dfc62a

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const { main, shellQuote } = require('./phoenix-bootstrap.cjs');
+const provider = "agents";
+process.env.PHOENIX_UI_PROVIDER_ID ||= provider;
+main(process.argv.slice(2), {
+  skillDir: path.resolve(__dirname, '..'),
+  self: `node ${shellQuote(__filename)}`,
+}).then(code => { process.exitCode = code; }).catch(error => {
+  process.stderr.write(`Phoenix UI: ${error.message}\n`);
+  process.exitCode = 4;
+});

package/vendor/phoenix-ui/bundle/blobs/8c7aaa03ec8131eb4c2f25f5f33cdcb7e011e7db0240f5a9d926386585ed1f49

@@ -0,0 +1,80 @@
+Typography carries information, hierarchy, and voice. Improve it inside the established visual world; do not replace the identity unless the user asked to.
+
+---
+
+## Visitor mode
+
+- **Persuade + Experience:** display type may carry the voice. Use decisive contrast and responsive scale when the composition benefits.
+- **Operate + Read:** stability, scanability, and measure come first. A single well-tuned family and fixed role scale are often right.
+- **Native:** follow [ios.md](ios.md) or [android.md](android.md), including platform scaling and accessibility behavior.
+
+If typography replacement would create a new identity, route through [new-work.md](new-work.md) and update DESIGN.md. Otherwise preserve confirmed families and improve their use.
+
+## Two isolated assessments
+
+When a sub-agent tool is available and permitted, run these independently; otherwise run them yourself in this order. Do not let detector findings anchor the design assessment.
+
+1. **Typographic assessment:** inspect representative pages and styles. Answer every question below with a file, selector, or computed value:
+   - **Authority and fit:** Which faces, weights, and roles are established? Do they fit the product and selected world, or are they unexamined defaults? Is every family necessary?
+   - **Hierarchy:** Can heading, body, label, metadata, and data roles be distinguished at a glance? Are adjacent sizes or weights too close to carry different jobs?
+   - **Scale and consistency:** Is there a deliberate role scale, or a collection of arbitrary values? Do repeated roles stay identical across screens and states?
+   - **Reading:** Does body copy stay within a comfortable 45–75 character measure? Are line height, paragraph rhythm, contrast, and tracking tuned to the actual face, width, language, and surface?
+   - **Stress:** What happens with long headings, localization expansion, zoom, narrow containers, missing weights, and font fallback?
+   - **Delivery:** Are only used assets loaded? Do fallback metrics, loading strategy, and variable-font settings avoid invisible text and disruptive reflow?
+2. **Mechanical scan:** run:
+
+```bash
+.trae-cn/skills/phoenix-ui/scripts/phoenix-ui detect --json --scope type [target files or dirs]
+```
+
+Also inspect dynamic or arbitrary font values the detector cannot interpret. Synthesize both assessments before editing, noting what each caught alone. A clean scan is a floor, not proof of good typography.
+
+## Set the system
+
+Before editing, state:
+
+- the roles the interface needs;
+- the intended contrast between those roles;
+- the reading measure and density;
+- which existing faces and weights are authoritative;
+- any performance, localization, or accessibility constraints.
+
+Use the fewest roles and families that make the hierarchy unmistakable. Combine size, weight, space, and tone deliberately instead of asking size alone to do all the work. Role names and tokens should describe purpose rather than values.
+
+## Apply
+
+- Keep body copy comfortably readable and zoomable. Use 1rem / 16px as the ordinary web body floor unless a dense role, platform convention, or user setting justifies otherwise.
+- Keep prose in the 45–75ch range. Tune line height inversely with measure: wider lines generally need more leading.
+- Compensate light text on dark surfaces on all three perceptual axes: slightly more line height, a touch more tracking, and one step more weight when the face needs it.
+- Tune line height to the face, width, language, and contrast, not a universal ratio.
+- Keep repeated roles consistent across screens and states.
+- Use numeric, tabular, code, and label features when their content benefits.
+- Load only used font assets and weights. Provide metric-compatible fallbacks and avoid blocking text.
+- Let marketing display type respond to available space when useful; keep dense product and reading surfaces spatially predictable.
+- Preserve browser zoom, user font settings, Dynamic Type, and platform text scaling.
+- Use paragraph spacing or first-line indentation as the primary paragraph rhythm; combining both usually double-marks the boundary.
+
+Do not make type decorative at the expense of comprehension, or introduce a second family without a clear role it alone can perform.
+
+## Verify
+
+- Primary, secondary, body, and metadata roles are recognizable without reading the copy.
+- Long text remains comfortable across relevant widths and languages.
+- The typography belongs to the product and its established world.
+- Loading does not create disruptive reflow or invisible text.
+- Zoom, text scaling, focus, contrast, and reduced viewport paths remain usable.
+- The final mechanical scan has no unexplained findings.
+
+Answer each item with rendered or source evidence, then rerun the scan. Do not substitute a bare “yes” for verification.
+
+When the hierarchy holds, hand off to `/phoenix-ui polish`.
+
+## Live-mode signature params
+
+Every variant declares a coarse `scale` parameter and authors its type ramp against `var(--p-scale, 1)`.
+
+```json
+{"id":"scale","kind":"range","min":0.85,"max":1.3,"step":0.05,"default":1,"label":"Scale"}
+```
+
+Add at most one pairing or weight parameter when it represents a real system choice. Follow [live.md](live.md)'s parameter contract.

package/vendor/phoenix-ui/bundle/blobs/8d35fdd9909ecb618b5fd2fb7ef49e90f234ff946b541b9acc14580b8a293b7d

@@ -0,0 +1,80 @@
+Typography carries information, hierarchy, and voice. Improve it inside the established visual world; do not replace the identity unless the user asked to.
+
+---
+
+## Visitor mode
+
+- **Persuade + Experience:** display type may carry the voice. Use decisive contrast and responsive scale when the composition benefits.
+- **Operate + Read:** stability, scanability, and measure come first. A single well-tuned family and fixed role scale are often right.
+- **Native:** follow [ios.md](ios.md) or [android.md](android.md), including platform scaling and accessibility behavior.
+
+If typography replacement would create a new identity, route through [new-work.md](new-work.md) and update DESIGN.md. Otherwise preserve confirmed families and improve their use.
+
+## Two isolated assessments
+
+When a sub-agent tool is available and permitted, run these independently; otherwise run them yourself in this order. Do not let detector findings anchor the design assessment.
+
+1. **Typographic assessment:** inspect representative pages and styles. Answer every question below with a file, selector, or computed value:
+   - **Authority and fit:** Which faces, weights, and roles are established? Do they fit the product and selected world, or are they unexamined defaults? Is every family necessary?
+   - **Hierarchy:** Can heading, body, label, metadata, and data roles be distinguished at a glance? Are adjacent sizes or weights too close to carry different jobs?
+   - **Scale and consistency:** Is there a deliberate role scale, or a collection of arbitrary values? Do repeated roles stay identical across screens and states?
+   - **Reading:** Does body copy stay within a comfortable 45–75 character measure? Are line height, paragraph rhythm, contrast, and tracking tuned to the actual face, width, language, and surface?
+   - **Stress:** What happens with long headings, localization expansion, zoom, narrow containers, missing weights, and font fallback?
+   - **Delivery:** Are only used assets loaded? Do fallback metrics, loading strategy, and variable-font settings avoid invisible text and disruptive reflow?
+2. **Mechanical scan:** run:
+
+```bash
+.github/skills/phoenix-ui/scripts/phoenix-ui detect --json --scope type [target files or dirs]
+```
+
+Also inspect dynamic or arbitrary font values the detector cannot interpret. Synthesize both assessments before editing, noting what each caught alone. A clean scan is a floor, not proof of good typography.
+
+## Set the system
+
+Before editing, state:
+
+- the roles the interface needs;
+- the intended contrast between those roles;
+- the reading measure and density;
+- which existing faces and weights are authoritative;
+- any performance, localization, or accessibility constraints.
+
+Use the fewest roles and families that make the hierarchy unmistakable. Combine size, weight, space, and tone deliberately instead of asking size alone to do all the work. Role names and tokens should describe purpose rather than values.
+
+## Apply
+
+- Keep body copy comfortably readable and zoomable. Use 1rem / 16px as the ordinary web body floor unless a dense role, platform convention, or user setting justifies otherwise.
+- Keep prose in the 45–75ch range. Tune line height inversely with measure: wider lines generally need more leading.
+- Compensate light text on dark surfaces on all three perceptual axes: slightly more line height, a touch more tracking, and one step more weight when the face needs it.
+- Tune line height to the face, width, language, and contrast, not a universal ratio.
+- Keep repeated roles consistent across screens and states.
+- Use numeric, tabular, code, and label features when their content benefits.
+- Load only used font assets and weights. Provide metric-compatible fallbacks and avoid blocking text.
+- Let marketing display type respond to available space when useful; keep dense product and reading surfaces spatially predictable.
+- Preserve browser zoom, user font settings, Dynamic Type, and platform text scaling.
+- Use paragraph spacing or first-line indentation as the primary paragraph rhythm; combining both usually double-marks the boundary.
+
+Do not make type decorative at the expense of comprehension, or introduce a second family without a clear role it alone can perform.
+
+## Verify
+
+- Primary, secondary, body, and metadata roles are recognizable without reading the copy.
+- Long text remains comfortable across relevant widths and languages.
+- The typography belongs to the product and its established world.
+- Loading does not create disruptive reflow or invisible text.
+- Zoom, text scaling, focus, contrast, and reduced viewport paths remain usable.
+- The final mechanical scan has no unexplained findings.
+
+Answer each item with rendered or source evidence, then rerun the scan. Do not substitute a bare “yes” for verification.
+
+When the hierarchy holds, hand off to `/phoenix-ui polish`.
+
+## Live-mode signature params
+
+Every variant declares a coarse `scale` parameter and authors its type ramp against `var(--p-scale, 1)`.
+
+```json
+{"id":"scale","kind":"range","min":0.85,"max":1.3,"step":0.05,"default":1,"label":"Scale"}
+```
+
+Add at most one pairing or weight parameter when it represents a real system choice. Follow [live.md](live.md)'s parameter contract.