peaks-cli 1.0.5 → 1.0.7

package/LICENSE

@@ -1,52 +1,21 @@
-Peaks Closed-Source Non-Commercial License
-Peaks 闭源非商用许可协议
-
-English Version
-
-Copyright (c) 2026 Peaks contributors. All rights reserved.
-
-1. License Grant
-You may use this software only for personal, internal evaluation, research, learning, or other non-commercial purposes authorized by the copyright holder.
-
-2. Commercial Use Prohibited
-Commercial use is prohibited without prior written permission from the copyright holder. Commercial use includes, but is not limited to, using the software to provide paid services, support commercial operations, generate revenue, integrate into commercial products, or use within a for-profit organization for business purposes.
-
-3. Modification Prohibited for Commercial Purposes
-You may not modify, adapt, translate, create derivative works from, or otherwise alter this software for any commercial purpose without prior written permission from the copyright holder.
-
-4. Redistribution Prohibited for Commercial Purposes
-You may not distribute, sublicense, sell, rent, lease, publish, host, mirror, package, bundle, or otherwise make this software or modified versions available to others for any commercial purpose without prior written permission from the copyright holder.
-
-5. No Open-Source License
-This software is closed source. No rights are granted except those expressly stated in this license. All rights not expressly granted are reserved by the copyright holder.
-
-6. No Warranty
-This software is provided "as is", without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, and non-infringement. The copyright holder is not liable for any claim, damages, or other liability arising from the software or its use.
-
-7. Additional Permission
-For commercial licensing, modification, distribution, or other permissions not granted by this license, contact the copyright holder and obtain written permission before proceeding.
-
-中文版本
-
-版权所有 (c) 2026 Peaks 贡献者。保留所有权利。
-
-1. 授权范围
-你仅可将本软件用于个人使用、内部评估、研究、学习，或版权持有人授权的其他非商业用途。
-
-2. 禁止商业使用
-未经版权持有人事先书面许可，禁止将本软件用于任何商业用途。商业用途包括但不限于：使用本软件提供付费服务、支持商业运营、产生收入、集成到商业产品中，或在营利性组织内用于业务目的。
-
-3. 禁止商业目的的修改
-未经版权持有人事先书面许可，你不得为了任何商业目的修改、改编、翻译、创作衍生作品，或以其他方式变更本软件。
-
-4. 禁止商业目的的分发
-未经版权持有人事先书面许可，你不得为了任何商业目的分发、再授权、销售、出租、租赁、发布、托管、镜像、打包、捆绑，或以其他方式向他人提供本软件或其修改版本。
-
-5. 非开源许可
-本软件为闭源软件。除本许可明确授予的权利外，不授予任何其他权利。所有未明确授予的权利均由版权持有人保留。
-
-6. 无担保
-本软件按“现状”提供，不附带任何明示或默示担保，包括但不限于适销性、特定用途适用性和不侵权担保。版权持有人不对因本软件或其使用产生的任何索赔、损害或其他责任承担责任。
-
-7. 额外许可
-如需商业授权、修改、分发或本许可未授予的其他权限，请在行动前联系版权持有人并取得书面许可。
+MIT License
+
+Copyright (c) 2026 Peaks contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -410,7 +410,7 @@ pnpm run build
 
 ## 许可
 
-本仓库使用闭源非商用许可，详见 [LICENSE](LICENSE)。未经版权持有人事先书面许可，禁止商业使用、禁止商业目的的修改，禁止商业目的的分发、再授权、销售、托管、打包或捆绑。
+本仓库使用 MIT 许可完全开源，详见 [LICENSE](LICENSE)。
 
 ## 设计立场
 

package/dist/src/cli/commands/shadcn-commands.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerShadcnCommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/shadcn-commands.js

@@ -0,0 +1,35 @@
+import { createShadcnInvocation, executeShadcnInvocation } from '../../services/shadcn/shadcn-service.js';
+import { fail } from '../../shared/result.js';
+import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+function printShadcnFailure(io, error, exitCode = 1) {
+    printResult(io, fail('shadcn', 'SHADCN_COMMAND_FAILED', redactSensitiveErrorMessage(getErrorMessage(error)), {}, ['Check the shadcn command arguments before retrying']), false);
+    process.exitCode = exitCode;
+}
+async function runShadcnCommand(io, args) {
+    try {
+        const invocation = createShadcnInvocation({ args });
+        const result = await executeShadcnInvocation(invocation);
+        const didFail = result.exitCode !== null && result.exitCode !== 0;
+        if (result.stdout.length > 0) {
+            io.stdout((didFail ? redactSensitiveErrorMessage(result.stdout) : result.stdout).trimEnd());
+        }
+        if (result.stderr.length > 0) {
+            io.stderr((didFail ? redactSensitiveErrorMessage(result.stderr) : result.stderr).trimEnd());
+        }
+        if (didFail) {
+            process.exitCode = result.exitCode;
+        }
+    }
+    catch (error) {
+        printShadcnFailure(io, error);
+    }
+}
+export function registerShadcnCommands(program, io) {
+    program
+        .command('shadcn')
+        .description('Run the pinned shadcn CLI bundled with Peaks')
+        .allowUnknownOption(true)
+        .helpOption(false)
+        .argument('<args...>', 'arguments forwarded to shadcn')
+        .action((args) => runShadcnCommand(io, args));
+}

package/dist/src/cli/program.js

@@ -4,6 +4,7 @@ import { registerCoreAndArtifactCommands } from './commands/core-artifact-comman
 import { registerWorkflowCommands } from './commands/workflow-commands.js';
 import { registerCapabilityWorkerConfigAndSCCommands } from './commands/capability-worker-config-sc-commands.js';
 import { registerCodegraphCommands } from './commands/codegraph-commands.js';
+import { registerShadcnCommands } from './commands/shadcn-commands.js';
 export { printResult } from './cli-helpers.js';
 export function createProgram(io = { stdout: (text) => console.log(text), stderr: (text) => console.error(text) }) {
     const program = new Command();
@@ -26,5 +27,6 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
     registerWorkflowCommands(program, io);
     registerCapabilityWorkerConfigAndSCCommands(program, io);
     registerCodegraphCommands(program, io);
+    registerShadcnCommands(program, io);
     return program;
 }

package/dist/src/services/codegraph/codegraph-service.d.ts

@@ -1,4 +1,5 @@
-declare const CODEGRAPH_PACKAGE_NAME = "@colbymchenry/codegraph@0.7.10";
+declare const CODEGRAPH_PACKAGE_NAME = "@colbymchenry/codegraph";
+declare const CODEGRAPH_PACKAGE_VERSION = "0.7.10";
 declare const CODEGRAPH_EXECUTABLE: string;
 declare const ALLOWED_SUBCOMMANDS: readonly ["status", "init", "index", "query", "files", "context", "affected"];
 type CodegraphSubcommand = (typeof ALLOWED_SUBCOMMANDS)[number];
@@ -28,6 +29,7 @@ export type CodegraphInvocation = {
     args: string[];
     cwd: string;
     packageName: typeof CODEGRAPH_PACKAGE_NAME;
+    packageVersion: typeof CODEGRAPH_PACKAGE_VERSION;
     subcommand: CodegraphSubcommand;
 };
 export type CodegraphExecutionResult = {

package/dist/src/services/codegraph/codegraph-service.js

@@ -2,10 +2,10 @@ import { existsSync, realpathSync, statSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
-const CODEGRAPH_PACKAGE_NAME = '@colbymchenry/codegraph@0.7.10';
+const CODEGRAPH_PACKAGE_NAME = '@colbymchenry/codegraph';
+const CODEGRAPH_PACKAGE_VERSION = '0.7.10';
 const CODEGRAPH_EXECUTABLE = process.execPath;
-const CODEGRAPH_NPX_CLI_PATH = resolveNpxCliPath();
-const CODEGRAPH_BINARY_NAME = 'codegraph';
+const CODEGRAPH_BINARY_PATH = resolveCodegraphBinaryPath();
 const CODEGRAPH_PROCESS_TIMEOUT_MS = 600_000;
 const CODEGRAPH_OUTPUT_LIMIT_BYTES = 10 * 1024 * 1024;
 const NODE_OPTIONS_ENV_KEY = 'NODE_OPTIONS';
@@ -24,23 +24,14 @@ const ALLOWED_OPTIONS_BY_SUBCOMMAND = {
     context: ['task'],
     affected: ['files', 'json']
 };
-function resolveNpxCliPath() {
+function resolveCodegraphBinaryPath() {
     const require = createRequire(import.meta.url);
-    try {
-        return require.resolve('npm/bin/npx-cli.js');
-    }
-    catch {
-        const nodeBinDirectory = dirname(process.execPath);
-        const candidatePaths = [
-            join(nodeBinDirectory, 'node_modules', 'npm', 'bin', 'npx-cli.js'),
-            resolve(nodeBinDirectory, '..', 'lib', 'node_modules', 'npm', 'bin', 'npx-cli.js')
-        ];
-        const npxCliPath = candidatePaths.find((candidatePath) => existsSync(candidatePath));
-        if (npxCliPath === undefined) {
-            throw new Error('Unable to resolve npm npx-cli.js from the current Node installation');
-        }
-        return npxCliPath;
+    const packageJsonPath = require.resolve('@colbymchenry/codegraph/package.json');
+    const binaryPath = resolve(dirname(packageJsonPath), 'dist', 'bin', 'codegraph.js');
+    if (!existsSync(binaryPath)) {
+        throw new Error('Unable to resolve local codegraph binary from @colbymchenry/codegraph');
     }
+    return binaryPath;
 }
 function assertSupportedSubcommand(subcommand) {
     if (!ALLOWED_SUBCOMMANDS.includes(subcommand)) {
@@ -126,7 +117,7 @@ function buildAffectedFileArgs(projectRoot, files) {
     return files.map((file) => normalizeProjectRelativeFile(projectRoot, file));
 }
 function buildCommandArgs(options, projectRoot) {
-    const args = [CODEGRAPH_NPX_CLI_PATH, '--no', '--package', CODEGRAPH_PACKAGE_NAME, CODEGRAPH_BINARY_NAME, options.subcommand];
+    const args = [CODEGRAPH_BINARY_PATH, options.subcommand];
     if (options.subcommand === 'query' && options.search) {
         args.push(options.search);
     }
@@ -256,6 +247,7 @@ export function createCodegraphInvocation(options) {
         args: buildCommandArgs(options, projectRoot),
         cwd: projectRoot,
         packageName: CODEGRAPH_PACKAGE_NAME,
+        packageVersion: CODEGRAPH_PACKAGE_VERSION,
         subcommand: options.subcommand
     };
 }

package/dist/src/services/doctor/doctor-service.js

@@ -53,8 +53,8 @@ export async function runDoctor(options = {}) {
     const hasUserConfig = existsSync(userConfigPath);
     checks.push({
         id: 'config:user',
-        ok: hasUserConfig,
-        message: hasUserConfig ? 'User config exists at ~/.peaks/config.json' : 'User config not found at ~/.peaks/config.json'
+        ok: true,
+        message: hasUserConfig ? 'User config exists at ~/.peaks/config.json' : 'Optional user config not found at ~/.peaks/config.json'
     });
     const failed = checks.filter((check) => !check.ok).length;
     return {

package/dist/src/services/shadcn/shadcn-service.d.ts

@@ -0,0 +1,27 @@
+declare const SHADCN_PACKAGE_NAME = "shadcn";
+declare const SHADCN_PACKAGE_VERSION = "4.7.0";
+declare const SHADCN_EXECUTABLE: string;
+export type ShadcnInvocationOptions = {
+    args: string[];
+    cwd?: string;
+};
+export type ShadcnInvocation = {
+    executable: typeof SHADCN_EXECUTABLE;
+    args: string[];
+    cwd: string;
+    packageName: typeof SHADCN_PACKAGE_NAME;
+    packageVersion: typeof SHADCN_PACKAGE_VERSION;
+};
+export type ShadcnExecutionResult = {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+};
+export type ShadcnProcessRunner = (invocation: ShadcnInvocation) => Promise<ShadcnExecutionResult>;
+declare function createShadcnEnvironment(sourceEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function createShadcnInvocation(options: ShadcnInvocationOptions): ShadcnInvocation;
+export declare function executeShadcnInvocation(invocation: ShadcnInvocation, runner?: ShadcnProcessRunner): Promise<ShadcnExecutionResult>;
+export declare const testInternals: {
+    createShadcnEnvironment: typeof createShadcnEnvironment;
+};
+export {};

package/dist/src/services/shadcn/shadcn-service.js

@@ -0,0 +1,128 @@
+import { existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+const SHADCN_PACKAGE_NAME = 'shadcn';
+const SHADCN_PACKAGE_VERSION = '4.7.0';
+const SHADCN_EXECUTABLE = process.execPath;
+const SHADCN_BINARY_PATH = resolveShadcnBinaryPath();
+const SHADCN_PROCESS_TIMEOUT_MS = 600_000;
+const SHADCN_OUTPUT_LIMIT_BYTES = 10 * 1024 * 1024;
+const POSITIONAL_ARGUMENT_PREFIX = '-';
+const PRESERVED_ENV_KEYS = ['PATH', 'Path', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP', 'SystemRoot', 'WINDIR'];
+function resolveShadcnBinaryPath() {
+    const require = createRequire(import.meta.url);
+    const binaryPath = require.resolve('shadcn');
+    if (!existsSync(binaryPath)) {
+        throw new Error('Unable to resolve local shadcn binary from shadcn');
+    }
+    return binaryPath;
+}
+function assertShadcnArgs(args) {
+    if (args.length === 0) {
+        throw new Error('shadcn arguments are required');
+    }
+    if (args[0]?.startsWith(POSITIONAL_ARGUMENT_PREFIX)) {
+        throw new Error('shadcn command must not start with -');
+    }
+}
+function createShadcnEnvironment(sourceEnv = process.env) {
+    const environment = {};
+    for (const key of PRESERVED_ENV_KEYS) {
+        const value = sourceEnv[key];
+        if (value !== undefined) {
+            environment[key] = value;
+        }
+    }
+    return environment;
+}
+function assertOutputLimit(currentSize, chunkSize) {
+    const nextSize = currentSize + chunkSize;
+    if (nextSize > SHADCN_OUTPUT_LIMIT_BYTES) {
+        throw new Error(`shadcn output exceeded ${SHADCN_OUTPUT_LIMIT_BYTES} bytes`);
+    }
+    return nextSize;
+}
+function terminateShadcnProcess(childProcess) {
+    if (childProcess.pid === undefined) {
+        childProcess.kill();
+        return;
+    }
+    if (process.platform === 'win32') {
+        const taskkillPath = process.env.SystemRoot ? resolve(process.env.SystemRoot, 'System32', 'taskkill.exe') : 'taskkill.exe';
+        spawn(taskkillPath, ['/pid', String(childProcess.pid), '/T', '/F'], { shell: false, stdio: 'ignore' });
+        return;
+    }
+    try {
+        process.kill(-childProcess.pid, 'SIGTERM');
+    }
+    catch {
+        childProcess.kill('SIGTERM');
+    }
+}
+function defaultShadcnProcessRunner(invocation) {
+    return new Promise((resolveResult, reject) => {
+        const childProcess = spawn(invocation.executable, invocation.args, {
+            cwd: invocation.cwd,
+            detached: process.platform !== 'win32',
+            env: createShadcnEnvironment(),
+            shell: false
+        });
+        const timeout = setTimeout(() => {
+            terminateShadcnProcess(childProcess);
+            reject(new Error(`shadcn process timed out after ${SHADCN_PROCESS_TIMEOUT_MS}ms`));
+        }, SHADCN_PROCESS_TIMEOUT_MS);
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let stdoutSize = 0;
+        let stderrSize = 0;
+        childProcess.stdout.on('data', (chunk) => {
+            try {
+                stdoutSize = assertOutputLimit(stdoutSize, chunk.length);
+                stdoutChunks.push(chunk);
+            }
+            catch (error) {
+                terminateShadcnProcess(childProcess);
+                reject(error);
+            }
+        });
+        childProcess.stderr.on('data', (chunk) => {
+            try {
+                stderrSize = assertOutputLimit(stderrSize, chunk.length);
+                stderrChunks.push(chunk);
+            }
+            catch (error) {
+                terminateShadcnProcess(childProcess);
+                reject(error);
+            }
+        });
+        childProcess.on('error', (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+        childProcess.on('close', (exitCode) => {
+            clearTimeout(timeout);
+            resolveResult({
+                exitCode,
+                stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+                stderr: Buffer.concat(stderrChunks).toString('utf8')
+            });
+        });
+    });
+}
+export function createShadcnInvocation(options) {
+    assertShadcnArgs(options.args);
+    return {
+        executable: SHADCN_EXECUTABLE,
+        args: [SHADCN_BINARY_PATH, ...options.args],
+        cwd: options.cwd ?? process.cwd(),
+        packageName: SHADCN_PACKAGE_NAME,
+        packageVersion: SHADCN_PACKAGE_VERSION
+    };
+}
+export async function executeShadcnInvocation(invocation, runner = defaultShadcnProcessRunner) {
+    return runner(invocation);
+}
+export const testInternals = {
+    createShadcnEnvironment
+};

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.0.5";
+export declare const CLI_VERSION = "1.0.7";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.0.5";
+export const CLI_VERSION = "1.0.7";

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "peaks-cli",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "MIT",
   "type": "module",
   "packageManager": "pnpm@10.11.0",
   "publishConfig": {
@@ -41,7 +41,9 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "commander": "^12.1.0"
+    "@colbymchenry/codegraph": "0.7.10",
+    "commander": "^12.1.0",
+    "shadcn": "4.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/scripts/install-skills.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, readdirSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { closeSync, constants, copyFileSync, existsSync, fchmodSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, realpathSync, readdirSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 function getPathStats(path) {
@@ -38,6 +38,200 @@ function createInstallResult() {
   return { installed: [], skipped: [] };
 }
 
+const PROJECT_CONFIG_DEFAULTS = {
+  version: '0.1.0',
+  currentWorkspace: null,
+  workspaces: [],
+  language: 'en',
+  model: 'sonnet',
+  economyMode: true,
+  swarmMode: true,
+  tokens: {},
+  providers: {
+    minimax: {
+      model: 'minimax-2.7'
+    }
+  },
+  proxy: {}
+};
+
+function createConfigResult(overrides = {}) {
+  return { created: false, updated: false, skipped: false, ...overrides };
+}
+
+function isInsidePath(childPath, parentPath) {
+  const relativePath = relative(parentPath, childPath);
+  return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeMissingConfigValues(existing, defaults) {
+  return Object.entries(defaults).reduce((next, [key, defaultValue]) => {
+    if (!(key in next)) {
+      return { ...next, [key]: defaultValue };
+    }
+
+    const existingValue = next[key];
+    if (isPlainObject(existingValue) && isPlainObject(defaultValue)) {
+      return { ...next, [key]: mergeMissingConfigValues(existingValue, defaultValue) };
+    }
+
+    return next;
+  }, { ...existing });
+}
+
+function readConfigFile(configPath, label) {
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, 'utf8'));
+    if (!isPlainObject(parsed)) {
+      throw new Error(`${label} config must contain a JSON object`);
+    }
+
+    return parsed;
+  } catch (error) {
+    const message = error instanceof SyntaxError ? `${label} config must contain valid JSON` : error instanceof Error ? error.message : String(error);
+    throw new Error(message);
+  }
+}
+
+function validateConfigPath(root, peaksRoot, configPath, label) {
+  const rootReal = realpathSync(root);
+  const peaksStats = lstatSync(peaksRoot);
+  const peaksReal = realpathSync(peaksRoot);
+  if (!peaksStats.isDirectory() || peaksStats.isSymbolicLink() || peaksReal !== resolve(rootReal, '.peaks')) {
+    throw new Error(`${label} config path must stay inside the ${label.toLowerCase()} root`);
+  }
+
+  const configStats = getPathStats(configPath);
+  if (configStats?.isSymbolicLink()) {
+    throw new Error(`${label} config path must not be a symlink`);
+  }
+  if (configStats && !configStats.isFile()) {
+    throw new Error(`${label} config path must be a file`);
+  }
+  if (configStats) {
+    const configReal = realpathSync(configPath);
+    if (!isInsidePath(configReal, rootReal) || !isInsidePath(configReal, peaksReal)) {
+      throw new Error(`${label} config path must stay inside the ${label.toLowerCase()} root`);
+    }
+  }
+}
+
+function validateProjectConfigPaths(projectRoot, peaksRoot, configPath) {
+  validateConfigPath(projectRoot, peaksRoot, configPath, 'Project');
+}
+
+function validateUserConfigPaths(userRoot, peaksRoot, configPath) {
+  validateConfigPath(userRoot, peaksRoot, configPath, 'User');
+}
+
+function validateOpenConfigFile(fd, configPath, label) {
+  const fdStats = fstatSync(fd);
+  const pathStats = lstatSync(configPath);
+  if (!fdStats.isFile() || !pathStats.isFile() || fdStats.dev !== pathStats.dev || fdStats.ino !== pathStats.ino) {
+    throw new Error(`${label} config path changed during write`);
+  }
+  if (fdStats.nlink !== 1 || pathStats.nlink !== 1) {
+    throw new Error(`${label} config path must not be hardlinked`);
+  }
+}
+
+function writeConfigFile(configPath, content, label, validateBeforeWrite) {
+  validateBeforeWrite();
+  if (typeof constants.O_NOFOLLOW !== 'number') {
+    throw new Error('Safe config writes require O_NOFOLLOW support');
+  }
+
+  const fd = openSync(configPath, constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+  try {
+    validateBeforeWrite();
+    validateOpenConfigFile(fd, configPath, label);
+    fchmodSync(fd, 0o600);
+    ftruncateSync(fd, 0);
+    writeFileSync(fd, content, 'utf8');
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function writeProjectConfig(projectRoot, peaksRoot, configPath, content) {
+  writeConfigFile(configPath, content, 'Project', () => validateProjectConfigPaths(projectRoot, peaksRoot, configPath));
+}
+
+function writeUserConfig(userRoot, peaksRoot, configPath, content) {
+  writeConfigFile(configPath, content, 'User', () => validateUserConfigPaths(userRoot, peaksRoot, configPath));
+}
+
+function resolveProjectRoot(options) {
+  const projectRoot = options.projectRoot ?? process.env.PEAKS_PROJECT_ROOT ?? process.env.INIT_CWD;
+  return projectRoot ? resolve(projectRoot) : null;
+}
+
+function writeMergedConfig(configPath, label, writeConfig) {
+  const existing = readConfigFile(configPath, label);
+  const next = existing === null ? PROJECT_CONFIG_DEFAULTS : mergeMissingConfigValues(existing, PROJECT_CONFIG_DEFAULTS);
+  const currentJson = existing === null ? null : `${JSON.stringify(existing, null, 2)}\n`;
+  const nextJson = `${JSON.stringify(next, null, 2)}\n`;
+
+  if (currentJson === nextJson) {
+    return createConfigResult();
+  }
+
+  writeConfig(nextJson);
+  return createConfigResult(existing === null ? { created: true } : { updated: true });
+}
+
+export function installUserConfig(options = {}) {
+  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || process.env.PEAKS_SKIP_USER_CONFIG_INSTALL === '1') {
+    return createConfigResult({ skipped: true });
+  }
+
+  const userRoot = resolve(options.userRoot ?? homedir());
+  const peaksRoot = resolve(userRoot, '.peaks');
+  const configPath = resolve(peaksRoot, 'config.json');
+  if (!isInsidePath(configPath, userRoot)) {
+    throw new Error('User config path must stay inside the user root');
+  }
+
+  if (!existsSync(peaksRoot)) {
+    mkdirSync(peaksRoot, { recursive: true });
+  }
+  validateUserConfigPaths(userRoot, peaksRoot, configPath);
+
+  return writeMergedConfig(configPath, 'User', (content) => writeUserConfig(userRoot, peaksRoot, configPath, content));
+}
+
+export function installProjectConfig(options = {}) {
+  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || process.env.PEAKS_SKIP_PROJECT_CONFIG_INSTALL === '1') {
+    return createConfigResult({ skipped: true });
+  }
+
+  const projectRoot = resolveProjectRoot(options);
+  if (!projectRoot) {
+    return createConfigResult({ skipped: true });
+  }
+
+  const peaksRoot = resolve(projectRoot, '.peaks');
+  const configPath = resolve(peaksRoot, 'config.json');
+  if (!isInsidePath(configPath, projectRoot)) {
+    throw new Error('Project config path must stay inside the project root');
+  }
+
+  if (!existsSync(peaksRoot)) {
+    mkdirSync(peaksRoot, { recursive: true });
+  }
+  validateProjectConfigPaths(projectRoot, peaksRoot, configPath);
+
+  return writeMergedConfig(configPath, 'Project', (content) => writeProjectConfig(projectRoot, peaksRoot, configPath, content));
+}
+
 export function installBundledSkills(options = {}) {
   const packageRoot = resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..'));
   const skillsRoot = join(packageRoot, 'skills');
@@ -129,6 +323,13 @@ if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(p
   try {
     const skillsResult = installBundledSkills();
     const outputStylesResult = installBundledOutputStyles();
+    let userConfigResult = createConfigResult({ skipped: true });
+    try {
+      userConfigResult = installUserConfig();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      process.stderr.write(`Peaks user config was not installed: ${message}\n`);
+    }
     if (skillsResult.installed.length > 0) {
       process.stdout.write(`Peaks skills linked: ${skillsResult.installed.join(', ')}\n`);
     }
@@ -141,6 +342,12 @@ if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(p
     if (outputStylesResult.skipped.length > 0) {
       process.stderr.write(`Peaks output styles skipped because local files already exist: ${outputStylesResult.skipped.join(', ')}\n`);
     }
+    if (userConfigResult.created) {
+      process.stdout.write('Peaks user config created: ~/.peaks/config.json\n');
+    }
+    if (userConfigResult.updated) {
+      process.stdout.write('Peaks user config updated: ~/.peaks/config.json\n');
+    }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     process.stderr.write(`Peaks skills and output styles were not installed: ${message}\n`);

package/skills/peaks-qa/SKILL.md

@@ -55,7 +55,7 @@ QA cannot pass a change until the report contains evidence for every applicable
 
 1. **Unit tests** — run the project test command or a focused test command that covers new/changed code. For legacy projects below the target coverage, require coverage for the new or changed code rather than failing on pre-existing uncovered code.
 2. **API validation** — when the change touches API contracts, data loading, request handling, auth, or integrations, exercise the relevant API path and record request/response evidence or a justified local substitute.
-3. **Frontend browser validation** — when the repository has a frontend or the change affects UI, launch the app and use `gstack/browse/dist/browse` for real browser end-to-end validation. Prefer headed or handoff mode so a visible browser actually opens; verify with `browse status`, `browse focus`, screenshot, or user confirmation when needed. Capture the route, actions, screenshots or observations, console errors, network failures, and acceptance result.
+3. **Frontend browser validation** — when the repository has a frontend or the change affects UI, launch the app and use `gstack/browse/dist/browse` for real browser end-to-end validation. Use headed or handoff mode by default so a visible browser actually opens; verify the visible browser with `browse status`, screenshot evidence, or user confirmation. Do not call Playwright MCP for browser validation. Capture the route, actions, screenshots or observations, console errors, network failures, and acceptance result.
 4. **Browser-error feedback loop** — if `gstack/browse/dist/browse` shows a page error, console exception, broken network request, hydration/render failure, or visible regression, return the work to RD/development with the exact evidence. Do not pass QA until the fixed build is retested in the browser.
 5. **Security check** — run security review for the changed surface and dependency/config changes. Record findings, fixes, and unresolved risks.
 6. **Performance check** — run the project’s available performance check, build-size check, Lighthouse-equivalent check, or browser performance inspection appropriate to the change. Record baseline/after numbers when available.
@@ -89,9 +89,9 @@ External analysis cannot pass QA by itself. Treat codegraph output as untrusted
 
 ## External capability guidance
 
-Use `peaks capabilities --source access-repo --json` before recommending browser or validation MCPs.
+Use `peaks capabilities --source access-repo --json` before recommending browser or validation tooling.
 
-- Playwright MCP can support controlled browser and E2E validation after the target app and environment are approved.
+- Headed gstack browse is the default for controlled browser and E2E validation after the target app and environment are approved; confirm a visible browser opened.
 - Chrome DevTools MCP can support console, network, accessibility, and performance inspection for QA evidence.
 - Agent Browser can support browser walkthroughs, but never submit forms, purchase, delete, or mutate authenticated state without explicit confirmation.
 - If browser automation is unavailable, fallback to local Playwright, screenshots, logs, and manual regression steps only as diagnostic evidence or an explicitly approved exception; do not count it as a passed frontend browser gate by default.

package/skills/peaks-rd/SKILL.md

@@ -93,7 +93,7 @@ Peaks PRD/RD/QA gates remain authoritative: OpenSpec structures the durable spec
 
 When RD work creates a frontend application and the user has not specified a technology stack, and the current scan plus existing project standards still do not establish a frontend stack, default to React + Vite + shadcn/ui with:
 
-- `pnpm dlx shadcn@latest init --preset [CODE] --template vite`
+- `peaks shadcn init --preset [CODE] --template vite`
 
 `[CODE]` is the preset code supplied by the shadcn registry or user workflow; if it is unknown, stop and resolve the intended preset before scaffolding.