@opengsd/gsd-core 1.7.0-rc.3 → 1.7.0-rc.4

package/gsd-core/bin/lib/model-resolver.cjs

@@ -78,6 +78,61 @@ function warnModelPolicyUnmappable(agentType, policyModel, tier) {
 function _resetModelPolicyWarningCacheForTests() {
     _modelPolicyUnmappableWarned.clear();
 }
+// Dedupe stderr warnings for unmappable model_overrides Claude IDs (#2041).
+const _modelOverrideUnmappableWarned = new Set();
+function warnModelOverrideUnmappable(agentType, overrideValue) {
+    const key = `${agentType}::${overrideValue}`;
+    if (_modelOverrideUnmappableWarned.has(key))
+        return;
+    _modelOverrideUnmappableWarned.add(key);
+    // Cap emission length so an oversized or secret-shaped value cannot leak in
+    // full to stderr/logs (#2041 security review). MUST go to stderr — resolve-
+    // model's JSON result is parsed from stdout.
+    const safe = overrideValue.length > 64 ? overrideValue.slice(0, 64) + '…' : overrideValue;
+    process.stderr.write(`gsd: warning — model_overrides value "${safe}" for ${agentType} ` +
+        `has no Claude agent alias; falling through to tier resolution.\n`);
+}
+// Test-only: reset the model_overrides warn-dedupe cache between cases (#2041).
+function _resetModelOverrideWarningCacheForTests() {
+    _modelOverrideUnmappableWarned.clear();
+}
+/**
+ * #2041 — Map a `model_overrides` value to its Claude Agent-tool alias on the
+ * claude runtime, mirroring the `model_policy` path (#1144). Claude Code's
+ * Agent tool `model` parameter documents only tier aliases (opus/sonnet/haiku/
+ * fable); a full Claude model ID returned verbatim is silently dropped by the
+ * spawner. Returns the value to return verbatim, or null to signal "fall
+ * through to normal tier/dynamic-routing resolution" (used when a Claude full
+ * ID has no alias — matches model_policy's warn-and-fall-through). Non-Claude
+ * runtimes and non-Claude values always pass through verbatim.
+ *
+ * Hardening (code+security review): a `typeof` guard preserves the pre-fix
+ * no-crash behavior if a malformed config surfaces a non-string value, and an
+ * `Object.hasOwn` lookup defeats `__proto__`/`constructor` lookups on the plain
+ * object literal so those reserved keys cannot return a truthy non-string.
+ */
+function mapClaudeOverrideForRuntime(override, configRuntime, agentType) {
+    // Defensive: model_overrides is typed Record<string,string> but a malformed
+    // config could surface a non-string; pass through verbatim (preserving the
+    // pre-fix no-crash behaviour) and let the downstream Agent tool reject it.
+    if (typeof override !== 'string')
+        return override;
+    const onClaude = !configRuntime || configRuntime === 'claude';
+    if (!onClaude)
+        return override;
+    // Object.hasOwn guards against __proto__/constructor returning a truthy
+    // non-string from the plain object literal (#2041 security review).
+    if (Object.hasOwn(CLAUDE_POLICY_ID_TO_ALIAS, override)) {
+        return CLAUDE_POLICY_ID_TO_ALIAS[override];
+    }
+    if (CLAUDE_AGENT_ALIASES.has(override))
+        return override;
+    if (override.startsWith('claude-')) {
+        warnModelOverrideUnmappable(agentType, override);
+        return null;
+    }
+    return override;
+}
 /**
  * #49 — Provider-neutral model policy preset resolution.
  */
@@ -134,11 +189,16 @@ function resolveModelPolicy(policy, tier) {
 }
 function resolveModelInternal(cwd, agentType) {
     const config = loadConfig(cwd);
-    // 1. Per-agent override
+    // 1. Per-agent override (#2041: map Claude full IDs → Agent-tool aliases on
+    // the claude runtime, mirroring the model_policy path #1144; non-Claude
+    // runtimes and non-Claude values pass through verbatim).
     const modelOverrides = config['model_overrides'];
     const override = modelOverrides?.[agentType];
     if (override) {
-        return override;
+        const mapped = mapClaudeOverrideForRuntime(override, config['runtime'], agentType);
+        if (mapped !== null)
+            return mapped;
+        // Unmappable Claude ID — fall through to tier resolution (matches model_policy).
     }
     // 2. Compute the tier
     // eslint-disable-next-line @typescript-eslint/no-base-to-string
@@ -252,8 +312,12 @@ function resolveModelForTier(cwd, agentType, attempt) {
     const attemptN = Number.isInteger(attempt) && attempt > 0 ? attempt : 0;
     const modelOverrides = config['model_overrides'];
     const override = modelOverrides?.[agentType];
-    if (override)
-        return override;
+    if (override) {
+        const mapped = mapClaudeOverrideForRuntime(override, config['runtime'], agentType);
+        if (mapped !== null)
+            return mapped;
+        // Unmappable Claude ID — fall through to dynamic_routing / model_policy resolution.
+    }
     if (config['model_policy'] && config['runtime'] && config['runtime'] !== 'claude') {
         return resolveModelInternal(cwd, agentType);
     }
@@ -454,6 +518,7 @@ module.exports = {
     resolveModelPolicy,
     resolveModelInternal,
     _resetModelPolicyWarningCacheForTests,
+    _resetModelOverrideWarningCacheForTests,
     VALID_GRANULARITIES,
     resolveGranularityInternal,
     assertValidGranularityOverride,

package/gsd-core/bin/lib/onboard-projection.cjs

@@ -0,0 +1,309 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- core-utils.cjs is an export= CommonJS module
+const coreUtils = require("./core-utils.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
+const planningWorkspace = require("./planning-workspace.cjs");
+const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+const { pathExistsInternal, toPosixPath } = coreUtils;
+const { planningDir, planningRoot } = planningWorkspace;
+const CODE_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.swift', '.java',
+    '.kt', '.kts', '.c', '.cpp', '.cc', '.h', '.hpp', '.cs', '.rb', '.php', '.dart',
+    '.m', '.mm', '.scala', '.groovy', '.lua', '.r', '.R', '.zig', '.ex', '.exs', '.clj',
+]);
+const CODE_SCAN_SKIP_DIRS = new Set([
+    'node_modules', '.git', '.planning', '.claude', '.codex', '__pycache__', 'target',
+    'dist', 'build', '.next', '.nuxt', '.svelte-kit', 'coverage', 'vendor', '.venv', 'venv',
+]);
+const PACKAGE_FILES = [
+    'package.json', 'requirements.txt', 'pyproject.toml', 'Cargo.toml', 'go.mod',
+    'Package.swift', 'build.gradle', 'build.gradle.kts', 'pom.xml', 'Gemfile',
+    'composer.json', 'pubspec.yaml', 'CMakeLists.txt', 'Makefile', 'build.zig',
+    'mix.exs', 'project.clj',
+];
+const REQUIRED_CODEBASE_MAP_FILES = [
+    'STACK.md', 'ARCHITECTURE.md', 'STRUCTURE.md', 'CONVENTIONS.md', 'TESTING.md',
+    'INTEGRATIONS.md', 'CONCERNS.md',
+];
+const FAST_CODEBASE_MAP_FILES = [
+    'STACK.md', 'INTEGRATIONS.md', 'ARCHITECTURE.md', 'STRUCTURE.md',
+];
+const PLANNING_DOC_SEGMENTS = new Set([
+    'adr', 'adrs', 'prd', 'prds', 'spec', 'specs', 'rfc', 'rfcs',
+]);
+function hasCodeFilesInternal(dir, depth = 0) {
+    if (depth > 3)
+        return false;
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        if (entry.isFile() && CODE_EXTENSIONS.has(node_path_1.default.extname(entry.name)))
+            return true;
+        if (entry.isDirectory() && !CODE_SCAN_SKIP_DIRS.has(entry.name)) {
+            if (hasCodeFilesInternal(node_path_1.default.join(dir, entry.name), depth + 1))
+                return true;
+        }
+    }
+    return false;
+}
+function hasPackageFileInternal(cwd) {
+    return PACKAGE_FILES.some((file) => pathExistsInternal(cwd, file));
+}
+function listPlanningDocCandidates(cwd) {
+    const roots = ['docs', 'adr', 'adrs', 'prd', 'prds', 'spec', 'specs', 'rfc', 'rfcs'];
+    const candidates = new Set();
+    function isPlanningDocCandidate(rel, name) {
+        const upperName = name.toUpperCase();
+        const relLower = rel.toLowerCase();
+        const pathSegments = relLower.split('/');
+        return (/(^|[-_ ])(ADR|PRD|SPEC|RFC)([-_ ]|\.)/i.test(name) ||
+            /^\d{4}[-_].+\.md$/i.test(name) ||
+            pathSegments.some((segment) => PLANNING_DOC_SEGMENTS.has(segment)) ||
+            upperName === 'REQUIREMENTS.MD');
+    }
+    function addCandidate(rel, name) {
+        if (name.toLowerCase().endsWith('.md') && isPlanningDocCandidate(rel, name)) {
+            candidates.add(toPosixPath(rel));
+        }
+    }
+    function visit(dir, relDir, depth) {
+        if (depth > 3)
+            return;
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (!CODE_SCAN_SKIP_DIRS.has(entry.name)) {
+                    visit(node_path_1.default.join(dir, entry.name), rel, depth + 1);
+                }
+                continue;
+            }
+            if (entry.isFile())
+                addCandidate(rel, entry.name);
+        }
+    }
+    let rootEntries = [];
+    try {
+        rootEntries = node_fs_1.default.readdirSync(cwd, { withFileTypes: true });
+    }
+    catch {
+        rootEntries = [];
+    }
+    for (const entry of rootEntries) {
+        if (entry.isFile())
+            addCandidate(entry.name, entry.name);
+    }
+    for (const root of roots) {
+        const full = node_path_1.default.join(cwd, root);
+        if (node_fs_1.default.existsSync(full))
+            visit(full, root, 0);
+    }
+    return [...candidates].sort();
+}
+function listCodebaseMapFiles(cwd) {
+    const codebaseDir = node_path_1.default.join(planningRoot(cwd), 'codebase');
+    if (!node_fs_1.default.existsSync(codebaseDir))
+        return [];
+    return REQUIRED_CODEBASE_MAP_FILES.filter((file) => node_fs_1.default.existsSync(node_path_1.default.join(codebaseDir, file)));
+}
+function getMapReadiness(hasCompleteMap, hasFastMap) {
+    if (hasCompleteMap)
+        return 'complete';
+    if (hasFastMap)
+        return 'fast';
+    return 'none';
+}
+function mapSummaryStatus(mapReadiness) {
+    if (mapReadiness === 'complete')
+        return '.planning/codebase/ (complete codebase map)';
+    if (mapReadiness === 'fast')
+        return '.planning/codebase/ (fast/partial codebase map; complete map still required for project setup)';
+    return 'missing';
+}
+function mapFinalStatus(mapReadiness) {
+    if (mapReadiness === 'complete')
+        return 'complete';
+    if (mapReadiness === 'fast')
+        return 'fast/partial; complete map still required for project setup';
+    return 'missing';
+}
+function planningMissing(projectExists, requirementsExists, roadmapExists, stateExists) {
+    const missing = [];
+    if (!projectExists)
+        missing.push('PROJECT.md');
+    if (!requirementsExists)
+        missing.push('REQUIREMENTS.md');
+    if (!roadmapExists)
+        missing.push('ROADMAP.md');
+    if (!stateExists)
+        missing.push('STATE.md');
+    return missing;
+}
+function nextAction(params) {
+    if (params.isBrownfield && params.needsOnboardCodebaseMap) {
+        return {
+            kind: 'map-codebase',
+            command: params.fastMode ? params.handoffCommands.map_codebase_fast : params.handoffCommands.map_codebase,
+            reason: 'Existing code was detected, but the required .planning/codebase/ map is missing.',
+        };
+    }
+    if (params.hasPlanningArtifacts && params.missingPlanningFiles.length > 0) {
+        return {
+            kind: 'partial-planning',
+            missing: params.missingPlanningFiles,
+            reason: 'Project planning exists but required planning files are missing.',
+        };
+    }
+    if (params.fastMode && params.mapReadiness === 'fast' && !params.projectExists) {
+        return {
+            kind: 'complete-map-before-new-project',
+            command: params.handoffCommands.map_codebase,
+            reason: 'The fast map is enough for lightweight onboarding, but project setup still requires the complete codebase map.',
+        };
+    }
+    if (params.hasDocsCandidates && !params.projectExists) {
+        return {
+            kind: 'ingest-docs',
+            command: params.handoffCommands.ingest_docs,
+            reason: 'Detected existing ADR/PRD/SPEC/RFC document(s) before project setup.',
+        };
+    }
+    if (!params.isBrownfield && !params.projectExists && !params.hasDocsCandidates) {
+        return {
+            kind: 'new-project',
+            command: params.handoffCommands.new_project,
+            reason: 'No existing code or planning docs were detected.',
+        };
+    }
+    if (!params.projectExists) {
+        return {
+            kind: 'new-project',
+            command: params.handoffCommands.new_project,
+            reason: 'Codebase context is ready for project initialization.',
+        };
+    }
+    if (!params.onboardingSummaryExists) {
+        return {
+            kind: 'write-summary',
+            summary_path: params.onboardingSummaryPath,
+            reason: 'Onboarding summary is missing.',
+        };
+    }
+    return {
+        kind: 'ready',
+        reason: 'Onboarding summary already exists.',
+    };
+}
+function buildHandoffCommands(cwd) {
+    const runtime = (0, runtime_slash_cjs_1.resolveRuntime)(cwd);
+    return {
+        ingest_docs: (0, runtime_slash_cjs_1.formatGsdSlash)('ingest-docs', runtime),
+        manager: (0, runtime_slash_cjs_1.formatGsdSlash)('manager', runtime),
+        map_codebase: (0, runtime_slash_cjs_1.formatGsdSlash)('map-codebase', runtime),
+        map_codebase_fast: (0, runtime_slash_cjs_1.formatGsdSlash)('map-codebase --fast', runtime),
+        new_project: (0, runtime_slash_cjs_1.formatGsdSlash)('new-project', runtime),
+        onboard: (0, runtime_slash_cjs_1.formatGsdSlash)('onboard', runtime),
+    };
+}
+function buildOnboardProjection(cwd, options) {
+    const handoffCommands = buildHandoffCommands(cwd);
+    const codebaseMapFiles = listCodebaseMapFiles(cwd);
+    const missingCodebaseMapFiles = REQUIRED_CODEBASE_MAP_FILES.filter((file) => !codebaseMapFiles.includes(file));
+    const missingFastCodebaseMapFiles = FAST_CODEBASE_MAP_FILES.filter((file) => !codebaseMapFiles.includes(file));
+    const docCandidates = listPlanningDocCandidates(cwd);
+    const hasCode = hasCodeFilesInternal(cwd);
+    const hasPackageFile = hasPackageFileInternal(cwd);
+    const isBrownfield = hasCode || hasPackageFile;
+    const hasCodebaseMap = codebaseMapFiles.length === REQUIRED_CODEBASE_MAP_FILES.length;
+    const hasFastCodebaseMap = missingFastCodebaseMapFiles.length === 0;
+    const mapReadinessValue = getMapReadiness(hasCodebaseMap, hasFastCodebaseMap);
+    const needsCodebaseMap = isBrownfield && !hasCodebaseMap;
+    const needsFastCodebaseMap = isBrownfield && !hasFastCodebaseMap;
+    const needsOnboardCodebaseMap = options.fast ? needsFastCodebaseMap : needsCodebaseMap;
+    const projectRootPath = node_path_1.default.join(planningRoot(cwd), 'PROJECT.md');
+    const projectScopedPath = node_path_1.default.join(planningDir(cwd), 'PROJECT.md');
+    const projectExists = node_fs_1.default.existsSync(projectRootPath) || node_fs_1.default.existsSync(projectScopedPath);
+    const requirementsExists = node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'REQUIREMENTS.md'));
+    const roadmapExists = node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'));
+    const stateExists = node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'STATE.md'));
+    const onboardingSummaryPath = node_path_1.default.join(planningRoot(cwd), 'onboarding', 'SUMMARY.md');
+    const onboardingSummaryExists = node_fs_1.default.existsSync(onboardingSummaryPath);
+    const hasPlanningArtifacts = projectExists || requirementsExists || roadmapExists || stateExists;
+    const missingPlanningFiles = planningMissing(projectExists, requirementsExists, roadmapExists, stateExists);
+    return {
+        commit_docs: options.commitDocs,
+        text_mode: options.textMode,
+        project_exists: projectExists,
+        planning_exists: node_fs_1.default.existsSync(planningRoot(cwd)),
+        requirements_exists: requirementsExists,
+        roadmap_exists: roadmapExists,
+        state_exists: stateExists,
+        config_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningDir(cwd), 'config.json')),
+        handoff_commands: handoffCommands,
+        has_existing_code: hasCode,
+        has_package_file: hasPackageFile,
+        is_brownfield: isBrownfield,
+        fast_mode: options.fast,
+        map_readiness: mapReadinessValue,
+        next_action: nextAction({
+            fastMode: options.fast,
+            isBrownfield,
+            needsOnboardCodebaseMap,
+            hasDocsCandidates: docCandidates.length > 0,
+            projectExists,
+            mapReadiness: mapReadinessValue,
+            onboardingSummaryExists,
+            onboardingSummaryPath: toPosixPath(node_path_1.default.relative(cwd, onboardingSummaryPath)),
+            hasPlanningArtifacts,
+            missingPlanningFiles,
+            handoffCommands,
+        }),
+        needs_codebase_map: needsCodebaseMap,
+        needs_fast_codebase_map: needsFastCodebaseMap,
+        has_codebase_map: hasCodebaseMap,
+        has_fast_codebase_map: hasFastCodebaseMap,
+        codebase_dir_exists: node_fs_1.default.existsSync(node_path_1.default.join(planningRoot(cwd), 'codebase')),
+        fast_codebase_map_files_required: FAST_CODEBASE_MAP_FILES,
+        codebase_map_files_present: codebaseMapFiles,
+        missing_codebase_map_files: missingCodebaseMapFiles,
+        missing_fast_codebase_map_files: missingFastCodebaseMapFiles,
+        codebase_map_summary_status: mapSummaryStatus(mapReadinessValue),
+        codebase_map_final_status: mapFinalStatus(mapReadinessValue),
+        has_docs_candidates: docCandidates.length > 0,
+        doc_candidate_count: docCandidates.length,
+        doc_candidates: docCandidates,
+        onboarding_summary_exists: onboardingSummaryExists,
+        onboarding_summary_path: toPosixPath(node_path_1.default.relative(cwd, onboardingSummaryPath)),
+        project_path: toPosixPath(node_path_1.default.relative(cwd, node_fs_1.default.existsSync(projectRootPath) ? projectRootPath : projectScopedPath)),
+        requirements_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'REQUIREMENTS.md'))),
+        roadmap_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'))),
+        state_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningDir(cwd), 'STATE.md'))),
+        codebase_dir: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningRoot(cwd), 'codebase'))),
+        onboarding_dir: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planningRoot(cwd), 'onboarding'))),
+    };
+}
+module.exports = {
+    REQUIRED_CODEBASE_MAP_FILES,
+    FAST_CODEBASE_MAP_FILES,
+    buildOnboardProjection,
+    hasCodeFilesInternal,
+    hasPackageFileInternal,
+    listCodebaseMapFiles,
+    listPlanningDocCandidates,
+};

package/gsd-core/bin/lib/runtime-name-policy.cjs

@@ -209,6 +209,7 @@ const RUNTIME_LABELS = {
     kimi: 'Kimi CLI',
     codebuddy: 'CodeBuddy',
     cline: 'Cline',
+    zcode: 'ZCode',
 };
 /**
  * Map a canonical runtime id to its short display label for the
@@ -255,6 +256,7 @@ const GLOBAL_CONFIG_HOME_FRAGMENTS = {
     codebuddy: "'.codebuddy'",
     cline: "'.cline'",
     kimi: "'.config', 'agents'",
+    zcode: "'.zcode'",
 };
 /**
  * Return the global config-home path-fragment source snippet for a runtime
@@ -277,7 +279,7 @@ function getGlobalConfigHomeFragment(runtime) {
  */
 const RUNTIME_FLAG_IDS = Object.freeze([
     'opencode', 'kilo', 'codex', 'copilot', 'antigravity', 'cursor',
-    'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'kimi',
+    'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy', 'cline', 'kimi', 'zcode',
 ]);
 /**
  * Return a frozen map of `is<Runtime>` boolean predicates for the given runtime

package/gsd-core/bin/lib/surface.cjs

@@ -32,6 +32,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -261,32 +262,52 @@ function resolveSurface(runtimeConfigDir, manifest, clusterMap, registry) {
  * Re-stage the active surface using the resolved layout.
  * Iterates layout.kinds and syncs each artifact kind to its destination.
  */
-function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry) {
+function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry, opts) {
     if (node_path_1.default.resolve(runtimeConfigDir) !== node_path_1.default.resolve(layout.configDir)) {
         throw new TypeError('applySurface runtimeConfigDir must match layout.configDir');
     }
     const skillManifest = normalizeSkillManifest(layout.configDir, manifest);
     const resolved = resolveSurface(layout.configDir, skillManifest, clusterMap, registry);
-    // Mirror installRuntimeArtifacts: skills kinds get per-runtime path rewrites
-    // so SKILL.md bodies reference the install target (pathPrefix), not the
-    // converter's default ~/.claude paths (#813). Delegated to the conversion
-    // module's deep seam (ADR-1508 / #1511 Phase 2) — no attribution resolver
-    // needed here (proven: Co-Authored-By never appears in staged content; see
-    // brief PROVEN KEY FACT). No getInstallExports() call required.
-    // #1615 adversarial review (PR #1622): commands kind was previously skipped,
-    // leaving raw @~/.claude/... references in Windsurf workflow bodies after a
-    // /gsd-surface profile change. Same gap affected any runtime with commands
-    // kinds (windsurf, opencode, kilo, cursor, augment, codebuddy, gemini).
-    //
-    // Asymmetry note: rewriteStagedSkillBodies mutates in place (returns void),
-    // but rewriteStagedCommandBodies copies to a fresh mkdtemp dir and returns
-    // its path (commands .md files are flat; mutating the staged source would
-    // corrupt the package source on full-profile runs). Caller MUST sync from
-    // the returned dir and clean it up.
+    // #1575: agents kind now mirrors createRuntimeArtifactInstallPlan — build
+    // agentCtx (pathPrefix + attribution) and pass it to kind.stage() so
+    // stageAgentsForRuntimeWithConverter applies the full inline-loop pipeline
+    // (pathRewrites -> attribution -> converter -> normalize). Without this,
+    // surface-path agents lack path-prefix rewrites and Co-Authored-By trailers,
+    // diverging from a fresh install.
+    const _homedirFn = opts?.homedir ?? (() => node_os_1.default.homedir());
+    const _resolvedTarget = node_path_1.default.resolve(layout.configDir).replace(/\\/g, '/');
+    const _homeDir = _homedirFn().replace(/\\/g, '/');
+    const _isGlobal = (layout.scope ?? 'global') === 'global';
+    const _isOpencode = layout.runtime === 'opencode';
+    const _isWindowsHost = (opts?.platform ?? process.platform) === 'win32';
+    const _pathPrefix = runtimeArtifactConversion._computePathPrefix({ isGlobal: _isGlobal, isOpencode: _isOpencode, isWindowsHost: _isWindowsHost, resolvedTarget: _resolvedTarget, homeDir: _homeDir });
+    const _attribution = opts?.resolveAttribution ? opts.resolveAttribution(layout.runtime) : undefined;
+    const agentCtx = { runtime: layout.runtime, pathPrefix: _pathPrefix, attribution: _attribution };
     const tempDirsToClean = [];
+    // #1575: When the surface has no state modifications AND the base profile is
+    // 'full', pass the '*' sentinel for agents staging so ALL agents are staged —
+    // matching the install path which uses { skills: '*' }. Without this, agents
+    // not referenced by any skill's _calls_agents_ manifest entry would be silently
+    // dropped from the surface path. For tiered profiles (core/standard) or when
+    // surface mods exist, pass the resolved set so only the filtered subset stages.
+    const _surfaceState = readSurface(layout.configDir);
+    const _baseProfileName = (_surfaceState && _surfaceState.baseProfile)
+        ? _surfaceState.baseProfile
+        : (readActiveProfile(layout.configDir) || 'full');
+    const _hasSurfaceMods = !!_surfaceState && (_surfaceState.disabledClusters.length > 0 ||
+        _surfaceState.explicitAdds.length > 0 ||
+        _surfaceState.explicitRemoves.length > 0);
+    const _isUnmodifiedFull = _baseProfileName === 'full' && !_hasSurfaceMods;
     try {
         for (const kind of layout.kinds) {
-            let staged = kind.stage(resolved);
+            let staged;
+            if (kind.kind === 'agents') {
+                const agentProfile = _isUnmodifiedFull ? { ...resolved, skills: '*' } : resolved;
+                staged = kind.stage(agentProfile, agentCtx);
+            }
+            else {
+                staged = kind.stage(resolved);
+            }
             if (kind.kind === 'skills') {
                 runtimeArtifactConversion.rewriteStagedSkillBodies(staged, {
                     runtime: layout.runtime,
@@ -306,7 +327,7 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry)
                 }
             }
             const dest = assertDestWithinConfigHome(layout.configDir, kind.destSubpath);
-            _syncGsdDir(staged, dest, kind, skillManifest);
+            _syncGsdDir(staged, dest, kind, skillManifest, layout.runtime);
         }
     }
     finally {
@@ -414,13 +435,17 @@ function pruneSkillDirs(skillsDir, retainedNames, prefix, manifest) {
  * user-owned dirs. GSD-owned = stem in manifest; removal targets = in manifest AND
  * not in staged set. User-owned (not in manifest) are always preserved.
  */
-function _syncGsdDir(stagedDir, destDir, kind, manifest) {
+function _syncGsdDir(stagedDir, destDir, kind, manifest, runtime) {
     if (!node_fs_1.default.existsSync(stagedDir))
         return;
     node_fs_1.default.mkdirSync(destDir, { recursive: true });
     // Normalize: allow legacy string context for backward-compat with internal callers
     const kindName = (typeof kind === 'string') ? kind : kind.kind;
     const kindPrefix = (typeof kind === 'object' && kind !== null) ? kind.prefix : 'gsd-';
+    // #1575: copilot agents are renamed .md -> .agent.md at copy time, mirroring
+    // the inline agent loop in bin/install.js (line ~9118). Other runtimes keep
+    // the staged filename verbatim.
+    const isCopilotAgents = runtime === 'copilot' && kindName === 'agents';
     if (kindName === 'skills') {
         // Skills kind: work with directories, not files.
         // Each staged entry is a directory named ${prefix}${stem}.
@@ -455,23 +480,19 @@ function _syncGsdDir(stagedDir, destDir, kind, manifest) {
         const stagedFiles = node_fs_1.default.readdirSync(stagedDir).filter(f => f.endsWith('.md'));
         const stagedDestNames = new Set();
         for (const file of stagedFiles) {
-            const destName = (kindName === 'agents' || namespacedByDir)
-                ? file
-                : `${kindPrefix}${file.slice(0, -3)}.md`;
+            const destName = isCopilotAgents
+                ? file.replace(/\.md$/, '.agent.md')
+                : (kindName === 'agents' || namespacedByDir)
+                    ? file
+                    : `${kindPrefix}${file.slice(0, -3)}.md`;
             node_fs_1.default.copyFileSync(node_path_1.default.join(stagedDir, file), node_path_1.default.join(destDir, destName));
             stagedDestNames.add(destName);
         }
         // Prune stale GSD-owned files not in the staged set, preserving user-owned files
         // (mirrors install's prefix-scoped _removeGsdEntries):
-        //   - agents: only gsd-* are GSD-owned
+        //   - agents: only gsd-* are GSD-owned (copilot: gsd-*.agent.md)
         //   - flat command dirs: only `${kindPrefix}`-prefixed are GSD-owned
         //   - namespaced command dirs: the whole dir is GSD-owned
-        //
-        // Manifest gate (#2018): when the manifest is empty/absent (e.g. an unresolvable
-        // install source root yields an empty staged dir), the staged set is untrustworthy.
-        // Skills are guarded by pruneSkillDirs' manifest-membership check; agents must be
-        // guarded here — skip the prune loop entirely so an empty manifest never deletes
-        // every gsd-* agent. Copying (above) still runs so genuinely new agents are added.
         const shouldPruneAgents = !(kindName === 'agents' && (!manifest || manifest.size === 0));
         if (shouldPruneAgents) {
             for (const file of node_fs_1.default.readdirSync(destDir).filter(f => f.endsWith('.md'))) {

package/gsd-core/bin/shared/model-catalog.json

@@ -62,6 +62,11 @@
       "sonnet": null,
       "haiku": null
     },
+    "zcode": {
+      "opus": null,
+      "sonnet": null,
+      "haiku": null
+    },
     "augment": {
       "opus": null,
       "sonnet": null,

package/gsd-core/references/gsd-run-resolver.md

@@ -0,0 +1,8 @@
+# Standard `gsd_run` Resolver
+
+Use this bootstrap block when a workflow must call `gsd-tools` from the active worktree/runtime.
+Keep this resolver centralized; workflows should reference this file instead of copying the shell probe.
+
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+```

package/gsd-core/templates/project.md

@@ -166,7 +166,7 @@ and implemented by workflows/transition.md and workflows/complete-milestone.md.
 
 For existing codebases:
 
-1. **Map codebase first** via `/gsd:map-codebase`
+1. **Onboard or map codebase first** via `/gsd:onboard` (recommended first-time path) or `/gsd:map-codebase`
 
 2. **Infer Validated requirements** from existing code:
    - What does the codebase actually do?

package/gsd-core/workflows/do.md

@@ -40,8 +40,9 @@ Evaluate `$ARGUMENTS` against these routing rules. Apply the **first matching**
 
 | If the text describes... | Route to | Why |
 |--------------------------|----------|-----|
-| Starting a new project, "set up", "initialize" | `/gsd:new-project` | Needs full project initialization |
-| Mapping or analyzing an existing codebase | `/gsd:map-codebase` | Codebase discovery |
+| Starting a new greenfield project, "set up", "initialize" | `/gsd:new-project` | Needs full project initialization |
+| First-time setup for an existing codebase, brownfield onboarding | `/gsd:onboard` | Safe map → docs ingest → project setup sequence |
+| Mapping or analyzing an existing codebase map | `/gsd:map-codebase` | Codebase discovery or refresh |
 | A bug, error, crash, failure, or something broken | `/gsd:debug` | Needs systematic investigation |
 | Spiking, "test if", "will this work", "experiment", "prove this out", validate feasibility | `/gsd:spike` | Throwaway experiment to validate feasibility |
 | Sketching, "mockup", "what would this look like", "prototype the UI", "design this", explore visual direction | `/gsd:sketch` | Throwaway HTML mockups to explore design |
@@ -61,7 +62,7 @@ Evaluate `$ARGUMENTS` against these routing rules. Apply the **first matching**
 | Completing a milestone, shipping, releasing | `/gsd:complete-milestone` | Milestone lifecycle |
 | A specific, actionable, small task (add feature, fix typo, update config) | `/gsd:quick` | Self-contained, single executor |
 
-**Requires `.planning/` directory:** All routes except `/gsd:new-project`, `/gsd:map-codebase`, `/gsd:spike`, `/gsd:sketch`, and `/gsd:help`. If the project doesn't exist and the route requires it, suggest `/gsd:new-project` first.
+**Requires `.planning/` directory:** All routes except `/gsd:new-project`, `/gsd:onboard`, `/gsd:map-codebase`, `/gsd:spike`, `/gsd:sketch`, and `/gsd:help`. If the project doesn't exist and the route requires it, suggest `/gsd:onboard` for existing codebases or `/gsd:new-project` for greenfield projects.
 
 **Ambiguity handling:** If the text could reasonably match multiple routes, ask the user via AskUserQuestion with the top 2-3 options. For example: