peaks-cli 1.0.6 → 1.0.8

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

@@ -4,18 +4,29 @@ import { createWorkflowRouterPlan, isSoloMode, isWorkflowMode } from '../../serv
 import { createAutonomousWorkflowPlan } from '../../services/workflow/workflow-autonomous-service.js';
 import { createRecommendationPlan } from '../../services/recommendations/recommendation-service.js';
 import { createRefactorDryRun } from '../../services/refactor/refactor-service.js';
-import { getCurrentWorkspaceConfig, readConfig } from '../../services/config/config-service.js';
+import { ensureWorkspaceConfigForCurrentPath, getCurrentWorkspaceConfig, readConfig } from '../../services/config/config-service.js';
 import { validateChangeIdOrThrow } from '../../shared/change-id.js';
 import { getEconomyAwareExecutionModelId } from '../../services/config/model-routing.js';
 import { getLocalArtifactPath } from '../../services/artifacts/workspace-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, isRecommendationWorkflow, printResult } from '../cli-helpers.js';
-function getWorkspaceContext() {
+function getCurrentWorkspaceContext() {
     const workspace = getCurrentWorkspaceConfig();
     if (!workspace)
         return {};
     return { workspace, artifactWorkspacePath: getLocalArtifactPath(workspace) };
 }
+function getWorkflowWorkspaceContext() {
+    try {
+        const workspace = ensureWorkspaceConfigForCurrentPath() ?? getCurrentWorkspaceConfig();
+        if (!workspace)
+            return {};
+        return { workspace, artifactWorkspacePath: getLocalArtifactPath(workspace) };
+    }
+    catch {
+        return {};
+    }
+}
 function parseMaxWorkers(io, command, value, asJson) {
     const maxWorkers = Number(value);
     if (!Number.isInteger(maxWorkers) || maxWorkers < 1) {
@@ -54,7 +65,7 @@ function runTechPlan(io, options) {
     }
     try {
         validatePlanningInput(options.changeId, options.goal);
-        const workspaceContext = getWorkspaceContext();
+        const workspaceContext = getCurrentWorkspaceContext();
         const plan = createTechPlan({
             changeId: options.changeId,
             goal: options.goal,
@@ -71,7 +82,7 @@ function runTechPlan(io, options) {
 }
 function runTechStatus(io, options) {
     try {
-        const workspaceContext = getWorkspaceContext();
+        const workspaceContext = getCurrentWorkspaceContext();
         printResult(io, ok('tech.status', getTechStatus({ changeId: options.changeId, ...workspaceContext })), options.json);
     }
     catch (error) {
@@ -97,7 +108,7 @@ function runWorkflowRoute(io, options) {
         return;
     try {
         validatePlanningInput(options.changeId, options.goal);
-        const workspaceContext = getWorkspaceContext();
+        const workspaceContext = getWorkflowWorkspaceContext();
         const plan = createWorkflowRouterPlan({
             changeId: options.changeId,
             goal: options.goal,
@@ -133,7 +144,7 @@ function runAutonomousWorkflow(io, options) {
         return;
     try {
         validatePlanningInput(options.changeId, options.goal);
-        const workspaceContext = getWorkspaceContext();
+        const workspaceContext = getWorkflowWorkspaceContext();
         const plan = createAutonomousWorkflowPlan({
             changeId: options.changeId,
             goal: options.goal,
@@ -166,7 +177,7 @@ function runSwarmPlan(io, options) {
         return;
     try {
         validatePlanningInput(options.changeId, options.goal);
-        const workspaceContext = getWorkspaceContext();
+        const workspaceContext = getWorkflowWorkspaceContext();
         const config = readConfig();
         const plan = createRdSwarmPlan({
             skill: 'rd',

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

@@ -28,4 +28,8 @@ export declare function addWorkspace(workspace: WorkspaceConfig, layer?: ConfigL
 export declare function removeWorkspace(workspaceId: string, layer?: ConfigLayer): boolean;
 export declare function setCurrentWorkspace(workspaceId: string, layer?: ConfigLayer): boolean;
 export declare function getCurrentWorkspaceConfig(): WorkspaceConfig | null;
+export declare function getWorkspaceConfigForPath(path?: string): WorkspaceConfig | null;
+export declare function ensureWorkspaceConfigForPath(path?: string): WorkspaceConfig | null;
+export declare function getWorkspaceConfigForCurrentPath(): WorkspaceConfig | null;
+export declare function ensureWorkspaceConfigForCurrentPath(): WorkspaceConfig | null;
 export type { TokenRef, WorkspaceConfig, PeaksConfig, ConfigLayer };

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

@@ -1,7 +1,8 @@
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
-import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { closeSync, constants, existsSync, fchmodSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { DEFAULT_CONFIG } from './config-types.js';
+import { stablePath } from '../../shared/path-utils.js';
 function getUserConfigPath() {
     return resolve(homedir(), '.peaks', 'config.json');
 }
@@ -26,10 +27,25 @@ function isSafeProjectConfigMarker(projectRoot) {
         return false;
     }
 }
+function normalizeBoundaryPath(path) {
+    const resolved = resolve(path);
+    let realPath = resolved;
+    try {
+        realPath = existsSync(resolved) ? realpathSync.native(resolved) : resolved;
+    }
+    catch {
+        realPath = resolved;
+    }
+    return process.platform === 'win32' || process.platform === 'darwin' ? realPath.toLowerCase() : realPath;
+}
+function getHomeBoundaryPaths() {
+    return new Set([homedir(), process.env.HOME, process.env.USERPROFILE].filter((path) => typeof path === 'string' && path.length > 0).map(normalizeBoundaryPath));
+}
 function findProjectRoot(startPath) {
+    const homeBoundaryPaths = getHomeBoundaryPaths();
     let current = resolve(startPath);
     let parent = dirname(current);
-    while (current !== parent) {
+    while (current !== parent && !homeBoundaryPaths.has(normalizeBoundaryPath(current))) {
         if (existsSync(resolve(current, '.peaks', 'config.json')) && isSafeProjectConfigMarker(current)) {
             return current;
         }
@@ -40,10 +56,10 @@ function findProjectRoot(startPath) {
 }
 export function resolveProjectRootForConfig(startPath) {
     const start = resolve(startPath);
-    const homePath = resolve(homedir());
+    const homeBoundaryPaths = getHomeBoundaryPaths();
     let current = start;
     let parent = dirname(current);
-    while (current !== parent && current !== homePath) {
+    while (current !== parent && !homeBoundaryPaths.has(normalizeBoundaryPath(current))) {
         if (existsSync(resolve(current, '.peaks', 'config.json')) && isSafeProjectConfigMarker(current)) {
             return current;
         }
@@ -102,6 +118,105 @@ function validateProjectBootstrapConfigPathForWrite(projectRoot, configPath) {
     const projectRootPath = resolve(projectRoot);
     validateProjectBootstrapConfigPath(projectRootPath, resolve(projectRootPath, '.peaks'), configPath);
 }
+function validateUserConfigPathForWrite(configPath) {
+    const userRoot = resolve(homedir());
+    const peaksPath = resolve(userRoot, '.peaks');
+    const userRootReal = realpathSync(userRoot);
+    const peaksStats = lstatSync(peaksPath);
+    const peaksReal = realpathSync(peaksPath);
+    if (!peaksStats.isDirectory() || peaksStats.isSymbolicLink() || peaksReal !== resolve(userRootReal, '.peaks')) {
+        throw new Error('User config path must stay inside the user root');
+    }
+    try {
+        const markerStats = lstatSync(configPath);
+        if (!markerStats.isFile() || markerStats.isSymbolicLink()) {
+            throw new Error('User config path must stay inside the user root');
+        }
+        const markerReal = realpathSync(configPath);
+        if (!isInsidePath(markerReal, userRootReal) || !isInsidePath(markerReal, peaksReal)) {
+            throw new Error('User config path must stay inside the user root');
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+function validateArtifactWorkspaceRoot(artifactRoot, workspaceRoot) {
+    const artifactStats = lstatSync(artifactRoot);
+    if (!artifactStats.isDirectory() || artifactStats.isSymbolicLink()) {
+        throw new Error('Artifact workspace marker must stay inside the artifact workspace');
+    }
+    const artifactRootReal = realpathSync(artifactRoot);
+    const workspaceRootReal = realpathSync(workspaceRoot);
+    if (isInsidePath(artifactRootReal, workspaceRootReal)) {
+        throw new Error('Artifact workspace must stay outside the project root');
+    }
+}
+function validateArtifactWorkspaceMarkerPath(artifactRoot, peaksPath, markerPath) {
+    const artifactStats = lstatSync(artifactRoot);
+    if (!artifactStats.isDirectory() || artifactStats.isSymbolicLink()) {
+        throw new Error('Artifact workspace marker must stay inside the artifact workspace');
+    }
+    const artifactRootReal = realpathSync(artifactRoot);
+    const peaksStats = lstatSync(peaksPath);
+    const peaksReal = realpathSync(peaksPath);
+    if (!peaksStats.isDirectory() || peaksStats.isSymbolicLink() || peaksReal !== resolve(artifactRootReal, '.peaks')) {
+        throw new Error('Artifact workspace marker must stay inside the artifact workspace');
+    }
+    try {
+        const markerStats = lstatSync(markerPath);
+        if (!markerStats.isFile() || markerStats.isSymbolicLink()) {
+            throw new Error('Artifact workspace marker must stay inside the artifact workspace');
+        }
+        if (markerStats.nlink !== 1) {
+            throw new Error('Config path must not be hardlinked');
+        }
+        const markerReal = realpathSync(markerPath);
+        if (!isInsidePath(markerReal, artifactRootReal) || !isInsidePath(markerReal, peaksReal)) {
+            throw new Error('Artifact workspace marker must stay inside the artifact workspace');
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+function validateOpenConfigFile(fd, configPath, errorMessage) {
+    const fdStats = fstatSync(fd);
+    const pathStats = lstatSync(configPath);
+    if (!fdStats.isFile() || !pathStats.isFile() || fdStats.dev !== pathStats.dev || fdStats.ino !== pathStats.ino) {
+        throw new Error(errorMessage);
+    }
+    if (fdStats.nlink !== 1 || pathStats.nlink !== 1) {
+        throw new Error('Config path must not be hardlinked');
+    }
+}
+function writeConfigFileSafely(configPath, content, validateBeforeWrite, errorMessage) {
+    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, errorMessage);
+        fchmodSync(fd, 0o600);
+        ftruncateSync(fd, 0);
+        writeFileSync(fd, content, 'utf-8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function writeProjectConfigFile(projectRoot, configPath, content) {
+    writeConfigFileSafely(configPath, content, () => validateProjectBootstrapConfigPathForWrite(projectRoot, configPath), 'Project config path must stay inside the project root');
+}
+function writeUserConfigFile(configPath, content) {
+    writeConfigFileSafely(configPath, content, () => validateUserConfigPathForWrite(configPath), 'User config path must stay inside the user root');
+}
 function readJsonFile(path) {
     if (!path || !existsSync(path))
         return null;
@@ -284,6 +399,10 @@ function isRecord(value) {
 function isSafeConfigSegment(value) {
     return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) && !value.includes('..') && !value.endsWith('.');
 }
+function toSafeConfigSegment(value) {
+    const normalized = value.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').replace(/\.+$/g, '');
+    return isSafeConfigSegment(normalized) ? normalized : 'workspace';
+}
 function toArtifactRemoteRepoConfig(value) {
     if (!isRecord(value) || (value.provider !== 'github' && value.provider !== 'gitlab') || typeof value.owner !== 'string' || typeof value.name !== 'string') {
         return null;
@@ -327,6 +446,15 @@ function toWorkspaceConfig(value) {
 function toWorkspaceConfigs(value) {
     return Array.isArray(value) ? value.map(toWorkspaceConfig).filter((workspace) => workspace !== null) : [];
 }
+function mergeWorkspaceConfigs(userWorkspaces, projectWorkspaces) {
+    const merged = new Map(userWorkspaces.map((workspace) => [workspace.workspaceId, workspace]));
+    for (const workspace of projectWorkspaces) {
+        if (!merged.has(workspace.workspaceId)) {
+            merged.set(workspace.workspaceId, workspace);
+        }
+    }
+    return [...merged.values()];
+}
 function toProviderModelConfig(value) {
     if (!isRecord(value))
         return {};
@@ -380,12 +508,16 @@ function toProxyConfig(value) {
         return null;
     return typeof value.httpProxy === 'string' && isValidProxyUrl(value.httpProxy) ? { httpProxy: value.httpProxy } : null;
 }
-function getProjectWritePath() {
-    const projectPath = getProjectConfigPath(findProjectRoot(process.cwd()));
-    if (!projectPath) {
+function getProjectWriteTarget() {
+    const projectRoot = findProjectRoot(process.cwd());
+    const configPath = getProjectConfigPath(projectRoot);
+    if (!projectRoot || !configPath) {
         throw new Error('Project config not found');
     }
-    return projectPath;
+    return { projectRoot, configPath };
+}
+function getProjectWritePath() {
+    return getProjectWriteTarget().configPath;
 }
 export function containsSensitiveConfigValue(value) {
     if (Array.isArray(value)) {
@@ -489,8 +621,7 @@ export function bootstrapProjectLanguageConfig(projectRoot, language) {
     if (typeof existing.language === 'string' && existing.language.trim().length > 0) {
         return;
     }
-    validateProjectBootstrapConfigPathForWrite(projectRoot, projectPath);
-    writeFileSync(projectPath, JSON.stringify({ ...existing, language: inferredLanguage }, null, 2), 'utf-8');
+    writeProjectConfigFile(projectRoot, projectPath, JSON.stringify({ ...existing, language: inferredLanguage }, null, 2));
 }
 export function readConfig(projectRoot) {
     const detectedRoot = projectRoot ?? findProjectRoot(process.cwd());
@@ -498,11 +629,13 @@ export function readConfig(projectRoot) {
     const projectPath = getProjectConfigPath(detectedRoot);
     const userConfig = toPeaksConfig(readJsonFile(userPath));
     const projectConfig = removeProjectSensitiveConfig(toPeaksConfig(readJsonFile(projectPath)));
-    const { proxy: projectProxy, ...projectConfigWithoutProxy } = projectConfig;
+    const { proxy: projectProxy, workspaces: projectWorkspaces, ...projectConfigWithoutProxy } = projectConfig;
+    const userWorkspaces = userConfig.workspaces ?? [];
     return {
         ...DEFAULT_CONFIG,
         ...userConfig,
-        ...projectConfigWithoutProxy
+        ...projectConfigWithoutProxy,
+        workspaces: mergeWorkspaceConfigs(userWorkspaces, projectWorkspaces ?? [])
     };
 }
 export function writeConfig(partial, layer = 'user') {
@@ -515,27 +648,33 @@ export function writeConfig(partial, layer = 'user') {
     validateProviderConfig(partial);
     validateProxyConfig(partial);
     if (layer === 'project') {
-        const projectPath = getProjectWritePath();
-        ensureDir(dirname(projectPath));
-        const existing = readJsonFile(projectPath) ?? {};
+        const { projectRoot, configPath } = getProjectWriteTarget();
+        ensureDir(dirname(configPath));
+        const existing = readJsonFile(configPath) ?? {};
         const merged = { ...existing, ...partial };
-        writeFileSync(projectPath, JSON.stringify(merged, null, 2), 'utf-8');
+        writeProjectConfigFile(projectRoot, configPath, JSON.stringify(merged, null, 2));
         return;
     }
     const userPath = getUserConfigPath();
     ensureDir(dirname(userPath));
-    const userPathDir = dirname(userPath);
-    ensureDir(userPathDir);
     const existing = readJsonFile(userPath) ?? {};
     const merged = { ...existing, ...partial };
-    writeFileSync(userPath, JSON.stringify(merged, null, 2), 'utf-8');
+    writeUserConfigFile(userPath, JSON.stringify(merged, null, 2));
 }
 export function getConfig(options = {}) {
     const projectRoot = findProjectRoot(process.cwd());
     const userConfig = readJsonFile(getUserConfigPath()) ?? {};
     const projectConfig = removeProjectSensitiveConfig(readJsonFile(getProjectConfigPath(projectRoot)) ?? {});
-    const { proxy: projectProxy, ...projectConfigWithoutProxy } = projectConfig;
-    const source = options.layer === 'user' ? userConfig : options.layer === 'project' ? projectConfig : { ...userConfig, ...projectConfigWithoutProxy };
+    const { proxy: projectProxy, workspaces: projectWorkspaces, ...projectConfigWithoutProxy } = projectConfig;
+    const source = options.layer === 'user'
+        ? userConfig
+        : options.layer === 'project'
+            ? projectConfig
+            : {
+                ...userConfig,
+                ...projectConfigWithoutProxy,
+                workspaces: mergeWorkspaceConfigs(toWorkspaceConfigs(userConfig.workspaces), toWorkspaceConfigs(projectWorkspaces))
+            };
     const config = isRecord(source) ? { ...source, ...(source.tokens !== undefined ? { tokens: toTokenConfig(source.tokens) } : {}) } : source;
     if (options.key !== undefined) {
         return getNestedValue(config, options.key);
@@ -564,12 +703,19 @@ export function setConfig(options) {
         }
     }
     validateProxyUrl(getProxyUrlCandidate(options.key, options.value));
-    const targetPath = layer === 'project' ? getProjectWritePath() : getUserConfigPath();
+    const projectTarget = layer === 'project' ? getProjectWriteTarget() : null;
+    const targetPath = projectTarget?.configPath ?? getUserConfigPath();
     ensureDir(dirname(targetPath));
     const existing = readJsonFile(targetPath) ?? {};
     const updated = { ...existing };
     setNestedValue(updated, options.key, options.value);
-    writeFileSync(targetPath, JSON.stringify(updated, null, 2), 'utf-8');
+    const content = JSON.stringify(updated, null, 2);
+    if (projectTarget) {
+        writeProjectConfigFile(projectTarget.projectRoot, targetPath, content);
+    }
+    else {
+        writeUserConfigFile(targetPath, content);
+    }
 }
 export function getWorkspaceConfig(workspaceId, projectRoot) {
     const config = readConfig(projectRoot ?? findProjectRoot(process.cwd()));
@@ -626,3 +772,77 @@ export function getCurrentWorkspaceConfig() {
         return null;
     return getWorkspaceConfig(config.currentWorkspace);
 }
+export function getWorkspaceConfigForPath(path = process.cwd()) {
+    const config = readConfig(findProjectRoot(path));
+    return findWorkspaceForPath(config.workspaces, path);
+}
+function createWorkspaceId(projectRoot, existingIds) {
+    const base = toSafeConfigSegment(basename(projectRoot));
+    if (!existingIds.has(base))
+        return base;
+    let suffix = 2;
+    while (existingIds.has(`${base}-${suffix}`)) {
+        suffix += 1;
+    }
+    return `${base}-${suffix}`;
+}
+function findWorkspaceForPath(workspaces, path) {
+    const targetPath = stablePath(path);
+    const matches = workspaces.flatMap((workspace) => {
+        if (!isAbsolute(workspace.rootPath) || !existsSync(workspace.rootPath))
+            return [];
+        const rootPath = stablePath(workspace.rootPath);
+        return isInsidePath(targetPath, rootPath) ? [{ workspace, rootPath }] : [];
+    });
+    if (matches.length === 0)
+        return null;
+    return matches.reduce((best, match) => match.rootPath.length > best.rootPath.length ? match : best).workspace;
+}
+function getWorkspaceArtifactRoot(workspace) {
+    return workspace.artifactStorage?.localPath ? resolve(workspace.artifactStorage.localPath) : resolve(homedir(), '.peaks', 'workspaces', workspace.workspaceId, 'artifacts');
+}
+function ensureArtifactWorkspaceMarker(workspace) {
+    const artifactRoot = getWorkspaceArtifactRoot(workspace);
+    const peaksPath = resolve(artifactRoot, '.peaks');
+    const markerPath = resolve(peaksPath, 'config.json');
+    ensureDir(artifactRoot);
+    validateArtifactWorkspaceRoot(artifactRoot, workspace.rootPath);
+    ensureDir(peaksPath);
+    validateArtifactWorkspaceMarkerPath(artifactRoot, peaksPath, markerPath);
+    if (!existsSync(markerPath)) {
+        writeConfigFileSafely(markerPath, '{}\n', () => validateArtifactWorkspaceMarkerPath(artifactRoot, peaksPath, markerPath), 'Artifact workspace marker must stay inside the artifact workspace');
+    }
+}
+export function ensureWorkspaceConfigForPath(path = process.cwd()) {
+    const projectRoot = resolveProjectRootForConfig(path);
+    if (!isAbsolute(projectRoot) || !existsSync(projectRoot))
+        return null;
+    const config = readLayerConfig('user');
+    const existingWorkspace = findWorkspaceForPath(config.workspaces, path);
+    if (existingWorkspace) {
+        ensureArtifactWorkspaceMarker(existingWorkspace);
+        if (!config.currentWorkspace) {
+            writeConfig({ currentWorkspace: existingWorkspace.workspaceId }, 'user');
+        }
+        return existingWorkspace;
+    }
+    const existingIds = new Set(config.workspaces.map((workspace) => workspace.workspaceId));
+    const workspaceId = createWorkspaceId(projectRoot, existingIds);
+    const workspace = {
+        workspaceId,
+        name: basename(projectRoot) || 'Workspace',
+        rootPath: stablePath(projectRoot),
+        artifactStorage: { mode: 'local', localPath: resolve(homedir(), '.peaks', 'workspaces', workspaceId, 'artifacts') },
+        installedCapabilityIds: []
+    };
+    ensureArtifactWorkspaceMarker(workspace);
+    const updatedWorkspaces = [...config.workspaces, workspace];
+    writeConfig({ workspaces: updatedWorkspaces, ...(!config.currentWorkspace ? { currentWorkspace: workspace.workspaceId } : {}) }, 'user');
+    return workspace;
+}
+export function getWorkspaceConfigForCurrentPath() {
+    return getWorkspaceConfigForPath(process.cwd());
+}
+export function ensureWorkspaceConfigForCurrentPath() {
+    return ensureWorkspaceConfigForPath(process.cwd());
+}

package/dist/src/shared/path-utils.d.ts

@@ -1,5 +1,5 @@
 import { type Platform } from './platform.js';
-export declare const SEP: "/" | "\\";
+export declare const SEP: "\\" | "/";
 export declare function normalizePath(p: string): string;
 export declare function pathsEqual(a: string, b: string): boolean;
 export declare function localPath(p: string, targetPlatform?: Platform): string;

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

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.0.6";
+export declare const CLI_VERSION = "1.0.8";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.0.6";
+export const CLI_VERSION = "1.0.8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",

package/scripts/install-skills.mjs

@@ -38,9 +38,23 @@ function createInstallResult() {
   return { installed: [], skipped: [] };
 }
 
-const PROJECT_CONFIG_DEFAULTS = {
-  version: '0.1.0',
-  currentWorkspace: null,
+function resolvePackageRoot(options = {}) {
+  return resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..'));
+}
+
+function readPackageVersion(packageRoot = resolvePackageRoot()) {
+  const packageJson = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
+  if (typeof packageJson.version !== 'string' || packageJson.version.length === 0) {
+    throw new Error('package.json version must be a non-empty string');
+  }
+
+  return packageJson.version;
+}
+
+function createConfigDefaults(packageRoot) {
+  return {
+    version: readPackageVersion(packageRoot),
+    currentWorkspace: null,
   workspaces: [],
   language: 'en',
   model: 'sonnet',
@@ -52,10 +66,11 @@ const PROJECT_CONFIG_DEFAULTS = {
       model: 'minimax-2.7'
     }
   },
-  proxy: {}
-};
+    proxy: {}
+  };
+}
 
-function createProjectConfigResult(overrides = {}) {
+function createConfigResult(overrides = {}) {
   return { created: false, updated: false, skipped: false, ...overrides };
 }
 
@@ -83,7 +98,7 @@ function mergeMissingConfigValues(existing, defaults) {
   }, { ...existing });
 }
 
-function readProjectConfig(configPath) {
+function readConfigFile(configPath, label) {
   if (!existsSync(configPath)) {
     return null;
   }
@@ -91,60 +106,68 @@ function readProjectConfig(configPath) {
   try {
     const parsed = JSON.parse(readFileSync(configPath, 'utf8'));
     if (!isPlainObject(parsed)) {
-      throw new Error('Project config must contain a JSON object');
+      throw new Error(`${label} config must contain a JSON object`);
     }
 
     return parsed;
   } catch (error) {
-    const message = error instanceof SyntaxError ? 'Project config must contain valid JSON' : error instanceof Error ? error.message : String(error);
+    const message = error instanceof SyntaxError ? `${label} config must contain valid JSON` : error instanceof Error ? error.message : String(error);
     throw new Error(message);
   }
 }
 
-function validateProjectConfigPaths(projectRoot, peaksRoot, configPath) {
-  const projectRootReal = realpathSync(projectRoot);
+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(projectRootReal, '.peaks')) {
-    throw new Error('Project config path must stay inside the project root');
+  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('Project config path must not be a symlink');
+    throw new Error(`${label} config path must not be a symlink`);
   }
   if (configStats && !configStats.isFile()) {
-    throw new Error('Project config path must be a file');
+    throw new Error(`${label} config path must be a file`);
   }
   if (configStats) {
     const configReal = realpathSync(configPath);
-    if (!isInsidePath(configReal, projectRootReal) || !isInsidePath(configReal, peaksReal)) {
-      throw new Error('Project config path must stay inside the project root');
+    if (!isInsidePath(configReal, rootReal) || !isInsidePath(configReal, peaksReal)) {
+      throw new Error(`${label} config path must stay inside the ${label.toLowerCase()} root`);
     }
   }
 }
 
-function validateOpenConfigFile(fd, configPath) {
+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('Project config path changed during write');
+    throw new Error(`${label} config path changed during write`);
   }
   if (fdStats.nlink !== 1 || pathStats.nlink !== 1) {
-    throw new Error('Project config path must not be hardlinked');
+    throw new Error(`${label} config path must not be hardlinked`);
   }
 }
 
-function writeProjectConfig(projectRoot, peaksRoot, configPath, content) {
-  validateProjectConfigPaths(projectRoot, peaksRoot, configPath);
+function writeConfigFile(configPath, content, label, validateBeforeWrite) {
+  validateBeforeWrite();
   if (typeof constants.O_NOFOLLOW !== 'number') {
-    throw new Error('Safe project config writes require O_NOFOLLOW support');
+    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 {
-    validateProjectConfigPaths(projectRoot, peaksRoot, configPath);
-    validateOpenConfigFile(fd, configPath);
+    validateBeforeWrite();
+    validateOpenConfigFile(fd, configPath, label);
     fchmodSync(fd, 0o600);
     ftruncateSync(fd, 0);
     writeFileSync(fd, content, 'utf8');
@@ -153,19 +176,61 @@ function writeProjectConfig(projectRoot, peaksRoot, configPath, content) {
   }
 }
 
+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, defaults, writeConfig) {
+  const existing = readConfigFile(configPath, label);
+  const next = { ...(existing === null ? defaults : mergeMissingConfigValues(existing, defaults)), version: defaults.version };
+  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', createConfigDefaults(options.packageRoot), (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 createProjectConfigResult({ skipped: true });
+    return createConfigResult({ skipped: true });
   }
 
   const projectRoot = resolveProjectRoot(options);
   if (!projectRoot) {
-    return createProjectConfigResult({ skipped: true });
+    return createConfigResult({ skipped: true });
   }
 
   const peaksRoot = resolve(projectRoot, '.peaks');
@@ -179,21 +244,11 @@ export function installProjectConfig(options = {}) {
   }
   validateProjectConfigPaths(projectRoot, peaksRoot, configPath);
 
-  const existing = readProjectConfig(configPath);
-  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 createProjectConfigResult();
-  }
-
-  writeProjectConfig(projectRoot, peaksRoot, configPath, nextJson);
-  return createProjectConfigResult(existing === null ? { created: true } : { updated: true });
+  return writeMergedConfig(configPath, 'Project', createConfigDefaults(options.packageRoot), (content) => writeProjectConfig(projectRoot, peaksRoot, configPath, content));
 }
 
 export function installBundledSkills(options = {}) {
-  const packageRoot = resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..'));
+  const packageRoot = resolvePackageRoot(options);
   const skillsRoot = join(packageRoot, 'skills');
   const targetRoot = resolve(options.targetRoot ?? process.env.PEAKS_CLAUDE_SKILLS_DIR ?? join(homedir(), '.claude', 'skills'));
 
@@ -239,7 +294,7 @@ export function installBundledSkills(options = {}) {
 }
 
 export function installBundledOutputStyles(options = {}) {
-  const packageRoot = resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..'));
+  const packageRoot = resolvePackageRoot(options);
   const outputStylesRoot = join(packageRoot, 'output-styles');
   const targetRoot = resolve(options.targetRoot ?? process.env.PEAKS_CLAUDE_OUTPUT_STYLES_DIR ?? join(homedir(), '.claude', 'output-styles'));
 
@@ -283,12 +338,12 @@ if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(p
   try {
     const skillsResult = installBundledSkills();
     const outputStylesResult = installBundledOutputStyles();
-    let projectConfigResult = createProjectConfigResult({ skipped: true });
+    let userConfigResult = createConfigResult({ skipped: true });
     try {
-      projectConfigResult = installProjectConfig();
+      userConfigResult = installUserConfig();
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      process.stderr.write(`Peaks project config was not installed: ${message}\n`);
+      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`);
@@ -302,11 +357,11 @@ 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 (projectConfigResult.created) {
-      process.stdout.write('Peaks project config created: .peaks/config.json\n');
+    if (userConfigResult.created) {
+      process.stdout.write('Peaks user config created: ~/.peaks/config.json\n');
     }
-    if (projectConfigResult.updated) {
-      process.stdout.write('Peaks project config updated: .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);