@juangcarmona/lighthouse 0.4.0 → 0.5.0

package/README.md

@@ -4,13 +4,13 @@ This package is the core Lighthouse harness. It provides the `lighthouse` comman
 
 ## Initialize a repository
 
-Install the exact Lighthouse package artifact selected for the release and run `lighthouse init --name <product>` in a new repository. Lighthouse creates the manifest, the `src/`, `docs/`, `infra/` and `scripts/` boundaries, the repository guardrails and the generated `LIGHTHOUSE.md`. Inspect the plan and projection, then run `lighthouse verify` before adding project-specific policy or exceptions.
+Install the exact Lighthouse package artifact selected for the release and run `lighthouse init --name <product>` in a new repository. Add `--profile visual-theme` when the project wants the Lighthouse UI contract. Lighthouse creates the manifest, the `src/`, `docs/`, `infra/` and `scripts/` boundaries, the repository guardrails and the generated `LIGHTHOUSE.md`. Inspect the plan and projection, then run `lighthouse verify` before adding project-specific policy or exceptions.
 
 Use `lighthouse reconcile` to preview missing Lighthouse-managed paths in an existing adoption. It does not write by default; add `--apply` only after reviewing the plan. Existing files whose content differs from the generated projection are conflicts and are never overwritten by reconciliation.
 
 Use `lighthouse upgrade` to preview a versioned foundation update. The command is dry-run by default, accepts `--scope harness`, `--scope sdlc` or `--scope all`, preserves customized projections and stops when ownership evidence is missing. Add `--apply` only after reviewing the plan, then run `lighthouse verify`.
 
-The harness package owns the baseline command and verification contract. The SDLC package owns lifecycle skills, commands, metacommands, routes and gates, and `lighthouse init` records its selected version in `.lighthouse/sdlc.json`. The UI package owns visual tokens, native recipes and `DESIGN.md`. Stack profiles own their source templates, guidance and checks.
+The harness package owns the baseline command and verification contract. The SDLC package owns lifecycle skills, commands, metacommands, routes and gates, and `lighthouse init` records its selected version in `.lighthouse/sdlc.json`. The UI package owns visual tokens, native recipes, `DESIGN.md` and its agent skill. Selecting `visual-theme` projects the guide and skill into the adopter and enables its deterministic guardrail. Stack profiles own their source templates, guidance and checks.
 
 ProductShape, ArcShape and OpenSpec keep their own files and commands. Add them through their supported integration routes when the project needs them, and keep their versions and managed paths visible in the project configuration.
 

package/assets/guardrails/catalog.json

@@ -41,6 +41,16 @@
       "verification": "deterministic",
       "check": "branch",
       "failureHint": "Use the branch pattern declared in lighthouse.json."
+    },
+    {
+      "id": "visual.design-contract",
+      "owner": "@juangcarmona/lighthouse-ui",
+      "appliesTo": { "baseline": false, "profiles": ["visual-theme"] },
+      "level": "required",
+      "kind": "hard",
+      "verification": "deterministic",
+      "check": "ui-design",
+      "failureHint": "Run lighthouse reconcile after reviewing the visual-theme profile plan, then run lighthouse verify again."
     }
   ]
 }

package/assets/schemas/lighthouse-manifest.schema.json

@@ -12,12 +12,13 @@
     "product": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$"},
     "profiles": {"type": "array", "items": {"enum": ["node-tooling", "dotnet-backend", "visual-theme"]}, "uniqueItems": true},
     "integrations": {"type": "object", "additionalProperties": false, "required": ["productShape", "arcShape"], "properties": {"productShape": {"$ref": "#/$defs/pin"}, "arcShape": {"$ref": "#/$defs/pin"}}},
-    "packages": {"type": "object", "additionalProperties": false, "required": ["sdlc"], "properties": {"sdlc": {"type": "object", "additionalProperties": false, "required": ["name", "version"], "properties": {"name": {"const": "@juangcarmona/lighthouse-sdlc"}, "version": {"$ref": "#/$defs/pin"}}}}},
+    "packages": {"type": "object", "additionalProperties": false, "required": ["sdlc"], "properties": {"sdlc": {"type": "object", "additionalProperties": false, "required": ["name", "version"], "properties": {"name": {"const": "@juangcarmona/lighthouse-sdlc"}, "version": {"$ref": "#/$defs/pin"}}}, "ui": {"type": "object", "additionalProperties": false, "required": ["name", "version"], "properties": {"name": {"const": "@juangcarmona/lighthouse-ui"}, "version": {"$ref": "#/$defs/pin"}}}}},
     "managed": {"anyOf": [
       {"const": ["LIGHTHOUSE.md"]},
       {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml"]},
       {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml", ".lighthouse/sdlc.json"]},
-      {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml", ".lighthouse/sdlc.json", ".lighthouse/upgrade.json"]}
+      {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml", ".lighthouse/sdlc.json", ".lighthouse/upgrade.json"]},
+      {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml", ".lighthouse/sdlc.json", ".lighthouse/upgrade.json", "docs/design/DESIGN.md", ".agents/skills/lighthouse-ui/SKILL.md"]}
     ]},
     "repository": {
       "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Lighthouse adoption and verification CLI",
   "repository": {
@@ -21,6 +21,7 @@
   },
   "dependencies": {
     "@arcshape/cli": "0.1.3",
+    "@juangcarmona/lighthouse-ui": "0.2.0",
     "@prodshape/cli": "0.22.0",
     "@juangcarmona/lighthouse-sdlc": "0.5.0"
   },

package/src/guardrails.mjs

@@ -7,6 +7,7 @@ const allowedLevels = new Set(['required', 'recommended', 'optional']);
 const allowedKinds = new Set(['hard', 'soft']);
 const allowedVerification = new Set(['deterministic', 'semantic', 'human']);
 const allowedStatuses = new Set(['passed', 'failed', 'drift', 'unavailable', 'unconfigured', 'pending-review', 'not-applicable']);
+const requiredVisualTokens = ['--lh-canvas', '--lh-surface', '--lh-text', '--lh-action', '--lh-border', '--lh-focus'];
 
 function descriptorProblems(descriptor) {
   const problems = [];
@@ -102,16 +103,30 @@ async function runDeterministicCheck(descriptor, context) {
     const problems = context.validateGitConventions(context.repository);
     return result(descriptor, problems.length ? 'failed' : 'passed', [{ value: context.branch ?? '' }, { pattern: context.repository.conventions.branchPattern }], problems);
   }
+  if (descriptor.check === 'ui-design') {
+    const expected = ['docs/design/DESIGN.md', '.agents/skills/lighthouse-ui/SKILL.md'];
+    const missing = [];
+    const drifted = [];
+    for (const path of expected) {
+      const target = context.resolve(path);
+      if (!context.managedFiles[path] || !(await context.exists(target))) missing.push(path);
+      else if (await context.readFile(target, 'utf8') !== context.managedFiles[path]) drifted.push(`${path} has drifted; regenerate it from the visual-theme profile.`);
+    }
+    const tokenProblems = requiredVisualTokens.filter((token) => !context.uiTokens?.includes(token)).map((token) => `${token} is missing from the installed Lighthouse UI token source.`);
+    const problems = [...missing.map((path) => `${path} is missing; run lighthouse reconcile after reviewing the visual-theme profile plan.`), ...drifted, ...tokenProblems];
+    const status = drifted.length ? 'drift' : problems.length ? 'failed' : 'passed';
+    return result(descriptor, status, [...expected.map((path) => ({ path })), ...requiredVisualTokens.map((token) => ({ token }))], problems);
+  }
   return result(descriptor, 'unavailable', [], [`No deterministic checker is registered for ${descriptor.id}.`]);
 }
 
-export async function evaluateGuardrails({ catalog, manifest, manifestProblems, repository, managedFiles, resolve, exists, isDirectory, readFile, validateGitConventions, branch }) {
+export async function evaluateGuardrails({ catalog, manifest, manifestProblems, repository, managedFiles, resolve, exists, isDirectory, readFile, validateGitConventions, branch, uiTokens }) {
   if (manifestProblems.length) {
     const descriptor = catalog.guardrails.find((item) => item.check === 'manifest') ?? catalog.guardrails[0];
     const failed = result(descriptor, 'failed', [{ path: 'lighthouse.json' }], manifestProblems.map((problem) => `Invalid lighthouse.json: ${problem}`));
     return report([failed]);
   }
-  const context = { manifest, repository, managedFiles, resolve, exists, isDirectory, readFile, validateGitConventions, branch };
+  const context = { manifest, repository, managedFiles, resolve, exists, isDirectory, readFile, validateGitConventions, branch, uiTokens };
   const results = [];
   for (const descriptor of catalog.guardrails) {
     if (!appliesTo(descriptor, manifest)) {

package/src/lighthouse.mjs

@@ -32,6 +32,7 @@ const upgradeStateRelative = '.lighthouse/upgrade.json';
 const upgradeStatePath = resolve(root, upgradeStateRelative);
 const layout = ['src', 'docs', 'infra', 'scripts'];
 const sdlcPackage = { name: '@juangcarmona/lighthouse-sdlc', version: installedPackageVersion('@juangcarmona/lighthouse-sdlc', 'contract.json') ?? '0.1.0' };
+const uiPackage = { name: '@juangcarmona/lighthouse-ui', version: installedPackageVersion('@juangcarmona/lighthouse-ui', 'DESIGN.md') ?? '0.1.0' };
 const managedPaths = [
   projection,
   'scripts/lighthouse-guard.mjs',
@@ -41,16 +42,16 @@ const managedPaths = [
   '.lighthouse/sdlc.json',
   upgradeStateRelative,
 ];
+const profileManagedPaths = Object.freeze({
+  'visual-theme': ['docs/design/DESIGN.md', '.agents/skills/lighthouse-ui/SKILL.md'],
+});
 const previousManagedPaths = managedPaths.slice(0, -1);
 const legacyManagedPaths = [projection];
+const supportedProfiles = ['node-tooling', 'dotnet-backend', 'visual-theme'];
 const branchPattern = '^(feat|fix|docs|refactor|test|chore|build|ci|perf|revert)/[1-9]\\d*-[a-z0-9]+(?:-[a-z0-9]+)*$';
 const authorityVersions = { productShape: '0.22.0', arcShape: '0.1.3' };
-const upgradeScopes = {
-  harness: [projection, 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml'],
-  sdlc: ['.lighthouse/sdlc.json'],
-};
 const upgradeSchema = './node_modules/@juangcarmona/lighthouse/assets/schemas/lighthouse-upgrade.schema.json';
-const usage = 'Usage: lighthouse <init|authorities|reconcile|upgrade|capabilities|verify> [--name <product>] [--scope <harness|sdlc|all>] [--format <text|json>] [--dry-run] [--apply]';
+const usage = 'Usage: lighthouse <init|authorities|reconcile|upgrade|capabilities|verify> [--name <product>] [--profile <profile>] [--scope <harness|sdlc|all>] [--format <text|json>] [--dry-run] [--apply]';
 
 const defaultRepository = () => ({
   layout: [...layout],
@@ -58,16 +59,59 @@ const defaultRepository = () => ({
   conventions: { commits: 'conventional', branchPattern },
 });
 
-function defaultManifest(product) {
+function managedPathsFor(manifest) {
+  const profiles = manifest?.profiles ?? [];
+  return [...managedPaths, ...profiles.flatMap((profile) => profileManagedPaths[profile] ?? [])];
+}
+
+function upgradeScopesFor(manifest) {
+  return {
+    harness: [projection, 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml', ...((manifest?.profiles ?? []).flatMap((profile) => profileManagedPaths[profile] ?? []))],
+    sdlc: ['.lighthouse/sdlc.json'],
+  };
+}
+
+function packageAsset(packageName, entry) {
+  const path = packageRequire.resolve(`${packageName}/${entry}`);
+  return readFileSync(path, 'utf8');
+}
+
+function profileAssets(manifest) {
+  if (!(manifest?.profiles ?? []).includes('visual-theme')) return {};
+  try {
+    return {
+      'docs/design/DESIGN.md': packageAsset('@juangcarmona/lighthouse-ui', 'DESIGN.md'),
+      '.agents/skills/lighthouse-ui/SKILL.md': packageAsset('@juangcarmona/lighthouse-ui', 'skills/ui-design/SKILL.md'),
+    };
+  } catch (error) {
+    throw new Error(`Cannot read the installed Lighthouse UI profile: ${error.message}`);
+  }
+}
+
+function profileArguments(args) {
+  const selected = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] !== '--profile' && !args[index].startsWith('--profile=')) continue;
+    const value = args[index] === '--profile' ? args[++index] : args[index].slice('--profile='.length);
+    if (!value || !supportedProfiles.includes(value)) throw new Error(`Unknown profile ${value ?? ''}; use ${supportedProfiles.join(', ')}.`);
+    if (!selected.includes(value)) selected.push(value);
+  }
+  return selected;
+}
+
+function defaultManifest(product, profiles = []) {
+  const draft = { profiles: [...profiles] };
+  const packages = { sdlc: { ...sdlcPackage } };
+  if (profiles.includes('visual-theme')) packages.ui = { ...uiPackage };
   return {
     $schema: './node_modules/@juangcarmona/lighthouse/assets/schemas/lighthouse-manifest.schema.json',
     schemaVersion: 1,
     baseline: '0.1.0',
     product,
-    profiles: [],
+    profiles: [...profiles],
     integrations: { productShape: null, arcShape: null },
-    packages: { sdlc: { ...sdlcPackage } },
-    managed: [...managedPaths],
+    packages,
+    managed: managedPathsFor(draft),
     repository: defaultRepository(),
   };
 }
@@ -167,7 +211,9 @@ function render(manifest) {
   const publicSite = repository.publicSite.enabled ? 'enabled' : 'disabled';
   const selectedSdlc = normalizeSdlcPackage(manifest);
   const sdlcLine = selectedSdlc ? `- SDLC package: \`${selectedSdlc.name}@${selectedSdlc.version}\`\n` : '';
-  return `<!-- Generated by Lighthouse. Edit lighthouse.json and regenerate this file. -->\n\n# ${manifest.product} repository baseline\n\n- Baseline: \`${manifest.baseline}\`\n- Product: \`${manifest.product}\`\n- Profiles: ${manifest.profiles.length ? manifest.profiles.map((x) => `\`${x}\``).join(', ') : 'none'}\n${sdlcLine}- ProductShape: ${manifest.integrations.productShape ?? 'not adopted'}\n- ArcShape: ${manifest.integrations.arcShape ?? 'not adopted'}\n- Public site: \`${publicSite}\`\n- Repository roots: ${repository.layout.map((x) => `\`${x}/\``).join(', ')}\n- Commit convention: \`${repository.conventions.commits}\`\n\n## Delivery contract\n\nProductShape remains the source of product intent and Product Changes. ArcShape remains the source of architecture documentation and decisions. Lighthouse installs the repository baseline and verifies the selected integrations without replacing either authority.\n\nThe repository keeps source code in \`src/\`, documentation in \`docs/\`, infrastructure in \`infra/\` and repository automation in \`scripts/\`. A project may record a narrow, owned exception, but an initializer never overwrites an existing project file.\n\nThe selected SDLC package owns lifecycle skills, commands, meta-commands, routes and gates. The \`.lighthouse/\` control plane records the selected package and host adapters without storing agent runtime data.\n\nWhen the public site is enabled, its publication is allowed only after ProductShape and ArcShape validate successfully. A missing or invalid authority stops the build before deployment and reports the command that can repair the missing input.\n\nThis file is managed. Put repository-specific policy in its own documentation and keep this projection generated from \`lighthouse.json\`.\n`;
+  const selectedUi = manifest.packages?.ui;
+  const uiLine = selectedUi ? `- UI package: \`${selectedUi.name}@${selectedUi.version}\`\n` : '';
+  return `<!-- Generated by Lighthouse. Edit lighthouse.json and regenerate this file. -->\n\n# ${manifest.product} repository baseline\n\n- Baseline: \`${manifest.baseline}\`\n- Product: \`${manifest.product}\`\n- Profiles: ${manifest.profiles.length ? manifest.profiles.map((x) => `\`${x}\``).join(', ') : 'none'}\n${sdlcLine}${uiLine}- ProductShape: ${manifest.integrations.productShape ?? 'not adopted'}\n- ArcShape: ${manifest.integrations.arcShape ?? 'not adopted'}\n- Public site: \`${publicSite}\`\n- Repository roots: ${repository.layout.map((x) => `\`${x}/\``).join(', ')}\n- Commit convention: \`${repository.conventions.commits}\`\n\n## Delivery contract\n\nProductShape remains the source of product intent and Product Changes. ArcShape remains the source of architecture documentation and decisions. Lighthouse installs the repository baseline and verifies the selected integrations without replacing either authority.\n\nThe repository keeps source code in \`src/\`, documentation in \`docs/\`, infrastructure in \`infra/\` and repository automation in \`scripts/\`. A project may record a narrow, owned exception, but an initializer never overwrites an existing project file.\n\nThe selected SDLC package owns lifecycle skills, commands, meta-commands, routes and gates. The \`.lighthouse/\` control plane records the selected package and host adapters without storing agent runtime data.\n\nWhen the public site is enabled, its publication is allowed only after ProductShape and ArcShape validate successfully. A missing or invalid authority stops the build before deployment and reports the command that can repair the missing input.\n\nThis file is managed. Put repository-specific policy in its own documentation and keep this projection generated from \`lighthouse.json\`.\n`;
 }
 
 function guardrailScript(manifest) {
@@ -259,6 +305,7 @@ function managedFiles(manifest) {
     '.husky/pre-push': prePushHook(),
     '.github/workflows/lighthouse.yml': workflow(),
   };
+  Object.assign(files, profileAssets(manifest));
   const controlPlane = sdlcControlPlane(manifest);
   if (controlPlane) files['.lighthouse/sdlc.json'] = controlPlane;
   return files;
@@ -269,9 +316,10 @@ function contentHash(content) {
 }
 
 function upgradeState(manifest, files = managedFiles(manifest), previous = null) {
+  const scopes = upgradeScopesFor(manifest);
   const entries = Object.fromEntries(Object.entries(files).map(([path, content]) => [path, {
     hash: contentHash(content),
-    scope: Object.entries(upgradeScopes).find(([, paths]) => paths.includes(path))?.[0] ?? 'harness',
+    scope: Object.entries(scopes).find(([, paths]) => paths.includes(path))?.[0] ?? 'harness',
   }]));
   return {
     $schema: upgradeSchema,
@@ -309,7 +357,8 @@ function stateProblems(state) {
   return problems;
 }
 
-function scopesFromArgs(args) {
+function scopesFromArgs(args, manifest) {
+  const upgradeScopes = upgradeScopesFor(manifest);
   const selected = new Set();
   for (let index = 0; index < args.length; index += 1) {
     if (args[index] !== '--scope' && !args[index].startsWith('--scope=')) continue;
@@ -325,7 +374,8 @@ function scopesFromArgs(args) {
   return selected.size ? selected : new Set(Object.keys(upgradeScopes));
 }
 
-function selectedPaths(scopes) {
+function selectedPaths(scopes, manifest) {
+  const upgradeScopes = upgradeScopesFor(manifest);
   return new Set([...scopes].flatMap((scope) => upgradeScopes[scope]));
 }
 
@@ -343,7 +393,8 @@ async function planUpgrade(manifest, scopes) {
   const state = await readUpgradeState();
   const problems = stateProblems(state);
   const files = managedFiles(manifest);
-  const paths = selectedPaths(scopes);
+  const paths = selectedPaths(scopes, manifest);
+  const upgradeScopes = upgradeScopesFor(manifest);
   const changes = [];
   for (const path of Object.keys(files).filter((candidate) => paths.has(candidate))) {
     const target = resolve(root, path);
@@ -418,7 +469,7 @@ function validate(manifest) {
   if (typeof manifest.product !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/.test(manifest.product)) {
     problems.push('product must be a readable name of 1–64 characters');
   }
-  const profiles = ['node-tooling', 'dotnet-backend', 'visual-theme'];
+  const profiles = supportedProfiles;
   if (!Array.isArray(manifest.profiles) || manifest.profiles.some((p) => !profiles.includes(p))
       || new Set(manifest.profiles).size !== manifest.profiles.length) {
     problems.push('profiles must be unique supported profile names');
@@ -435,26 +486,42 @@ function validate(manifest) {
   if ('packages' in manifest) {
     const packages = manifest.packages;
     const selected = packages?.sdlc;
+    const selectedUi = packages?.ui;
+    const hasVisualProfile = manifest.profiles?.includes('visual-theme');
     if (!packages || typeof packages !== 'object' || Array.isArray(packages)
-        || Object.keys(packages).length !== 1
+        || !Object.keys(packages).every((key) => ['sdlc', 'ui'].includes(key))
+        || Object.keys(packages).length < 1 || Object.keys(packages).length > 2
         || !selected || typeof selected !== 'object' || Array.isArray(selected)
         || Object.keys(selected).length !== 2
         || selected.name !== sdlcPackage.name
         || typeof selected.version !== 'string' || !pin.test(selected.version)) {
       problems.push(`packages.sdlc must declare ${sdlcPackage.name} and an exact version or commit hash`);
     }
+    if (hasVisualProfile && (!selectedUi || typeof selectedUi !== 'object' || Array.isArray(selectedUi)
+        || Object.keys(selectedUi).length !== 2
+        || selectedUi.name !== uiPackage.name
+        || typeof selectedUi.version !== 'string' || !pin.test(selectedUi.version))) {
+      problems.push(`packages.ui must declare ${uiPackage.name} and an exact version or commit hash when visual-theme is selected`);
+    }
+    if (!hasVisualProfile && selectedUi) problems.push('packages.ui requires the visual-theme profile');
+  } else if (manifest.profiles?.includes('visual-theme')) {
+    problems.push(`packages must declare ${sdlcPackage.name} and ${uiPackage.name} when visual-theme is selected`);
   }
   const legacyManaged = Array.isArray(manifest.managed)
     && manifest.managed.length === legacyManagedPaths.length
     && manifest.managed.every((entry, index) => entry === legacyManagedPaths[index]);
+  const expectedManagedPaths = managedPathsFor(manifest);
   const completeManaged = Array.isArray(manifest.managed)
+    && manifest.managed.length === expectedManagedPaths.length
+    && manifest.managed.every((entry, index) => entry === expectedManagedPaths[index]);
+  const profilelessManaged = Array.isArray(manifest.managed)
     && manifest.managed.length === managedPaths.length
     && manifest.managed.every((entry, index) => entry === managedPaths[index]);
   const previousCompleteManaged = Array.isArray(manifest.managed)
     && manifest.managed.length === previousManagedPaths.length
     && manifest.managed.every((entry, index) => entry === previousManagedPaths[index]);
-  if (!legacyManaged && !previousCompleteManaged && !completeManaged) {
-    problems.push(`managed must be ${legacyManagedPaths.join(', ')}, the previous Lighthouse guardrail set or the current complete set`);
+  if (!legacyManaged && !profilelessManaged && !previousCompleteManaged && !completeManaged) {
+    problems.push(`managed must be ${legacyManagedPaths.join(', ')}, the previous Lighthouse guardrail set or the selected profile set`);
   }
   if ('repository' in manifest) {
     const repository = manifest.repository;
@@ -563,7 +630,12 @@ function printReconciliationPlan(plan) {
 async function initialize(args) {
   let manifest = await readManifest();
   const manifestMissing = !manifest;
-  if (!manifest) manifest = defaultManifest(productNameFromArgs(args));
+  const selectedProfiles = profileArguments(args);
+  if (!manifest) manifest = defaultManifest(productNameFromArgs(args), selectedProfiles);
+  else if (selectedProfiles.some((profile) => !(manifest.profiles ?? []).includes(profile))) {
+    const missing = selectedProfiles.filter((profile) => !(manifest.profiles ?? []).includes(profile));
+    throw new Error(`The existing lighthouse.json does not select ${missing.join(', ')}; edit its profiles and rerun lighthouse init.`);
+  }
   const problems = validate(manifest);
   if (problems.length) throw new Error(problems.map((problem) => `Invalid lighthouse.json: ${problem}`).join('\n'));
   const plan = await planInitialization(manifest, manifestMissing);
@@ -682,7 +754,7 @@ async function upgrade(args) {
   if (!manifest) throw new Error('Cannot read lighthouse.json: file does not exist; run lighthouse init --name <product>.');
   const problems = validate(manifest);
   if (problems.length) throw new Error(problems.map((problem) => `Invalid lighthouse.json: ${problem}`).join('\n'));
-  const plan = await planUpgrade(manifest, scopesFromArgs(args));
+  const plan = await planUpgrade(manifest, scopesFromArgs(args, manifest));
   const format = formatFromArgs(args);
   const apply = args.includes('--apply');
   const dryRun = args.includes('--dry-run') || !apply;
@@ -849,6 +921,7 @@ async function verify(manifest, format = 'text') {
     readFile,
     validateGitConventions,
     branch: gitBranch(),
+    uiTokens: manifest?.profiles?.includes('visual-theme') ? packageAsset('@juangcarmona/lighthouse-ui', 'tokens.css') : null,
   });
   const adoption = Object.values(capabilityAdoption(await readUpgradeState()));
   for (const item of adoption) {
@@ -1052,6 +1125,15 @@ for (let index = 0; index < commandArgs.length; index += 1) {
   if (arg === '--apply') { if (!['authorities', 'reconcile', 'upgrade'].includes(command)) invalidArgument = true; continue; }
   if (arg === '--name') { if (!commandArgs[index + 1]) invalidArgument = true; else index += 1; continue; }
   if (arg.startsWith('--name=') && arg.length > '--name='.length) continue;
+  if (arg === '--profile') {
+    if (command !== 'init' || !commandArgs[index + 1]) invalidArgument = true;
+    else index += 1;
+    continue;
+  }
+  if (arg.startsWith('--profile=') && arg.length > '--profile='.length) {
+    if (command !== 'init') invalidArgument = true;
+    continue;
+  }
   if (arg === '--format') {
     if (!['verify', 'upgrade', 'capabilities'].includes(command) || !['text', 'json'].includes(commandArgs[index + 1])) invalidArgument = true;
     else index += 1;