@structured-vibe-coding/core 0.20.0 → 0.21.0

package/dist/{agents-YN3Z3VOH.js → agents-U5RVEZTX.js}

@@ -26,8 +26,8 @@ import {
   renderProtocolMd,
   renderThinAgent,
   writeAgentHandoff
-} from "./chunk-O4OQWVC7.js";
-import "./chunk-HUSXETPS.js";
+} from "./chunk-5GLH6ZWU.js";
+import "./chunk-AERAWOAK.js";
 import "./chunk-TNWFMRIA.js";
 import "./chunk-MHODNFIL.js";
 import "./chunk-O5SP6X5R.js";

package/dist/{chunk-O4OQWVC7.js → chunk-5GLH6ZWU.js}

@@ -6,7 +6,7 @@ import {
   loadConfig,
   readRole,
   readTeamConfig
-} from "./chunk-HUSXETPS.js";
+} from "./chunk-AERAWOAK.js";
 import {
   buildContext,
   defaultMemoryDir,

package/dist/{chunk-HUSXETPS.js → chunk-AERAWOAK.js}

@@ -3322,7 +3322,7 @@ async function buildAgentPrompt(ctx, config, projectRoot, budget, runtime) {
   }
   try {
     const { loadMcpConfig } = await import("./sources-3TXUPU6V.js");
-    const { gatherMcpContextForChange, formatMcpContextForHandoff } = await import("./gather-ZKVMJW5L.js");
+    const { gatherMcpContextForChange, formatMcpContextForHandoff } = await import("./gather-A3Q4WSPH.js");
     const mcpCfg = await loadMcpConfig(projectRoot);
     if (mcpCfg.auto_fetch_on_handoff && mcpCfg.sources.length) {
       const fetched = await gatherMcpContextForChange(projectRoot, ctx);

package/dist/{chunk-EDXT3RTN.js → chunk-ICRQOQWE.js}

@@ -26,7 +26,7 @@ function toProcessEnv(base, extra) {
 }
 
 // src/version.ts
-var SDD_CORE_VERSION = "0.20.0" ? "0.20.0" : "0.0.0-dev";
+var SDD_CORE_VERSION = "0.21.0" ? "0.21.0" : "0.0.0-dev";
 
 // src/mcp/client.ts
 function mcpTimeoutMs() {

package/dist/{chunk-NY5FFWXG.js → chunk-Z2ULYVHO.js}

@@ -4,7 +4,7 @@ import {
   gitUserName,
   loadConfig,
   readTeamConfig
-} from "./chunk-HUSXETPS.js";
+} from "./chunk-AERAWOAK.js";
 import {
   ChangeMetaSchema,
   activeStages,
@@ -970,7 +970,7 @@ async function createChange(input) {
   await materializeStageArtifacts(projectRoot, config, id, workflow, meta, firstStage);
   await setActiveChange(projectRoot, config, id);
   try {
-    const { refreshActiveAgentContext } = await import("./agents-YN3Z3VOH.js");
+    const { refreshActiveAgentContext } = await import("./agents-U5RVEZTX.js");
     await refreshActiveAgentContext(projectRoot);
   } catch {
   }
@@ -1072,7 +1072,7 @@ async function advanceStage(projectRoot, config, changeId, opts) {
         stage2
       );
       try {
-        const { refreshActiveAgentContext } = await import("./agents-YN3Z3VOH.js");
+        const { refreshActiveAgentContext } = await import("./agents-U5RVEZTX.js");
         await refreshActiveAgentContext(projectRoot);
       } catch {
       }
@@ -1129,7 +1129,7 @@ async function advanceStage(projectRoot, config, changeId, opts) {
     stage
   );
   try {
-    const { refreshActiveAgentContext } = await import("./agents-YN3Z3VOH.js");
+    const { refreshActiveAgentContext } = await import("./agents-U5RVEZTX.js");
     await refreshActiveAgentContext(projectRoot);
   } catch {
   }
@@ -1262,7 +1262,7 @@ async function completeChange(projectRoot, config, changeId) {
   let promoted;
   if (ctx.meta.workflow === "greenfield" || ctx.meta.flags?.greenfield === true) {
     try {
-      const { promoteGreenfieldToMemory: promoteGreenfieldToMemory2 } = await import("./greenfield-O2DI27HY.js");
+      const { promoteGreenfieldToMemory: promoteGreenfieldToMemory2 } = await import("./greenfield-QTMU2MH6.js");
       promoted = await promoteGreenfieldToMemory2(projectRoot, config, changeId);
     } catch {
     }

package/dist/{gather-ZKVMJW5L.js → gather-A3Q4WSPH.js}

@@ -3,7 +3,7 @@ import {
   gatherMcpContext,
   gatherMcpContextForChange,
   listMatchingSourceIds
-} from "./chunk-EDXT3RTN.js";
+} from "./chunk-ICRQOQWE.js";
 import "./chunk-4BRO7BOJ.js";
 import "./chunk-MHODNFIL.js";
 import "./chunk-O5SP6X5R.js";

package/dist/{greenfield-O2DI27HY.js → greenfield-QTMU2MH6.js}

@@ -6,8 +6,8 @@ import {
   startFeatureFromBacklog,
   startGreenfield,
   updateFeatureStatus
-} from "./chunk-NY5FFWXG.js";
-import "./chunk-HUSXETPS.js";
+} from "./chunk-Z2ULYVHO.js";
+import "./chunk-AERAWOAK.js";
 import "./chunk-TNWFMRIA.js";
 import "./chunk-MHODNFIL.js";
 import "./chunk-O5SP6X5R.js";

package/dist/index.d.ts

@@ -3397,6 +3397,32 @@ declare function runGuide(root: string, input?: {
     now?: () => Date;
 }): Promise<RoleCommandResult>;
 
+declare const SETUP_STEP_IDS: readonly ["folder", "workflow", "host", "roles", "model", "check", "start"];
+type SetupStepId = (typeof SETUP_STEP_IDS)[number];
+declare const SETUP_WHY: Record<SetupStepId, string>;
+type SetupRolesChoice = "duties" | "software" | "keep";
+type SetupModelState = "configured" | "missing" | {
+    error: string;
+};
+type SetupStatus = {
+    folder: boolean;
+    host: string | null;
+    roles: string[];
+    model: SetupModelState;
+};
+type SetupStepInput = {
+    step: SetupStepId;
+    workflow?: string;
+    host?: false | AgentTarget;
+    roles?: SetupRolesChoice;
+    /** When the model is missing, true exits 1. False prints the sentence and exits 0. */
+    requireModel?: boolean;
+};
+declare function parseSetupStep(raw: string): SetupStepId | null;
+declare function formatSetupStatus(status: SetupStatus): string;
+declare function readSetupStatus(root: string, env?: Record<string, string | undefined>): Promise<SetupStatus>;
+declare function runSetupStep(root: string, input: SetupStepInput, env?: Record<string, string | undefined>): Promise<RoleCommandResult>;
+
 declare function recordSignoff(root: string, input: {
     note?: string;
     stage?: string;
@@ -4005,4 +4031,4 @@ declare function formatEpicGraph(nodes: StoryNode[]): {
 /** Graph errors, then open dependencies. Null means the branch may be created. */
 declare function branchBlock(nodes: StoryNode[], story: string): string | null;
 
-export { AGENT_INTEGRATIONS, AGENT_TARGET_OPTIONS, ALL_AGENT_TARGETS, type AdapterExtractResult, AdapterRegistry, type AdvanceResult, type AgentInstallPlan, AgentInstallPreflightError, type AgentIntegration, type AgentTarget, type AgentTargetOption, type AllowRoleInput, type ArtifactDef, ArtifactDefSchema, type BuildRefinePlanOptions, type CallMcpToolResult, type ChangeContext, type ChangeMeta, ChangeMetaSchema, type ChangeMetrics, ChangeMetricsSchema, type ChangePhaseOrder, type CodeContextCaps, type CodeContextGap, type CodeContextGapCode, type CodeContextRequest, type CodeContextResult, type CodeContextSummary, type CodeSlice, type Complexity, type Config, ConfigSchema, type CreateChangeInput, DEFAULT_CODE_CONTEXT_CAPS, DEFAULT_INIT_INTEGRATION, type DecideInput, type DecisionMetric, DecisionMetricSchema, type DecisionModel, type DecisionOutcome, type Duty, EMBEDDINGS_UNAVAILABLE, EMBEDDING_MODEL, type Embedder, type FastembedHooks, type FocusPlan, type Gate, GateSchema, type GatherMcpOptions, type GenerateCodeContextDeps, type GeneratedManifest, type GeneratedState, type GitHeadRunner, type GreenfieldFeature, type IndexStats, type InitOptions, type InitResult, type InstallAgentOptions, type InstallAgentResult, type InstallAgentsOptions, type InstallAgentsResult, type InstalledAgentSnapshot, type KeptFile, type KeptReason, type LanguageAdapter, type McpConfig, McpConfigSchema, type McpFetchResult, type McpInvoke, McpInvokeSchema, type McpMatchContext, type McpSource, McpSourceSchema, type McpWhen, McpWhenSchema, type MetricsImportResult, type ModelChoice, type ModelContext, type ModelEntry, type ModelsConfig, ModelsConfigSchema, PROTOCOL_MD, type PhaseMetric, PhaseMetricSchema, type PhaseTiming, type PhaseTimingRow, type PlannedWrite, type PriceCard, type Prices, type ProductTeamMember, RRF_K, type RawHit, type ReconcileGeneratedResult, type RefineArtifactRef, type RefineMode, type RefinePlan, type RemoveAgentHostsResult, type RenderChangeReportInput, type RoleCommandResult, type RoleLists, type RoleModel, type RoleProfile, type RouteDeps, type RouteHit, type RouteItem, type RunRoleInput, SDD_AGENT_ROLES, SDD_CORE_VERSION, SDD_DIR, SUMMARY_TOKEN_CAP, type SddAgentRole, type SddAgentRoleId, SddError, type SearchConfig, SearchConfigError, type SearchHit, type SearchProvider, type SearchQuery, type SearchResult, type SearchRuntime, type SearchScope, type Stage, StageSchema, type StartFeatureInput, type StartGreenfieldInput, type StartGreenfieldResult, type StoryDraft, type StoryNode, type SymbolInfo, type SymbolKind, type SyncChangeResult, type TeamConfig, TeamSchema, type TokenCounts, type TokenUsageMetric, TokenUsageMetricSchema, VerifyCommandSchema, type VerifyResult, type VerifyStatus, WORK_TYPES, type WorkType, type Workflow, WorkflowSchema, acceptNetwork, activePointerPath, activeStages, addLesson, addMcpSource, advanceStage, agentHostPaths, agentKickoffMessage, allowRole, approveGate, archiveDir, assertAgentInstallable, assertSessionLogAllowed, branchBlock, budgetForStage, buildAgentPrompt, buildContext, buildRefinePlan, buildRetrievedInner, callMcpSourceTool, canLeaveStage, changeDirName, changeMetaPath, changePath, changesDir, changesPathRel, checkModels, checkTeam, chunkCode, chunkMarkdown, classifyPath, clearActiveIf, clearRegisteredSearchProviders, compareChangesByFirstPhase, completeChange, configPath, contentHash, copyDir, copyDirSkipExisting, costFor, countTokens, createBuiltinProvider, createChange, createFastembedEmbedder, createRole, createRoleFromTemplate, decide, defaultConfig, defaultMcpConfig, defaultMcpYamlPath, defaultMemoryDir, defaultPricesYamlPath, defaultSearchYamlPath, defaultTeamsDir, defaultTemplatesDir, defaultWorkflowsDir, defaultsRoot, deleteRole, describeFsError, describeKept, displayArchivePath, displayChangePath, domainsDir, duplicateRole, dutyForStage, editRole, embedSearchQuery, emptyChangeMetrics, ensureDir, ensureMcpConfig, errorMessage, executeSearch, explainMatch, explainModel, extractiveSummary, fallbackAdapter, fallbackIncompleteStageId, fallbackWarning, fastembedImportCount, findFeaturesBacklogPath, firstActiveStageId, formatDuration, formatEpicGraph, formatJsonSummary, formatMcpContextForHandoff, formatModels, formatStatus, formatTeam, formatTokenInventory, ftsTokens, fuseByRank, fuseHits, gatherMcpContext, gatherMcpContextForChange, generateCodeContext, generatedState, getActiveChangeId, getFacts, getHeadSha, getIntegration, getStage, gitUserName, guidancePaths, handoffRole, hideRole, importSessionMetrics, incompletePriorStageErrors, indexDbPath, inferComplexity, initProject, initTeam, installAgentIntegration, installAgentIntegrations, integrationKeyFor, interpolate, interpolateArgs, isHardDenied, isIgnoredPath, isInitialized, isPrunedDir, isSddError, isSecretPath, isStageSkipped, isSubstantiveArtifactContent, isWorkType, keywordHits, listBacklogFeatures, listBundledWorkflowNames, listChanges, listDirs, listFacts, listFiles, listMatchingSourceIds, listMcpSourceTools, listRoleTemplates, listScopeHits, listTeamTemplates, listWorkflowNames, loadBrain, loadChangeMeta, loadConfig, loadEpicStories, loadExcluder, loadGeneratedManifest, loadInstalledAgent, loadMcpConfig, loadModels, loadPrices, loadProductTeam, loadSearchConfig, loadWorkflow, markGenerated, matchMcpSources, mcpConfigPath, mcpTimeoutMs, memoryDir, memoryPathRel, mergeCaps, mergeConfigDefaults, mergeRankedHits, migrateTeamMemory, missingBundledWorkflows, modelFromEnv, nextStageId, nowIso, optionForTarget, packHits, parseAgentTargets, parseFeaturesBacklog, parseIntegration, parseStoryDraft, pathExists, phaseTiming, pinRole, planAgentIntegration, planNetwork, postRoom, prepareGuide, productTeamHome, promoteGreenfieldToMemory, queueRole, rankScope, readChangeMetrics, readHandoffCodePoints, readTeamConfig, readText, readYaml, rebuildNetwork, recommendWorkflow, reconcileGeneratedTree, recordDecisionMetric, recordDecisionRequest, recordSignoff, refreshActiveAgentContext, refreshConfiguredGuidance, registerSearchProvider, removeMcpSource, removeOtherAgentHosts, removeOtherAgentHostsDetailed, removePath, renderAgentsMd, renderBlock, renderChangeReport, renderMemoryIndex, renderProductTeamSection, renderProtocolMd, renderSddReadme, renderThinAgent, repairRequiredIgnores, reportAllChanges, reportChange, resolveActiveDirectory, resolveBot, resolveChangeId, resolveEmbedder, resolveFocus, resolveSearchProvider, resolveStages, reviewRoom, roleContextBody, routeRole, rrf, runGuide, runLocalVerify, runLoop, runNetwork, runRole, saveChangeMeta, saveConfig, saveGeneratedManifest, saveMcpConfig, scopeForPath, sddRoot, searchConfigPath, searchPreamble, selectModel, setActiveChange, setFact, setRoleContext, setRoleMessaging, shouldAutoSkip, showFact, showMemory, showRoleGroup, showRoles, showRoom, showTeam, skipStage, slugify, spawnModelCommand, startFeatureFromBacklog, startGreenfield, startPhase, storyIdTaken, switchWorkflow, syncChangeHead, takeRole, templatesDir, toProcessEnv, todayIsoDate, tokenizeKeywords, transitionPhase, typescriptAdapter, uniqueChangeDirName, updateFeatureStatus, validBranchName, withMcpSource, workKind, workflowUnavailableMessage, workflowsDir, writeAgentHandoff, writeRefineBrief, writeText, writeTextIfMissing, writeYaml };
+export { AGENT_INTEGRATIONS, AGENT_TARGET_OPTIONS, ALL_AGENT_TARGETS, type AdapterExtractResult, AdapterRegistry, type AdvanceResult, type AgentInstallPlan, AgentInstallPreflightError, type AgentIntegration, type AgentTarget, type AgentTargetOption, type AllowRoleInput, type ArtifactDef, ArtifactDefSchema, type BuildRefinePlanOptions, type CallMcpToolResult, type ChangeContext, type ChangeMeta, ChangeMetaSchema, type ChangeMetrics, ChangeMetricsSchema, type ChangePhaseOrder, type CodeContextCaps, type CodeContextGap, type CodeContextGapCode, type CodeContextRequest, type CodeContextResult, type CodeContextSummary, type CodeSlice, type Complexity, type Config, ConfigSchema, type CreateChangeInput, DEFAULT_CODE_CONTEXT_CAPS, DEFAULT_INIT_INTEGRATION, type DecideInput, type DecisionMetric, DecisionMetricSchema, type DecisionModel, type DecisionOutcome, type Duty, EMBEDDINGS_UNAVAILABLE, EMBEDDING_MODEL, type Embedder, type FastembedHooks, type FocusPlan, type Gate, GateSchema, type GatherMcpOptions, type GenerateCodeContextDeps, type GeneratedManifest, type GeneratedState, type GitHeadRunner, type GreenfieldFeature, type IndexStats, type InitOptions, type InitResult, type InstallAgentOptions, type InstallAgentResult, type InstallAgentsOptions, type InstallAgentsResult, type InstalledAgentSnapshot, type KeptFile, type KeptReason, type LanguageAdapter, type McpConfig, McpConfigSchema, type McpFetchResult, type McpInvoke, McpInvokeSchema, type McpMatchContext, type McpSource, McpSourceSchema, type McpWhen, McpWhenSchema, type MetricsImportResult, type ModelChoice, type ModelContext, type ModelEntry, type ModelsConfig, ModelsConfigSchema, PROTOCOL_MD, type PhaseMetric, PhaseMetricSchema, type PhaseTiming, type PhaseTimingRow, type PlannedWrite, type PriceCard, type Prices, type ProductTeamMember, RRF_K, type RawHit, type ReconcileGeneratedResult, type RefineArtifactRef, type RefineMode, type RefinePlan, type RemoveAgentHostsResult, type RenderChangeReportInput, type RoleCommandResult, type RoleLists, type RoleModel, type RoleProfile, type RouteDeps, type RouteHit, type RouteItem, type RunRoleInput, SDD_AGENT_ROLES, SDD_CORE_VERSION, SDD_DIR, SETUP_STEP_IDS, SETUP_WHY, SUMMARY_TOKEN_CAP, type SddAgentRole, type SddAgentRoleId, SddError, type SearchConfig, SearchConfigError, type SearchHit, type SearchProvider, type SearchQuery, type SearchResult, type SearchRuntime, type SearchScope, type SetupModelState, type SetupRolesChoice, type SetupStatus, type SetupStepId, type SetupStepInput, type Stage, StageSchema, type StartFeatureInput, type StartGreenfieldInput, type StartGreenfieldResult, type StoryDraft, type StoryNode, type SymbolInfo, type SymbolKind, type SyncChangeResult, type TeamConfig, TeamSchema, type TokenCounts, type TokenUsageMetric, TokenUsageMetricSchema, VerifyCommandSchema, type VerifyResult, type VerifyStatus, WORK_TYPES, type WorkType, type Workflow, WorkflowSchema, acceptNetwork, activePointerPath, activeStages, addLesson, addMcpSource, advanceStage, agentHostPaths, agentKickoffMessage, allowRole, approveGate, archiveDir, assertAgentInstallable, assertSessionLogAllowed, branchBlock, budgetForStage, buildAgentPrompt, buildContext, buildRefinePlan, buildRetrievedInner, callMcpSourceTool, canLeaveStage, changeDirName, changeMetaPath, changePath, changesDir, changesPathRel, checkModels, checkTeam, chunkCode, chunkMarkdown, classifyPath, clearActiveIf, clearRegisteredSearchProviders, compareChangesByFirstPhase, completeChange, configPath, contentHash, copyDir, copyDirSkipExisting, costFor, countTokens, createBuiltinProvider, createChange, createFastembedEmbedder, createRole, createRoleFromTemplate, decide, defaultConfig, defaultMcpConfig, defaultMcpYamlPath, defaultMemoryDir, defaultPricesYamlPath, defaultSearchYamlPath, defaultTeamsDir, defaultTemplatesDir, defaultWorkflowsDir, defaultsRoot, deleteRole, describeFsError, describeKept, displayArchivePath, displayChangePath, domainsDir, duplicateRole, dutyForStage, editRole, embedSearchQuery, emptyChangeMetrics, ensureDir, ensureMcpConfig, errorMessage, executeSearch, explainMatch, explainModel, extractiveSummary, fallbackAdapter, fallbackIncompleteStageId, fallbackWarning, fastembedImportCount, findFeaturesBacklogPath, firstActiveStageId, formatDuration, formatEpicGraph, formatJsonSummary, formatMcpContextForHandoff, formatModels, formatSetupStatus, formatStatus, formatTeam, formatTokenInventory, ftsTokens, fuseByRank, fuseHits, gatherMcpContext, gatherMcpContextForChange, generateCodeContext, generatedState, getActiveChangeId, getFacts, getHeadSha, getIntegration, getStage, gitUserName, guidancePaths, handoffRole, hideRole, importSessionMetrics, incompletePriorStageErrors, indexDbPath, inferComplexity, initProject, initTeam, installAgentIntegration, installAgentIntegrations, integrationKeyFor, interpolate, interpolateArgs, isHardDenied, isIgnoredPath, isInitialized, isPrunedDir, isSddError, isSecretPath, isStageSkipped, isSubstantiveArtifactContent, isWorkType, keywordHits, listBacklogFeatures, listBundledWorkflowNames, listChanges, listDirs, listFacts, listFiles, listMatchingSourceIds, listMcpSourceTools, listRoleTemplates, listScopeHits, listTeamTemplates, listWorkflowNames, loadBrain, loadChangeMeta, loadConfig, loadEpicStories, loadExcluder, loadGeneratedManifest, loadInstalledAgent, loadMcpConfig, loadModels, loadPrices, loadProductTeam, loadSearchConfig, loadWorkflow, markGenerated, matchMcpSources, mcpConfigPath, mcpTimeoutMs, memoryDir, memoryPathRel, mergeCaps, mergeConfigDefaults, mergeRankedHits, migrateTeamMemory, missingBundledWorkflows, modelFromEnv, nextStageId, nowIso, optionForTarget, packHits, parseAgentTargets, parseFeaturesBacklog, parseIntegration, parseSetupStep, parseStoryDraft, pathExists, phaseTiming, pinRole, planAgentIntegration, planNetwork, postRoom, prepareGuide, productTeamHome, promoteGreenfieldToMemory, queueRole, rankScope, readChangeMetrics, readHandoffCodePoints, readSetupStatus, readTeamConfig, readText, readYaml, rebuildNetwork, recommendWorkflow, reconcileGeneratedTree, recordDecisionMetric, recordDecisionRequest, recordSignoff, refreshActiveAgentContext, refreshConfiguredGuidance, registerSearchProvider, removeMcpSource, removeOtherAgentHosts, removeOtherAgentHostsDetailed, removePath, renderAgentsMd, renderBlock, renderChangeReport, renderMemoryIndex, renderProductTeamSection, renderProtocolMd, renderSddReadme, renderThinAgent, repairRequiredIgnores, reportAllChanges, reportChange, resolveActiveDirectory, resolveBot, resolveChangeId, resolveEmbedder, resolveFocus, resolveSearchProvider, resolveStages, reviewRoom, roleContextBody, routeRole, rrf, runGuide, runLocalVerify, runLoop, runNetwork, runRole, runSetupStep, saveChangeMeta, saveConfig, saveGeneratedManifest, saveMcpConfig, scopeForPath, sddRoot, searchConfigPath, searchPreamble, selectModel, setActiveChange, setFact, setRoleContext, setRoleMessaging, shouldAutoSkip, showFact, showMemory, showRoleGroup, showRoles, showRoom, showTeam, skipStage, slugify, spawnModelCommand, startFeatureFromBacklog, startGreenfield, startPhase, storyIdTaken, switchWorkflow, syncChangeHead, takeRole, templatesDir, toProcessEnv, todayIsoDate, tokenizeKeywords, transitionPhase, typescriptAdapter, uniqueChangeDirName, updateFeatureStatus, validBranchName, withMcpSource, workKind, workflowUnavailableMessage, workflowsDir, writeAgentHandoff, writeRefineBrief, writeText, writeTextIfMissing, writeYaml };

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   mcpTimeoutMs,
   toProcessEnv,
   withMcpSource
-} from "./chunk-EDXT3RTN.js";
+} from "./chunk-ICRQOQWE.js";
 import {
   McpConfigSchema,
   McpInvokeSchema,
@@ -68,7 +68,7 @@ import {
   renderThinAgent,
   saveGeneratedManifest,
   writeAgentHandoff
-} from "./chunk-O4OQWVC7.js";
+} from "./chunk-5GLH6ZWU.js";
 import {
   ChangeMetricsSchema,
   DecisionMetricSchema,
@@ -100,7 +100,7 @@ import {
   switchWorkflow,
   transitionPhase,
   updateFeatureStatus
-} from "./chunk-NY5FFWXG.js";
+} from "./chunk-Z2ULYVHO.js";
 import {
   EMBEDDINGS_UNAVAILABLE,
   EMBEDDING_MODEL,
@@ -190,7 +190,7 @@ import {
   showTeam,
   workKind,
   writePackedCache
-} from "./chunk-HUSXETPS.js";
+} from "./chunk-AERAWOAK.js";
 import {
   ArtifactDefSchema,
   ChangeMetaSchema,
@@ -1395,7 +1395,7 @@ ${output}`);
     status = failed.length ? "fail" : "pass";
     reason = failed.length ? `failed: ${failed.join(", ")}` : void 0;
   }
-  const ok10 = status === "pass";
+  const ok11 = status === "pass";
   const checklist = stage.gate?.checklist ?? [];
   const lines = buildSummaryLines(
     ctx.meta.title,
@@ -1446,7 +1446,7 @@ ${output}`);
   ctx.meta.verify_results = {
     ...ctx.meta.verify_results,
     [stage.id]: {
-      ok: ok10,
+      ok: ok11,
       status,
       ...results.length && headSha2 ? { head_sha: headSha2 } : {},
       at: nowIso(),
@@ -1462,7 +1462,7 @@ ${output}`);
     checklist,
     evidencePath: evidenceDir,
     resultsPath: summaryPath,
-    ok: ok10
+    ok: ok11
   };
 }
 
@@ -1875,10 +1875,10 @@ function formatMarkdown(input) {
 `;
   return { markdown: packed ? frame + packed : frame, truncated: input.summary.truncated };
 }
-function formatJsonSummary(summary, gaps, slices, ok10) {
+function formatJsonSummary(summary, gaps, slices, ok11) {
   return JSON.stringify(
     {
-      ok: ok10,
+      ok: ok11,
       summary,
       gaps,
       slices: slices.map((s) => ({
@@ -3608,8 +3608,8 @@ function asRecord(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return {};
   return value;
 }
-function result(name, ok10, text2) {
-  return { ok: ok10, name, text: clip(text2) };
+function result(name, ok11, text2) {
+  return { ok: ok11, name, text: clip(text2) };
 }
 async function git(cwd, args) {
   return new Promise((resolve) => {
@@ -6511,6 +6511,130 @@ async function runGuide(root, input = {}) {
   return fail9("The guide stopped after 16 steps.");
 }
 
+// src/role/setup-tour.ts
+import { join as join19 } from "pathe";
+var SETUP_STEP_IDS = [
+  "folder",
+  "workflow",
+  "host",
+  "roles",
+  "model",
+  "check",
+  "start"
+];
+var SETUP_WHY = {
+  folder: "sdd reads .sdd/config.yaml first.",
+  workflow: "Stage lists on new role files come from this workflow.",
+  host: "A host is optional. Drafts use a role model, not the host.",
+  roles: "These files say who drafts each stage. Existing files stay.",
+  model: "A draft needs SDD_ROLE_MODEL. Setup does not write that command into the repo.",
+  check: "This is what is already in place.",
+  start: "The first change is optional. sdd go asks the role for that stage."
+};
+function ok10(stdout) {
+  return { exitCode: 0, stdout };
+}
+function fail10(stdout) {
+  return { exitCode: 1, stdout };
+}
+function parseSetupStep(raw) {
+  const id = raw.trim();
+  return SETUP_STEP_IDS.includes(id) ? id : null;
+}
+function formatSetupStatus(status) {
+  const folder = status.folder ? "Folder: ready." : "Folder: not set up.";
+  const host = status.host ? `Host: ${status.host}.` : "Host: none.";
+  const roles = status.roles.length > 0 ? `Roles: ${status.roles.join(", ")}.` : "Roles: none.";
+  const model = status.model === "configured" ? "Model: configured." : status.model === "missing" ? "Model: No role model is configured." : `Model: ${status.model.error}`;
+  return [folder, host, roles, model].join("\n");
+}
+async function roleNames(root) {
+  const names = await listFiles(join19(root, ".sdd", "roles"));
+  return names.filter((name) => name.endsWith(".md")).map((name) => name.slice(0, -".md".length)).sort((left, right) => left.localeCompare(right));
+}
+async function modelState(root, env) {
+  if (modelFromEnv(env)) return "configured";
+  const loaded = await loadModels(root);
+  if (loaded === null) return "missing";
+  if ("error" in loaded) return { error: loaded.error };
+  return "configured";
+}
+async function readSetupStatus(root, env = process.env) {
+  const installed = await loadInstalledAgent(root);
+  return {
+    folder: await isInitialized(root),
+    host: installed?.ai ?? null,
+    roles: await roleNames(root),
+    model: await modelState(root, env)
+  };
+}
+function withRoleHints(result2) {
+  if (result2.exitCode !== 0) return result2;
+  const hints = [
+    "Add stages with sdd role edit <name> --stages ...",
+    'Add context with sdd role context <name> --text "..."'
+  ];
+  const body = result2.stdout.trim();
+  return ok10(body.length > 0 ? `${body}
+${hints.join("\n")}` : hints.join("\n"));
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+async function runSetupStep(root, input, env = process.env) {
+  const workflow = input.workflow?.trim() || "feature";
+  try {
+    if (input.step === "folder") {
+      if (!await isInitialized(root)) {
+        await initProject({ projectRoot: root, agents: false });
+      }
+      return ok10("Folder: ready.");
+    }
+    if (input.step === "workflow") {
+      const lines = [`Workflow: ${workflow}.`];
+      if ((await roleNames(root)).length > 0) lines.push("Roles are already here.");
+      return ok10(lines.join("\n"));
+    }
+    if (input.step === "host") {
+      const installed = await loadInstalledAgent(root);
+      if (installed) return ok10(`Host: ${installed.ai}.`);
+      if (!input.host) return ok10("Host: none.");
+      if (!await isInitialized(root)) {
+        await initProject({ projectRoot: root, agents: input.host });
+      } else {
+        await installAgentIntegration({ projectRoot: root, target: input.host });
+      }
+      const after = await loadInstalledAgent(root);
+      return ok10(`Host: ${after?.ai ?? input.host}.`);
+    }
+    if (input.step === "roles") {
+      const choice = input.roles ?? "duties";
+      if (choice === "keep") {
+        const names = await roleNames(root);
+        const line = names.length > 0 ? "Roles are already here." : "Roles: none.";
+        return withRoleHints(ok10(line));
+      }
+      if (choice === "software") {
+        return withRoleHints(await initTeam(root, "software", gitUserName(root)));
+      }
+      return withRoleHints(await prepareGuide(root, { workflow, agents: false }));
+    }
+    if (input.step === "model") {
+      const state = await modelState(root, env);
+      if (state === "configured") return ok10("Model: configured.");
+      if (typeof state === "object") return fail10(state.error);
+      if (input.requireModel) return fail10("No role model is configured.");
+      return ok10("No role model is configured.");
+    }
+    if (input.step === "check") {
+      return ok10(formatSetupStatus(await readSetupStatus(root, env)));
+    }
+    return ok10('Next: sdd go "what you want to build"');
+  } catch (error) {
+    return fail10(messageOf(error));
+  }
+}
+
 // src/role/models/show.ts
 function formatModelChoice(workType, choice) {
   return `${workType}  ${choice.id}  ${choice.kind}  ${choice.provider}  ${choice.why}`;
@@ -6549,7 +6673,7 @@ function explainModel(config, workType, ctx) {
 }
 
 // src/stories.ts
-import { join as join19 } from "pathe";
+import { join as join20 } from "pathe";
 var STORY_ID = /^S-\d+$/i;
 var EPIC_KEY = /^[A-Za-z0-9][A-Za-z0-9-]{0,39}$/;
 function validBranchName(name) {
@@ -6591,7 +6715,7 @@ function parseStoryDraft(input) {
 async function metasIn(dir) {
   const out = [];
   for (const id of await listDirs(dir)) {
-    const path = join19(dir, id, "meta.yaml");
+    const path = join20(dir, id, "meta.yaml");
     if (!await pathExists(path)) continue;
     try {
       out.push(ChangeMetaSchema.parse(await readYaml(path)));
@@ -6739,6 +6863,8 @@ export {
   SDD_AGENT_ROLES,
   SDD_CORE_VERSION,
   SDD_DIR,
+  SETUP_STEP_IDS,
+  SETUP_WHY,
   SUMMARY_TOKEN_CAP,
   SddError,
   SearchConfigError,
@@ -6834,6 +6960,7 @@ export {
   formatJsonSummary,
   formatMcpContextForHandoff,
   formatModels,
+  formatSetupStatus,
   formatStatus,
   formatTeam,
   formatTokenInventory,
@@ -6918,6 +7045,7 @@ export {
   parseAgentTargets,
   parseFeaturesBacklog,
   parseIntegration,
+  parseSetupStep,
   parseStoryDraft,
   pathExists,
   phaseTiming,
@@ -6932,6 +7060,7 @@ export {
   rankScope,
   readChangeMetrics,
   readHandoffCodePoints,
+  readSetupStatus,
   readTeamConfig,
   readText,
   readYaml,
@@ -6975,6 +7104,7 @@ export {
   runLoop,
   runNetwork,
   runRole,
+  runSetupStep,
   saveChangeMeta,
   saveConfig,
   saveGeneratedManifest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-vibe-coding/core",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Core engine for sdd — Spec-Driven Development workflows, change packs, greenfield, and AI agent handoff (used by the sdd CLI)",
   "type": "module",
   "main": "./dist/index.js",