init: lean AGENTS.md section + opt-in @conciv/skills docs pack

.changeset/lean-agents-md-docs-pack.md

@@ -0,0 +1,7 @@
+---
+'@conciv/cli': patch
+---
+
+`conciv init` now teaches agents the MCP discovery workflow (`await external_catalog({})`) instead of a static AGENTS.md command list. It also offers an opt-in docs pack step during plan review, declined by default and never enabled by `--yes`, that adds `@conciv/skills` as a dev dependency and runs `@tanstack/intent install` for setup, extension-authoring, and debugging guidance.
+
+The interactive wizard was reworked to a single-pass flow, modeled on the TanStack CLI: it asks the harness, framework, and docs-pack questions once, renders one plan, and asks for one confirmation, and declining cancels outright instead of dropping into an edit loop. The execution phase now streams each step's live command output through clack's `taskLog`, instead of buffering it behind a spinner until the step settles.

packages/cli/src/init/exec.ts

@@ -1,23 +1,36 @@
-import {execFile} from 'node:child_process'
+import {spawn} from 'node:child_process'
 
 export type CommandOutcome = {code: number; output: string}
 
 export function execFileOutcome(
   bin: string,
   args: string[],
   options: {cwd: string; env?: NodeJS.ProcessEnv},
+  onLine: (line: string) => void,
 ): Promise<CommandOutcome> {
   return new Promise((settle, reject) => {
-    execFile(bin, args, options, (error, stdout, stderr) => {
-      if (error === null) {
-        settle({code: 0, output: `${stdout}${stderr}`})
+    const child = spawn(bin, args, options)
+    let output = ''
+    let pending = ''
+    const consume = (chunk: Buffer): void => {
+      const text = chunk.toString()
+      output += text
+      pending += text
+      const lines = pending.split('\n')
+      pending = lines.pop() ?? ''
+      for (const line of lines) onLine(line)
+    }
+    child.stdout?.on('data', consume)
+    child.stderr?.on('data', consume)
+    child.on('error', reject)
+    child.on('close', (code, signal) => {
+      if (pending.length > 0) onLine(pending)
+      if (code === null) {
+        const note = signal ? `terminated by ${signal}` : 'terminated without exit code'
+        settle({code: 1, output: output.length > 0 ? `${output}\n${note}` : note})
         return
       }
-      if (typeof error.code !== 'number') {
-        reject(error)
-        return
-      }
-      settle({code: error.code, output: `${stdout}${stderr}`})
+      settle({code, output})
     })
   })
 }

packages/cli/src/init/pipeline.ts

@@ -6,6 +6,7 @@ import {captureFile, guardBackups, onInterrupt, type FileBackup} from './interru
 import type {LedgerEntry, ManualCard, StepNote, StepOutcome, StepPlan} from './ledger.js'
 import {emitOutro} from './outro.js'
 import {preflight} from './preflight.js'
+import {docsPackStep} from './steps/docs-pack.js'
 import {fallbackStep} from './steps/framework/fallback.js'
 import {nextjsStep} from './steps/framework/nextjs.js'
 import {viteStep} from './steps/framework/vite.js'
@@ -38,6 +39,7 @@ export type RunSettings = {
 export type InitContext = Omit<RunSettings, 'interrupt'> & {
   report: (line: string) => void
   note: (note: StepNote) => void
+  feed: (line: string) => void
 }
 
 export type InitStep = {
@@ -60,7 +62,12 @@ export type InitResult =
   | {outcome: 'planned'; plan: string}
   | {outcome: 'completed'; steps: LedgerEntry[]; next: string[]}
 
-export type SpawnBin = (bin: string, args: string[], cwd: string) => Promise<{code: number; output: string}>
+export type SpawnBin = (
+  bin: string,
+  args: string[],
+  cwd: string,
+  onLine: (line: string) => void,
+) => Promise<{code: number; output: string}>
 
 export type InitRuntime = {
   addDependency: AddDep
@@ -74,8 +81,8 @@ export type InitRuntime = {
 
 type Emission = {kind: 'line'; text: string} | {kind: 'note'; note: StepNote}
 
-function spawnBin(bin: string, args: string[], cwd: string): Promise<CommandOutcome> {
-  return execFileOutcome(bin, args, {cwd})
+function spawnBin(bin: string, args: string[], cwd: string, onLine: (line: string) => void): Promise<CommandOutcome> {
+  return execFileOutcome(bin, args, {cwd}, onLine)
 }
 
 function defaultRuntime(): InitRuntime {
@@ -109,6 +116,7 @@ function stepList(detected: Detected, selections: ConfirmedSelections, runtime:
     ...(selections.framework ? [frameworkStep(detected)] : []),
     agentsMdStep(consented),
     ...harnessFileInits.map((init) => harnessInitStep(init, consented, {home: runtime.env.HOME, run: runtime.spawn})),
+    ...(selections.docsPack ? [docsPackStep(runtime.addDependency, runtime.spawn)] : []),
   ]
 }
 
@@ -137,7 +145,7 @@ async function planRows(steps: InitStep[], ctx: InitContext): Promise<PlanRow[]>
 }
 
 function quietContext(cwd: string, yes: boolean): InitContext {
-  return {cwd, yes, dryRun: true, report: () => {}, note: () => {}, backup: () => {}}
+  return {cwd, yes, dryRun: true, report: () => {}, note: () => {}, backup: () => {}, feed: () => {}}
 }
 
 export async function runInit(options: InitOptions, overrides: Partial<InitRuntime> = {}): Promise<InitResult> {
@@ -215,6 +223,7 @@ export async function runSteps(steps: InitStep[], settings: RunSettings, output:
 async function runOne(step: InitStep, settings: RunSettings, output: InitOutput): Promise<LedgerEntry> {
   const emissions: Emission[] = []
   const {interrupt, ...base} = settings
+  const line = output.step(step.running)
   const ctx: InitContext = {
     ...base,
     report: (text) => {
@@ -223,8 +232,10 @@ async function runOne(step: InitStep, settings: RunSettings, output: InitOutput)
     note: (note) => {
       emissions.push({kind: 'note', note})
     },
+    feed: (text) => {
+      line.line(text)
+    },
   }
-  const line = output.step(step.running)
   const release = interrupt(() => {
     line.settle({status: 'skipped', summary: `${step.title} — interrupted`})
   })

packages/cli/src/init/silent.ts

@@ -6,7 +6,7 @@ export function silentOutput(): InitOutput {
     intro: quiet,
     spinner: () => ({stop: quiet, fail: quiet}),
     plan: quiet,
-    step: () => ({settle: quiet}),
+    step: () => ({line: quiet, settle: quiet}),
     note: quiet,
     line: quiet,
     success: quiet,

packages/cli/src/init/steps/docs-pack.ts

@@ -0,0 +1,99 @@
+import {existsSync, readFileSync} from 'node:fs'
+import {join} from 'node:path'
+import {addDependencyCommand, detectPackageManager, dlxCommand} from 'nypm'
+import {captureFile} from '../interrupt.js'
+import type {ManualCard} from '../ledger.js'
+import type {InitContext, InitStep, SpawnBin} from '../pipeline.js'
+import type {AddDep} from './install-it.js'
+import {hasDependency, readManifest} from './manifest.js'
+
+const skillsName = '@conciv/skills'
+const intentPackage = '@tanstack/intent@latest'
+const intentBlockStartMarker = '<!-- intent-skills:start -->'
+const intentBlockEndMarker = '<!-- intent-skills:end -->'
+
+type IntentCommands = {
+  spawn: [string, ...string[]]
+  intentLine: string
+  addCommand: string
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function intentBlockPresent(cwd: string): boolean {
+  const agentsMdPath = join(cwd, 'AGENTS.md')
+  if (!existsSync(agentsMdPath)) return false
+  const content = readFileSync(agentsMdPath, 'utf8')
+  return content.includes(intentBlockStartMarker) && content.includes(intentBlockEndMarker)
+}
+
+async function resolveIntentCommands(cwd: string): Promise<IntentCommands> {
+  const found = await detectPackageManager(cwd, {ignoreArgv: true})
+  const pmName = found?.name ?? 'npm'
+  const intentLine = dlxCommand(pmName, intentPackage, {args: ['install']})
+  const [bin, ...args] = intentLine.split(' ')
+  if (bin === undefined) throw new Error(`nypm dlxCommand returned an empty command: ${intentLine}`)
+  return {spawn: [bin, ...args], intentLine, addCommand: addDependencyCommand(pmName, skillsName, {dev: true})}
+}
+
+async function failureCard(cwd: string, depPresent: boolean): Promise<ManualCard> {
+  const commands = await resolveIntentCommands(cwd)
+  const lines = depPresent ? [commands.intentLine] : [commands.addCommand, commands.intentLine]
+  return {
+    title: `Add the ${skillsName} docs pack`,
+    body: 'The automatic setup failed. Run these in your project:',
+    snippet: lines.join('\n'),
+  }
+}
+
+function present(ctx: InitContext): boolean {
+  return hasDependency(readManifest(ctx.cwd), skillsName) && intentBlockPresent(ctx.cwd)
+}
+
+export function docsPackStep(add: AddDep, spawn: SpawnBin): InitStep {
+  return {
+    id: 'docs-pack',
+    title: `Add the ${skillsName} docs pack`,
+    running: `Adding the ${skillsName} docs pack…`,
+    completed: `Added the ${skillsName} docs pack`,
+    detect: async (ctx) => (present(ctx) ? 'present' : 'missing'),
+    plan: async () => ({
+      summary: `add ${skillsName} as a dev dependency and run \`intent install\` for skill-loading guidance`,
+      wouldEdit: ['package.json', 'AGENTS.md'],
+    }),
+    apply: async (ctx) => {
+      const depPresent = hasDependency(readManifest(ctx.cwd), skillsName)
+      if (!depPresent) {
+        ctx.backup(captureFile(join(ctx.cwd, 'package.json')))
+        const addFailure = await add(skillsName, {cwd: ctx.cwd}).then(
+          () => null,
+          (error: unknown) => message(error),
+        )
+        if (addFailure !== null)
+          return {status: 'manual', cards: [await failureCard(ctx.cwd, depPresent)], detail: addFailure}
+      }
+      if (intentBlockPresent(ctx.cwd)) return {status: 'done'}
+      ctx.backup(captureFile(join(ctx.cwd, 'AGENTS.md')))
+      const commands = await resolveIntentCommands(ctx.cwd)
+      const [bin, ...args] = commands.spawn
+      const outcome = await spawn(bin, args, ctx.cwd, ctx.feed).catch((error: unknown) => ({
+        code: -1,
+        output: message(error),
+      }))
+      if (outcome.code === 0) return {status: 'done'}
+      const reason = outcome.output.trim()
+      return {
+        status: 'manual',
+        cards: [await failureCard(ctx.cwd, true)],
+        detail: reason.length === 0 ? 'intent install failed' : reason,
+      }
+    },
+    verify: async (ctx) => present(ctx),
+    manualCard: () => ({
+      title: `Add the ${skillsName} docs pack`,
+      body: `Add ${skillsName} as a dev dependency, then run \`${intentPackage} install\` with your package manager's dlx equivalent, or re-run conciv init.`,
+    }),
+  }
+}

packages/cli/src/init/steps/harness/agents-md.ts

@@ -9,7 +9,10 @@ const startMarker = '<!-- conciv:start -->'
 const endMarker = '<!-- conciv:end -->'
 
 export function agentsSection(consented: HarnessId[]): string {
-  const setUpFor = consented.length > 0 ? ['', `Set up for: ${consented.join(', ')}.`] : []
+  const setUpFor =
+    consented.length > 0
+      ? ['', `Set up for: ${consented.join(', ')}.`]
+      : ['', 'No harness was connected; install one and re-run `conciv init` to finish setup.']
   const notes = consented.flatMap((id) => {
     const note = harnessAgentsMdNote(id)
     return note === undefined ? [] : ['', note]
@@ -19,15 +22,13 @@ export function agentsSection(consented: HarnessId[]): string {
     '',
     '## conciv',
     '',
-    'conciv connects coding agents to the app running in the browser.',
+    'conciv is connected via MCP.',
     '',
-    'Run `conciv tools --help` to discover every command. The CLI finds the running dev server itself: no config, no addresses.',
+    'Capabilities are discovered inside the sandbox with `await external_catalog({})`, never a static list.',
     '',
-    '- `conciv tools page` - read and drive the live page; `--help` lists every capability',
-    '- `conciv tools react` - inspect and edit live React components',
-    '- `conciv tools server` - inspect and nudge the dev server; `--help` lists every capability',
+    "The project's conciv dev server must be running.",
     '',
-    'These commands need the dev server running.',
+    'One-shot CLI equivalent: `conciv tools --help`.',
     ...setUpFor,
     ...notes,
     '',

packages/cli/src/init/steps/harness/install-harness.ts

@@ -8,7 +8,12 @@ import type {InitContext, InitStep} from '../../pipeline.js'
 
 export type HarnessInitIo = {
   home: string
-  run: (bin: string, args: string[], cwd: string) => Promise<{code: number; output: string}>
+  run: (
+    bin: string,
+    args: string[],
+    cwd: string,
+    onLine: (line: string) => void,
+  ) => Promise<{code: number; output: string}>
 }
 
 function stateDirOf(cwd: string): string {
@@ -29,7 +34,7 @@ function writePlanFiles(ctx: InitContext, plan: HarnessInitPlan): void {
 
 async function runCommand(ctx: InitContext, io: HarnessInitIo, command: HarnessInitCommand): Promise<string | null> {
   const rendered = `${command.bin} ${command.args.join(' ')}`
-  const outcome = await io.run(command.bin, command.args, ctx.cwd).catch((error: unknown) => {
+  const outcome = await io.run(command.bin, command.args, ctx.cwd, ctx.feed).catch((error: unknown) => {
     const reason = error instanceof Error ? error.message : String(error)
     return {code: -1, output: reason}
   })

packages/cli/src/init/steps/install-it.ts

@@ -1,30 +1,16 @@
-import {readFileSync} from 'node:fs'
 import {join} from 'node:path'
 import {addDependencyCommand, addDevDependency, detectPackageManager} from 'nypm'
-import {z} from 'zod'
 import {captureFile} from '../interrupt.js'
 import type {ManualCard} from '../ledger.js'
 import type {InitStep} from '../pipeline.js'
+import {hasDependency, readManifest, type PackageJson} from './manifest.js'
 
 const itName = '@conciv/it'
 
-const manifestSchema = z.object({
-  dependencies: z.record(z.string(), z.string()).optional(),
-  devDependencies: z.record(z.string(), z.string()).optional(),
-})
-
-export type PackageJson = z.infer<typeof manifestSchema>
-
 export type AddDep = (name: string, opts: {cwd: string}) => Promise<void>
 
 export function hasIt(pkg: PackageJson): boolean {
-  return itName in (pkg.dependencies ?? {}) || itName in (pkg.devDependencies ?? {})
-}
-
-function readManifest(cwd: string): PackageJson {
-  const parsed = manifestSchema.safeParse(JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')))
-  if (!parsed.success) return {}
-  return parsed.data
+  return hasDependency(pkg, itName)
 }
 
 async function installCard(cwd: string): Promise<ManualCard> {

packages/cli/src/init/steps/manifest.ts

@@ -0,0 +1,20 @@
+import {readFileSync} from 'node:fs'
+import {join} from 'node:path'
+import {z} from 'zod'
+
+const manifestSchema = z.object({
+  dependencies: z.record(z.string(), z.string()).optional(),
+  devDependencies: z.record(z.string(), z.string()).optional(),
+})
+
+export type PackageJson = z.infer<typeof manifestSchema>
+
+export function readManifest(cwd: string): PackageJson {
+  const parsed = manifestSchema.safeParse(JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')))
+  if (!parsed.success) return {}
+  return parsed.data
+}
+
+export function hasDependency(pkg: PackageJson, name: string): boolean {
+  return name in (pkg.dependencies ?? {}) || name in (pkg.devDependencies ?? {})
+}