@secondlayer/cli 12.2.0 → 13.0.1

package/dist/cli.js

@@ -2481,25 +2481,6 @@ var require_commander = __commonJS((exports) => {
   exports.InvalidOptionArgumentError = InvalidArgumentError;
 });
 
-// ../../node_modules/commander/esm.mjs
-var import__, program, createCommand, createArgument, createOption, CommanderError, InvalidArgumentError, InvalidOptionArgumentError, Command, Argument, Option, Help;
-var init_esm = __esm(() => {
-  import__ = __toESM(require_commander(), 1);
-  ({
-    program,
-    createCommand,
-    createArgument,
-    createOption,
-    CommanderError,
-    InvalidArgumentError,
-    InvalidOptionArgumentError,
-    Command,
-    Argument,
-    Option,
-    Help
-  } = import__.default);
-});
-
 // src/lib/session.ts
 import {
   chmod,
@@ -2550,11 +2531,12 @@ var init_session = __esm(() => {
 });
 
 // src/lib/resolve-auth.ts
+import { resolveApiKey } from "@secondlayer/sdk";
 function resolveApiUrl() {
   return (process.env.SL_API_URL ?? process.env.SL_PLATFORM_API_URL ?? LOCAL_API_URL).replace(/\/+$/, "");
 }
 function resolveEnvKey() {
-  return process.env.SL_API_KEY;
+  return resolveApiKey();
 }
 async function resolveAuth() {
   const apiUrl = resolveApiUrl();
@@ -2619,7 +2601,7 @@ async function httpPlatform(path2, opts = {}) {
   try {
     auth = await resolveAuth();
   } catch {
-    throw new CliHttpError(401, "SESSION_EXPIRED", { error: "Not logged in" }, isOssMode() ? "Not authenticated — set SL_API_KEY from `secondlayer init`" : "Not logged in — run `secondlayer login`");
+    throw new CliHttpError(401, "SESSION_EXPIRED", { error: "Not logged in" }, isOssMode() ? "Not authenticated — set INSTANCE_TOKEN from `secondlayer init`" : "Not logged in — run `secondlayer login`");
   }
   return request(`${auth.apiUrl}${path2}`, {
     ...opts,
@@ -2725,6 +2707,24 @@ function output(opts) {
   }
   opts.human();
 }
+function wrapText(text, width = 76) {
+  const words = text.split(/\s+/).filter(Boolean);
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    if (line.length === 0)
+      line = word;
+    else if (line.length + 1 + word.length <= width)
+      line += ` ${word}`;
+    else {
+      lines.push(line);
+      line = word;
+    }
+  }
+  if (line.length > 0)
+    lines.push(line);
+  return lines;
+}
 function stripAnsi(text) {
   return text.replace(ANSI_ESCAPE_PATTERN, "");
 }
@@ -28309,7 +28309,7 @@ function handleApiError(err, action2) {
   const status = err instanceof ApiError || err instanceof CliHttpError ? err.status : undefined;
   if (err instanceof CliHttpError && err.code === "SESSION_EXPIRED" || status === 401) {
     printError("Authentication required.", {
-      hint: isOssMode() ? "Set SL_API_KEY / INSTANCE_TOKEN from `secondlayer init`." : "Run `secondlayer login` to re-authenticate."
+      hint: isOssMode() ? "Set INSTANCE_TOKEN from `secondlayer init` (SL_API_KEY is a legacy alias)." : "Run `secondlayer login` to re-authenticate."
     });
     process.exit(1);
   }
@@ -28317,6 +28317,19 @@ function handleApiError(err, action2) {
   printError(`Failed to ${action2}: ${detail}`, { hint: nextStepHint(status) });
   process.exit(1);
 }
+function withErrorHandling(fn, options3) {
+  return async (...args) => {
+    try {
+      await fn(...args);
+    } catch (err) {
+      if (options3?.onError) {
+        options3.onError(err);
+      } else {
+        handleApiError(err, options3?.action ?? "execute command");
+      }
+    }
+  };
+}
 async function getPlatformClient() {
   const { apiUrl, ephemeralKey } = await resolveAuth();
   return new SecondLayer({ baseUrl: apiUrl, apiKey: ephemeralKey });
@@ -28325,7 +28338,7 @@ async function listSubgraphsApi() {
   return (await getPlatformClient()).subgraphs.list();
 }
 async function getSubgraphApi(name) {
-  return (await getPlatformClient()).subgraphs.get(name);
+  return (await getPlatformClient()).subgraphs.status(name);
 }
 async function getSubgraphOpenApi(name, options3) {
   return (await getPlatformClient()).subgraphs.openapi(name, options3);
@@ -28360,6 +28373,15 @@ async function querySubgraphTableCount(name, table, params = {}) {
 async function getSubgraphGaps(name, opts) {
   return (await getPlatformClient()).subgraphs.gaps(name, opts);
 }
+async function listSubgraphOperationsApi(name) {
+  return (await getPlatformClient()).subgraphs.operations(name);
+}
+async function getSubgraphOperationApi(name, operationId) {
+  return (await getPlatformClient()).subgraphs.getOperation(name, operationId);
+}
+async function getSubgraphSourceApi(name) {
+  return (await getPlatformClient()).subgraphs.getSource(name);
+}
 async function getContractPrintSchema(contractId) {
   let client;
   try {
@@ -28761,6 +28783,7 @@ async function runTokenLogin() {
     error('No token on stdin. Usage: echo "$KEY" | secondlayer login --with-token');
     process.exit(1);
   }
+  process.env.INSTANCE_TOKEN = token;
   process.env.SL_API_KEY = token;
   let account;
   try {
@@ -28852,7 +28875,7 @@ function registerLoginCommand(program2) {
   program2.command("login", { hidden: true }).description("Log in to Secondlayer (magic-link email)").option("--force", "Skip the already-logged-in check and re-run the flow").option("--with-token", "Read an API key from stdin (non-interactive)").addHelpText("after", `
 Examples:
   $ secondlayer login
-  $ echo "$SL_API_KEY" | secondlayer login --with-token`).action((opts) => opts.withToken ? runTokenLogin() : runLoginFlow({ force: opts.force }));
+  $ echo "$INSTANCE_TOKEN" | secondlayer login --with-token`).action((opts) => opts.withToken ? runTokenLogin() : runLoginFlow({ force: opts.force }));
 }
 var init_login = __esm(() => {
   init_http();
@@ -28959,13 +28982,14 @@ var exports_subgraph_test = {};
 __export(exports_subgraph_test, {
   runSubgraphTest: () => runSubgraphTest,
   loadCassette: () => loadCassette,
+  indexReadFailure: () => indexReadFailure,
   filterHashOf: () => filterHashOf,
   DECODER_VERSION: () => DECODER_VERSION
 });
 import { createHash } from "node:crypto";
 import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname as dirname4, resolve as resolve2 } from "node:path";
-import { Index } from "@secondlayer/sdk";
+import { Index, resolveApiKey as resolveApiKey2, resolveBaseUrl } from "@secondlayer/sdk";
 import {
   DECODED_EVENT_TYPES
 } from "@secondlayer/stacks/filters";
@@ -29001,6 +29025,53 @@ function eventTypeFor(filter) {
   const candidate = filter.type === "print_event" ? "print" : filter.type;
   return DECODED_EVENT_TYPES.includes(candidate) ? candidate : null;
 }
+function indexApiUrl() {
+  return resolveBaseUrl();
+}
+function indexReadFailure(err, ctx) {
+  const e2 = err;
+  const status = typeof e2?.status === "number" ? e2.status : undefined;
+  const range = `blocks ${ctx.fromHeight}–${ctx.toHeight}`;
+  const where = `reading source "${ctx.source}" (${range}) from ${ctx.apiUrl}`;
+  const offlineHint = `Replay a recorded cassette instead of reading: secondlayer subgraphs test ${ctx.file} --offline`;
+  if (status === 402) {
+    const details = e2.body?.details;
+    return {
+      message: `Blocks ${ctx.fromHeight}–${ctx.toHeight} are below the free read window.`,
+      hint: details?.oldest_seekable_height ? `Try --from ${details.oldest_seekable_height}, or add a paid API key (INSTANCE_TOKEN) to test against older history.` : "Add a paid API key (INSTANCE_TOKEN) to test against older history."
+    };
+  }
+  if (status === 401 || status === 403) {
+    const credential = resolveApiKey2() ? "INSTANCE_TOKEN is set in this shell" : "no INSTANCE_TOKEN is set in this shell";
+    return {
+      message: `Index read rejected (HTTP ${status}) while ${where}.`,
+      hint: `${credential}. This read uses the same SL_API_URL + INSTANCE_TOKEN pair as \`secondlayer subgraphs deploy\` — confirm both point at the instance you deployed to (\`secondlayer status\`), then retry. ${offlineHint}`
+    };
+  }
+  if (status === 404) {
+    return {
+      message: `Index read returned 404 while ${where}.`,
+      hint: `${ctx.apiUrl} answered but serves no /v1/index/events — check SL_API_URL points at a Secondlayer instance, not a Stacks node.`
+    };
+  }
+  if (status === 429) {
+    return {
+      message: `Rate limited while ${where}.`,
+      hint: `Wait a moment and retry, or narrow the range with --to. ${offlineHint}`
+    };
+  }
+  if (status !== undefined && status >= 500) {
+    return {
+      message: `Index read failed with HTTP ${status} while ${where}.`,
+      hint: `The instance is reachable but erroring — check it with \`secondlayer status\`, then retry. ${offlineHint}`
+    };
+  }
+  const detail = err instanceof Error ? err.message : String(err);
+  return {
+    message: `Index read failed while ${where}: ${detail}`,
+    hint: `Confirm the instance is up and reachable: secondlayer status. ${offlineHint}`
+  };
+}
 async function runSubgraphTest(file, options3) {
   const absPath = resolve2(file);
   if (!existsSync2(absPath)) {
@@ -29070,13 +29141,15 @@ async function runSubgraphTest(file, options3) {
         });
         events[name] = envelope.events;
       } catch (err) {
-        const e2 = err;
-        if (e2?.status === 402) {
-          const details = e2.body?.details;
-          error(`Blocks ${fromHeight}–${toHeight} are below the free read window.${details?.oldest_seekable_height ? ` Try --from ${details.oldest_seekable_height}, or add a paid API key (SL_API_KEY) to test against older history.` : " Add a paid API key (SL_API_KEY) to test against older history."}`);
-          process.exit(1);
-        }
-        throw err;
+        const failure = indexReadFailure(err, {
+          source: name,
+          fromHeight,
+          toHeight,
+          apiUrl: indexApiUrl(),
+          file
+        });
+        printError(failure.message, { hint: failure.hint });
+        process.exit(1);
       }
     }
     if (options3.record !== false) {
@@ -29183,11 +29256,13 @@ __export(exports_subgraphs, {
   runSubgraphClientCodegen: () => runSubgraphClientCodegen,
   runPayloadsCodegen: () => runPayloadsCodegen,
   registerSubgraphsCommand: () => registerSubgraphsCommand,
-  parseVisibilityOption: () => parseVisibilityOption,
   parseSubgraphSpecFormat: () => parseSubgraphSpecFormat,
   parseStartBlockOption: () => parseStartBlockOption,
   ormFlagsConflictingWithPayloads: () => ormFlagsConflictingWithPayloads,
+  operationDetailPairs: () => operationDetailPairs,
   installScaffoldDependencies: () => installScaffoldDependencies,
+  formatOperationRange: () => formatOperationRange,
+  formatOperationProgress: () => formatOperationProgress,
   ensureScaffoldPackageJson: () => ensureScaffoldPackageJson,
   createSubgraphDeployPreview: () => createSubgraphDeployPreview,
   collectPinnedPrintSources: () => collectPinnedPrintSources
@@ -29259,13 +29334,6 @@ function parseStartBlockOption(value) {
   }
   return parsed;
 }
-function parseVisibilityOption(value) {
-  if (value === undefined)
-    return;
-  if (value === "public" || value === "private")
-    return value;
-  throw new Error('--visibility must be "public" or "private"');
-}
 function collectPinnedPrintSources(sources) {
   const out = [];
   for (const [sourceName, raw] of Object.entries(sources ?? {})) {
@@ -29559,6 +29627,40 @@ ${dim("Columns")}`);
   const deployTarget = context.bundled ? "tenant API" : "local database";
   info(`Dry run only. No ${deployTarget} changes were made.`);
 }
+function formatOperationRange(op) {
+  if (op.fromBlock === null && op.toBlock === null)
+    return "whole subgraph";
+  return `${op.fromBlock ?? "start"} → ${op.toBlock ?? "tip"}`;
+}
+function formatOperationProgress(progress) {
+  if (progress === null)
+    return "—";
+  return `${(progress * 100).toFixed(1)}%`;
+}
+function colorOperationStatus(status) {
+  if (status === "completed")
+    return green(status);
+  if (status === "failed")
+    return red(status);
+  if (status === "cancelled")
+    return yellow(status);
+  return status;
+}
+function operationDetailPairs(op) {
+  return [
+    ["ID", op.id],
+    ["Subgraph", op.subgraphName],
+    ["Kind", op.kind],
+    ["Status", op.status],
+    ["Range", formatOperationRange(op)],
+    ["Progress", formatOperationProgress(op.progress)],
+    ["Processed Blocks", op.processedBlocks?.toLocaleString() ?? "—"],
+    ["Error", op.error ?? "none"],
+    ["Created", op.createdAt],
+    ["Started", op.startedAt ?? "—"],
+    ["Finished", op.finishedAt ?? "—"]
+  ];
+}
 function formatDuration(seconds2) {
   if (seconds2 < 90)
     return `${Math.max(1, Math.round(seconds2))}s`;
@@ -29614,7 +29716,16 @@ function formatSubgraphSync(sync) {
 }
 function registerSubgraphsCommand(program2) {
   const subgraphs = program2.command("subgraphs").description("Manage materialized subgraphs");
-  subgraphs.command("create <name>").description("Create a new subgraph definition file").option("--from-contract <contractId>", "Generate sources/schema/handlers from the contract's observed print events (requires network)").option("--table-per-topic", "With --from-contract: one table per print topic instead of a single wide table").addHelpText("after", `
+  subgraphs.command("create <name>").description("Start here: create a new subgraph definition file (see also: subgraphs scaffold)").option("--from-contract <contractId>", "Generate sources/schema/handlers from the contract's observed print events (requires network)").option("--table-per-topic", "With --from-contract: one table per print topic instead of a single wide table").addHelpText("after", `
+create is the default way to start a subgraph. It writes subgraphs/<name>.ts —
+an empty starter, or with --from-contract a schema inferred from the print
+events that contract has already emitted into your index.
+
+Use "secondlayer subgraphs scaffold" instead when you need what create cannot
+infer: typed contract_call tables generated from a contract's ABI (read from a
+Stacks node, so it works before your index holds that contract's history), or a
+trait-wide source with --trait sip-010.
+
 Examples:
   $ secondlayer subgraphs create my-graph
   $ secondlayer subgraphs create sbtc-flows --from-contract SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-registry
@@ -29724,7 +29835,10 @@ Stopped watching.`);
     });
     await new Promise(() => {});
   });
-  subgraphs.command("deploy <file>").alias("update").description("Deploy a subgraph definition file (alias: update — deploy is create-or-update)").option("--start-block <n>", "Override the subgraph definition startBlock for this deploy").option("--tip-first", "Go live at chain tip immediately; history backfills in the background (requires order-tolerant handlers — commutative or insert-only writes)").option("--dry-run", "Validate and preview deploy without writing changes").option("-y, --yes", "Skip the reindex confirmation prompt").option("--strict", "Run `tsc --noEmit` against the handler before deploy (slower; catches TS type errors)").addOption(new Option("--visibility <visibility>", "Hosted only. Public/private namespace.").hideHelp()).option("--allow-uncommitted", "Deploy even though the source file is not committed to git (the deployed definition will exist only in the database)").action(async (file, options3) => {
+  subgraphs.command("deploy <file>").alias("update").description("Deploy a subgraph definition file (alias: update — deploy is create-or-update)").option("--start-block <n>", "Override the subgraph definition startBlock for this deploy").option("--tip-first", "Go live at chain tip immediately; history backfills in the background (requires order-tolerant handlers — commutative or insert-only writes)").option("--dry-run", "Validate and preview deploy without writing changes").option("-y, --yes", "Skip the reindex confirmation prompt").option("--strict", "Run `tsc --noEmit` against the handler before deploy (slower; catches TS type errors)").option("--allow-uncommitted", "Deploy even though the source file is not committed to git (the deployed definition will exist only in the database)").addHelpText("after", `
+By default the source file must be committed to git — otherwise the
+deployed definition's only copy is the row in the database. Pass
+--allow-uncommitted to deploy anyway.`).action(async (file, options3) => {
     try {
       const absPath = resolve3(file);
       if (!options3.dryRun) {
@@ -29756,7 +29870,6 @@ Stopped watching.`);
         await requireAuth();
       }
       const dryRun = options3.dryRun;
-      const visibility = parseVisibilityOption(options3.visibility);
       const startBlock = parseStartBlockOption(options3.startBlock);
       if (startBlock !== undefined) {
         warn(`--start-block ${startBlock} overrides the definition's startBlock for this deploy.`);
@@ -29829,8 +29942,7 @@ Stopped watching.`);
           schema: effectiveDef.schema,
           handlerCode,
           sourceCode: source,
-          ...deployStartBlock !== undefined ? { startBlock: deployStartBlock } : {},
-          ...visibility ? { visibility } : {}
+          ...deployStartBlock !== undefined ? { startBlock: deployStartBlock } : {}
         });
         for (const w2 of result.warnings ?? [])
           warn(w2);
@@ -29838,12 +29950,8 @@ Stopped watching.`);
           try {
             const { apiUrl } = await resolveAuth();
             const firstTable = Object.keys(effectiveDef.schema ?? {})[0];
-            const isPublic = result.visibility === "public";
-            if (isPublic && firstTable) {
-              info(`  Read:      ${apiUrl}/v1/subgraphs/${effectiveDef.name}/${firstTable}`);
-              info(`  Share:     ${apiUrl}/v1/subgraphs/${effectiveDef.name} (public — no key needed)`);
-            } else if (firstTable) {
-              info(`  REST:      ${apiUrl}/api/subgraphs/${effectiveDef.name}/${firstTable}`);
+            if (firstTable) {
+              info(`  REST:      ${apiUrl}/v1/subgraphs/${effectiveDef.name}/${firstTable}`);
             }
             if (result.reindexStarted) {
               const denom = result.estimatedEvents != null ? ` ~${result.estimatedEvents.toLocaleString()} events —` : "";
@@ -30023,14 +30131,17 @@ Synced — exiting watch.`));
   subgraphs.command("spec <nameOrFile>").description("Output API documentation for a deployed subgraph or a local subgraph file").option("--format <format>", "Output format: openapi, agent, markdown", "openapi").option("-o, --output <path>", "Write output to a file").option("--server <url>", "Override the server URL in generated docs").action(async (nameOrFile, options3) => {
     try {
       const format2 = parseSubgraphSpecFormat(options3.format);
-      const specOptions = options3.server ? { serverUrl: options3.server } : undefined;
+      const specOptions = { serverUrl: options3.server ?? resolveApiUrl() };
       const absPath = resolve3(nameOrFile);
       if (nameOrFile.endsWith(".ts") && !existsSync3(absPath)) {
         error(`File not found: ${absPath}`);
         process.exit(1);
       }
       const isLocalFile = nameOrFile.endsWith(".ts");
-      const spec = isLocalFile ? await specFromLocalFile(absPath, format2, specOptions) : format2 === "openapi" ? await getSubgraphOpenApi(nameOrFile, specOptions) : format2 === "agent" ? await getSubgraphAgentSchema(nameOrFile, specOptions) : await getSubgraphMarkdown(nameOrFile, specOptions);
+      const spec = isLocalFile ? await specFromLocalFile(absPath, format2, {
+        ...specOptions,
+        forcePublicRead: true
+      }) : format2 === "openapi" ? await getSubgraphOpenApi(nameOrFile, specOptions) : format2 === "agent" ? await getSubgraphAgentSchema(nameOrFile, specOptions) : await getSubgraphMarkdown(nameOrFile, specOptions);
       await writeOrPrintSubgraphSpec(spec, format2, options3.output);
     } catch (err) {
       if (err instanceof Error && err.message.startsWith("--format")) {
@@ -30040,16 +30151,14 @@ Synced — exiting watch.`));
       handleApiError(err, "generate subgraph spec");
     }
   });
-  subgraphs.command("codegen <file>").description("Generate an ORM schema (Prisma, Drizzle, or Kysely) for a subgraph's tables — point it at your BYO database").option("--target <orm>", "ORM target: prisma | drizzle | kysely", "prisma").option("--schema <name>", "Postgres schema name (defaults to subgraph_<name>)").option("--env <var>", "datasource url env var", "DATABASE_URL").option("--models-only", "Emit only Prisma models (compose via prismaSchemaFolder)").option("--payloads", "Emit a .d.ts of print payload types for pinned print_event sources, inferred from observed on-chain events (requires network)").option("-o, --output <path>", "Write to a file (defaults to stdout)").action(async (file, options3, command) => {
-    deprecatedCodegenNotice("secondlayer subgraphs codegen", options3.payloads ? "secondlayer codegen prints" : "secondlayer codegen subgraph");
-    await runSubgraphSchemaCodegen(file, options3, (key) => command.getOptionValueSource(key));
-  });
   subgraphs.command("test <file>").description("Run a subgraph's handlers against real chain data without deploying").option("--from <height>", "Start block height (required on first run)").option("--to <height>", "End block height (defaults to --from + 100)").option("--offline", "Replay the recorded cassette; never hit the network").option("--no-record", "Don't write a cassette").option("--limit <n>", "Max events per source", "500").addHelpText("after", `
 Examples:
   $ secondlayer subgraphs test subgraphs/bns-names.ts --from 167484 --to 167600
   $ secondlayer subgraphs test subgraphs/bns-names.ts --offline`).action(async (file, options3) => {
     const { runSubgraphTest: runSubgraphTest2 } = await Promise.resolve().then(() => (init_subgraph_test(), exports_subgraph_test));
-    await runSubgraphTest2(file, options3);
+    await withErrorHandling(runSubgraphTest2, {
+      action: `test ${file}`
+    })(file, options3);
   });
   subgraphs.command("reindex <name>").description("Drop a subgraph's data and rebuild it from its start block (destructive)").option("-y, --yes", "Skip confirmation").addHelpText("after", `
 Reindex is always whole-subgraph: it drops every row and rebuilds from the
@@ -30119,7 +30228,13 @@ Examples:
       handleApiError(err, "backfill subgraph");
     }
   });
-  subgraphs.command("cancel <name>").description("Cancel a running reindex or backfill operation").action(async (name) => {
+  subgraphs.command("stop <name>").description("Stop a running reindex or backfill operation").addHelpText("after", `
+Stopping leaves the rows already written in place — it cancels the operation,
+it does not roll it back. Re-run reindex or backfill to finish the work.
+
+Examples:
+  $ secondlayer subgraphs stop my-graph
+  $ secondlayer subgraphs operations my-graph   # confirm it went to cancelled`).action(async (name) => {
     try {
       info(`Stopping operation for subgraph "${name}"...`);
       const result = await stopSubgraphApi(name);
@@ -30128,6 +30243,87 @@ Examples:
       handleApiError(err, "stop subgraph operation");
     }
   });
+  subgraphs.command("operations <name> [operationId]").description("Show a subgraph's operation history — the verify step for deploy, reindex, and backfill").option("--json", "Output as JSON").addHelpText("after", `
+Every deploy that reindexes, every reindex, and every backfill enqueues a
+tracked operation. This is where you check whether it ran, is still queued, or
+failed — and why. Pass an operation id for a single one.
+
+Examples:
+  $ secondlayer subgraphs operations my-graph
+  $ secondlayer subgraphs operations my-graph --json
+  $ secondlayer subgraphs operations my-graph 0f1c9d2e-4b7a-...`).action(async (name, operationId, options3) => {
+    try {
+      if (operationId) {
+        const op = await getSubgraphOperationApi(name, operationId);
+        output({
+          json: options3.json,
+          data: op,
+          human: () => console.log(formatKeyValue(operationDetailPairs(op)))
+        });
+        return;
+      }
+      const { operations } = await listSubgraphOperationsApi(name);
+      output({
+        json: options3.json,
+        data: { operations },
+        human: () => {
+          if (operations.length === 0) {
+            console.log(dim("No operations recorded"));
+            return;
+          }
+          console.log(formatTable(["ID", "Kind", "Status", "Range", "Progress", "Started"], operations.map((op) => [
+            op.id,
+            op.kind,
+            colorOperationStatus(op.status),
+            formatOperationRange(op),
+            formatOperationProgress(op.progress),
+            op.startedAt ? op.startedAt.replace("T", " ").slice(0, 19) : dim("—")
+          ])));
+          console.log(dim(`
+${operations.length} operation(s)`));
+          const failed = operations.filter((op) => op.error);
+          for (const op of failed) {
+            console.log(dim(`
+${op.id}: ${op.error}`));
+          }
+        }
+      });
+    } catch (err) {
+      handleApiError(err, "get subgraph operations");
+    }
+  });
+  subgraphs.command("source <name>").description("Print the source of a deployed subgraph definition").option("-o, --output <path>", "Write the source to a file").option("--json", "Output the full response as JSON").addHelpText("after", `
+Recovers the definition that is actually deployed, which is not always what is
+on disk. Subgraphs deployed before source capture return no source — redeploy
+to make them recoverable.
+
+Examples:
+  $ secondlayer subgraphs source my-graph
+  $ secondlayer subgraphs source my-graph -o subgraphs/my-graph.ts`).action(async (name, options3) => {
+    try {
+      const result = await getSubgraphSourceApi(name);
+      if (options3.json) {
+        writeData(JSON.stringify(result, null, 2));
+        return;
+      }
+      if (result.sourceCode === null) {
+        error(`No source stored for "${name}"${result.reason ? ` — ${result.reason}` : ""}`);
+        process.exit(1);
+      }
+      if (options3.output) {
+        const outPath = resolve3(options3.output);
+        const dir = resolve3(outPath, "..");
+        if (!existsSync3(dir))
+          mkdirSync2(dir, { recursive: true });
+        await writeTextFile(outPath, result.sourceCode);
+        success(`Wrote ${name} v${result.version} source to ${outPath}`);
+        return;
+      }
+      writeData(result.sourceCode);
+    } catch (err) {
+      handleApiError(err, "get subgraph source");
+    }
+  });
   subgraphs.command("gaps <name>").description("Show block gaps for a subgraph").option("--resolved", "Include resolved gaps").option("--limit <n>", "Max gaps to return", "50").option("--json", "Output as JSON").action(async (name, options3) => {
     try {
       const result = await getSubgraphGaps(name, {
@@ -30259,7 +30455,14 @@ ${rows.length} row(s)`));
       handleApiError(err, "delete subgraph");
     }
   });
-  subgraphs.command("scaffold [contractAddress]").description("Scaffold a defineSubgraph() file from a contract or trait").option("-o, --output <path>", "Output file path (required)").option("-k, --api-key <key>", "Stacks node API key for direct RPC URLs").option("--functions <names>", "Comma-separated public functions to index as typed contract_call tables").option("--trait <std>", "Scaffold a trait-scoped source (sip-009|sip-010|sip-013) — no contract needed").option("--no-install", "Skip bun install after writing package.json").addHelpText("after", `
+  subgraphs.command("scaffold [contractAddress]").description("Generate a defineSubgraph() file from a contract ABI or trait (start with: subgraphs create)").option("-o, --output <path>", "Output file path (required)").option("-k, --api-key <key>", "Stacks node API key for direct RPC URLs").option("--functions <names>", "Comma-separated public functions to index as typed contract_call tables").option("--trait <std>", "Scaffold a trait-scoped source (sip-009|sip-010|sip-013) — no contract needed").option("--no-install", "Skip bun install after writing package.json").addHelpText("after", `
+"secondlayer subgraphs create <name>" is the documented starting point. Reach
+for scaffold when you need what create cannot infer: typed contract_call tables
+from the contract's ABI, or a trait-wide source (--trait sip-010). scaffold
+reads the ABI from a Stacks node, so it does not need your index to hold that
+contract's history yet, and it writes a package.json and installs dependencies
+next to the output file.
+
 Examples:
   $ secondlayer subgraphs scaffold SP3D6PV2ACBPEKYJTCMH7HEN02KP87QSP8KTEH335.megapont-ape-club-nft -o subgraphs/apes.ts
   $ secondlayer subgraphs scaffold SP00...token --functions transfer,mint -o subgraphs/token.ts
@@ -30322,10 +30525,6 @@ Examples:
       process.exit(1);
     }
   });
-  subgraphs.command("client <subgraphName>").description("Generate a typed query client for a deployed subgraph").option("-o, --output <path>", "Output file path (required)").action(async (subgraphName, options3) => {
-    deprecatedCodegenNotice("secondlayer subgraphs client", "secondlayer codegen client");
-    await runSubgraphClientCodegen(subgraphName, options3);
-  });
 }
 async function runSubgraphClientCodegen(subgraphName, options3) {
   try {
@@ -30347,7 +30546,7 @@ async function runSubgraphClientCodegen(subgraphName, options3) {
     handleApiError(err, "generate subgraph client");
   }
 }
-async function runSubgraphSchemaCodegen(file, options3, optionSource, defaultTarget = "prisma") {
+async function runSubgraphSchemaCodegen(file, options3, optionSource, defaultTarget = "kysely") {
   if (options3.payloads) {
     const conflicts = ormFlagsConflictingWithPayloads(optionSource);
     if (conflicts.length > 0) {
@@ -30405,11 +30604,9 @@ async function runSubgraphSchemaCodegen(file, options3, optionSource, defaultTar
 }
 var ORM_ONLY_CODEGEN_FLAGS;
 var init_subgraphs2 = __esm(() => {
-  init_esm();
   init_subgraph_scaffold();
   init_subgraphs();
   init_api_client();
-  init_codegen();
   init_config2();
   init_filter_params();
   init_fs();
@@ -30447,7 +30644,7 @@ function fail(action2, err) {
   const message = err instanceof Error ? err.message : String(err);
   error(`Failed to ${action2}: ${message}`);
   if (/\b403\b/.test(message) || /forbidden/i.test(message)) {
-    note("The local API refused this read. Check INSTANCE_TOKEN / SL_API_KEY.");
+    note("The local API refused this read. Check INSTANCE_TOKEN.");
   }
   process.exit(1);
 }
@@ -30486,10 +30683,6 @@ function emitOne(doc, label, json) {
 }
 function registerIndexCommand(program2) {
   const index = program2.command("index").description("Query the decoded Index layer (events + contract calls)");
-  index.command("codegen").description("Generate a typed schema (Prisma, Kysely, Drizzle, or JSON-Schema) for the Index domain tables — point it at your BYO database mirror").option("--target <orm>", "prisma | kysely | drizzle | json-schema", "kysely").option("--schema <name>", "Postgres schema to qualify table names with").option("--tables <list>", "Comma-separated subset of Index tables (default: all)").option("--env <var>", "Prisma datasource url env var", "DATABASE_URL").option("-o, --output <path>", "Write to a file (defaults to stdout)").action(async (o3) => {
-    deprecatedCodegenNotice("secondlayer index codegen", "secondlayer codegen index");
-    await runIndexCodegen(o3);
-  });
   const rangeFlags = (cmd) => cmd.option("--contract-id <id>", "Filter by contract id").option("--from-height <n>", "Start block height (inclusive)").option("--to-height <n>", "End block height (inclusive)").option("--cursor <cursor>", "Resume token from a previous next_cursor").option("--limit <n>", "Rows per page").option("--json", "Print the full envelope as JSON");
   const heightFlags = (cmd) => cmd.option("--from-height <n>", "Start block height (inclusive)").option("--to-height <n>", "End block height (inclusive)").option("--cursor <cursor>", "Resume token from a previous next_cursor").option("--limit <n>", "Rows per page").option("--json", "Print the full envelope as JSON");
   rangeFlags(index.command("ft-transfers")).description("List decoded SIP-010 fungible-token transfers").option("--sender <principal>", "Filter by sender").option("--recipient <principal>", "Filter by recipient").action(async (o3) => {
@@ -30642,57 +30835,22 @@ var init_index_api = __esm(() => {
   init_fs();
   init_output();
   init_resolve_auth();
-  init_codegen();
-});
-
-// src/commands/codegen.ts
-var exports_codegen = {};
-__export(exports_codegen, {
-  registerCodegenCommand: () => registerCodegenCommand,
-  deprecatedCodegenNotice: () => deprecatedCodegenNotice
-});
-function registerCodegenCommand(program2) {
-  const codegen = program2.command("codegen").description("Generate typed code: contracts, subgraphs, Index, clients");
-  codegen.command("contracts [files...]").description("Generate TypeScript interfaces from Clarity contracts").option("-c, --config <path>", "Path to config file").option("-o, --output <path>", "Output file path").option("-k, --api-key <key>", "Stacks node API key for direct RPC URLs").option("-w, --watch", "Watch for changes").action(async (files, options3) => {
-    const { generate: generate2 } = await Promise.resolve().then(() => (init_generate(), exports_generate));
-    await generate2(files, { ...options3, out: options3.output });
-  });
-  codegen.command("subgraph <file>").description("Generate an ORM schema (Kysely, Prisma, or Drizzle) for a subgraph's tables").option("--target <orm>", "ORM target: kysely | prisma | drizzle", "kysely").option("--schema <name>", "Postgres schema name (defaults to subgraph_<name>)").option("--env <var>", "datasource url env var", "DATABASE_URL").option("--models-only", "Emit only Prisma models (compose via prismaSchemaFolder)").option("-o, --output <path>", "Write to a file (defaults to stdout)").action(async (file, options3, command) => {
-    const { runSubgraphSchemaCodegen: runSubgraphSchemaCodegen2 } = await Promise.resolve().then(() => (init_subgraphs2(), exports_subgraphs));
-    await runSubgraphSchemaCodegen2(file, options3, (key) => command.getOptionValueSource(key), "kysely");
-  });
-  codegen.command("index").description("Generate a typed schema (Kysely, Prisma, Drizzle, or JSON-Schema) for the Index domain tables").option("--target <orm>", "kysely | prisma | drizzle | json-schema", "kysely").option("--schema <name>", "Postgres schema to qualify table names with").option("--tables <list>", "Comma-separated subset of Index tables (default: all)").option("--env <var>", "Prisma datasource url env var", "DATABASE_URL").option("-o, --output <path>", "Write to a file (defaults to stdout)").action(async (options3) => {
-    const { runIndexCodegen: runIndexCodegen2 } = await Promise.resolve().then(() => (init_index_api(), exports_index_api));
-    await runIndexCodegen2(options3);
-  });
-  codegen.command("client <subgraphName>").description("Generate a typed query client for a deployed subgraph").option("-o, --output <path>", "Output file path (required)").action(async (subgraphName, options3) => {
-    const { runSubgraphClientCodegen: runSubgraphClientCodegen2 } = await Promise.resolve().then(() => (init_subgraphs2(), exports_subgraphs));
-    await runSubgraphClientCodegen2(subgraphName, options3);
-  });
-  codegen.command("prints <file>").description("Emit a .d.ts of print payload types for a subgraph's pinned print_event sources (inferred from observed on-chain events; requires network)").option("-o, --output <path>", "Write to a file (defaults to stdout)").action(async (file, options3) => {
-    const { runPayloadsCodegen: runPayloadsCodegen2 } = await Promise.resolve().then(() => (init_subgraphs2(), exports_subgraphs));
-    await runPayloadsCodegen2(file, options3.output);
-  });
-}
-function deprecatedCodegenNotice(oldPath, newPath) {
-  warn(`\`${oldPath}\` is deprecated — use \`${newPath}\`. (The new verb defaults --target to kysely everywhere; this alias keeps its original default so your output does not change.)`);
-}
-var init_codegen = __esm(() => {
-  init_output();
 });
 
 // src/lib/docker.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+function run2(command, args) {
+  const result = spawnSync2(command, args, { encoding: "utf8" });
+  return {
+    ok: !result.error && result.status === 0,
+    stdout: result.stdout ?? ""
+  };
+}
 async function isDockerAvailable() {
-  try {
-    const result = await Bun.$`docker info`.quiet().nothrow();
-    return result.exitCode === 0;
-  } catch {
-    return false;
-  }
+  return run2("docker", ["info"]).ok;
 }
 async function requireDocker() {
-  const whichResult = await Bun.$`which docker`.quiet().nothrow();
-  if (whichResult.exitCode !== 0) {
+  if (!run2("which", ["docker"]).ok) {
     throw new DockerNotAvailableError(`Docker is not installed.
 
 ` + `Install Docker:
@@ -32711,6 +32869,155 @@ var init_src = __esm(() => {
   src_default = Postgres;
 });
 
+// src/lib/devnet-compose.ts
+function buildDevnetCompose(opts = {}) {
+  const owner = opts.owner ?? DEFAULT_IMAGE_OWNER;
+  const tag = opts.imageTag ?? DEFAULT_IMAGE_TAG;
+  const apiPort = opts.apiPort ?? 3800;
+  const indexerPort = opts.indexerPort ?? 3700;
+  const apiPublish = `127.0.0.1:${apiPort}`;
+  const apiImage = `ghcr.io/${owner}/secondlayer-api:${tag}`;
+  const indexerImage = `ghcr.io/${owner}/secondlayer-indexer:${tag}`;
+  const dbUrl = "postgres://secondlayer:secondlayer@postgres:5432/secondlayer";
+  const DEV_SECRETS_KEY = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef";
+  return `# Generated by \`secondlayer devnet connect\` — do not edit by hand.
+# Secondlayer app services for local clarinet devnet development.
+name: secondlayer-devnet
+
+services:
+  postgres:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_USER: secondlayer
+      POSTGRES_PASSWORD: secondlayer
+      POSTGRES_DB: secondlayer
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U secondlayer"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+    restart: unless-stopped
+
+  migrate:
+    image: ${apiImage}
+    command: ["bun", "run", "packages/shared/src/db/migrate.ts"]
+    environment:
+      DATABASE_URL: ${dbUrl}
+    depends_on:
+      postgres:
+        condition: service_healthy
+    restart: "no"
+
+  api:
+    image: ${apiImage}
+    environment:
+      INSTANCE_MODE: oss
+      DATABASE_URL: ${dbUrl}
+      PORT: 3800
+      # 0.0.0.0 is forced: a container process that binds loopback is
+      # unreachable through a published port. The real reach is the publish
+      # spec below, handed over verbatim so /v1 reads stay keyless on devnet.
+      LISTEN_HOST: "0.0.0.0"
+      API_PUBLISH_ADDR: "${apiPublish}"
+      # Boot guard reads LISTEN_HOST, so a token is required to start at all.
+      # It gates writes only — reads are open on this loopback publish.
+      INSTANCE_TOKEN: ${DEV_INSTANCE_TOKEN}
+      NODE_ENV: production
+      DATA_DIR: /data
+      # Shared across api + subgraph-processor so the secret the api encrypts
+      # (e.g. a subscription's signing secret) can be decrypted by the emitter.
+      # OSS auto-generates a per-process key when unset — that splits them.
+      # Local-dev fixed value; not a production secret.
+      SECONDLAYER_SECRETS_KEY: ${DEV_SECRETS_KEY}
+    ports:
+      - "${apiPublish}:3800"
+    volumes:
+      - subgraphs_data:/data/subgraphs
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3800/health"]
+      interval: 10s
+      timeout: 3s
+      start_period: 10s
+      retries: 5
+    restart: unless-stopped
+
+  indexer:
+    image: ${indexerImage}
+    environment:
+      DATABASE_URL: ${dbUrl}
+      PORT: 3700
+      NODE_ENV: production
+      # Keep every network key aligned: the indexer writes index_progress under
+      # STACKS_NETWORK, the subgraph processor reads it under NETWORK. If they
+      # differ, catch-up finds no progress row and subgraphs never advance.
+      NETWORKS: testnet
+      STACKS_NETWORK: testnet
+      NETWORK: testnet
+      # Fed by the devnet node's event observer — never reach out to Hiro mainnet.
+      AUTO_BACKFILL_ENABLED: "false"
+      TIP_FOLLOWER_ENABLED: "false"
+    # Deliberately published on every interface, unlike the api: the devnet's
+    # stacks-node runs in its own container and POSTs events to
+    # host.docker.internal:3700, which resolves to the host gateway address,
+    # not 127.0.0.1. A loopback publish here would drop every block.
+    ports:
+      - "${indexerPort}:3700"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3700/health"]
+      interval: 10s
+      timeout: 3s
+      start_period: 10s
+      retries: 5
+    restart: unless-stopped
+
+  subgraph-processor:
+    image: ${apiImage}
+    command: ["bun", "run", "packages/subgraphs/src/service.ts"]
+    environment:
+      DATABASE_URL: ${dbUrl}
+      NODE_ENV: production
+      DATA_DIR: /data
+      # Must match the indexer's network key (see indexer note) — catch-up reads
+      # index_progress under NETWORK.
+      NETWORK: testnet
+      STACKS_NETWORK: testnet
+      # The emitter blocks webhook delivery to private/loopback IPs by default.
+      # On a local devnet you deliver to your own localhost receiver, so allow it.
+      SECONDLAYER_ALLOW_PRIVATE_EGRESS: "true"
+      # Must match the api's key so the emitter can decrypt signing secrets.
+      SECONDLAYER_SECRETS_KEY: ${DEV_SECRETS_KEY}
+    volumes:
+      - subgraphs_data:/data/subgraphs
+    depends_on:
+      migrate:
+        condition: service_completed_successfully
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      disable: true
+    restart: unless-stopped
+
+volumes:
+  postgres_data:
+  subgraphs_data:
+`;
+}
+var DEFAULT_IMAGE_OWNER = "ryanwaits", DEFAULT_IMAGE_TAG = "latest", DEV_INSTANCE_TOKEN = "dev-instance-token";
+
 // src/lib/dev-state.ts
 var exports_dev_state = {};
 __export(exports_dev_state, {
@@ -34315,12 +34622,1484 @@ var init_node_impl = __esm(() => {
   init_output();
 });
 
-// src/cli.ts
-init_esm();
+// src/lib/instance-init.ts
+import { randomBytes as randomBytes3 } from "node:crypto";
+import { existsSync as existsSync10, readFileSync as readFileSync9, writeFileSync as writeFileSync8 } from "node:fs";
+import { resolve as resolve15 } from "node:path";
+import { generateEd25519KeyPair } from "@secondlayer/shared/crypto/ed25519";
+import { INSTANCE_NETWORKS } from "@secondlayer/shared/db/queries/instance";
+function parseInstanceNetwork(value) {
+  const network = value.trim().toLowerCase();
+  if (INSTANCE_NETWORKS.includes(network)) {
+    return network;
+  }
+  throw new Error(`network must be mainnet, testnet, or devnet (got ${value})`);
+}
+function generateInstanceToken() {
+  return randomBytes3(32).toString("hex");
+}
+function generateSecretsKey() {
+  return randomBytes3(32).toString("hex");
+}
+function generateSigningPrivateKey() {
+  return generateEd25519KeyPair().privateKeyPem;
+}
+function escapeEnvValue(value) {
+  if (!/[\s#"']/.test(value) && !value.includes("\\"))
+    return value;
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n")}"`;
+}
+function unescapeEnvValue(raw) {
+  let value = raw.trim();
+  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    value = value.slice(1, -1);
+  }
+  return value.replace(/\\n/g, `
+`).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+}
+function readEnvValue(envPath, key) {
+  if (!existsSync10(envPath))
+    return null;
+  const match = readFileSync9(envPath, "utf8").match(new RegExp(`^${key}=(.*)$`, "m"));
+  return match ? unescapeEnvValue(match[1]) : null;
+}
+function buildInstanceEnv(input4) {
+  const token = input4.existing?.INSTANCE_TOKEN || input4.existing?.SL_API_KEY || generateInstanceToken();
+  const secrets = input4.existing?.SECONDLAYER_SECRETS_KEY || generateSecretsKey();
+  const signing = input4.existing?.STREAMS_SIGNING_PRIVATE_KEY || input4.existing?.SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY || generateSigningPrivateKey();
+  const apiUrl = input4.apiUrl ?? "http://127.0.0.1:3800";
+  const archiveKey = input4.existing?.ARCHIVE_SIGNING_PUBLIC_KEY;
+  return {
+    INSTANCE_MODE: "oss",
+    STACKS_NETWORK: input4.network,
+    INSTANCE_TOKEN: token,
+    SECONDLAYER_SECRETS_KEY: secrets,
+    STREAMS_SIGNING_PRIVATE_KEY: signing,
+    SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY: signing,
+    ALLOW_UNSIGNED_WEBHOOKS: "false",
+    SL_API_URL: input4.existing?.SL_API_URL || apiUrl,
+    SL_API_KEY: token,
+    ...archiveKey ? { ARCHIVE_SIGNING_PUBLIC_KEY: archiveKey } : {}
+  };
+}
+function renderInstanceEnv(env2) {
+  const lines2 = [
+    "# Generated by secondlayer init. Do not commit.",
+    `INSTANCE_MODE=${env2.INSTANCE_MODE}`,
+    `STACKS_NETWORK=${env2.STACKS_NETWORK}`,
+    "# The instance credential. The API validates bearer tokens against it,",
+    "# and the CLI/SDK/MCP read it first when authenticating.",
+    `INSTANCE_TOKEN=${env2.INSTANCE_TOKEN}`,
+    `SECONDLAYER_SECRETS_KEY=${env2.SECONDLAYER_SECRETS_KEY}`,
+    `STREAMS_SIGNING_PRIVATE_KEY=${escapeEnvValue(env2.STREAMS_SIGNING_PRIVATE_KEY)}`,
+    `SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY=${escapeEnvValue(env2.SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY)}`,
+    `ALLOW_UNSIGNED_WEBHOOKS=${env2.ALLOW_UNSIGNED_WEBHOOKS}`,
+    `SL_API_URL=${env2.SL_API_URL}`,
+    "# Legacy alias of INSTANCE_TOKEN, same value. Kept for existing setups;",
+    "# INSTANCE_TOKEN wins if the two ever disagree.",
+    `SL_API_KEY=${env2.SL_API_KEY}`
+  ];
+  if (env2.ARCHIVE_SIGNING_PUBLIC_KEY) {
+    lines2.push(`ARCHIVE_SIGNING_PUBLIC_KEY=${escapeEnvValue(env2.ARCHIVE_SIGNING_PUBLIC_KEY)}`);
+  }
+  lines2.push("");
+  return lines2.join(`
+`);
+}
+function writeInstanceEnv(cwd, env2, file = INSTANCE_ENV_FILE) {
+  const path11 = resolve15(cwd, file);
+  writeFileSync8(path11, renderInstanceEnv(env2), { mode: 384 });
+  return path11;
+}
+function loadExistingInstanceEnv(cwd, file = INSTANCE_ENV_FILE) {
+  const path11 = resolve15(cwd, file);
+  return {
+    INSTANCE_TOKEN: readEnvValue(path11, "INSTANCE_TOKEN"),
+    SECONDLAYER_SECRETS_KEY: readEnvValue(path11, "SECONDLAYER_SECRETS_KEY"),
+    STREAMS_SIGNING_PRIVATE_KEY: readEnvValue(path11, "STREAMS_SIGNING_PRIVATE_KEY"),
+    SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY: readEnvValue(path11, "SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY"),
+    SL_API_URL: readEnvValue(path11, "SL_API_URL"),
+    SL_API_KEY: readEnvValue(path11, "SL_API_KEY"),
+    ARCHIVE_SIGNING_PUBLIC_KEY: readEnvValue(path11, "ARCHIVE_SIGNING_PUBLIC_KEY")
+  };
+}
+var INSTANCE_ENV_FILE = ".env.local";
+var init_instance_init = () => {};
+
+// src/lib/observer-stanza.ts
+function parseObserverMode(value) {
+  const mode = value.trim().toLowerCase();
+  if (OBSERVER_MODES.includes(mode)) {
+    return mode;
+  }
+  throw new UnsupportedObserverError(`observer mode must be indexer or signer-shared (got ${value})`);
+}
+function parseRecoverySource(value) {
+  const source = value.trim().toLowerCase();
+  if (RECOVERY_SOURCES.includes(source)) {
+    return source;
+  }
+  throw new UnsupportedObserverError(`recovery source must be journal or archive (got ${value})`);
+}
+function parseObserverEndpoint(value) {
+  const trimmed = value.trim();
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) || trimmed.startsWith("unix:")) {
+    throw new UnsupportedObserverError(`observer endpoint must be host:port, not a URL (${value})`);
+  }
+  const match = trimmed.match(/^([a-zA-Z0-9._-]+):(\d+)$/);
+  if (!match) {
+    throw new UnsupportedObserverError(`observer endpoint must be host:port (got ${value})`);
+  }
+  const port = Number(match[2]);
+  if (port < 1 || port > 65535) {
+    throw new UnsupportedObserverError(`observer port out of range (${port})`);
+  }
+  return trimmed;
+}
+function validateObserverStanza(input4) {
+  const endpoint = parseObserverEndpoint(input4.endpoint);
+  const host = endpoint.slice(0, endpoint.lastIndexOf(":"));
+  if (input4.network !== "devnet" && LOOPBACK_HOSTS.has(host.toLowerCase())) {
+    throw new UnsupportedObserverError(`loopback observer endpoint is not container-visible on ${input4.network}; use a docker DNS name such as indexer:3700`);
+  }
+  if (input4.mode === "signer-shared" && !input4.recovery) {
+    throw new UnsupportedObserverError("signer-shared mode requires --recovery journal or --recovery archive");
+  }
+  return { endpoint };
+}
+function renderObserverStanza(input4) {
+  const { endpoint } = validateObserverStanza(input4);
+  const indexer = input4.mode === "indexer";
+  const timeoutMs = indexer ? 2000 : 500;
+  const disableRetries = !indexer;
+  const comment = indexer ? "# Pure indexer: retry delivery. A slow observer can stall the node." : "# Signer-shared: do not retry. Missed blocks refill from the journal/archive.";
+  return [
+    comment,
+    "[[events_observer]]",
+    `endpoint = "${endpoint}"`,
+    'events_keys = ["*"]',
+    `timeout_ms = ${timeoutMs}`,
+    `disable_retries = ${disableRetries}`,
+    ""
+  ].join(`
+`);
+}
+function defaultObserverEndpoint(network) {
+  if (network === "devnet")
+    return "127.0.0.1:3700";
+  return "indexer:3700";
+}
+var OBSERVER_MODES, RECOVERY_SOURCES, UnsupportedObserverError, LOOPBACK_HOSTS;
+var init_observer_stanza = __esm(() => {
+  OBSERVER_MODES = ["indexer", "signer-shared"];
+  RECOVERY_SOURCES = ["journal", "archive"];
+  UnsupportedObserverError = class UnsupportedObserverError extends Error {
+    name = "UnsupportedObserverError";
+  };
+  LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+});
+
+// src/lib/oss-compose.ts
+function buildOssCompose(opts = {}) {
+  const owner = opts.owner ?? DEFAULT_IMAGE_OWNER;
+  const tag = opts.imageTag ?? DEFAULT_IMAGE_TAG;
+  const runtimeImage = `ghcr.io/${owner}/secondlayer-runtime:${tag}`;
+  const consoleImage = `ghcr.io/${owner}/secondlayer-console:${tag}`;
+  return `# Generated by \`secondlayer setup\` — do not edit by hand.
+# Mirrors docker/oss/docker-compose.yml; see that file for the source of truth
+# on env vars, profiles, and third-party digest pins. \`secondlayer\`/\`console\`
+# are swapped from a repo build to the published OSS images (no checkout here).
+name: secondlayer
+
+services:
+  postgres:
+    image: postgres:17-alpine@sha256:d4bb0a8c1b7bb2e29f976d099e7bfb9a5d8858cffe9e46b35cd302cd1f1f8168
+    environment:
+      POSTGRES_USER: \${POSTGRES_USER:-secondlayer}
+      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:-secondlayer}
+      POSTGRES_DB: \${POSTGRES_DB:-secondlayer}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    ports:
+      - "\${POSTGRES_PORT:-127.0.0.1:5432}:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U \${POSTGRES_USER:-secondlayer}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
+  secondlayer:
+    image: ${runtimeImage}
+    environment:
+      INSTANCE_MODE: oss
+      NETWORK: \${NETWORK:-\${STACKS_NETWORK:-mainnet}}
+      STACKS_NETWORK: \${STACKS_NETWORK:-mainnet}
+      NODE_MODE: \${NODE_MODE:-external}
+      SECONDLAYER_ALLOW_UNDERSIZED: \${SECONDLAYER_ALLOW_UNDERSIZED:-false}
+      DATABASE_URL: postgres://\${POSTGRES_USER:-secondlayer}:\${POSTGRES_PASSWORD:-secondlayer}@postgres:5432/\${POSTGRES_DB:-secondlayer}
+      DATA_DIR: /data
+      API_PORT: "3800"
+      INDEXER_PORT: "3700"
+      # See docker/oss/docker-compose.yml: API_PORT above is the *container*
+      # port; \${API_PORT} in ports:/here is the *publish spec* from .env.
+      LISTEN_HOST: "0.0.0.0"
+      API_PUBLISH_ADDR: \${API_PORT:-127.0.0.1:3800}
+      INSTANCE_TOKEN: \${INSTANCE_TOKEN:-}
+      SECONDLAYER_SECRETS_KEY: \${SECONDLAYER_SECRETS_KEY:-}
+      STREAMS_SIGNING_PRIVATE_KEY: \${STREAMS_SIGNING_PRIVATE_KEY:-}
+      SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY: \${SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY:-}
+      ALLOW_UNSIGNED_WEBHOOKS: \${ALLOW_UNSIGNED_WEBHOOKS:-false}
+      LOG_LEVEL: \${LOG_LEVEL:-info}
+      NODE_ENV: production
+      STACKS_NODE_RPC_URL: \${STACKS_NODE_RPC_URL:-}
+      OBSERVER_JOURNAL_ENABLED: \${OBSERVER_JOURNAL_ENABLED:-true}
+      STREAMS_API_URL: http://127.0.0.1:3800
+      STREAMS_INTERNAL_API_KEY: \${STREAMS_INTERNAL_API_KEY:-}
+      SBTC_DECODER_ENABLED: \${SBTC_DECODER_ENABLED:-true}
+      POX4_DECODER_ENABLED: \${POX4_DECODER_ENABLED:-true}
+      BNS_DECODER_ENABLED: \${BNS_DECODER_ENABLED:-false}
+      SUBGRAPH_SOURCE: \${SUBGRAPH_SOURCE:-streams-index}
+      SUBGRAPH_INDEX_API_URL: http://127.0.0.1:3800
+      BITCOIN_RPC_PASSWORD: \${BITCOIN_RPC_PASSWORD:-}
+    ports:
+      - "\${API_PORT:-127.0.0.1:3800}:3800"
+      - "\${INDEXER_PORT:-127.0.0.1:3700}:3700"
+    # \`secondlayer observer\`'s default endpoint is \`indexer:3700\` — this
+    # alias is what makes that default actually resolve on this network,
+    # without renaming the service. Mirrors docker/oss/docker-compose.yml.
+    networks:
+      default:
+        aliases:
+          - indexer
+    volumes:
+      - subgraphs_data:/data/subgraphs
+    depends_on:
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3800/health"]
+      interval: 30s
+      timeout: 5s
+      start_period: 40s
+      retries: 3
+    restart: unless-stopped
+
+  console:
+    image: ${consoleImage}
+    environment:
+      SL_API_URL: http://secondlayer:3800
+      INSTANCE_TOKEN: \${INSTANCE_TOKEN:-}
+      CONSOLE_TOKEN: \${CONSOLE_TOKEN:-}
+      NODE_ENV: production
+    ports:
+      - "\${CONSOLE_PORT:-3801}:3801"
+    depends_on:
+      secondlayer:
+        condition: service_started
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3801/console"]
+      interval: 30s
+      timeout: 5s
+      start_period: 15s
+      retries: 3
+    restart: unless-stopped
+    profiles: ["console"]
+
+  bitcoind:
+    # Digest = kylemanna/bitcoind:latest as published 2026-07-20 — see
+    # docker/oss/docker-compose.yml for why the digest is the real pin here.
+    image: kylemanna/bitcoind:latest@sha256:86bbcaa99bf3bf3d5df7fd6d9217b3a41194db4c4e34385064f2cfc9fa7bdf91
+    volumes:
+      - \${BITCOIN_DATA_DIR:-./data/bitcoin}:/bitcoin/.bitcoin
+    ports:
+      - "127.0.0.1:8332:8332"
+      - "8333:8333"
+    healthcheck:
+      test: ["CMD-SHELL", "bitcoin-cli -rpcuser=\${BITCOIN_RPC_USER:-stacks} -rpcpassword=\${BITCOIN_RPC_PASSWORD:-changeme} getblockchaininfo | grep -q '\\"blocks\\"' && [ $$(bitcoin-cli -rpcuser=\${BITCOIN_RPC_USER:-stacks} -rpcpassword=\${BITCOIN_RPC_PASSWORD:-changeme} getblockcount) -gt 666050 ]"]
+      interval: 60s
+      timeout: 15s
+      start_period: 120s
+      retries: 3
+    restart: unless-stopped
+    deploy:
+      resources:
+        limits:
+          memory: 32G
+    profiles: ["full-node"]
+
+  stacks-node:
+    # Consensus-critical — digest-pinned to 4.0.1. See docker/oss/docker-compose.yml.
+    image: ghcr.io/stacks-network/stacks-core:4.0.1@sha256:ceb768f881ef52a1d2792a2b4a89d81e092b1df11293b04c31ce36613c3f9711
+    volumes:
+      - \${STACKS_DATA_DIR:-./data/stacks}:/stacks-blockchain/data
+      - ./Config.toml:/stacks-blockchain/Config.toml:ro
+    ports:
+      - "20443:20443"
+      - "20444:20444"
+    restart: unless-stopped
+    command: ["stacks-node", "start", "--config", "/stacks-blockchain/Config.toml"]
+    # full-node only — see docker/oss/docker-compose.yml. No standalone
+    # "stacks-node, public Bitcoin" profile: nothing here wires the node at
+    # a real public Bitcoin RPC, so that combination never actually synced.
+    profiles: ["full-node"]
+
+volumes:
+  postgres_data:
+  subgraphs_data:
+`;
+}
+function buildOssStacksConfigToml(opts) {
+  const mode = opts.network === "mainnet" ? "mainnet" : "testnet";
+  return `[node]
+working_dir = "/stacks-blockchain/data"
+rpc_bind = "0.0.0.0:20443"
+p2p_bind = "0.0.0.0:20444"
+seed = ""
+marf_compress = true
+bootstrap_node = "02196f005965cebe6ddc3901b7b1cc1aa7a88f305bb8c5893456b8f9a605923893@seed.mainnet.hiro.so:20444,02539449ad94e6e6392d8c1deb2b4e61f80ae2a18964349bc14336d8b903c46a8c@cet.stacksnodes.org:20444,02ececc8ce79b8adf813f13a0255f8ae58d4357309ba0cedd523d9f1a306fcfb79@sgt.stacksnodes.org:20444,0303144ba518fe7a0fb56a8a7d488f950307a4330f146e1e1458fc63fb33defe96@est.stacksnodes.org:20444"
+
+# Event observer points directly at the bundled indexer service, same docker
+# network. Retries off / low timeout: a stuck indexer must never starve a
+# co-located signer of block_proposal events. See docker/oss/Config.toml.
+[[events_observer]]
+endpoint = "secondlayer:3700"
+events_keys = ["*"]
+timeout_ms = 500
+disable_retries = true
+
+[burnchain]
+chain = "bitcoin"
+mode = "${mode}"
+peer_host = "bitcoind"
+username = "stacks"
+password = "${opts.bitcoinRpcPassword}"
+rpc_port = 8332
+peer_port = 8333
+`;
+}
+function buildOssBitcoinConf(opts) {
+  return `server=1
+txindex=1
+rpcallowip=0.0.0.0/0
+rpcbind=0.0.0.0
+rpcuser=stacks
+rpcpassword=${opts.rpcPassword}
+# Prune: 0 = archive (required for Stacks); set to 550+ only for pruned chains.
+prune=0
+dbcache=4096
+`;
+}
+var init_oss_compose = () => {};
+
+// src/lib/setup-wizard.ts
+import { spawn as spawn4, spawnSync as spawnSync5 } from "node:child_process";
+import { randomBytes as randomBytes4 } from "node:crypto";
+import { existsSync as existsSync11 } from "node:fs";
+import { writeFile as writeFile7 } from "node:fs/promises";
+import { createServer } from "node:net";
+import { join as join19, resolve as resolvePath2 } from "node:path";
+import { FLOORS, diskFloorGb } from "@secondlayer/shared/runtime";
+function parseSetupNodeMode(value) {
+  const mode = value.trim().toLowerCase();
+  if (SETUP_NODE_MODES.includes(mode)) {
+    return mode;
+  }
+  throw new Error(`node mode must be external, stacks, or full (got ${value})`);
+}
+function resolveNonInteractiveConfig(flags) {
+  if (!flags.network) {
+    throw new MissingSetupFlagError("--network", "Missing --network <mainnet|testnet|devnet>. Non-interactive setup requires it explicitly — there is no safe default.");
+  }
+  if (!flags.nodeMode) {
+    throw new MissingSetupFlagError("--node-mode", "Missing --node-mode <external|stacks|full>. Non-interactive setup requires it explicitly — there is no safe default.");
+  }
+  if (!flags.against && !flags.skipBootstrap) {
+    throw new MissingSetupFlagError("--against", "Missing --against <manifest-url>. Pass an archive manifest to bootstrap from, or --skip-bootstrap to sync from genesis instead.");
+  }
+  const network = parseInstanceNetwork(flags.network);
+  const nodeMode = parseSetupNodeMode(flags.nodeMode);
+  const dir = resolvePath2(flags.dir ?? process.cwd());
+  return {
+    network,
+    nodeMode,
+    apiPort: flags.apiPort ?? "127.0.0.1:3800",
+    indexerPort: "127.0.0.1:3700",
+    postgresPort: "127.0.0.1:5432",
+    dir,
+    against: flags.against,
+    skipBootstrap: !!flags.skipBootstrap,
+    skipVerify: !!flags.skipVerify,
+    yes: !!flags.yes,
+    force: !!flags.force,
+    owner: flags.owner ?? DEFAULT_IMAGE_OWNER,
+    imageTag: flags.imageTag ?? DEFAULT_IMAGE_TAG
+  };
+}
+function guardrailPreview(nodeMode, network) {
+  return {
+    ramFloorMb: nodeMode === "full" ? FLOORS.fullRamMb : FLOORS.appRamMb,
+    diskFloorGb: diskFloorGb(nodeMode, network)
+  };
+}
+function isBunRuntime() {
+  return typeof process !== "undefined" && typeof process.versions === "object" && process.versions !== null && typeof process.versions.bun === "string";
+}
+async function checkDocker() {
+  const probe = spawnSync5("docker", ["info"], { stdio: "ignore" });
+  return !probe.error && probe.status === 0;
+}
+function isPortFree(host, port) {
+  return new Promise((resolvePromise) => {
+    const srv = createServer();
+    srv.once("error", () => resolvePromise(false));
+    srv.once("listening", () => srv.close(() => resolvePromise(true)));
+    srv.listen(port, host);
+  });
+}
+function parsePublishSpec(spec) {
+  const idx = spec.lastIndexOf(":");
+  if (idx === -1)
+    return { host: "127.0.0.1", port: Number(spec) };
+  return { host: spec.slice(0, idx), port: Number(spec.slice(idx + 1)) };
+}
+function dockerPublishedHostPorts() {
+  const probe = spawnSync5("docker", ["ps", "--format", "{{.Ports}}"], {
+    encoding: "utf8"
+  });
+  const ports = new Set;
+  if (probe.error || probe.status !== 0 || !probe.stdout)
+    return ports;
+  for (const match of probe.stdout.matchAll(/:(\d+)->/g)) {
+    ports.add(Number(match[1]));
+  }
+  return ports;
+}
+async function resolveAvailablePublishSpec(spec, claimedByDocker = new Set, maxAttempts = 20) {
+  const { host, port } = parsePublishSpec(spec);
+  for (let attempt = 0;attempt < maxAttempts; attempt++) {
+    const candidate = port + attempt;
+    if (claimedByDocker.has(candidate))
+      continue;
+    if (await isPortFree(host, candidate)) {
+      return { spec: `${host}:${candidate}`, remapped: attempt > 0 };
+    }
+  }
+  return { spec, remapped: false };
+}
+function randomHex(bytes) {
+  return randomBytes4(bytes).toString("hex");
+}
+function resolveSecrets(config) {
+  const envPath = join19(config.dir, ".env");
+  const existing = config.force || !existsSync11(envPath) ? {} : readEnvFile(config.dir, envPath);
+  const instance = buildInstanceEnv({
+    network: config.network,
+    existing: {
+      INSTANCE_TOKEN: existing.INSTANCE_TOKEN,
+      SECONDLAYER_SECRETS_KEY: existing.SECONDLAYER_SECRETS_KEY,
+      STREAMS_SIGNING_PRIVATE_KEY: existing.STREAMS_SIGNING_PRIVATE_KEY,
+      SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY: existing.SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY,
+      SL_API_URL: existing.SL_API_URL,
+      SL_API_KEY: existing.SL_API_KEY,
+      ARCHIVE_SIGNING_PUBLIC_KEY: existing.ARCHIVE_SIGNING_PUBLIC_KEY
+    },
+    apiUrl: `http://${normalizeLoopbackHost(config.apiPort)}`
+  });
+  return {
+    instance,
+    postgresPassword: existing.POSTGRES_PASSWORD || randomHex(24),
+    bitcoinRpcPassword: existing.BITCOIN_RPC_PASSWORD || randomHex(24)
+  };
+}
+function normalizeLoopbackHost(apiPort) {
+  return apiPort.includes(":") ? apiPort : `127.0.0.1:${apiPort}`;
+}
+function readEnvFile(dir, envPath) {
+  const shared = loadExistingInstanceEnv(dir, ".env");
+  return {
+    ...shared,
+    POSTGRES_PASSWORD: readEnvValue(envPath, "POSTGRES_PASSWORD"),
+    BITCOIN_RPC_PASSWORD: readEnvValue(envPath, "BITCOIN_RPC_PASSWORD")
+  };
+}
+function renderSetupEnv(config, secrets) {
+  const i3 = secrets.instance;
+  const lines2 = [
+    "# Generated by `secondlayer setup`. Do not commit.",
+    `NETWORK=${config.network}`,
+    `STACKS_NETWORK=${config.network}`,
+    `NODE_MODE=${config.nodeMode}`,
+    `API_PORT=${config.apiPort}`,
+    `INDEXER_PORT=${config.indexerPort}`,
+    "POSTGRES_USER=secondlayer",
+    `POSTGRES_PASSWORD=${secrets.postgresPassword}`,
+    "POSTGRES_DB=secondlayer",
+    `POSTGRES_PORT=${config.postgresPort}`,
+    "# The instance credential. The API validates bearer tokens against it,",
+    "# and the CLI/SDK/MCP read it first when authenticating.",
+    `INSTANCE_TOKEN=${i3.INSTANCE_TOKEN}`,
+    `SECONDLAYER_SECRETS_KEY=${i3.SECONDLAYER_SECRETS_KEY}`,
+    `STREAMS_SIGNING_PRIVATE_KEY=${escapeEnvValue(i3.STREAMS_SIGNING_PRIVATE_KEY)}`,
+    `SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY=${escapeEnvValue(i3.SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY)}`,
+    `ALLOW_UNSIGNED_WEBHOOKS=${i3.ALLOW_UNSIGNED_WEBHOOKS}`,
+    "# Legacy alias of INSTANCE_TOKEN, same value.",
+    `SL_API_KEY=${i3.SL_API_KEY}`,
+    `SL_API_URL=${i3.SL_API_URL}`
+  ];
+  if (i3.ARCHIVE_SIGNING_PUBLIC_KEY) {
+    lines2.push(`ARCHIVE_SIGNING_PUBLIC_KEY=${escapeEnvValue(i3.ARCHIVE_SIGNING_PUBLIC_KEY)}`);
+  }
+  if (config.nodeMode === "full") {
+    lines2.push("BITCOIN_RPC_USER=stacks", `BITCOIN_RPC_PASSWORD=${secrets.bitcoinRpcPassword}`);
+  }
+  lines2.push("");
+  return lines2.join(`
+`);
+}
+async function writeSetupFiles(config, secrets) {
+  const composePath = join19(config.dir, "docker-compose.yml");
+  const envPath = join19(config.dir, ".env");
+  await writeFile7(composePath, buildOssCompose({ owner: config.owner, imageTag: config.imageTag }));
+  await writeFile7(envPath, renderSetupEnv(config, secrets), { mode: 384 });
+  const result = { composePath, envPath };
+  if (config.nodeMode === "full") {
+    const configTomlPath = join19(config.dir, "Config.toml");
+    await writeFile7(configTomlPath, buildOssStacksConfigToml({
+      network: config.network,
+      bitcoinRpcPassword: secrets.bitcoinRpcPassword ?? ""
+    }));
+    result.configTomlPath = configTomlPath;
+  }
+  if (config.nodeMode === "full") {
+    const bitcoinConfPath = join19(config.dir, "bitcoin.conf");
+    await writeFile7(bitcoinConfPath, buildOssBitcoinConf({ rpcPassword: secrets.bitcoinRpcPassword ?? "" }));
+    result.bitcoinConfPath = bitcoinConfPath;
+  }
+  return result;
+}
+function composeProfileArgs(nodeMode) {
+  if (nodeMode === "full")
+    return ["--profile", "full-node"];
+  return [];
+}
+function runStreaming(command, args, opts) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn4(command, args, {
+      cwd: opts.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    const pump = (stream2) => (chunk) => {
+      const text2 = chunk.toString("utf8");
+      if (stream2 === "stdout")
+        stdout += text2;
+      else
+        stderr += text2;
+      if (opts.onLine) {
+        for (const line of text2.split(`
+`)) {
+          if (line.length > 0)
+            opts.onLine(line, stream2);
+        }
+      }
+    };
+    child.stdout?.on("data", pump("stdout"));
+    child.stderr?.on("data", pump("stderr"));
+    child.once("error", reject);
+    child.once("close", (code) => {
+      resolvePromise({ code: code ?? 1, stdout, stderr });
+    });
+  });
+}
+async function dockerComposeUp(config, files, onLine) {
+  const args = [
+    "compose",
+    "-f",
+    files.composePath,
+    "--env-file",
+    files.envPath,
+    ...composeProfileArgs(config.nodeMode),
+    "up",
+    "-d"
+  ];
+  return runStreaming("docker", args, { cwd: config.dir, onLine });
+}
+async function pollHealth(config, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 120000;
+  const intervalMs = opts.intervalMs ?? 2000;
+  const url = `http://${normalizeLoopbackHost(config.apiPort)}/health`;
+  const deadline = Date.now() + timeoutMs;
+  for (;; ) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(3000) });
+      if (res.ok)
+        return true;
+    } catch {}
+    opts.onTick?.();
+    if (Date.now() >= deadline)
+      return false;
+    await new Promise((r2) => setTimeout(r2, intervalMs));
+  }
+}
+function getObserverInfo(config) {
+  if (config.nodeMode !== "external") {
+    return { applicable: false };
+  }
+  const endpoint = defaultObserverEndpoint(config.network);
+  const stanza = renderObserverStanza({
+    mode: "indexer",
+    endpoint,
+    network: config.network
+  });
+  return { applicable: true, stanza, endpoint };
+}
+function cliEntry() {
+  const entry = process.argv[1];
+  if (!entry) {
+    throw new Error("Could not resolve the secondlayer CLI entry to shell out to.");
+  }
+  return [process.execPath, entry];
+}
+async function runBootstrap(config, against, onLine) {
+  const [command, ...prefix] = cliEntry();
+  const args = [...prefix, "bootstrap", "--against", against, "--yes"];
+  return runStreaming(command, args, { cwd: config.dir, onLine });
+}
+async function runVerify(config, against, onLine) {
+  const [command, ...prefix] = cliEntry();
+  const args = [...prefix, "verify", "all", "--against", against];
+  return runStreaming(command, args, { cwd: config.dir, onLine });
+}
+function buildSuccessSummary(config, secrets) {
+  const apiUrl = `http://${normalizeLoopbackHost(config.apiPort)}`;
+  const lines2 = [
+    "Secondlayer is up.",
+    "",
+    `  api        ${apiUrl}`,
+    `  network    ${config.network}`,
+    `  node mode  ${config.nodeMode}`,
+    `  dir        ${config.dir}`,
+    "",
+    "Export the instance token for writes (reads on loopback need no credential):",
+    `  export INSTANCE_TOKEN=${secrets.instance.INSTANCE_TOKEN}`,
+    "",
+    "Try it:",
+    "  secondlayer subgraphs create my-balances --from-contract SP....my-contract",
+    "  secondlayer subgraphs deploy subgraphs/my-balances.ts",
+    `  curl ${apiUrl}/v1/subgraphs/my-balances/balances`,
+    "",
+    "Docs: https://secondlayer.tools/docs/self-host"
+  ];
+  return lines2.join(`
+`);
+}
+async function runSetup(initialConfig, emit2) {
+  let config = initialConfig;
+  emit2({ type: "step-start", step: "preflight" });
+  if (!await checkDocker()) {
+    emit2({
+      type: "step-error",
+      step: "preflight",
+      message: "Docker isn't reachable. Start Docker Desktop/OrbStack, or install Docker, then re-run."
+    });
+    return { ok: false, config };
+  }
+  const claimedByDocker = dockerPublishedHostPorts();
+  const ports = {
+    api: await resolveAvailablePublishSpec(config.apiPort, claimedByDocker),
+    indexer: await resolveAvailablePublishSpec(config.indexerPort, claimedByDocker),
+    postgres: await resolveAvailablePublishSpec(config.postgresPort, claimedByDocker)
+  };
+  config = {
+    ...config,
+    apiPort: ports.api.spec,
+    indexerPort: ports.indexer.spec,
+    postgresPort: ports.postgres.spec
+  };
+  for (const [label, result] of [
+    ["api", ports.api],
+    ["indexer", ports.indexer],
+    ["postgres", ports.postgres]
+  ]) {
+    if (result.remapped) {
+      emit2({
+        type: "step-log",
+        step: "preflight",
+        line: `${label} port was already in use locally, using ${result.spec} instead`
+      });
+    }
+  }
+  const floors = guardrailPreview(config.nodeMode, config.network);
+  emit2({
+    type: "step-done",
+    step: "preflight",
+    detail: `NODE_MODE=${config.nodeMode} on ${config.network} needs at least ${floors.ramFloorMb}MB RAM and ${floors.diskFloorGb}GB disk.`
+  });
+  emit2({ type: "step-start", step: "secrets" });
+  const secrets = resolveSecrets({
+    dir: config.dir,
+    network: config.network,
+    apiPort: config.apiPort,
+    force: config.force
+  });
+  emit2({ type: "step-done", step: "secrets" });
+  emit2({ type: "step-start", step: "config" });
+  const files = await writeSetupFiles(config, secrets);
+  emit2({
+    type: "step-done",
+    step: "config",
+    detail: `${files.composePath}, ${files.envPath}`
+  });
+  emit2({ type: "step-start", step: "docker-up" });
+  const up = await dockerComposeUp(config, files, (line) => emit2({ type: "step-log", step: "docker-up", line }));
+  if (up.code !== 0) {
+    emit2({
+      type: "step-error",
+      step: "docker-up",
+      message: `docker compose up failed (exit ${up.code}).
+${up.stderr || up.stdout}`
+    });
+    return { ok: false, config, secrets, files };
+  }
+  const healthy = await pollHealth(config, {
+    onTick: () => emit2({
+      type: "step-log",
+      step: "docker-up",
+      line: "waiting for /health…"
+    })
+  });
+  if (!healthy) {
+    emit2({
+      type: "step-error",
+      step: "docker-up",
+      message: "Containers started but /health never came up. Check `docker compose logs`."
+    });
+    return { ok: false, config, secrets, files };
+  }
+  emit2({ type: "step-done", step: "docker-up" });
+  emit2({ type: "step-start", step: "observer" });
+  const observer = getObserverInfo(config);
+  if (observer.applicable && observer.stanza) {
+    emit2({
+      type: "step-log",
+      step: "observer",
+      line: "ACTION REQUIRED — paste this into your Stacks node's Config.toml:"
+    });
+    for (const line of observer.stanza.split(`
+`)) {
+      if (line.length > 0)
+        emit2({ type: "step-log", step: "observer", line });
+    }
+    emit2({
+      type: "step-done",
+      step: "observer",
+      detail: `endpoint ${observer.endpoint} — see the ACTION REQUIRED lines above`
+    });
+  } else {
+    emit2({
+      type: "step-done",
+      step: "observer",
+      detail: "bundled node — the observer is pre-configured, nothing to paste"
+    });
+  }
+  let bootstrapped = false;
+  if (config.skipBootstrap) {
+    emit2({ type: "step-skip", step: "bootstrap", reason: "--skip-bootstrap" });
+  } else if (config.against) {
+    emit2({ type: "step-start", step: "bootstrap" });
+    const res = await runBootstrap(config, config.against, (line) => emit2({ type: "step-log", step: "bootstrap", line }));
+    if (res.code === 0) {
+      bootstrapped = true;
+      emit2({ type: "step-done", step: "bootstrap" });
+    } else {
+      emit2({
+        type: "step-error",
+        step: "bootstrap",
+        message: `secondlayer bootstrap exited ${res.code}.`
+      });
+    }
+  }
+  if (config.skipVerify) {
+    emit2({ type: "step-skip", step: "verify", reason: "--skip-verify" });
+  } else if (!config.against) {
+    emit2({
+      type: "step-skip",
+      step: "verify",
+      reason: "no manifest to verify against"
+    });
+  } else if (!bootstrapped) {
+    emit2({
+      type: "step-skip",
+      step: "verify",
+      reason: "bootstrap did not run — nothing restored yet to verify"
+    });
+  } else {
+    emit2({ type: "step-start", step: "verify" });
+    const res = await runVerify(config, config.against, (line) => emit2({ type: "step-log", step: "verify", line }));
+    if (res.code === 0) {
+      emit2({ type: "step-done", step: "verify" });
+    } else {
+      emit2({
+        type: "step-error",
+        step: "verify",
+        message: `secondlayer verify exited ${res.code}.`
+      });
+    }
+  }
+  const summary = buildSuccessSummary(config, secrets);
+  emit2({ type: "step-start", step: "summary" });
+  emit2({ type: "step-done", step: "summary", detail: summary });
+  return { ok: true, config, secrets, files, observer, summary };
+}
+var SETUP_NODE_MODES, DEFAULT_ARCHIVE_MANIFEST = "https://archive.secondlayer.tools/latest.json", MissingSetupFlagError;
+var init_setup_wizard = __esm(() => {
+  init_instance_init();
+  init_observer_stanza();
+  init_oss_compose();
+  SETUP_NODE_MODES = ["external", "stacks", "full"];
+  MissingSetupFlagError = class MissingSetupFlagError extends Error {
+    flag;
+    constructor(flag, message) {
+      super(message);
+      this.name = "MissingSetupFlagError";
+      this.flag = flag;
+    }
+  };
+});
+
+// src/lib/setup-tui.tsx
+var exports_setup_tui = {};
+__export(exports_setup_tui, {
+  runSetupTui: () => runSetupTui
+});
+import {
+  CliRenderEvents,
+  createCliRenderer
+} from "@opentui/core";
+import { createRoot, useKeyboard, useRenderer } from "@opentui/react";
+import { createContext, useContext, useEffect, useRef, useState } from "react";
+import { jsxDEV } from "@opentui/react/jsx-dev-runtime";
+function useTerminalThemeMode() {
+  const renderer = useRenderer();
+  const [mode, setMode] = useState(renderer.themeMode ?? "dark");
+  useEffect(() => {
+    let cancelled = false;
+    renderer.waitForThemeMode(500).then((resolved) => {
+      if (!cancelled && resolved)
+        setMode(resolved);
+    });
+    const onThemeMode = (next) => setMode(next);
+    renderer.on(CliRenderEvents.THEME_MODE, onThemeMode);
+    return () => {
+      cancelled = true;
+      renderer.off(CliRenderEvents.THEME_MODE, onThemeMode);
+    };
+  }, [renderer]);
+  return mode;
+}
+function formatFloor(f2) {
+  return `needs ≥ ${(f2.ramFloorMb / 1024).toFixed(0)}GB RAM, ≥ ${f2.diskFloorGb}GB disk`;
+}
+function useSpinner(active) {
+  const [frame, setFrame] = useState(0);
+  useEffect(() => {
+    if (!active)
+      return;
+    const id = setInterval(() => setFrame((f2) => (f2 + 1) % SPINNER_FRAMES.length), 80);
+    return () => clearInterval(id);
+  }, [active]);
+  return SPINNER_FRAMES[frame];
+}
+function App({ flags }) {
+  const renderer = useRenderer();
+  const themeMode = useTerminalThemeMode();
+  const colors2 = themeMode === "light" ? LIGHT_COLORS : DARK_COLORS;
+  const [stage, setStage] = useState("welcome");
+  const [network, setNetwork] = useState(safeParseNetwork(flags.network));
+  const [nodeMode, setNodeMode] = useState(safeParseNodeMode(flags.nodeMode));
+  const [preview, setPreview] = useState(guardrailPreview(NODE_MODE_OPTIONS[0].value, "mainnet"));
+  const [against, setAgainst] = useState(flags.against);
+  const [skipBootstrap, setSkipBootstrap] = useState(!!flags.skipBootstrap);
+  const [events, setEvents] = useState([]);
+  const [log, setLog] = useState([]);
+  const [fatal, setFatal] = useState(null);
+  const [summary, setSummary] = useState(null);
+  const started = useRef(false);
+  function exit(code) {
+    renderer.destroy();
+    process.exit(code);
+  }
+  useKeyboard((key) => {
+    if (key.eventType === "release")
+      return;
+    if ((stage === "done" || stage === "error") && (key.name === "q" || key.name === "return")) {
+      exit(fatal ? 1 : 0);
+      return;
+    }
+    if (stage === "welcome" && (key.name === "return" || key.name === "space")) {
+      advanceFromWelcome();
+      return;
+    }
+    if (stage === "welcome" && key.name === "q") {
+      exit(0);
+    }
+  });
+  function advanceFromWelcome() {
+    if (!network) {
+      setStage("network");
+    } else if (!nodeMode) {
+      setStage("nodeMode");
+    } else if (!against && !skipBootstrap) {
+      setStage("manifestChoice");
+    } else {
+      setStage("confirm");
+    }
+  }
+  function afterNetwork(net3) {
+    setNetwork(net3);
+    if (!nodeMode)
+      setStage("nodeMode");
+    else if (!against && !skipBootstrap)
+      setStage("manifestChoice");
+    else
+      setStage("confirm");
+  }
+  function afterNodeMode(mode) {
+    setNodeMode(mode);
+    if (!against && !skipBootstrap)
+      setStage("manifestChoice");
+    else
+      setStage("confirm");
+  }
+  const config = network && nodeMode ? {
+    network,
+    nodeMode,
+    apiPort: flags.apiPort ?? "127.0.0.1:3800",
+    indexerPort: "127.0.0.1:3700",
+    postgresPort: "127.0.0.1:5432",
+    dir: flags.dir ?? process.cwd(),
+    against: skipBootstrap ? undefined : against,
+    skipBootstrap,
+    skipVerify: !!flags.skipVerify,
+    yes: false,
+    force: !!flags.force,
+    owner: flags.owner ?? DEFAULT_IMAGE_OWNER,
+    imageTag: flags.imageTag ?? DEFAULT_IMAGE_TAG
+  } : null;
+  useEffect(() => {
+    if (stage !== "running" || started.current || !config)
+      return;
+    started.current = true;
+    let failed = false;
+    runSetup(config, (event) => {
+      setEvents((prev) => [...prev, event]);
+      if (event.type === "step-log") {
+        setLog((prev) => [...prev.slice(-40), event.line]);
+      }
+      if (event.type === "step-error") {
+        failed = true;
+        setLog((prev) => [...prev.slice(-40), `ERROR: ${event.message}`]);
+      }
+    }).then((result) => {
+      if (!result.ok) {
+        setFatal("Setup could not finish — see the log above.");
+        setStage("error");
+        return;
+      }
+      setSummary(result.summary ?? null);
+      setStage(failed ? "error" : "done");
+      if (failed)
+        setFatal("Setup finished but at least one step reported an error.");
+    }).catch((err) => {
+      setFatal(err instanceof Error ? err.message : String(err));
+      setStage("error");
+    });
+  }, [stage, config]);
+  return /* @__PURE__ */ jsxDEV(ColorsContext.Provider, {
+    value: colors2,
+    children: /* @__PURE__ */ jsxDEV("box", {
+      style: {
+        border: true,
+        borderStyle: "single",
+        borderColor: colors2.borderIdle,
+        backgroundColor: colors2.bg,
+        padding: 1
+      },
+      title: "secondlayer setup",
+      children: /* @__PURE__ */ jsxDEV("box", {
+        style: { flexDirection: "column" },
+        children: [
+          stage === "welcome" && /* @__PURE__ */ jsxDEV(Welcome, {}, undefined, false, undefined, this),
+          stage === "network" && /* @__PURE__ */ jsxDEV(Picker, {
+            title: "Network",
+            options: NETWORK_OPTIONS,
+            onSelect: (value) => afterNetwork(parseInstanceNetwork(value))
+          }, undefined, false, undefined, this),
+          stage === "nodeMode" && /* @__PURE__ */ jsxDEV(Picker, {
+            title: "Node mode",
+            options: NODE_MODE_OPTIONS,
+            subtitle: formatFloor(preview),
+            onChange: (value) => setPreview(guardrailPreview(parseSetupNodeMode(value), network ?? "mainnet")),
+            onSelect: (value) => afterNodeMode(parseSetupNodeMode(value))
+          }, undefined, false, undefined, this),
+          stage === "manifestChoice" && /* @__PURE__ */ jsxDEV(Picker, {
+            title: "Bootstrap from",
+            options: [
+              {
+                name: "Hosted archive (recommended)",
+                description: DEFAULT_ARCHIVE_MANIFEST,
+                value: "hosted"
+              },
+              {
+                name: "Custom manifest URL or path",
+                description: "Enter your own",
+                value: "custom"
+              },
+              {
+                name: "Sync from genesis",
+                description: "Skip bootstrap — slower, no download",
+                value: "skip"
+              }
+            ],
+            onSelect: (value) => {
+              if (value === "hosted") {
+                setAgainst(DEFAULT_ARCHIVE_MANIFEST);
+                setStage("confirm");
+              } else if (value === "skip") {
+                setSkipBootstrap(true);
+                setStage("confirm");
+              } else {
+                setStage("manifestInput");
+              }
+            }
+          }, undefined, false, undefined, this),
+          stage === "manifestInput" && /* @__PURE__ */ jsxDEV(ManifestInput, {
+            onSubmit: (value) => {
+              setAgainst(value.trim() || DEFAULT_ARCHIVE_MANIFEST);
+              setStage("confirm");
+            }
+          }, undefined, false, undefined, this),
+          stage === "confirm" && config && /* @__PURE__ */ jsxDEV(Confirm, {
+            config,
+            onConfirm: () => setStage("running")
+          }, undefined, false, undefined, this),
+          stage === "running" && /* @__PURE__ */ jsxDEV(RunningView, {
+            events,
+            log
+          }, undefined, false, undefined, this),
+          stage === "done" && summary && /* @__PURE__ */ jsxDEV(Done, {
+            summary
+          }, undefined, false, undefined, this),
+          stage === "error" && /* @__PURE__ */ jsxDEV(ErrorView, {
+            message: fatal ?? "Setup failed.",
+            log
+          }, undefined, false, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
+    }, undefined, false, undefined, this)
+  }, undefined, false, undefined, this);
+}
+function safeParseNetwork(value) {
+  if (!value)
+    return;
+  try {
+    return parseInstanceNetwork(value);
+  } catch {
+    return;
+  }
+}
+function safeParseNodeMode(value) {
+  if (!value)
+    return;
+  try {
+    return parseSetupNodeMode(value);
+  } catch {
+    return;
+  }
+}
+function Welcome() {
+  const colors2 = useContext(ColorsContext);
+  return /* @__PURE__ */ jsxDEV("box", {
+    style: { flexDirection: "column" },
+    children: [
+      /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.bright,
+        children: "Guided self-host setup."
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.muted,
+        children: [
+          `
+`,
+          "This writes secrets, a docker-compose file, and .env into a target directory, brings the stack up, and (optionally) restores verified history from the archive.",
+          `
+
+`,
+          "Press Enter to begin, or q to quit."
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+function Picker({
+  title,
+  subtitle,
+  options: options3,
+  onChange,
+  onSelect
+}) {
+  const colors2 = useContext(ColorsContext);
+  return /* @__PURE__ */ jsxDEV("box", {
+    style: { flexDirection: "column" },
+    children: [
+      /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.bright,
+        children: title
+      }, undefined, false, undefined, this),
+      subtitle && /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.accent,
+        children: subtitle
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV("select", {
+        style: { height: options3.length * 2 + 1 },
+        options: options3,
+        focused: true,
+        showDescription: true,
+        backgroundColor: "transparent",
+        textColor: colors2.fg,
+        focusedBackgroundColor: colors2.raise,
+        focusedTextColor: colors2.bright,
+        selectedBackgroundColor: colors2.raise,
+        selectedTextColor: colors2.accent,
+        descriptionColor: colors2.muted,
+        selectedDescriptionColor: colors2.fg,
+        onChange: (_index, option) => {
+          if (option)
+            onChange?.(String(option.value));
+        },
+        onSelect: (_index, option) => {
+          if (option)
+            onSelect(String(option.value));
+        }
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.muted,
+        children: [
+          `
+`,
+          "↑↓ to move, enter to choose"
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+function ManifestInput({ onSubmit }) {
+  const colors2 = useContext(ColorsContext);
+  return /* @__PURE__ */ jsxDEV("box", {
+    style: { flexDirection: "column" },
+    children: [
+      /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.bright,
+        children: "Manifest URL or local path"
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.muted,
+        children: [
+          "Suggested: ",
+          DEFAULT_ARCHIVE_MANIFEST
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV("input", {
+        focused: true,
+        placeholder: DEFAULT_ARCHIVE_MANIFEST,
+        textColor: colors2.fg,
+        focusedTextColor: colors2.accent,
+        placeholderColor: colors2.muted,
+        onSubmit: (value) => onSubmit(String(value ?? ""))
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.muted,
+        children: [
+          `
+`,
+          "enter to accept (blank = suggested default)"
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+function Confirm({
+  config,
+  onConfirm
+}) {
+  const colors2 = useContext(ColorsContext);
+  useKeyboard((key) => {
+    if (key.eventType === "release")
+      return;
+    if (key.name === "return")
+      onConfirm();
+  });
+  return /* @__PURE__ */ jsxDEV("box", {
+    style: { flexDirection: "column" },
+    children: [
+      /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.bright,
+        children: "Ready"
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.fg,
+        children: [
+          `
+`,
+          "network ",
+          config.network,
+          `
+`,
+          "node mode ",
+          config.nodeMode,
+          `
+`,
+          "dir ",
+          config.dir,
+          `
+`,
+          "api port ",
+          config.apiPort,
+          `
+`,
+          "bootstrap",
+          " ",
+          config.skipBootstrap ? "skip (sync from genesis)" : config.against,
+          `
+`,
+          "image ghcr.io/",
+          config.owner,
+          "/secondlayer-runtime:",
+          config.imageTag
+        ]
+      }, undefined, true, undefined, this),
+      /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.accent,
+        children: [
+          `
+`,
+          "Press Enter to start."
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+function RunningView({ events, log }) {
+  const colors2 = useContext(ColorsContext);
+  const latestByStep = new Map;
+  for (const e2 of events)
+    latestByStep.set(e2.step, e2);
+  const anyActive = STEP_ORDER.some((step) => latestByStep.get(step)?.type === "step-start");
+  const spinner = useSpinner(anyActive);
+  return /* @__PURE__ */ jsxDEV("box", {
+    style: { flexDirection: "column" },
+    children: [
+      STEP_ORDER.map((step) => {
+        const e2 = latestByStep.get(step);
+        const active = e2?.type === "step-start";
+        const symbol = !e2 ? "·" : active ? spinner : e2.type === "step-done" ? "✓" : e2.type === "step-skip" ? "–" : e2.type === "step-error" ? "✗" : " ";
+        const color = active ? colors2.accent : e2?.type === "step-done" ? colors2.success : e2?.type === "step-error" ? colors2.error : e2?.type === "step-skip" ? colors2.muted : colors2.muted;
+        return /* @__PURE__ */ jsxDEV("text", {
+          fg: color,
+          children: [
+            symbol,
+            " ",
+            STEP_LABEL[step]
+          ]
+        }, step, true, undefined, this);
+      }),
+      /* @__PURE__ */ jsxDEV("box", {
+        style: {
+          border: true,
+          borderStyle: "single",
+          borderColor: colors2.borderIdle,
+          marginTop: 1,
+          height: 10
+        },
+        title: "log",
+        children: /* @__PURE__ */ jsxDEV("box", {
+          style: { flexDirection: "column", padding: 1 },
+          children: log.length === 0 ? /* @__PURE__ */ jsxDEV("text", {
+            fg: colors2.muted,
+            children: "waiting…"
+          }, undefined, false, undefined, this) : log.map((line, i3) => /* @__PURE__ */ jsxDEV("text", {
+            fg: line.startsWith("ERROR:") ? colors2.error : colors2.fg,
+            children: line
+          }, `${i3}:${line}`, false, undefined, this))
+        }, undefined, false, undefined, this)
+      }, undefined, false, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+function Done({ summary }) {
+  const colors2 = useContext(ColorsContext);
+  return /* @__PURE__ */ jsxDEV("box", {
+    style: { flexDirection: "column" },
+    children: [
+      /* @__PURE__ */ jsxDEV("box", {
+        style: { backgroundColor: colors2.successBg, padding: 1 },
+        children: /* @__PURE__ */ jsxDEV("text", {
+          fg: colors2.success,
+          children: summary
+        }, undefined, false, undefined, this)
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.muted,
+        children: [
+          `
+`,
+          "press enter or q to exit"
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+function ErrorView({ message, log }) {
+  const colors2 = useContext(ColorsContext);
+  return /* @__PURE__ */ jsxDEV("box", {
+    style: { flexDirection: "column" },
+    children: [
+      /* @__PURE__ */ jsxDEV("box", {
+        style: { backgroundColor: colors2.errorBg, padding: 1 },
+        children: /* @__PURE__ */ jsxDEV("text", {
+          fg: colors2.error,
+          children: message
+        }, undefined, false, undefined, this)
+      }, undefined, false, undefined, this),
+      log.slice(-10).map((line, i3) => /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.muted,
+        children: line
+      }, `${i3}:${line}`, false, undefined, this)),
+      /* @__PURE__ */ jsxDEV("text", {
+        fg: colors2.muted,
+        children: [
+          `
+`,
+          "press enter or q to exit"
+        ]
+      }, undefined, true, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
+async function runSetupTui(flags) {
+  const renderer = await createCliRenderer({ exitOnCtrlC: true });
+  createRoot(renderer).render(/* @__PURE__ */ jsxDEV(App, {
+    flags
+  }, undefined, false, undefined, this));
+  return new Promise((resolve16, reject) => {
+    let settled = false;
+    const onDestroy = () => {
+      if (settled)
+        return;
+      settled = true;
+      resolve16();
+    };
+    const onError = (event) => {
+      if (settled)
+        return;
+      settled = true;
+      try {
+        renderer.destroy();
+      } catch {}
+      reject(event.error ?? new Error("OpenTUI renderer error"));
+    };
+    renderer.once(CliRenderEvents.DESTROY, onDestroy);
+    renderer.once(CliRenderEvents.RENDER_ERROR, onError);
+    renderer.once(CliRenderEvents.HANDLER_ERROR, onError);
+  });
+}
+var DARK_COLORS, LIGHT_COLORS, ColorsContext, NETWORK_OPTIONS, NODE_MODE_OPTIONS, SPINNER_FRAMES, STEP_LABEL, STEP_ORDER;
+var init_setup_tui = __esm(() => {
+  init_instance_init();
+  init_oss_compose();
+  init_setup_wizard();
+  DARK_COLORS = {
+    bg: "#151515",
+    raise: "#202020",
+    fg: "#d7d1c9",
+    muted: "#8d867e",
+    bright: "#f2ede5",
+    accent: "#29c6be",
+    success: "#22c55e",
+    warning: "#eab308",
+    error: "#ef4444",
+    borderIdle: "#FFFFFF14",
+    successBg: "#22c55e14",
+    errorBg: "#ef444414"
+  };
+  LIGHT_COLORS = {
+    bg: "#ffffff",
+    raise: "#f8f6f2",
+    fg: "#1f2228",
+    muted: "#7d8288",
+    bright: "#0a0a0a",
+    accent: "#29c6be",
+    success: "#22c55e",
+    warning: "#eab308",
+    error: "#ef4444",
+    borderIdle: "#0A0A0A14",
+    successBg: "#22c55e14",
+    errorBg: "#ef444414"
+  };
+  ColorsContext = createContext(DARK_COLORS);
+  NETWORK_OPTIONS = [
+    {
+      name: "mainnet",
+      description: "Production Stacks chain. Large: plan for hundreds of GB.",
+      value: "mainnet"
+    },
+    {
+      name: "testnet",
+      description: "Stacks testnet. Small history.",
+      value: "testnet"
+    },
+    { name: "devnet", description: "Local Clarinet devnet.", value: "devnet" }
+  ];
+  NODE_MODE_OPTIONS = SETUP_NODE_MODES.map((mode) => ({
+    name: mode,
+    description: mode === "external" ? "You run the Stacks node; paste an observer stanza into its Config.toml." : mode === "stacks" ? "You run the Stacks node yourself, no bundled bitcoind (same as external — no bundled-stacks-only profile exists)." : "Bundled Stacks node + bitcoind.",
+    value: mode
+  }));
+  SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  STEP_LABEL = {
+    preflight: "Preflight",
+    secrets: "Secrets",
+    config: "Write config",
+    "docker-up": "docker compose up",
+    observer: "Observer stanza",
+    bootstrap: "Bootstrap",
+    verify: "Verify",
+    summary: "Summary"
+  };
+  STEP_ORDER = Object.keys(STEP_LABEL);
+});
+
+// ../../node_modules/commander/esm.mjs
+var import__ = __toESM(require_commander(), 1);
+var {
+  program,
+  createCommand,
+  createArgument,
+  createOption,
+  CommanderError,
+  InvalidArgumentError,
+  InvalidOptionArgumentError,
+  Command,
+  Argument,
+  Option,
+  Help
+} = import__.default;
 // package.json
 var package_default = {
   name: "@secondlayer/cli",
-  version: "12.2.0",
+  version: "13.0.1",
   description: "Run a Stacks index on your own hardware — set it up, restore verified history, and keep it current.",
   repository: {
     type: "git",
@@ -34361,13 +36140,16 @@ var package_default = {
     "@biomejs/wasm-nodejs": "^1.9.0",
     "@dsnp/parquetjs": "^1.8.8",
     "@inquirer/prompts": "^8.2.0",
+    "@opentui/core": "^0.5.3",
+    "@opentui/react": "^0.5.3",
     "@secondlayer/bundler": "^0.5.1",
     "@secondlayer/scaffold": "^1.5.4",
-    "@secondlayer/sdk": "^8.0.1",
-    "@secondlayer/shared": "^10.0.1",
+    "@secondlayer/sdk": "^9.0.0",
+    "@secondlayer/shared": "^11.0.0",
     "@secondlayer/stacks": "^4.0.0",
-    "@secondlayer/subgraphs": "^4.0.2",
+    "@secondlayer/subgraphs": "^4.0.4",
     esbuild: "^0.27.4",
+    react: "^19.1.0",
     "smol-toml": "^1.6.1",
     zod: "^4.3.6"
   },
@@ -34381,8 +36163,7 @@ var package_default = {
     commander: "^14.0.0",
     execa: "^9.5.3",
     "fast-glob": "^3.3.3",
-    got: "^13.0.0",
-    react: "^19.1.0"
+    got: "^13.0.0"
   }
 };
 
@@ -34498,10 +36279,30 @@ async function runRefill(opts) {
     }
   });
 }
-
-// src/commands/index.ts
-init_codegen();
-
+// src/commands/codegen.ts
+function registerCodegenCommand(program2) {
+  const codegen = program2.command("codegen").description("Generate typed code: contracts, subgraphs, Index, clients");
+  codegen.command("contracts [files...]").description("Generate TypeScript interfaces from Clarity contracts").option("-c, --config <path>", "Path to config file").option("-o, --output <path>", "Output file path").option("-k, --api-key <key>", "Stacks node API key for direct RPC URLs").option("-w, --watch", "Watch for changes").action(async (files, options3) => {
+    const { generate: generate2 } = await Promise.resolve().then(() => (init_generate(), exports_generate));
+    await generate2(files, { ...options3, out: options3.output });
+  });
+  codegen.command("subgraph <file>").description("Generate an ORM schema (Kysely, Prisma, or Drizzle) for a subgraph's tables").option("--target <orm>", "ORM target: kysely | prisma | drizzle", "kysely").option("--schema <name>", "Postgres schema name (defaults to subgraph_<name>)").option("--env <var>", "datasource url env var", "DATABASE_URL").option("--models-only", "Emit only Prisma models (compose via prismaSchemaFolder)").option("-o, --output <path>", "Write to a file (defaults to stdout)").action(async (file, options3, command) => {
+    const { runSubgraphSchemaCodegen: runSubgraphSchemaCodegen2 } = await Promise.resolve().then(() => (init_subgraphs2(), exports_subgraphs));
+    await runSubgraphSchemaCodegen2(file, options3, (key) => command.getOptionValueSource(key), "kysely");
+  });
+  codegen.command("index").description("Generate a typed schema (Kysely, Prisma, Drizzle, or JSON-Schema) for the Index domain tables").option("--target <orm>", "kysely | prisma | drizzle | json-schema", "kysely").option("--schema <name>", "Postgres schema to qualify table names with").option("--tables <list>", "Comma-separated subset of Index tables (default: all)").option("--env <var>", "Prisma datasource url env var", "DATABASE_URL").option("-o, --output <path>", "Write to a file (defaults to stdout)").action(async (options3) => {
+    const { runIndexCodegen: runIndexCodegen2 } = await Promise.resolve().then(() => (init_index_api(), exports_index_api));
+    await runIndexCodegen2(options3);
+  });
+  codegen.command("client <subgraphName>").description("Generate a typed query client for a deployed subgraph").option("-o, --output <path>", "Output file path (required)").action(async (subgraphName, options3) => {
+    const { runSubgraphClientCodegen: runSubgraphClientCodegen2 } = await Promise.resolve().then(() => (init_subgraphs2(), exports_subgraphs));
+    await runSubgraphClientCodegen2(subgraphName, options3);
+  });
+  codegen.command("prints <file>").description("Emit a .d.ts of print payload types for a subgraph's pinned print_event sources (inferred from observed on-chain events; requires network)").option("-o, --output <path>", "Write to a file (defaults to stdout)").action(async (file, options3) => {
+    const { runPayloadsCodegen: runPayloadsCodegen2 } = await Promise.resolve().then(() => (init_subgraphs2(), exports_subgraphs));
+    await runPayloadsCodegen2(file, options3.output);
+  });
+}
 // src/commands/config.ts
 init_config2();
 
@@ -34959,22 +36760,138 @@ function registerConsoleCommand(program2) {
     }
   });
 }
+// src/commands/context.ts
+init_http();
+import { SecondLayer as SecondLayer2 } from "@secondlayer/sdk";
+
+// src/lib/instance-diagnosis.ts
+var BOOTSTRAP_STEP = "Restore verified history: secondlayer bootstrap --against <manifest>";
+var OBSERVER_STEP = "Confirm your node streams into this instance — secondlayer observer --mode indexer --endpoint secondlayer:3700 prints the stanza its config needs";
+var SELF_HOST_DOCS_STEP = "Docs: https://www.secondlayer.tools/docs/self-host";
+function hasNoChainData(status) {
+  const integrity = status.chainIntegrity;
+  if (!integrity || integrity.reason === "check_failed")
+    return false;
+  if (integrity.maxHeight !== 0)
+    return false;
+  return (status.chainTip ?? null) === null;
+}
+function emptyIndexIssue(status) {
+  const decoders = status.index?.decoders ?? [];
+  const stalled = decoders.filter((d2) => d2.status !== "ok").length;
+  const decoderClause = stalled > 0 ? ` and ${stalled} decoder${stalled === 1 ? "" : "s"} report unavailable because there is nothing to decode` : "";
+  return {
+    title: "No blocks indexed yet — this instance holds 0 blocks.",
+    detail: `Streams has no tip${decoderClause}, which is what makes the overall status DEGRADED. This is the expected state for a fresh instance: nothing is broken, but no read returns data until history lands.`,
+    nextSteps: [BOOTSTRAP_STEP, OBSERVER_STEP, SELF_HOST_DOCS_STEP]
+  };
+}
+var SERVICE_STEPS = [
+  "See the raw per-service report: secondlayer status --json",
+  "Check the containers from docker/oss: docker compose ps, then docker compose logs --tail=50 secondlayer"
+];
+function diagnoseInstanceStatus(status) {
+  const overall = String(status.status ?? "unknown");
+  if (hasNoChainData(status)) {
+    return { state: "empty-index", overall, issues: [emptyIndexIssue(status)] };
+  }
+  const issues = [];
+  for (const service of status.services ?? []) {
+    if (service.status === "ok")
+      continue;
+    issues.push({
+      title: `Service ${service.name} reports ${service.status}.`,
+      nextSteps: SERVICE_STEPS
+    });
+  }
+  const integrity = status.chainIntegrity;
+  if (integrity && integrity.ok === false) {
+    issues.push({
+      title: "Chain-data integrity check failed.",
+      detail: integrity.reason ?? "The tip the instance serves is not backed by the history it implies.",
+      nextSteps: [
+        "Verify against the archive: secondlayer verify all --against <manifest>",
+        "Repair what diverged: secondlayer repair --against <manifest> --apply"
+      ]
+    });
+  }
+  if (issues.length === 0 && overall !== "healthy") {
+    issues.push({
+      title: `The API reports status=${overall} but names no failing service.`,
+      detail: "Every service in the report is ok, so the degradation is in a surface this command does not summarize.",
+      nextSteps: SERVICE_STEPS
+    });
+  }
+  return {
+    state: issues.length > 0 ? "degraded" : "healthy",
+    overall,
+    issues
+  };
+}
+var CONTEXT_FIELDS = [
+  "account",
+  "streamsTip",
+  "indexTip",
+  "subgraphs",
+  "subscriptions",
+  "activeOperations"
+];
+function explainContextNulls(snapshot, probe) {
+  const nullFields = CONTEXT_FIELDS.filter((field) => (snapshot[field] ?? null) === null);
+  if (nullFields.length === 0) {
+    return { summary: "Every field resolved.", nulls: {} };
+  }
+  if (!probe.status) {
+    const reason = `No instance answered at ${probe.apiUrl} (${probe.statusError ?? "unreachable"}), so this read never reached an API.`;
+    return {
+      summary: `${reason} Start it from docker/oss with: docker compose up -d — or point SL_API_URL at the instance you meant.`,
+      nulls: Object.fromEntries(nullFields.map((field) => [field, reason]))
+    };
+  }
+  const emptyIndex = hasNoChainData(probe.status);
+  const blocks = probe.status.chainIntegrity?.maxHeight ?? null;
+  const accountReason = probe.selfHosted ? "Expected: a self-hosted instance has no account system. Accounts exist only on the metered archive deployment at api.secondlayer.tools, so null here is normal and not a failure." : "Not authenticated — run `secondlayer login`, or export INSTANCE_TOKEN.";
+  const listReason = unresolvedReadReason(probe, blocks);
+  const chainReason = emptyIndex ? `No blocks indexed yet — this instance holds 0 blocks, so there is no tip to report. ${BOOTSTRAP_STEP}` : listReason;
+  const nulls = {};
+  for (const field of nullFields) {
+    if (field === "account")
+      nulls[field] = accountReason;
+    else if (field === "streamsTip" || field === "indexTip")
+      nulls[field] = chainReason;
+    else if (field === "activeOperations")
+      nulls[field] = (snapshot.subgraphs ?? null) === null ? "Not probed: in-flight operations are read per subgraph, and the subgraph list did not resolve." : listReason;
+    else
+      nulls[field] = listReason;
+  }
+  const summary = emptyIndex ? `Instance at ${probe.apiUrl} is reachable but holds 0 blocks — the chain fields are null because nothing has been indexed yet. ${BOOTSTRAP_STEP}` : nullFields.length === 1 && nullFields[0] === "account" ? `Instance at ${probe.apiUrl} is reachable and indexed to block ${blocks ?? "unknown"}; only \`account\` is null, which is normal when self-hosting.` : `Instance at ${probe.apiUrl} is reachable, but ${nullFields.length} field${nullFields.length === 1 ? "" : "s"} did not resolve — see \`nulls\` below for each one.`;
+  return { summary, nulls };
+}
+function unresolvedReadReason(probe, blocks) {
+  const where = `The instance at ${probe.apiUrl} is reachable${blocks !== null ? ` and indexed to block ${blocks}` : ""}, but this read returned nothing.`;
+  return probe.hasCredential ? `${where} Check the surface directly: secondlayer status --json` : `${where} No credential resolved: export INSTANCE_TOKEN — an instance published past loopback requires it on every /v1 read.`;
+}
+
 // src/commands/context.ts
 init_output();
 init_resolve_auth();
-import { SecondLayer as SecondLayer2 } from "@secondlayer/sdk";
 function registerContextCommand(program2) {
   program2.command("context").description("Print an agent orientation snapshot: account, live Streams/Index tips, your subgraphs/subscriptions, and in-flight reindex operations").option("--json", "Print as JSON (default)").action(async (o3) => {
     try {
-      const sl = new SecondLayer2({
-        baseUrl: resolveApiUrl(),
-        apiKey: resolveEnvKey()
-      });
+      const apiUrl = resolveApiUrl();
+      const apiKey = resolveEnvKey();
+      const sl = new SecondLayer2({ baseUrl: apiUrl, apiKey });
       const snapshot = await sl.context();
+      const diagnostics = await explain(snapshot, apiUrl, apiKey);
+      const payload = { ...snapshot, diagnostics };
       output({
         json: o3.json,
-        data: snapshot,
-        human: () => writeData(JSON.stringify(snapshot, null, 2))
+        data: payload,
+        human: () => {
+          writeData(JSON.stringify(payload, null, 2));
+          if (diagnostics)
+            note(diagnostics.summary);
+        }
       });
     } catch (err) {
       error(err instanceof Error ? err.message : String(err));
@@ -34982,6 +36899,25 @@ function registerContextCommand(program2) {
     }
   });
 }
+async function explain(snapshot, apiUrl, apiKey) {
+  const hasNull = Object.values(snapshot).some((v2) => (v2 ?? null) === null);
+  if (!hasNull)
+    return null;
+  let status = null;
+  let statusError;
+  try {
+    status = await httpPlatformAnon("/public/status");
+  } catch (err) {
+    statusError = err instanceof Error ? err.message : String(err);
+  }
+  return explainContextNulls(snapshot, {
+    apiUrl,
+    selfHosted: isOssMode(),
+    hasCredential: Boolean(apiKey),
+    status,
+    statusError
+  });
+}
 // src/commands/status.ts
 init_http();
 init_output();
@@ -34990,10 +36926,11 @@ function registerStatusCommand(program2) {
   program2.command("status").description("Show local instance status").option("--json", "Output as JSON").action(async (options3) => {
     try {
       const status = await httpPlatformAnon("/public/status");
+      const diagnosis = diagnoseInstanceStatus(status);
       output({
         json: options3.json,
-        data: status,
-        human: () => printPublicStatus(status)
+        data: { ...status, diagnosis },
+        human: () => printPublicStatus(status, diagnosis)
       });
     } catch {
       console.log("");
@@ -35007,7 +36944,7 @@ function registerStatusCommand(program2) {
     }
   });
 }
-function printPublicStatus(status) {
+function printPublicStatus(status, diagnosis) {
   const overall = String(status.status ?? "unknown");
   const color = overall === "healthy" ? green : red;
   console.log("");
@@ -35045,6 +36982,19 @@ function printPublicStatus(status) {
     }
     console.log("");
   }
+  if (diagnosis.issues.length > 0) {
+    console.log(blue("Diagnosis"));
+    for (const issue of diagnosis.issues) {
+      console.log(`  ${yellow(issue.title)}`);
+      for (const line of issue.detail ? wrapText(issue.detail, 74) : []) {
+        console.log(dim(`  ${line}`));
+      }
+      for (const step of issue.nextSteps) {
+        console.log(dim(`    → ${step}`));
+      }
+    }
+    console.log("");
+  }
   if (typeof status.timestamp === "string") {
     console.log(dim(`Last updated: ${status.timestamp}`));
   }
@@ -35061,7 +37011,7 @@ import {
   validateSubscriptionFilterForTable
 } from "@secondlayer/shared/schemas/subscriptions";
 async function validateSubscriptionTargetFromApi(client2, input2) {
-  const subgraph = await client2.subgraphs.get(input2.subgraphName);
+  const subgraph = await client2.subgraphs.status(input2.subgraphName);
   const errors2 = validateSubscriptionFilterForTable({
     subgraphName: input2.subgraphName,
     tableName: input2.tableName,
@@ -35876,7 +37826,7 @@ Examples:
     try {
       const client2 = await getSubscriptionClient();
       const { id } = await resolveSubscriptionRef(client2, idOrName);
-      const { data } = await client2.subscriptions.recentDeliveries(id);
+      const { data } = await client2.subscriptions.deliveries(id);
       if (options3.json)
         printJson(data);
       else
@@ -35905,7 +37855,7 @@ Examples:
       const ok = await confirmOrExit(`Requeue ${outboxId} for "${detail.name}"?`, options3.yes);
       if (!ok)
         return;
-      const res = await client2.subscriptions.requeueDead(id, outboxId);
+      const res = await client2.subscriptions.requeue(id, outboxId);
       if (options3.json)
         printJson(res);
       else
@@ -35950,9 +37900,9 @@ Examples:
       const client2 = await getSubscriptionClient();
       const { id, detail } = await resolveSubscriptionRef(client2, idOrName);
       const [deliveries, dead, subgraph] = await Promise.allSettled([
-        client2.subscriptions.recentDeliveries(id),
+        client2.subscriptions.deliveries(id),
         client2.subscriptions.dead(id),
-        detail.subgraphName ? client2.subgraphs.get(detail.subgraphName) : Promise.resolve(null)
+        detail.subgraphName ? client2.subgraphs.status(detail.subgraphName) : Promise.resolve(null)
       ]);
       const report = buildDoctorReport({
         subscription: detail,
@@ -35973,7 +37923,7 @@ Examples:
       const signingSecret = resolveSigningSecret(options3);
       const client2 = await getSubscriptionClient();
       const { detail } = await resolveSubscriptionRef(client2, idOrName);
-      const subgraph = detail.subgraphName ? await client2.subgraphs.get(detail.subgraphName).catch(() => null) : null;
+      const subgraph = detail.subgraphName ? await client2.subgraphs.status(detail.subgraphName).catch(() => null) : null;
       const row = await representativeRow(client2, detail, subgraph);
       const fixture = buildSubscriptionTestFixture({
         subscription: detail,
@@ -36027,152 +37977,10 @@ POST result (client-side, not logged):`));
   });
 }
 // src/commands/devnet.ts
-import { spawnSync as spawnSync2 } from "node:child_process";
+import { spawnSync as spawnSync3 } from "node:child_process";
 import { existsSync as existsSync6, mkdirSync as mkdirSync4, writeFileSync as writeFileSync6 } from "node:fs";
 import { dirname as dirname8, join as join9 } from "node:path";
 
-// src/lib/devnet-compose.ts
-var DEFAULT_IMAGE_OWNER = "ryanwaits";
-var DEFAULT_IMAGE_TAG = "latest";
-function buildDevnetCompose(opts = {}) {
-  const owner = opts.owner ?? DEFAULT_IMAGE_OWNER;
-  const tag = opts.imageTag ?? DEFAULT_IMAGE_TAG;
-  const apiPort = opts.apiPort ?? 3800;
-  const indexerPort = opts.indexerPort ?? 3700;
-  const apiImage = `ghcr.io/${owner}/secondlayer-api:${tag}`;
-  const indexerImage = `ghcr.io/${owner}/secondlayer-indexer:${tag}`;
-  const dbUrl = "postgres://secondlayer:secondlayer@postgres:5432/secondlayer";
-  const DEV_SECRETS_KEY = "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef";
-  const DEV_INSTANCE_TOKEN = "dev-instance-token";
-  return `# Generated by \`secondlayer devnet connect\` — do not edit by hand.
-# Secondlayer app services for local clarinet devnet development.
-name: secondlayer-devnet
-
-services:
-  postgres:
-    image: postgres:17-alpine
-    environment:
-      POSTGRES_USER: secondlayer
-      POSTGRES_PASSWORD: secondlayer
-      POSTGRES_DB: secondlayer
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U secondlayer"]
-      interval: 5s
-      timeout: 5s
-      retries: 10
-    restart: unless-stopped
-
-  migrate:
-    image: ${apiImage}
-    command: ["bun", "run", "packages/shared/src/db/migrate.ts"]
-    environment:
-      DATABASE_URL: ${dbUrl}
-    depends_on:
-      postgres:
-        condition: service_healthy
-    restart: "no"
-
-  api:
-    image: ${apiImage}
-    environment:
-      INSTANCE_MODE: oss
-      DATABASE_URL: ${dbUrl}
-      PORT: 3800
-      LISTEN_HOST: "0.0.0.0"
-      INSTANCE_TOKEN: ${DEV_INSTANCE_TOKEN}
-      NODE_ENV: production
-      DATA_DIR: /data
-      # Shared across api + subgraph-processor so the secret the api encrypts
-      # (e.g. a subscription's signing secret) can be decrypted by the emitter.
-      # OSS auto-generates a per-process key when unset — that splits them.
-      # Local-dev fixed value; not a production secret.
-      SECONDLAYER_SECRETS_KEY: ${DEV_SECRETS_KEY}
-    ports:
-      - "${apiPort}:3800"
-    volumes:
-      - subgraphs_data:/data/subgraphs
-    depends_on:
-      migrate:
-        condition: service_completed_successfully
-      postgres:
-        condition: service_healthy
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:3800/health"]
-      interval: 10s
-      timeout: 3s
-      start_period: 10s
-      retries: 5
-    restart: unless-stopped
-
-  indexer:
-    image: ${indexerImage}
-    environment:
-      DATABASE_URL: ${dbUrl}
-      PORT: 3700
-      NODE_ENV: production
-      # Keep every network key aligned: the indexer writes index_progress under
-      # STACKS_NETWORK, the subgraph processor reads it under NETWORK. If they
-      # differ, catch-up finds no progress row and subgraphs never advance.
-      NETWORKS: testnet
-      STACKS_NETWORK: testnet
-      NETWORK: testnet
-      # Fed by the devnet node's event observer — never reach out to Hiro mainnet.
-      AUTO_BACKFILL_ENABLED: "false"
-      TIP_FOLLOWER_ENABLED: "false"
-    # Bind on all interfaces so the devnet's stacks-node container can POST to
-    # host.docker.internal:3700.
-    ports:
-      - "${indexerPort}:3700"
-    extra_hosts:
-      - "host.docker.internal:host-gateway"
-    depends_on:
-      migrate:
-        condition: service_completed_successfully
-      postgres:
-        condition: service_healthy
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:3700/health"]
-      interval: 10s
-      timeout: 3s
-      start_period: 10s
-      retries: 5
-    restart: unless-stopped
-
-  subgraph-processor:
-    image: ${apiImage}
-    command: ["bun", "run", "packages/subgraphs/src/service.ts"]
-    environment:
-      DATABASE_URL: ${dbUrl}
-      NODE_ENV: production
-      DATA_DIR: /data
-      # Must match the indexer's network key (see indexer note) — catch-up reads
-      # index_progress under NETWORK.
-      NETWORK: testnet
-      STACKS_NETWORK: testnet
-      # The emitter blocks webhook delivery to private/loopback IPs by default.
-      # On a local devnet you deliver to your own localhost receiver, so allow it.
-      SECONDLAYER_ALLOW_PRIVATE_EGRESS: "true"
-      # Must match the api's key so the emitter can decrypt signing secrets.
-      SECONDLAYER_SECRETS_KEY: ${DEV_SECRETS_KEY}
-    volumes:
-      - subgraphs_data:/data/subgraphs
-    depends_on:
-      migrate:
-        condition: service_completed_successfully
-      postgres:
-        condition: service_healthy
-    healthcheck:
-      disable: true
-    restart: unless-stopped
-
-volumes:
-  postgres_data:
-  subgraphs_data:
-`;
-}
-
 // src/lib/devnet-config.ts
 import { existsSync as existsSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "node:fs";
 import { dirname as dirname7, join as join7, parse as parsePath } from "node:path";
@@ -36229,6 +38037,7 @@ stacks_node_events_observers = [${entry}]
 
 // src/commands/devnet.ts
 init_output();
+init_resolve_auth();
 
 // src/commands/faucet.ts
 import { randomBytes as randomBytes2 } from "node:crypto";
@@ -36362,7 +38171,7 @@ is what makes minting possible without Bitcoin.`).action(async (opts) => {
 // src/commands/devnet.ts
 var COMPOSE_REL = join9(".secondlayer", "docker-compose.yml");
 function ensureDocker() {
-  const probe = spawnSync2("docker", ["info"], { stdio: "ignore" });
+  const probe = spawnSync3("docker", ["info"], { stdio: "ignore" });
   if (probe.error || probe.status !== 0) {
     error(`Docker isn't available.
 
@@ -36373,7 +38182,7 @@ function ensureDocker() {
   }
 }
 function dockerCompose(composePath, args) {
-  const res = spawnSync2("docker", ["compose", "-f", composePath, ...args], {
+  const res = spawnSync3("docker", ["compose", "-f", composePath, ...args], {
     stdio: "inherit"
   });
   return res.status ?? 1;
@@ -36455,7 +38264,10 @@ ${bold("Secondlayer stack up")}`);
   console.log(`
 ${bold("Next:")}`);
   console.log(`  ${yellow("clarinet devnet start")}   ${dim("# auto-deploys + streams to the indexer")}`);
-  console.log(`  ${yellow("SL_API_URL=http://localhost:3800 SL_API_KEY=dummy secondlayer subgraphs deploy ./subgraph.ts")}`);
+  console.log(`  ${yellow(`SL_API_URL=http://localhost:3800 INSTANCE_TOKEN=${DEV_INSTANCE_TOKEN} secondlayer subgraphs deploy ./subgraph.ts`)}`);
+  console.log(dim(`
+The api is published on 127.0.0.1 only: /v1 reads need no credential.
+Writes (deploys, subscriptions) send INSTANCE_TOKEN=${DEV_INSTANCE_TOKEN}.`));
   console.log(dim(`
 Stop with: secondlayer devnet down`));
 }
@@ -36495,12 +38307,18 @@ async function logs(service, options3) {
 }
 async function jget(url) {
   try {
-    const r2 = await fetch(url, { signal: AbortSignal.timeout(1500) });
+    const r2 = await fetch(url, {
+      signal: AbortSignal.timeout(1500),
+      headers: { authorization: `Bearer ${statusToken()}` }
+    });
     return r2.ok ? await r2.json() : null;
   } catch {
     return null;
   }
 }
+function statusToken() {
+  return resolveEnvKey() ?? DEV_INSTANCE_TOKEN;
+}
 var SYS_COLS = new Set([
   "_id",
   "_block_height",
@@ -36752,10 +38570,7 @@ Examples:
       process.exit(1);
     }
   });
-  streams.command("pull").description("Download finalized bulk parquet dumps to a local dir (verifies sha256)").requiredOption("--to <dir>", "output directory").option("--dumps-url <url>", "public dumps base URL (or SL_STREAMS_DUMPS_URL)").option("--from-block <n>", "only files covering blocks >= n").option("--to-block <n>", "only files covering blocks <= n").addHelpText("after", `
-Examples:
-  $ secondlayer streams pull --to ./dump
-  $ secondlayer streams pull --to ./dump --from-block 150000 --to-block 200000`).action(async (options3) => {
+  const runDumps = async (options3) => {
     try {
       const fromBlock = parseHeight(options3.fromBlock, "--from-block");
       const toBlock = parseHeight(options3.toBlock, "--to-block");
@@ -36784,7 +38599,11 @@ Examples:
       error(err instanceof Error ? err.message : String(err));
       process.exit(1);
     }
-  });
+  };
+  streams.command("dumps").description("Download finalized bulk parquet dumps to a local dir (verifies sha256)").requiredOption("--to <dir>", "output directory").option("--dumps-url <url>", "public dumps base URL (or SL_STREAMS_DUMPS_URL)").option("--from-block <n>", "only files covering blocks >= n").option("--to-block <n>", "only files covering blocks <= n").addHelpText("after", `
+Examples:
+  $ secondlayer streams dumps --to ./dump
+  $ secondlayer streams dumps --to ./dump --from-block 150000 --to-block 200000`).action(runDumps);
   streams.command("canonical <height>").description("Canonical block metadata at a given height").option("--json", "Output as JSON (streams always emits JSON)").action(async (heightArg) => {
     try {
       const height = parseHeight(heightArg, "<height>");
@@ -36972,17 +38791,28 @@ function registerDoctorCommand(program2) {
 async function runInstanceDoctor(jsonOutput) {
   const config = await loadConfig2();
   const apiUrl = resolveApiUrl();
-  const issues = [];
   const results = { network: config.network, apiUrl };
   let apiHealthy = false;
   let statusData = null;
+  let unreachableError = null;
   try {
     statusData = await httpPlatformAnon("/public/status");
     apiHealthy = true;
-  } catch {
-    issues.push(`Cannot reach ${apiUrl}/public/status`);
+  } catch (err) {
+    unreachableError = err instanceof Error ? err.message : String(err);
   }
   results.apiHealthy = apiHealthy;
+  const diagnosis = statusData ? diagnoseInstanceStatus(statusData) : null;
+  const issues = diagnosis ? diagnosis.issues : [
+    {
+      title: `Cannot reach ${apiUrl}/public/status.`,
+      detail: unreachableError ?? undefined,
+      nextSteps: [
+        "Start the instance from docker/oss: docker compose up -d",
+        `If it runs elsewhere, point the CLI at it: SL_API_URL=<url> (currently ${apiUrl})`
+      ]
+    }
+  ];
   if (jsonOutput) {
     console.log(JSON.stringify({ ...results, status: statusData, issues }, null, 2));
     return;
@@ -36998,9 +38828,14 @@ async function runInstanceDoctor(jsonOutput) {
     const tip = statusData.chainTip;
     const streams = statusData.streams;
     const index = statusData.index;
+    const blocks = statusData.chainIntegrity?.maxHeight;
     console.log(blue("Instance"));
+    console.log(`  status: ${statusData.status ?? "unknown"}`);
     if (typeof tip === "number")
       console.log(`  tip: ${tip.toLocaleString()}`);
+    if (typeof blocks === "number") {
+      console.log(`  blocks indexed: ${blocks.toLocaleString()}`);
+    }
     if (streams?.status)
       console.log(`  streams: ${streams.status}`);
     if (index?.status)
@@ -37012,17 +38847,31 @@ async function runInstanceDoctor(jsonOutput) {
     console.log(`  ${green("None")}`);
   } else {
     for (const issue of issues) {
-      console.log(`  ${red("•")} ${issue}`);
+      console.log(`  ${red("•")} ${issue.title}`);
+      for (const line of issue.detail ? wrapText(issue.detail, 72) : []) {
+        console.log(dim(`    ${line}`));
+      }
+      for (const step of issue.nextSteps) {
+        console.log(dim(`    → ${step}`));
+      }
     }
   }
   console.log("");
   if (issues.length > 0) {
-    warn(`${issues.length} issue(s) found`);
+    warn(`${issues.length} issue${issues.length === 1 ? "" : "s"} found${doctorVerdictSuffix(diagnosis)}`);
   } else {
     success("All checks passed");
   }
   console.log("");
 }
+function doctorVerdictSuffix(diagnosis) {
+  if (!diagnosis)
+    return " — the CLI could not reach this instance.";
+  if (diagnosis.state === "empty-index") {
+    return " — the instance is up but holds no chain data yet.";
+  }
+  return ` — the API reports status=${diagnosis.overall}.`;
+}
 async function runLocalDoctor(jsonOutput) {
   const config = await loadConfig2();
   const report = await checkHealth();
@@ -39177,7 +41026,7 @@ function registerBootstrapCommand(program2) {
 }
 // src/commands/uninstall.ts
 init_output();
-import { spawnSync as spawnSync3 } from "node:child_process";
+import { spawnSync as spawnSync4 } from "node:child_process";
 import { existsSync as existsSync8, readFileSync as readFileSync7 } from "node:fs";
 import { join as join17, resolve as resolve13 } from "node:path";
 import { planUninstall, uninstallCommand } from "@secondlayer/shared/runtime";
@@ -39228,7 +41077,7 @@ function registerUninstallCommand(program2) {
       });
       return;
     }
-    const res = spawnSync3("docker", cmd, { stdio: "inherit" });
+    const res = spawnSync4("docker", cmd, { stdio: "inherit" });
     if ((res.status ?? 1) !== 0) {
       printError(`docker ${cmd.join(" ")} exited ${res.status}`);
       process.exit(UNINSTALL_EXIT.FAILED);
@@ -39504,110 +41353,15 @@ function registerBackupCommand(program2) {
 function registerRestoreCommand(program2) {
   attachRestoreCommand(program2.command("restore").description("Restore an instance from a backup bundle"));
 }
-// src/lib/instance-init.ts
-import { randomBytes as randomBytes3 } from "node:crypto";
-import { existsSync as existsSync10, readFileSync as readFileSync9, writeFileSync as writeFileSync8 } from "node:fs";
-import { resolve as resolve15 } from "node:path";
-import { generateEd25519KeyPair } from "@secondlayer/shared/crypto/ed25519";
-import { INSTANCE_NETWORKS } from "@secondlayer/shared/db/queries/instance";
-var INSTANCE_ENV_FILE = ".env.local";
-function parseInstanceNetwork(value) {
-  const network = value.trim().toLowerCase();
-  if (INSTANCE_NETWORKS.includes(network)) {
-    return network;
-  }
-  throw new Error(`network must be mainnet, testnet, or devnet (got ${value})`);
-}
-function generateInstanceToken() {
-  return randomBytes3(32).toString("hex");
-}
-function generateSecretsKey() {
-  return randomBytes3(32).toString("hex");
-}
-function generateSigningPrivateKey() {
-  return generateEd25519KeyPair().privateKeyPem;
-}
-function escapeEnvValue(value) {
-  if (!/[\s#"']/.test(value) && !value.includes("\\"))
-    return value;
-  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n")}"`;
-}
-function unescapeEnvValue(raw) {
-  let value = raw.trim();
-  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
-    value = value.slice(1, -1);
-  }
-  return value.replace(/\\n/g, `
-`).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
-}
-function readEnvValue(envPath, key) {
-  if (!existsSync10(envPath))
-    return null;
-  const match = readFileSync9(envPath, "utf8").match(new RegExp(`^${key}=(.*)$`, "m"));
-  return match ? unescapeEnvValue(match[1]) : null;
-}
-function buildInstanceEnv(input4) {
-  const token = input4.existing?.INSTANCE_TOKEN || input4.existing?.SL_API_KEY || generateInstanceToken();
-  const secrets = input4.existing?.SECONDLAYER_SECRETS_KEY || generateSecretsKey();
-  const signing = input4.existing?.STREAMS_SIGNING_PRIVATE_KEY || input4.existing?.SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY || generateSigningPrivateKey();
-  const apiUrl = input4.apiUrl ?? "http://127.0.0.1:3800";
-  const archiveKey = input4.existing?.ARCHIVE_SIGNING_PUBLIC_KEY;
-  return {
-    INSTANCE_MODE: "oss",
-    STACKS_NETWORK: input4.network,
-    INSTANCE_TOKEN: token,
-    SECONDLAYER_SECRETS_KEY: secrets,
-    STREAMS_SIGNING_PRIVATE_KEY: signing,
-    SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY: signing,
-    ALLOW_UNSIGNED_WEBHOOKS: "false",
-    SL_API_URL: input4.existing?.SL_API_URL || apiUrl,
-    SL_API_KEY: token,
-    ...archiveKey ? { ARCHIVE_SIGNING_PUBLIC_KEY: archiveKey } : {}
-  };
-}
-function renderInstanceEnv(env2) {
-  const lines2 = [
-    "# Generated by secondlayer init. Do not commit.",
-    `INSTANCE_MODE=${env2.INSTANCE_MODE}`,
-    `STACKS_NETWORK=${env2.STACKS_NETWORK}`,
-    `INSTANCE_TOKEN=${env2.INSTANCE_TOKEN}`,
-    `SECONDLAYER_SECRETS_KEY=${env2.SECONDLAYER_SECRETS_KEY}`,
-    `STREAMS_SIGNING_PRIVATE_KEY=${escapeEnvValue(env2.STREAMS_SIGNING_PRIVATE_KEY)}`,
-    `SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY=${escapeEnvValue(env2.SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY)}`,
-    `ALLOW_UNSIGNED_WEBHOOKS=${env2.ALLOW_UNSIGNED_WEBHOOKS}`,
-    `SL_API_URL=${env2.SL_API_URL}`,
-    `SL_API_KEY=${env2.SL_API_KEY}`
-  ];
-  if (env2.ARCHIVE_SIGNING_PUBLIC_KEY) {
-    lines2.push(`ARCHIVE_SIGNING_PUBLIC_KEY=${escapeEnvValue(env2.ARCHIVE_SIGNING_PUBLIC_KEY)}`);
-  }
-  lines2.push("");
-  return lines2.join(`
-`);
-}
-function writeInstanceEnv(cwd, env2, file = INSTANCE_ENV_FILE) {
-  const path11 = resolve15(cwd, file);
-  writeFileSync8(path11, renderInstanceEnv(env2), { mode: 384 });
-  return path11;
-}
-function loadExistingInstanceEnv(cwd, file = INSTANCE_ENV_FILE) {
-  const path11 = resolve15(cwd, file);
-  return {
-    INSTANCE_TOKEN: readEnvValue(path11, "INSTANCE_TOKEN"),
-    SECONDLAYER_SECRETS_KEY: readEnvValue(path11, "SECONDLAYER_SECRETS_KEY"),
-    STREAMS_SIGNING_PRIVATE_KEY: readEnvValue(path11, "STREAMS_SIGNING_PRIVATE_KEY"),
-    SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY: readEnvValue(path11, "SECONDLAYER_WEBHOOK_SIGNING_PRIVATE_KEY"),
-    SL_API_URL: readEnvValue(path11, "SL_API_URL"),
-    SL_API_KEY: readEnvValue(path11, "SL_API_KEY"),
-    ARCHIVE_SIGNING_PUBLIC_KEY: readEnvValue(path11, "ARCHIVE_SIGNING_PUBLIC_KEY")
-  };
-}
-
 // src/commands/init.ts
+init_instance_init();
 init_output();
 function registerInitCommand(program2) {
-  program2.command("init").description("Write local env (token, secrets key, webhook signing key). Idempotent.").option("--network <network>", "mainnet, testnet, or devnet", process.env.STACKS_NETWORK ?? "mainnet").option("--api-url <url>", "Local API URL", "http://127.0.0.1:3800").option("--force", "Overwrite generated values even if .env.local exists").action((opts) => {
-    const network = parseInstanceNetwork(opts.network);
+  program2.command("init").description("Write local env (token, secrets key, webhook signing key). Idempotent.").option("--api-url <url>", "Local API URL", "http://127.0.0.1:3800").option("--force", "Overwrite generated values even if .env.local exists").addHelpText("after", `
+--network <mainnet|testnet|devnet> is the top-level global flag (see
+\`secondlayer --help\`) — default mainnet, same as before.
+`).action((opts) => {
+    const network = parseInstanceNetwork(process.env.STACKS_NETWORK ?? "mainnet");
     const existing = opts.force ? {} : loadExistingInstanceEnv(process.cwd());
     const env2 = buildInstanceEnv({
       network,
@@ -39624,89 +41378,252 @@ function registerInitCommand(program2) {
     note("Export these or pass --env-file to compose. Do not commit the file.");
   });
 }
-// src/lib/observer-stanza.ts
-var OBSERVER_MODES = ["indexer", "signer-shared"];
-var RECOVERY_SOURCES = ["journal", "archive"];
-
-class UnsupportedObserverError extends Error {
-  name = "UnsupportedObserverError";
+// src/commands/observer.ts
+init_instance_init();
+init_observer_stanza();
+init_output();
+function registerObserverCommand(program2) {
+  program2.command("observer").description("Print the Stacks events_observer stanza for this node mode").option("--mode <mode>", "indexer (retry) or signer-shared (no retry)", "indexer").option("--endpoint <host:port>", "Observer callback the node will POST to").option("--recovery <source>", "Required for signer-shared: journal or archive").addHelpText("after", `
+--network <mainnet|testnet|devnet> is the top-level global flag (see
+\`secondlayer --help\`) — default mainnet, same as before.
+`).action((opts) => {
+    const mode = parseObserverMode(opts.mode);
+    const network = parseInstanceNetwork(process.env.STACKS_NETWORK ?? "mainnet");
+    const endpoint = opts.endpoint ?? defaultObserverEndpoint(network);
+    const recovery = opts.recovery ? parseRecoverySource(opts.recovery) : undefined;
+    if (mode === "signer-shared") {
+      note("Signer-shared nodes skip observer retries. Pair with a journal or archive for completeness.");
+    }
+    writeData(renderObserverStanza({ mode, endpoint, network, recovery }));
+  });
 }
-function parseObserverMode(value) {
-  const mode = value.trim().toLowerCase();
-  if (OBSERVER_MODES.includes(mode)) {
-    return mode;
+// src/commands/setup.ts
+init_output();
+
+// src/lib/setup-prompts.ts
+init_instance_init();
+init_oss_compose();
+init_setup_wizard();
+import { confirm as confirm9, input as input4, select as select5 } from "@inquirer/prompts";
+
+class SetupCancelledError extends Error {
+  constructor() {
+    super("Setup cancelled — nothing was changed.");
+    this.name = "SetupCancelledError";
   }
-  throw new UnsupportedObserverError(`observer mode must be indexer or signer-shared (got ${value})`);
 }
-function parseRecoverySource(value) {
-  const source = value.trim().toLowerCase();
-  if (RECOVERY_SOURCES.includes(source)) {
-    return source;
+function safeParse(value, parse2) {
+  if (!value)
+    return;
+  try {
+    return parse2(value);
+  } catch {
+    return;
   }
-  throw new UnsupportedObserverError(`recovery source must be journal or archive (got ${value})`);
 }
-function parseObserverEndpoint(value) {
-  const trimmed = value.trim();
-  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) || trimmed.startsWith("unix:")) {
-    throw new UnsupportedObserverError(`observer endpoint must be host:port, not a URL (${value})`);
-  }
-  const match = trimmed.match(/^([a-zA-Z0-9._-]+):(\d+)$/);
-  if (!match) {
-    throw new UnsupportedObserverError(`observer endpoint must be host:port (got ${value})`);
+var NODE_MODE_DESCRIPTIONS = {
+  external: "You run the Stacks node; paste an observer stanza into its Config.toml.",
+  stacks: "You run the Stacks node yourself, no bundled bitcoind (same as external).",
+  full: "Bundled Stacks node + bitcoind."
+};
+async function promptSetupConfig(flags) {
+  const network = safeParse(flags.network, parseInstanceNetwork) ?? await select5({
+    message: "Network",
+    choices: [
+      {
+        name: "mainnet",
+        value: "mainnet",
+        description: "Production Stacks chain. Large: plan for hundreds of GB."
+      },
+      {
+        name: "testnet",
+        value: "testnet",
+        description: "Stacks testnet. Small history."
+      },
+      {
+        name: "devnet",
+        value: "devnet",
+        description: "Local Clarinet devnet."
+      }
+    ]
+  });
+  const nodeMode = safeParse(flags.nodeMode, parseSetupNodeMode) ?? await select5({
+    message: "Node mode",
+    choices: SETUP_NODE_MODES.map((mode) => {
+      const floor = guardrailPreview(mode, network);
+      return {
+        name: mode,
+        value: mode,
+        description: `${NODE_MODE_DESCRIPTIONS[mode]} needs ≥ ${(floor.ramFloorMb / 1024).toFixed(0)}GB RAM, ≥ ${floor.diskFloorGb}GB disk.`
+      };
+    })
+  });
+  let against = flags.against;
+  let skipBootstrap = !!flags.skipBootstrap;
+  if (!skipBootstrap && !against) {
+    const choice = await select5({
+      message: "Bootstrap from",
+      choices: [
+        {
+          name: "Hosted archive (recommended)",
+          value: "hosted",
+          description: DEFAULT_ARCHIVE_MANIFEST
+        },
+        {
+          name: "Custom manifest URL or path",
+          value: "custom",
+          description: "Enter your own"
+        },
+        {
+          name: "Sync from genesis",
+          value: "skip",
+          description: "Skip bootstrap — slower, no download"
+        }
+      ]
+    });
+    if (choice === "hosted") {
+      against = DEFAULT_ARCHIVE_MANIFEST;
+    } else if (choice === "skip") {
+      skipBootstrap = true;
+    } else {
+      against = (await input4({
+        message: "Manifest URL or local path",
+        default: DEFAULT_ARCHIVE_MANIFEST
+      })).trim();
+    }
   }
-  const port = Number(match[2]);
-  if (port < 1 || port > 65535) {
-    throw new UnsupportedObserverError(`observer port out of range (${port})`);
+  const config = {
+    network,
+    nodeMode,
+    apiPort: flags.apiPort ?? "127.0.0.1:3800",
+    indexerPort: "127.0.0.1:3700",
+    postgresPort: "127.0.0.1:5432",
+    dir: flags.dir ?? process.cwd(),
+    against: skipBootstrap ? undefined : against,
+    skipBootstrap,
+    skipVerify: !!flags.skipVerify,
+    yes: false,
+    force: !!flags.force,
+    owner: flags.owner ?? DEFAULT_IMAGE_OWNER,
+    imageTag: flags.imageTag ?? DEFAULT_IMAGE_TAG
+  };
+  console.error("");
+  console.error(`  network      ${config.network}`);
+  console.error(`  node mode    ${config.nodeMode}`);
+  console.error(`  dir          ${config.dir}`);
+  console.error(`  api port     ${config.apiPort}`);
+  console.error(`  bootstrap    ${config.skipBootstrap ? "skip (sync from genesis)" : config.against}`);
+  console.error("");
+  const proceed = await confirm9({ message: "Start setup?", default: true });
+  if (!proceed)
+    throw new SetupCancelledError;
+  return config;
+}
+
+// src/commands/setup.ts
+init_setup_wizard();
+function renderProgress(event) {
+  switch (event.type) {
+    case "step-start":
+      note(`→ ${event.step}`);
+      return;
+    case "step-log":
+      note(`  ${event.line}`);
+      return;
+    case "step-done":
+      success(event.step + (event.detail ? `: ${event.detail}` : ""));
+      return;
+    case "step-skip":
+      note(`  skipped ${event.step} (${event.reason})`);
+      return;
+    case "step-error":
+      printError(`${event.step} failed: ${event.message}`);
+      return;
   }
-  return trimmed;
 }
-var LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
-function validateObserverStanza(input4) {
-  const endpoint = parseObserverEndpoint(input4.endpoint);
-  const host = endpoint.slice(0, endpoint.lastIndexOf(":"));
-  if (input4.network !== "devnet" && LOOPBACK_HOSTS.has(host.toLowerCase())) {
-    throw new UnsupportedObserverError(`loopback observer endpoint is not container-visible on ${input4.network}; use a docker DNS name such as indexer:3700`);
+async function executeAndRender(config) {
+  console.error(bold("Secondlayer setup"));
+  console.error(dim(`  network=${config.network} node-mode=${config.nodeMode} dir=${config.dir}`));
+  console.error("");
+  let failed = false;
+  const result = await runSetup(config, (event) => {
+    if (event.type === "step-error")
+      failed = true;
+    renderProgress(event);
+  });
+  if (!result.ok) {
+    process.exit(1);
   }
-  if (input4.mode === "signer-shared" && !input4.recovery) {
-    throw new UnsupportedObserverError("signer-shared mode requires --recovery journal or --recovery archive");
+  if (failed) {
+    warn("Setup finished with at least one step reporting an error above.");
   }
-  return { endpoint };
+  console.error("");
+  if (result.summary)
+    console.log(result.summary);
+  process.exit(failed ? 1 : 0);
 }
-function renderObserverStanza(input4) {
-  const { endpoint } = validateObserverStanza(input4);
-  const indexer = input4.mode === "indexer";
-  const timeoutMs = indexer ? 2000 : 500;
-  const disableRetries = !indexer;
-  const comment = indexer ? "# Pure indexer: retry delivery. A slow observer can stall the node." : "# Signer-shared: do not retry. Missed blocks refill from the journal/archive.";
-  return [
-    comment,
-    "[[events_observer]]",
-    `endpoint = "${endpoint}"`,
-    'events_keys = ["*"]',
-    `timeout_ms = ${timeoutMs}`,
-    `disable_retries = ${disableRetries}`,
-    ""
-  ].join(`
-`);
+async function runNonInteractive(flags) {
+  let config;
+  try {
+    config = resolveNonInteractiveConfig(flags);
+  } catch (err) {
+    if (err instanceof MissingSetupFlagError) {
+      printError(err.message, { hint: `Pass ${err.flag} and re-run.` });
+    } else {
+      printError(err instanceof Error ? err.message : String(err));
+    }
+    process.exit(1);
+  }
+  await executeAndRender(config);
 }
-function defaultObserverEndpoint(network) {
-  if (network === "devnet")
-    return "127.0.0.1:3700";
-  return "indexer:3700";
+async function runPromptedInteractive(flags) {
+  let config;
+  try {
+    config = await promptSetupConfig(flags);
+  } catch (err) {
+    if (err instanceof SetupCancelledError) {
+      note(err.message);
+      process.exit(0);
+    }
+    printError(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+  await executeAndRender(config);
 }
+function registerSetupCommand(program2) {
+  program2.command("setup").description("Guided self-host onboarding: secrets, config, docker, bootstrap, verify — one command").option("--node-mode <mode>", "external, stacks, or full (required)").option("--api-port <spec>", "API publish spec", "127.0.0.1:3800").option("--dir <path>", "Target directory for compose + .env", process.cwd()).option("--against <manifest>", `Archive manifest to bootstrap from (suggested default: ${DEFAULT_ARCHIVE_MANIFEST})`).option("--skip-bootstrap", "Sync from genesis instead of restoring an archive").option("--skip-verify", "Skip the post-bootstrap verify pass").option("--yes", "Non-interactive: skip the TUI, require flags, never prompt").option("--force", "Regenerate secrets even if a .env already exists in --dir").option("--owner <owner>", "ghcr image owner (namespace) to pull from").option("--image-tag <tag>", "Published image tag to run").addHelpText("after", `
+--network <mainnet|testnet|devnet> is the top-level global flag (see
+\`secondlayer --help\`) — required here too, just parsed one level up.
 
-// src/commands/observer.ts
-init_output();
-function registerObserverCommand(program2) {
-  program2.command("observer").description("Print the Stacks events_observer stanza for this node mode").option("--mode <mode>", "indexer (retry) or signer-shared (no retry)", "indexer").option("--endpoint <host:port>", "Observer callback the node will POST to").option("--recovery <source>", "Required for signer-shared: journal or archive").option("--network <network>", "mainnet, testnet, or devnet", process.env.STACKS_NETWORK ?? "mainnet").action((opts) => {
-    const mode = parseObserverMode(opts.mode);
-    const network = parseInstanceNetwork(opts.network);
-    const endpoint = opts.endpoint ?? defaultObserverEndpoint(network);
-    const recovery = opts.recovery ? parseRecoverySource(opts.recovery) : undefined;
-    if (mode === "signer-shared") {
-      note("Signer-shared nodes skip observer retries. Pair with a journal or archive for completeness.");
+Examples:
+  $ secondlayer setup
+  $ secondlayer setup --yes --network mainnet --node-mode external --against ${DEFAULT_ARCHIVE_MANIFEST}
+  $ secondlayer setup --yes --network testnet --node-mode external --skip-bootstrap --skip-verify
+
+Without a TTY (piped, CI, an agent), or with --yes, the TUI is skipped: every
+decision with no safe default (--network, --node-mode, and --against unless
+--skip-bootstrap) must come from a flag or the command fails fast naming it.
+`).action(async (opts) => {
+    const flags = {
+      ...opts,
+      network: opts.network ?? process.env.STACKS_NETWORK
+    };
+    const interactive = process.stdout.isTTY && !flags.yes;
+    if (!interactive) {
+      await runNonInteractive(flags);
+      return;
+    }
+    if (!isBunRuntime()) {
+      await runPromptedInteractive(flags);
+      return;
+    }
+    try {
+      const { runSetupTui: runSetupTui2 } = await Promise.resolve().then(() => (init_setup_tui(), exports_setup_tui));
+      await runSetupTui2(flags);
+    } catch (err) {
+      warn(`Interactive TUI unavailable (${err instanceof Error ? err.message : String(err)}) — falling back to guided prompts.`);
+      await runPromptedInteractive(flags);
     }
-    writeData(renderObserverStanza({ mode, endpoint, network, recovery }));
   });
 }
 // src/commands/start.ts
@@ -39732,7 +41649,7 @@ function registerStartCommand(program2) {
       });
       process.exit(1);
     }
-    const extra = parsed.config.NODE_MODE === "full" ? " --profile full-node" : parsed.config.NODE_MODE === "stacks" ? " --profile stacks-node" : "";
+    const extra = parsed.config.NODE_MODE === "full" ? " --profile full-node" : "";
     const cmd = `docker compose -f docker/oss/docker-compose.yml${extra} up -d`;
     if (opts.print) {
       console.log(cmd);
@@ -39745,24 +41662,30 @@ function registerStartCommand(program2) {
 }
 // src/cli.ts
 var { version } = package_default;
-program.name("secondlayer").alias("sl").description("Secondlayer CLI — run a Stacks index on your own hardware").version(version).option("--network <network>", "Override network (local, testnet, mainnet)").option("--api-key <key>", "API credential (overrides SL_API_KEY)").option("--api-url <url>", "API endpoint (overrides SL_API_URL)").showSuggestionAfterError(true).showHelpAfterError("(run `secondlayer --help` to see available commands)");
+program.name("secondlayer").alias("sl").description("Secondlayer CLI — run a Stacks index on your own hardware").version(version).option("--network <network>", "Override network (local, testnet, mainnet)").option("--api-key <key>", "API credential (overrides INSTANCE_TOKEN)").option("--api-url <url>", "API endpoint (overrides SL_API_URL)").showSuggestionAfterError(true).showHelpAfterError("(run `secondlayer --help` to see available commands)");
 program.hook("preAction", (thisCommand) => {
   const { network, apiKey, apiUrl } = thisCommand.opts();
   if (network)
     process.env.STACKS_NETWORK = network;
-  if (apiKey)
+  if (apiKey) {
+    process.env.INSTANCE_TOKEN = apiKey;
     process.env.SL_API_KEY = apiKey;
+  }
   if (apiUrl)
     process.env.SL_API_URL = apiUrl;
 });
 program.addHelpText("after", `
 Quickstart:
-  $ secondlayer init --network mainnet
-  $ secondlayer bootstrap --against <manifest>
+  $ secondlayer setup
   $ secondlayer subgraphs create my-watcher --from-contract SP....my-contract
   $ secondlayer subgraphs deploy subgraphs/my-watcher.ts
+
+Manual / scripted setup, one step at a time:
+  $ secondlayer init --network mainnet
+  $ secondlayer bootstrap --against <manifest>
 `);
 program.commandsGroup("Getting started:");
+registerSetupCommand(program);
 registerInitCommand(program);
 registerBootstrapCommand(program);
 registerObserverCommand(program);
@@ -39778,19 +41701,6 @@ registerStreamsCommand(program);
 registerIndexCommand(program);
 program.commandsGroup("Project & codegen:");
 registerCodegenCommand(program);
-var configureGenerate = (cmd) => cmd.option("-c, --config <path>", "Path to config file").option("-o, --output <path>", "Output file path (required when using direct files)").option("-k, --api-key <key>", "Stacks node API key for direct RPC URLs").option("-w, --watch", "Watch for changes").action(async (files, options3) => {
-  const { deprecatedCodegenNotice: deprecatedCodegenNotice2 } = await Promise.resolve().then(() => (init_codegen(), exports_codegen));
-  deprecatedCodegenNotice2("secondlayer contracts generate", "secondlayer codegen contracts");
-  options3.out = options3.output;
-  const { generate: generate2 } = await Promise.resolve().then(() => (init_generate(), exports_generate));
-  await generate2(files, options3);
-});
-var contracts = program.command("contracts").description("Work with Clarity contracts");
-configureGenerate(contracts.command("generate [files...]").aliases(["gen"]).description("Generate TypeScript interfaces from Clarity contracts")).addHelpText("after", `
-Examples:
-  $ secondlayer contracts generate
-  $ secondlayer contracts generate ./contracts/pool.clar -o ./src/generated.ts
-  $ secondlayer contracts generate --config secondlayer.config.ts --watch`);
 program.commandsGroup("Local development:");
 registerLocalCommand(program);
 registerDevnetCommand(program);
@@ -39808,5 +41718,5 @@ program.commandsGroup("Archive:");
 registerCreditsCommand(program);
 program.parse();
 
-//# debugId=5BF91F30BB4466C964756E2164756E21
+//# debugId=E4B3B7874FAC14F764756E2164756E21
 //# sourceMappingURL=cli.js.map