@treeseed/sdk 0.6.50 → 0.7.0

package/dist/operations/services/{knowledge-coop-launch.js → hub-provider-launch.js}

@@ -1,4 +1,4 @@
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -18,12 +18,12 @@ import { templateCatalogRoot } from "./runtime-paths.js";
 import { scaffoldTemplateProject } from "./template-registry.js";
 import { buildKnowledgeCoopKnowledgePackPackage, buildKnowledgeCoopTemplatePackage, importKnowledgeCoopKnowledgePack } from "./knowledge-coop-packaging.js";
 import { resolveTreeseedToolBinary } from "../../managed-dependencies.js";
-class KnowledgeCoopLaunchError extends Error {
+class KnowledgeHubProviderLaunchError extends Error {
   phase;
   phases;
   constructor(phase, message, phases = []) {
     super(message);
-    this.name = "KnowledgeCoopLaunchError";
+    this.name = "KnowledgeHubProviderLaunchError";
     this.phase = phase;
     this.phases = [...phases];
   }
@@ -132,13 +132,13 @@ The first release should verify that the hub is live, the core direction is visi
 `);
   writeText(resolve(projectRoot, "src/content/notes", `${noteSlug}.mdx`), `---
 title: ${input.projectName} Operating Model
-description: The initial working agreements for this Knowledge Coop hub.
+description: The initial working agreements for this Knowledge Hub.
 date: ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}
 summary: Managed launch created the default branches, runtime wiring, and first operational checkpoints.
 status: live
 ---
 
-This hub starts with a managed launch, a seeded objective, and a visible first workstream so the team can continue from a known baseline.
+This hub starts with a Knowledge Hub launch, a seeded objective, and a visible first workstream so the team can continue from a known baseline.
 `);
   writeText(resolve(projectRoot, "src/content/proposals", "establish-initial-operating-routine.mdx"), `---
 id: ${proposalId}
@@ -166,11 +166,11 @@ id: ${decisionId}
 title: Adopt The Initial Launch Posture
 description: Record the launch decision for the first operating cycle of the hub.
 date: ${(/* @__PURE__ */ new Date()).toISOString().slice(0, 10)}
-summary: The managed launch will begin with a narrow first release and explicit direction artifacts.
+summary: The Knowledge Hub launch will begin with a narrow first release and explicit direction artifacts.
 status: live
 decisionType: approved
 rationale: The initial launch should bias toward clarity, setup completion, and a visible first release loop.
-authority: Knowledge Coop managed launch
+authority: Knowledge Hub launch
 primaryContributor: ${stewardSlug}
 relatedObjectives:
   - launch-knowledge-hub
@@ -514,13 +514,15 @@ function commandAvailable(command) {
   }
   return spawnSync("bash", ["-lc", `command -v ${command}`], { stdio: "ignore" }).status === 0;
 }
-function appendPhase(phases, phase, status, detail) {
-  phases.push({
+async function appendPhase(phases, phase, status, detail, reporter) {
+  const record = {
     phase,
     status,
     detail,
     timestamp: nowIso()
-  });
+  };
+  phases.push(record);
+  await reporter?.(record);
 }
 function stringValue(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : "";
@@ -565,6 +567,7 @@ function buildProcessingHostEnvironmentOverlay(input, scope) {
   return overlay;
 }
 function scaffoldKnowledgeCoopSource(projectRoot, input) {
+  const repositoryName = slugify(input.repoName ?? input.projectSlug, "project");
   const templateId = input.sourceKind === "template" ? slugify(input.sourceRef ?? "starter-basic", "starter-basic") : "starter-basic";
   const templateCatalogEnv = { TREESEED_TEMPLATE_CATALOG_URL: currentTemplateCatalogUrl() };
   if (input.sourceKind === "knowledge_pack") {
@@ -590,13 +593,59 @@ function scaffoldKnowledgeCoopSource(projectRoot, input) {
     slug: input.projectSlug,
     siteUrl: resolveManagedWebUrl(slugify(input.projectSlug, "project")),
     contactEmail: input.contactEmail ?? `hello+${slugify(input.projectSlug, "project")}@knowledge.coop`,
-    repositoryUrl: `https://github.com/${slugify(input.repoOwner ?? resolveDefaultGitHubOwner(), "treeseed-ai")}/${slugify(input.projectSlug, "project")}`
+    repositoryUrl: `https://github.com/${slugify(input.repoOwner ?? resolveDefaultGitHubOwner(), "treeseed-ai")}/${repositoryName}`
   }, {
     cwd: projectRoot,
     env: templateCatalogEnv
   });
 }
-async function validateKnowledgeCoopManagedLaunchPrerequisites(tenantRoot = process.cwd(), { valuesOverlay = {} } = {}) {
+function repositoryHostGitHubEnvOverlay() {
+  const token = process.env.TREESEED_HOSTED_HUBS_GITHUB_TOKEN || process.env.TREESEED_REPOSITORY_HOST_GITHUB_TOKEN || process.env.GH_TOKEN || process.env.GITHUB_TOKEN || "";
+  return token ? { ...process.env, GH_TOKEN: token, GITHUB_TOKEN: token } : process.env;
+}
+function prepareKnowledgeHubContentRepositoryRoot(sourceRoot, contentRoot, input) {
+  mkdirSync(contentRoot, { recursive: true });
+  const contentSource = resolve(sourceRoot, "src", "content");
+  if (existsSync(contentSource)) {
+    cpSync(contentSource, resolve(contentRoot, "src", "content"), { recursive: true });
+  }
+  const publicSource = resolve(sourceRoot, "public");
+  if (existsSync(publicSource)) {
+    cpSync(publicSource, resolve(contentRoot, "public"), { recursive: true });
+  }
+  writeFileSync(resolve(contentRoot, "README.md"), `# ${input.projectName} Content
+
+Content source for the ${input.projectName} TreeSeed Knowledge Hub.
+`, "utf8");
+  writeFileSync(resolve(contentRoot, "treeseed.content.json"), `${JSON.stringify({
+    schemaVersion: 1,
+    kind: "treeseed_hub_content",
+    projectId: input.projectId,
+    projectSlug: input.projectSlug,
+    contentRoot: "src/content",
+    productionSource: "r2_published_artifacts",
+    overlayPolicy: "src_content_when_present"
+  }, null, 2)}
+`, "utf8");
+}
+function stripSoftwareContentOverlay(sourceRoot, input) {
+  const contentRoot = resolve(sourceRoot, "src", "content");
+  rmSync(contentRoot, { recursive: true, force: true });
+  mkdirSync(contentRoot, { recursive: true });
+  writeFileSync(resolve(contentRoot, ".gitkeep"), "", "utf8");
+  writeFileSync(
+    resolve(contentRoot, "README.md"),
+    `# Preview content overlay
+
+This software repository does not own ordinary Knowledge Hub content. Production content is published from the content repository to R2 artifacts. Checked-out files under \`src/content\` are for local, staging, or preview overlays only.
+
+Hub: ${input.projectName}
+Content source: ${input.contentRepository?.name ?? `${slugify(input.projectSlug, "project")}-content`}
+`,
+    "utf8"
+  );
+}
+async function validateKnowledgeHubProviderLaunchPrerequisites(tenantRoot = process.cwd(), { valuesOverlay = {} } = {}) {
   const values = collectTreeseedConfigSeedValues(tenantRoot, "prod", process.env, valuesOverlay);
   const requiredConfig = [
     ["TREESEED_BETTER_AUTH_SECRET"],
@@ -628,8 +677,9 @@ async function validateKnowledgeCoopManagedLaunchPrerequisites(tenantRoot = proc
     commands
   };
 }
-async function executeKnowledgeCoopManagedLaunch(input) {
+async function executeKnowledgeHubProviderLaunch(input, options = {}) {
   const phases = [];
+  const reportPhase = options.onPhase;
   const prodEnvOverlay = {
     ...buildCloudflareHostEnvironmentOverlay(input, "prod"),
     ...buildProcessingHostEnvironmentOverlay(input, "prod")
@@ -638,35 +688,82 @@ async function executeKnowledgeCoopManagedLaunch(input) {
     ...buildCloudflareHostEnvironmentOverlay(input, "staging"),
     ...buildProcessingHostEnvironmentOverlay(input, "staging")
   };
-  const preflight = await validateKnowledgeCoopManagedLaunchPrerequisites(process.cwd(), { valuesOverlay: prodEnvOverlay });
+  const preflight = await validateKnowledgeHubProviderLaunchPrerequisites(process.cwd(), { valuesOverlay: prodEnvOverlay });
   if (!preflight.ok) {
-    throw new KnowledgeCoopLaunchError(
+    throw new KnowledgeHubProviderLaunchError(
       "runtime_connection_failed",
-      `Knowledge Coop launch preflight failed: ${[...preflight.missingConfig, ...preflight.providerChecks.issues].join("; ") || "provider checks failed."}`,
+      `Knowledge Hub launch preflight failed: ${[...preflight.missingConfig, ...preflight.providerChecks.issues].join("; ") || "provider checks failed."}`,
       []
     );
   }
-  const workingRoot = mkdtempSync(join(tmpdir(), `knowledge-coop-launch-${slugify(input.projectSlug, "project")}-`));
+  const workingRoot = mkdtempSync(join(tmpdir(), `hub-provider-launch-${slugify(input.projectSlug, "project")}-`));
   const repoOwner = slugify(input.repoOwner ?? resolveDefaultGitHubOwner(), "treeseed-ai");
-  const repoName = slugify(input.projectSlug, "project");
+  const repoName = slugify(input.repoName ?? input.projectSlug, "project");
+  const githubEnv = repositoryHostGitHubEnvOverlay();
+  let packageSourceRoot = null;
   try {
-    appendPhase(phases, "repo_provision", "running", "Creating GitHub repository.");
-    const repository = await createGitHubRepository({
+    await appendPhase(phases, "repo_provision", "running", "Creating or connecting GitHub software repository.", reportPhase);
+    const repository = input.existingRepository?.url ? {
+      slug: `${input.existingRepository.owner}/${input.existingRepository.name}`,
+      owner: input.existingRepository.owner,
+      name: input.existingRepository.name,
+      url: input.existingRepository.url,
+      visibility: input.existingRepository.visibility ?? input.repoVisibility ?? "private"
+    } : await createGitHubRepository({
       owner: repoOwner,
       name: repoName,
-      description: input.summary ?? `Knowledge Coop hub for ${input.projectName}`,
+      description: input.summary ?? `Knowledge Hub for ${input.projectName}`,
       visibility: input.repoVisibility ?? "private",
       homepageUrl: resolveManagedWebUrl(repoName),
       topics: ["knowledge-coop", "treeseed", "knowledge-hub"]
-    });
-    appendPhase(phases, "repo_provision", "completed", `Created ${repository.slug}.`);
-    appendPhase(phases, "content_bootstrap", "running", "Scaffolding the project and seeding initial content.");
+    }, { env: githubEnv });
+    await appendPhase(phases, "repo_provision", "completed", `${input.existingRepository?.url ? "Connected" : "Created"} ${repository.slug}.`, reportPhase);
+    await appendPhase(phases, "content_bootstrap", "running", "Scaffolding the project and seeding initial content.", reportPhase);
     await scaffoldKnowledgeCoopSource(workingRoot, input);
     ensureHostedProjectFiles(workingRoot);
     const managedDefaults = applyManagedProjectDefaults(workingRoot, input);
     const seed = seedKnowledgeCoopContent(workingRoot, input);
-    appendPhase(phases, "content_bootstrap", "completed", "Scaffolded the repo and seeded Direct content.");
-    appendPhase(phases, "workflow_bootstrap", "running", "Initializing git branches and GitHub workflows.");
+    packageSourceRoot = mkdtempSync(join(tmpdir(), `knowledge-coop-package-${slugify(input.projectSlug, "project")}-`));
+    cpSync(workingRoot, packageSourceRoot, { recursive: true });
+    await appendPhase(phases, "content_bootstrap", "completed", "Scaffolded the repo and seeded Direct content.", reportPhase);
+    let contentRepository = null;
+    let contentRepositoryWorkingRoot = null;
+    if (input.contentRepository?.name) {
+      await appendPhase(phases, "content_repository", "running", "Creating content repository.", reportPhase);
+      contentRepositoryWorkingRoot = mkdtempSync(join(tmpdir(), `knowledge-coop-content-${slugify(input.projectSlug, "project")}-`));
+      prepareKnowledgeHubContentRepositoryRoot(workingRoot, contentRepositoryWorkingRoot, input);
+      const createdContentRepository = input.contentRepository.url ? {
+        slug: `${slugify(input.contentRepository.owner ?? repoOwner, "treeseed-ai")}/${slugify(input.contentRepository.name, `${repoName}-content`)}`,
+        owner: slugify(input.contentRepository.owner ?? repoOwner, "treeseed-ai"),
+        name: slugify(input.contentRepository.name, `${repoName}-content`),
+        url: input.contentRepository.url,
+        visibility: input.contentRepository.visibility ?? input.repoVisibility ?? "private"
+      } : await createGitHubRepository({
+        owner: slugify(input.contentRepository.owner ?? repoOwner, "treeseed-ai"),
+        name: slugify(input.contentRepository.name, `${repoName}-content`),
+        description: input.summary ?? `Content source for ${input.projectName}`,
+        visibility: input.contentRepository.visibility ?? input.repoVisibility ?? "private",
+        homepageUrl: resolveManagedWebUrl(repoName),
+        topics: ["knowledge-coop", "treeseed", "knowledge-hub", "content"]
+      }, { env: githubEnv });
+      const contentInitResult = initializeGitHubRepositoryWorkingTree(contentRepositoryWorkingRoot, createdContentRepository, {
+        defaultBranch: input.contentRepository.defaultBranch ?? "main",
+        createStaging: true,
+        commitMessage: `Initialize ${input.projectName} content`
+      });
+      contentRepository = {
+        slug: createdContentRepository.slug,
+        owner: createdContentRepository.owner,
+        name: createdContentRepository.name,
+        url: createdContentRepository.url,
+        defaultBranch: contentInitResult.defaultBranch,
+        stagingBranch: contentInitResult.stagingBranch,
+        visibility: createdContentRepository.visibility
+      };
+      await appendPhase(phases, "content_repository", "completed", `${input.contentRepository.url ? "Connected" : "Created"} ${contentRepository.slug}.`, reportPhase);
+      stripSoftwareContentOverlay(workingRoot, input);
+    }
+    await appendPhase(phases, "workflow_bootstrap", "running", "Initializing git branches and GitHub workflows.", reportPhase);
     const initResult = initializeGitHubRepositoryWorkingTree(workingRoot, repository, {
       defaultBranch: "main",
       createStaging: true,
@@ -685,8 +782,8 @@ async function executeKnowledgeCoopManagedLaunch(input) {
       }));
     }
     const workflowSummary = { ...workflows, environmentSync: githubEnvironmentSync };
-    appendPhase(phases, "workflow_bootstrap", "completed", "Configured GitHub workflows, secrets, and variables.");
-    appendPhase(phases, "hosting_registration", "running", "Provisioning Cloudflare resources and deploy state.");
+    await appendPhase(phases, "workflow_bootstrap", "completed", "Configured GitHub workflows, secrets, and variables.", reportPhase);
+    await appendPhase(phases, "hosting_registration", "running", "Provisioning Cloudflare resources and deploy state.", reportPhase);
     const staging = await reconcileTreeseedTarget({
       tenantRoot: workingRoot,
       target: createPersistentDeployTarget("staging"),
@@ -703,7 +800,7 @@ async function executeKnowledgeCoopManagedLaunch(input) {
       target: createPersistentDeployTarget("prod"),
       env: { ...process.env, ...prodEnvOverlay }
     });
-    appendPhase(phases, "hosting_registration", "completed", "Provisioned Cloudflare resources.");
+    await appendPhase(phases, "hosting_registration", "completed", "Provisioned Cloudflare resources.", reportPhase);
     const launchConfig = loadCliDeployConfig(workingRoot);
     const managedRuntime = launchConfig.runtime?.mode === "treeseed_managed";
     let services = [];
@@ -711,7 +808,7 @@ async function executeKnowledgeCoopManagedLaunch(input) {
     let schedules = [];
     let railwayVerification = [];
     if (managedRuntime) {
-      appendPhase(phases, "runtime_connection", "running", "Deploying Railway services and registering runtime connectivity.");
+      await appendPhase(phases, "runtime_connection", "running", "Deploying Railway services and registering runtime connectivity.", reportPhase);
       const railwayEnv = { ...process.env, ...prodEnvOverlay };
       validateRailwayDeployPrerequisites(workingRoot, "prod", { env: railwayEnv });
       services = configuredRailwayServices(workingRoot, "prod");
@@ -722,9 +819,9 @@ async function executeKnowledgeCoopManagedLaunch(input) {
       schedules = await ensureRailwayScheduledJobs(workingRoot, "prod", { env: railwayEnv });
       railwayVerification = await verifyRailwayScheduledJobs(workingRoot, "prod", { env: railwayEnv });
       finalizeDeploymentState(workingRoot, { scope: "prod", serviceResults: deployments });
-      appendPhase(phases, "runtime_connection", "completed", "Deployed Railway services and recorded runtime readiness.");
+      await appendPhase(phases, "runtime_connection", "completed", "Deployed Railway services and recorded runtime readiness.", reportPhase);
     } else {
-      appendPhase(phases, "runtime_connection", "completed", "Skipped managed runtime deployment for hub-only or BYO runtime launch.");
+      await appendPhase(phases, "runtime_connection", "completed", "Skipped managed runtime deployment for hub-only or BYO runtime launch.", reportPhase);
     }
     const defaultWorkstream = createDefaultWorkstream(input.projectId, input, seed);
     const projectMetadata = loadProjectMetadata(
@@ -736,7 +833,8 @@ async function executeKnowledgeCoopManagedLaunch(input) {
       managedDefaults.projectApiBaseUrl,
       { slug: repository.slug, url: repository.url }
     );
-    const templatePackage = buildKnowledgeCoopTemplatePackage(workingRoot, {
+    const packageRoot = packageSourceRoot ?? workingRoot;
+    const templatePackage = buildKnowledgeCoopTemplatePackage(packageRoot, {
       projectSlug: input.projectSlug,
       title: `${input.projectName} template`,
       summary: input.summary ?? null,
@@ -749,7 +847,7 @@ async function executeKnowledgeCoopManagedLaunch(input) {
         }
       }
     });
-    const knowledgePackPackage = buildKnowledgeCoopKnowledgePackPackage(workingRoot, {
+    const knowledgePackPackage = buildKnowledgeCoopKnowledgePackPackage(packageRoot, {
       projectSlug: input.projectSlug,
       title: `${input.projectName} knowledge pack`,
       summary: input.summary ?? null,
@@ -769,10 +867,12 @@ async function executeKnowledgeCoopManagedLaunch(input) {
         owner: repository.owner,
         name: repository.name,
         url: repository.url,
-        defaultBranch: initResult.defaultBranch,
-        stagingBranch: initResult.stagingBranch,
+        defaultBranch: input.existingRepository?.defaultBranch ?? initResult.defaultBranch,
+        stagingBranch: input.existingRepository?.stagingBranch ?? initResult.stagingBranch,
         visibility: repository.visibility
       },
+      contentRepository,
+      contentRepositoryWorkingRoot,
       workflows: workflowSummary,
       cloudflare: {
         staging,
@@ -795,16 +895,19 @@ async function executeKnowledgeCoopManagedLaunch(input) {
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    const phase = error instanceof KnowledgeCoopLaunchError ? error.phase : phases.some((entry) => entry.phase === "runtime_connection" && entry.status === "running") ? "runtime_connection_failed" : phases.some((entry) => entry.phase === "hosting_registration" && entry.status === "running") ? "hosting_registration_failed" : phases.some((entry) => entry.phase === "workflow_bootstrap" && entry.status === "running") ? "workflow_bootstrap_failed" : phases.some((entry) => entry.phase === "content_bootstrap" && entry.status === "running") ? "content_bootstrap_failed" : "repo_provision_failed";
-    appendPhase(phases, phase.replace(/_failed$/u, ""), "failed", message);
-    throw new KnowledgeCoopLaunchError(phase, message, phases);
+    const phase = error instanceof KnowledgeHubProviderLaunchError ? error.phase : phases.some((entry) => entry.phase === "runtime_connection" && entry.status === "running") ? "runtime_connection_failed" : phases.some((entry) => entry.phase === "hosting_registration" && entry.status === "running") ? "hosting_registration_failed" : phases.some((entry) => entry.phase === "workflow_bootstrap" && entry.status === "running") ? "workflow_bootstrap_failed" : phases.some((entry) => entry.phase === "content_bootstrap" && entry.status === "running") ? "content_bootstrap_failed" : "repo_provision_failed";
+    await appendPhase(phases, phase.replace(/_failed$/u, ""), "failed", message, reportPhase);
+    throw new KnowledgeHubProviderLaunchError(phase, message, phases);
   } finally {
     if (input.preserveWorkingTree === false) {
       rmSync(workingRoot, { recursive: true, force: true });
     }
+    if (packageSourceRoot && packageSourceRoot !== workingRoot && input.preserveWorkingTree === false) {
+      rmSync(packageSourceRoot, { recursive: true, force: true });
+    }
   }
 }
 export {
-  executeKnowledgeCoopManagedLaunch,
-  validateKnowledgeCoopManagedLaunchPrerequisites
+  executeKnowledgeHubProviderLaunch,
+  validateKnowledgeHubProviderLaunchPrerequisites
 };

package/dist/operations/services/project-platform.js

@@ -1230,7 +1230,11 @@ async function monitorProjectPlatform(options) {
     r2: options.dryRun ? { ok: true, skipped: true, reason: "dry_run" } : probeR2(options.tenantRoot, siteConfig, state, target),
     queue: options.dryRun ? Promise.resolve({ ok: true, skipped: true, reason: "dry_run" }) : probeQueue(siteConfig, state),
     scaleProbe: probeScaleConfiguration(siteConfig, state),
-    railwayResources: options.scope === "local" || !apiSelected && !agentsSelected ? Promise.resolve({ ok: true, skipped: true, reason: options.scope === "local" ? "local_scope" : "railway_not_selected" }) : verifyRailwayManagedResources(options.tenantRoot, options.scope, { env, settleDeployments: true }),
+    railwayResources: options.scope === "local" || !apiSelected && !agentsSelected ? Promise.resolve({ ok: true, skipped: true, reason: options.scope === "local" ? "local_scope" : "railway_not_selected" }) : verifyRailwayManagedResources(options.tenantRoot, options.scope, {
+      env,
+      settleDeployments: true,
+      onProgress: options.write
+    }),
     readiness: state.readiness
   };
   const resolvedChecks = {

package/dist/operations/services/railway-deploy.d.ts

@@ -13,7 +13,7 @@ export declare function runRailway(args: any, { cwd, capture, allowFailure, inpu
     capture?: boolean | undefined;
     allowFailure?: boolean | undefined;
 }): import("child_process").SpawnSyncReturns<string>;
-export declare function waitForRailwayManagedDeploymentsSettled(tenantRoot: any, scope: any, { services, env, timeoutMs, pollMs, }?: {
+export declare function waitForRailwayManagedDeploymentsSettled(tenantRoot: any, scope: any, { services, env, timeoutMs, pollMs, onProgress, }?: {
     services?: ({
         key: string;
         scope: string;
@@ -319,7 +319,7 @@ export declare function verifyRailwayScheduledJobs(tenantRoot: any, scope: any,
     unsupported?: undefined;
     message?: undefined;
 }>;
-export declare function verifyRailwayManagedResources(tenantRoot: any, scope: any, { fetchImpl, apiToken, apiUrl, env, settleDeployments, settleTimeoutMs, settlePollMs, }?: {
+export declare function verifyRailwayManagedResources(tenantRoot: any, scope: any, { fetchImpl, apiToken, apiUrl, env, settleDeployments, settleTimeoutMs, settlePollMs, onProgress, }?: {
     fetchImpl?: typeof fetch | undefined;
     env?: NodeJS.ProcessEnv | undefined;
     settleDeployments?: boolean | undefined;

package/dist/operations/services/railway-deploy.js

@@ -112,6 +112,21 @@ function railwayStatusDeploymentSettled(status) {
   const normalized = String(status ?? "").trim().toUpperCase();
   return normalized === "SUCCESS" || normalized === "SLEEPING";
 }
+function formatRailwayDeploymentStatusSummary(scope, checks) {
+  const aliases = {
+    api: "api",
+    workdayManager: "manager",
+    workerRunner: "runner"
+  };
+  const parts = checks.map((check) => {
+    const name = aliases[check.service] ?? String(check.serviceName ?? check.service ?? "service");
+    const status = String(check.status ?? "unknown").toUpperCase();
+    const instanceStatuses = Array.isArray(check.observed?.instanceStatuses) && check.observed.instanceStatuses.length > 0 ? `/${check.observed.instanceStatuses.join("+")}` : "";
+    const stopped = check.observed?.deploymentStopped === true ? "/stopped" : "";
+    return `${name}=${status}${instanceStatuses}${stopped}`;
+  });
+  return `[railway][monitor][${scope}] ${parts.join(" ")}`;
+}
 function collectRailwayDeploymentStatusChecks(statusPayload, scope, services) {
   const expectedEnvironment = resolveRailwayEnvironmentForScope(scope);
   const environments = railwayStatusEnvironmentNodes(statusPayload);
@@ -394,7 +409,8 @@ async function waitForRailwayManagedDeploymentsSettled(tenantRoot, scope, {
   services = configuredRailwayServices(tenantRoot, scope),
   env = process.env,
   timeoutMs = 6e5,
-  pollMs = 15e3
+  pollMs = 15e3,
+  onProgress
 } = {}) {
   const deadline = Date.now() + timeoutMs;
   const projectId = services.find((service) => typeof service.projectId === "string" && service.projectId.trim())?.projectId ?? null;
@@ -414,6 +430,7 @@ async function waitForRailwayManagedDeploymentsSettled(tenantRoot, scope, {
   }
   let checks = [];
   let lastError = null;
+  let lastSummary = "";
   for (; ; ) {
     lastError = null;
     try {
@@ -434,6 +451,11 @@ async function waitForRailwayManagedDeploymentsSettled(tenantRoot, scope, {
         message: error instanceof Error ? error.message : String(error)
       }));
     }
+    const summary = formatRailwayDeploymentStatusSummary(scope, checks);
+    if (summary !== lastSummary || !checks.every((entry) => entry.ok === true)) {
+      onProgress?.(summary, "stdout");
+      lastSummary = summary;
+    }
     if (checks.every((entry) => entry.ok === true)) {
       return { ok: true, checks };
     }
@@ -1017,7 +1039,8 @@ async function verifyRailwayManagedResources(tenantRoot, scope, {
   env = process.env,
   settleDeployments = false,
   settleTimeoutMs = 6e5,
-  settlePollMs = 15e3
+  settlePollMs = 15e3,
+  onProgress
 } = {}) {
   const effectiveApiToken = apiToken || resolveRailwayAuthToken(env);
   const effectiveApiUrl = apiUrl || resolveRailwayApiUrl(env);
@@ -1129,7 +1152,8 @@ async function verifyRailwayManagedResources(tenantRoot, scope, {
       services: deploymentStatusServices.length > 0 ? deploymentStatusServices : services,
       env: effectiveEnv,
       timeoutMs: settleTimeoutMs,
-      pollMs: settlePollMs
+      pollMs: settlePollMs,
+      onProgress
     });
     for (const check of settled.checks ?? []) {
       checks.push(check);

package/dist/operations-registry.js

@@ -33,6 +33,21 @@ const TRESEED_OPERATION_SPECS = [
   operation({ id: "template.sync", name: "sync", aliases: [], group: "Validation", summary: "Validate or reconcile the managed template surface for the current site.", description: "Use remote template metadata plus the local scaffold artifact to check or apply updates to the managed scaffold surface.", provider: "default", related: ["template", "init", "status"] }),
   operation({ id: "project.init", name: "init", aliases: [], group: "Workflow", summary: "Scaffold a new Treeseed tenant project.", description: "Create a new Treeseed tenant directory from a remote-catalog template backed by the packaged scaffold artifact.", provider: "default", related: ["config", "switch", "dev"] }),
   operation({ id: "project.config", name: "config", aliases: [], group: "Workflow", summary: "Configure and test the runtime foundation.", description: "Apply safe repairs, collect environment values, write local machine config, initialize environments, sync providers, and run doctor-style checks.", provider: "default", related: ["status", "switch", "dev"] }),
+  operation({ id: "hub.planLaunch", name: "hub.plan_launch", aliases: [], group: "Workflow", summary: "Plan an online Knowledge Hub launch.", description: "Normalize a Knowledge Hub launch intent, resolve repository topology, and return the durable launch plan shared by CLI and Market.", provider: "default", related: ["hub.validate_launch", "hub.execute_launch"] }),
+  operation({ id: "hub.validateLaunch", name: "hub.validate_launch", aliases: [], group: "Validation", summary: "Validate an online Knowledge Hub launch intent.", description: "Validate the shared Knowledge Hub launch intent and repository plan before execution.", provider: "default", related: ["hub.plan_launch", "hub.execute_launch"] }),
+  operation({ id: "hub.executeLaunch", name: "hub.execute_launch", aliases: [], group: "Workflow", summary: "Execute an online Knowledge Hub launch.", description: "Execute a Knowledge Hub launch through the shared SDK launch contract.", provider: "default", related: ["hub.plan_launch", "hub.resume_launch"] }),
+  operation({ id: "hub.resumeLaunch", name: "hub.resume_launch", aliases: [], group: "Workflow", summary: "Resume an online Knowledge Hub launch.", description: "Resume a previously planned Knowledge Hub launch from durable launch state.", provider: "default", related: ["hub.execute_launch"] }),
+  operation({ id: "hub.planUpdate", name: "hub.plan_update", aliases: [], group: "Workflow", summary: "Plan a Knowledge Hub update.", description: "Create a preview plan for template, knowledge pack, runtime, capability, or repository-topology updates.", provider: "default", related: ["hub.validate_update", "hub.execute_update"] }),
+  operation({ id: "hub.validateUpdate", name: "hub.validate_update", aliases: [], group: "Validation", summary: "Validate a Knowledge Hub update plan.", description: "Validate a planned update before it becomes binding work.", provider: "default", related: ["hub.plan_update"] }),
+  operation({ id: "hub.executeUpdate", name: "hub.execute_update", aliases: [], group: "Workflow", summary: "Execute a Knowledge Hub update.", description: "Apply a capability-gated Knowledge Hub update after required review or Decision approval.", provider: "default", related: ["hub.plan_update", "hub.resume_update"] }),
+  operation({ id: "hub.resumeUpdate", name: "hub.resume_update", aliases: [], group: "Workflow", summary: "Resume a Knowledge Hub update.", description: "Resume a previously planned Knowledge Hub update from durable state.", provider: "default", related: ["hub.execute_update"] }),
+  operation({ id: "repositoryHost.validate", name: "repository_host.validate", aliases: [], group: "Validation", summary: "Validate Repository Host configuration.", description: "Validate a GitHub Repository Host for Knowledge Hub repository provisioning.", provider: "default", related: ["repository_host.create_repositories"] }),
+  operation({ id: "repositoryHost.createRepositories", name: "repository_host.create_repositories", aliases: [], group: "Workflow", summary: "Create or connect Knowledge Hub repositories.", description: "Create or connect the software and content repositories for a Knowledge Hub repository plan.", provider: "default", related: ["hub.plan_launch"] }),
+  operation({ id: "content.verifyPackage", name: "content.verify_package", aliases: [], group: "Validation", summary: "Verify a content package before publishing.", description: "Verify Knowledge Hub content package metadata before publishing content artifacts.", provider: "default", related: ["content.publish"] }),
+  operation({ id: "content.publish", name: "content.publish", aliases: [], group: "Workflow", summary: "Publish Knowledge Hub content artifacts.", description: "Publish verified Knowledge Hub content artifacts to the configured content target.", provider: "default", related: ["content.verify_package"] }),
+  operation({ id: "workspace.planAttachParent", name: "workspace.plan_attach_parent", aliases: [], group: "Workflow", summary: "Plan parent workspace attachment.", description: "Plan how a Knowledge Hub software/content repository pair attaches to a parent repository workspace.", provider: "default", related: ["workspace.attach_parent"] }),
+  operation({ id: "workspace.attachParent", name: "workspace.attach_parent", aliases: [], group: "Workflow", summary: "Attach a parent workspace.", description: "Attach a parent repository workspace after technical steward approval.", provider: "default", related: ["workspace.plan_attach_parent", "workspace.update_submodule_pointers"] }),
+  operation({ id: "workspace.updateSubmodulePointers", name: "workspace.update_submodule_pointers", aliases: [], group: "Workflow", summary: "Update workspace submodule pointers.", description: "Update parent workspace submodule pointers for software and content repositories.", provider: "default", related: ["workspace.attach_parent"] }),
   operation({ id: "project.export", name: "export", aliases: [], group: "Utilities", summary: "Export a Markdown snapshot of the current codebase.", description: "Generate a Markdown codebase snapshot for the selected directory using the SDK-owned repomix integration and store it under .treeseed/exports.", provider: "default", related: ["status", "config"] }),
   operation({ id: "deploy.release", name: "release", aliases: [], group: "Workflow", summary: "Release changed packages and market from staging to production.", description: "Select changed packages plus dependents, validate publish workflows, release packages first, then promote market from staging to main with aligned package pointers.", provider: "default", related: ["stage", "status", "rollback"] }),
   operation({ id: "deploy.destroy", name: "destroy", aliases: [], group: "Workflow", summary: "Destroy a persistent environment and its local state.", description: "Delete the selected persistent environment resources and remove the local deploy state after confirmation.", provider: "default", related: ["config", "status"] }),

package/dist/operations-types.d.ts

@@ -44,6 +44,7 @@ export type TreeseedOperationContext = {
     cwd: string;
     env: NodeJS.ProcessEnv;
     write?: TreeseedOperationWriter;
+    onProgress?: (event: Record<string, unknown>) => void | Promise<void>;
     spawn?: TreeseedOperationSpawn;
     outputFormat?: 'human' | 'json';
     prompt?: TreeseedOperationPrompt;

package/dist/operations.d.ts

@@ -1,6 +1,8 @@
 export { TRESEED_OPERATION_SPECS, findTreeseedOperation, listTreeseedOperationNames, } from './operations-registry.ts';
 export { collectTreeseedConfigSeedValues } from './operations/services/config-runtime.ts';
+export { createKnowledgeHubRepositories, defaultHubContentResolutionPolicy, executeKnowledgeHubLaunch, normalizeKnowledgeHubLaunchIntent, planKnowledgeHubLaunch, planKnowledgeHubRepositories, validateRepositoryHost, } from './operations/services/hub-launch.ts';
 export { TreeseedOperationsSdk } from './operations/runtime.ts';
+export type { HubContentResolutionPolicy, KnowledgeHubLaunchIntent, KnowledgeHubLaunchPhase, KnowledgeHubLaunchPlan, KnowledgeHubLaunchResult, KnowledgeHubRepositoryPlan, RepositoryHost, } from './operations/services/hub-launch.ts';
 export type { TreeseedOperationContext, TreeseedOperationImplementation, TreeseedOperationId, TreeseedOperationMetadata, TreeseedOperationProvider, TreeseedOperationProviderId, TreeseedOperationRequest, TreeseedOperationResult, TreeseedOperationGroup, } from './operations-types.ts';
 export { TreeseedOperationError } from './operations-types.ts';
 export { TreeseedWorkflowSdk } from './workflow.ts';

package/dist/operations.js

@@ -4,6 +4,15 @@ import {
   listTreeseedOperationNames
 } from "./operations-registry.js";
 import { collectTreeseedConfigSeedValues } from "./operations/services/config-runtime.js";
+import {
+  createKnowledgeHubRepositories,
+  defaultHubContentResolutionPolicy,
+  executeKnowledgeHubLaunch,
+  normalizeKnowledgeHubLaunchIntent,
+  planKnowledgeHubLaunch,
+  planKnowledgeHubRepositories,
+  validateRepositoryHost
+} from "./operations/services/hub-launch.js";
 import { TreeseedOperationsSdk } from "./operations/runtime.js";
 import { TreeseedOperationError } from "./operations-types.js";
 import { TreeseedWorkflowSdk } from "./workflow.js";
@@ -13,6 +22,13 @@ export {
   TreeseedOperationsSdk,
   TreeseedWorkflowSdk,
   collectTreeseedConfigSeedValues,
+  createKnowledgeHubRepositories,
+  defaultHubContentResolutionPolicy,
+  executeKnowledgeHubLaunch,
   findTreeseedOperation,
-  listTreeseedOperationNames
+  listTreeseedOperationNames,
+  normalizeKnowledgeHubLaunchIntent,
+  planKnowledgeHubLaunch,
+  planKnowledgeHubRepositories,
+  validateRepositoryHost
 };

package/dist/remote.d.ts

@@ -230,4 +230,15 @@ export declare class RemoteTreeseedRunnerClient {
         ok: true;
         payload: RemoteJob;
     }>;
+    consumeCredentialSession(jobId: string, sessionId: string): Promise<{
+        ok: true;
+        payload: {
+            id: string;
+            hostKind: string;
+            hostId: string;
+            purpose: string;
+            provider?: string | null;
+            config: Record<string, string>;
+        };
+    }>;
 }

package/dist/remote.js

@@ -262,6 +262,12 @@ class RemoteTreeseedRunnerClient {
       requireAuth: true
     });
   }
+  consumeCredentialSession(jobId, sessionId) {
+    return this.client.requestJson(`/v1/jobs/${encodeURIComponent(jobId)}/provider-credential-sessions/${encodeURIComponent(sessionId)}/consume`, {
+      method: "POST",
+      requireAuth: true
+    });
+  }
 }
 export {
   CloudflareQueuePullClient,