typeclaw 0.4.0 → 0.5.1

package/src/cli/channel.ts

@@ -25,7 +25,7 @@ import {
 import { runKakaotalkBootstrap } from '@/init/kakaotalk-auth'
 import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 
-import { c, done, errorLine } from './ui'
+import { c, done, errorLine, printSlackAppManifestSetup } from './ui'
 
 const CHANNEL_LABELS: Record<ChannelKind, string> = {
   'slack-bot': 'Slack',
@@ -834,50 +834,7 @@ async function promptDiscordToken(): Promise<string> {
 }
 
 async function promptSlackTokens(): Promise<{ bot: string; app: string }> {
-  note(
-    [
-      '1. https://api.slack.com/apps → Create New App → From a manifest.',
-      '   Pick your workspace, then paste this JSON manifest:',
-      '',
-      '   {',
-      '     "display_information": { "name": "TypeClaw" },',
-      '     "features": {',
-      '       "bot_user": { "display_name": "TypeClaw", "always_online": true }',
-      '     },',
-      '     "oauth_config": {',
-      '       "scopes": {',
-      '         "bot": [',
-      '           "app_mentions:read", "chat:write", "users:read", "files:read",',
-      '           "channels:history", "channels:read",',
-      '           "groups:history",   "groups:read",',
-      '           "im:history",       "im:read",',
-      '           "mpim:history",     "mpim:read"',
-      '         ]',
-      '       }',
-      '     },',
-      '     "settings": {',
-      '       "event_subscriptions": {',
-      '         "bot_events": [',
-      '           "app_mention",',
-      '           "message.channels", "message.groups",',
-      '           "message.im",       "message.mpim"',
-      '         ]',
-      '       },',
-      '       "socket_mode_enabled": true',
-      '     }',
-      '   }',
-      '',
-      '2. Install to Workspace, then OAuth & Permissions →',
-      '   copy the Bot User OAuth Token (xoxb-...).',
-      '3. Basic Information → App-Level Tokens → Generate Token and',
-      '   Scopes, add the connections:write scope, and copy the',
-      '   token (xapp-...). Socket Mode needs this; the manifest',
-      '   cannot grant it.',
-      '4. Invite the bot to any private channel or DM you want it in:',
-      '   /invite @TypeClaw',
-    ].join('\n'),
-    'Get a Slack bot',
-  )
+  printSlackAppManifestSetup()
   const bot = await promptSlackBotToken()
   note(
     [

package/src/cli/init.ts

@@ -11,7 +11,7 @@ import {
   type KnownModelRef,
   type KnownProviderId,
 } from '@/config/providers'
-import type { DockerAvailability } from '@/container'
+import { checkDockerAvailable, type DockerAvailability } from '@/container'
 import {
   findAgentDir,
   formatEagerGithubWebhookInstallResult,
@@ -29,9 +29,10 @@ import {
 } from '@/init'
 import { runKakaotalkBootstrap } from '@/init/kakaotalk-auth'
 import { fetchModelOptions, type ModelOption } from '@/init/models-dev'
-import { makeOAuthLoginRunner } from '@/init/oauth-login'
+import { makeOAuthLoginRunner, type OAuthLoginResult } from '@/init/oauth-login'
 
-import { c, done, errorLine } from './ui'
+import { buildOAuthCallbacks } from './oauth-callbacks'
+import { c, done, errorLine, printSlackAppManifestSetup } from './ui'
 
 // ESC and Ctrl+C both produce clack's cancel symbol (the keypress layer
 // aliases both to the same "cancel" action — there's no way to tell them
@@ -54,9 +55,15 @@ import { c, done, errorLine } from './ui'
 // a clean exit. Inside an active clack prompt Ctrl+C is still aliased to
 // cancel, so the abort hotkey is "cancel twice in a row".
 export class WizardAbortedError extends Error {
-  constructor() {
+  // When the wizard ran a successful eager OAuth login before aborting, the
+  // resulting credentials are already on disk at `<cwd>/secrets.json`. The
+  // CLI surfaces this on abort so the user knows to either re-run init in
+  // the same directory (the credentials will be reused) or delete the file.
+  readonly oauthCredentialsSaved: boolean
+  constructor(options: { oauthCredentialsSaved?: boolean } = {}) {
     super('Wizard aborted by user')
     this.name = 'WizardAbortedError'
+    this.oauthCredentialsSaved = options.oauthCredentialsSaved === true
   }
 }
 
@@ -102,11 +109,37 @@ export const init = defineCommand({
     intro('Initializing TypeClaw...')
     log.info('Press ESC at any prompt to go back. Press ESC twice in a row to abort.')
 
+    // Docker preflight runs BEFORE the wizard so an OAuth login (which the
+    // wizard fires the moment the user picks "OAuth (browser login)") doesn't
+    // burn a real browser flow on an agent folder we can't actually start.
+    // `runInit` re-runs the preflight as a defense-in-depth gate, but
+    // surfacing the failure here lets the user fix Docker without re-doing
+    // every wizard step.
+    const preflightSpinner = spinner()
+    preflightSpinner.start('Checking Docker...')
+    const preflight = await checkDockerAvailable()
+    if (!preflight.ok) {
+      preflightSpinner.error(preflightFailureSummary(preflight))
+      note(preflightFailureGuidance(preflight).join('\n'), 'Docker check failed')
+      process.exit(1)
+    }
+    preflightSpinner.stop('Docker is reachable.')
+
     let collected: CollectedInputs
     try {
       collected = await collectWizardInputs(cwd, defaultWizardPrompts)
     } catch (error) {
       if (error instanceof WizardAbortedError) {
+        if (error.oauthCredentialsSaved) {
+          note(
+            [
+              'OAuth credentials were saved to `secrets.json` before you aborted.',
+              'Re-run `typeclaw init` here to pick up where you left off (the credentials',
+              'will be reused), or delete `secrets.json` if you want a clean restart.',
+            ].join('\n'),
+            'Saved OAuth credentials',
+          )
+        }
         cancel('Aborted.')
         process.exit(0)
       }
@@ -309,9 +342,24 @@ export interface WizardPrompts {
   hasExistingChannelSecrets: (cwd: string, channel: Exclude<ChannelChoice, 'none'>) => Promise<boolean>
   askReuseExistingChannel: (channel: Exclude<ChannelChoice, 'none'>) => Promise<StepResult<'reuse' | 'prompt'>>
   runChannelFlow: (choice: ChannelChoice) => Promise<StepResult<CollectedInputs['channelSecrets']>>
-  buildOAuthAuth: (provider: (typeof KNOWN_PROVIDERS)[KnownProviderId]) => LLMAuth
+  runOAuthLogin: (
+    provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+    cwd: string,
+    model: KnownModelRef,
+  ) => Promise<OAuthLoginResult>
+  // Asked after a failed OAuth login. `apiKeyAvailable` is true when the
+  // provider also supports api-key auth (so the wizard can offer a fallback
+  // path); false for OAuth-only providers like openai-codex, where the only
+  // options are retry or abort.
+  askOAuthFailureRecovery: (
+    provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+    reason: string,
+    apiKeyAvailable: boolean,
+  ) => Promise<OAuthFailureRecovery>
 }
 
+export type OAuthFailureRecovery = 'retry' | 'api-key' | 'abort'
+
 export const defaultWizardPrompts: WizardPrompts = {
   loadCatalog,
   readExistingApiKey: readExistingProviderApiKey,
@@ -326,10 +374,8 @@ export const defaultWizardPrompts: WizardPrompts = {
   hasExistingChannelSecrets,
   askReuseExistingChannel,
   runChannelFlow,
-  buildOAuthAuth: (provider) => ({
-    kind: 'oauth',
-    runLogin: makeOAuthLoginRunner(buildOAuthCallbacks(provider.name)),
-  }),
+  runOAuthLogin: (provider, cwd, model) => makeOAuthLoginRunner(buildOAuthCallbacks(provider.name))({ cwd, model }),
+  askOAuthFailureRecovery,
 }
 
 export async function collectWizardInputs(cwd: string, prompts: WizardPrompts): Promise<CollectedInputs> {
@@ -337,10 +383,15 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
   const state: WizardState = { catalog }
   let step: StepId = 'pick-provider'
   let pendingBackOrigin: StepId | null = null
+  let oauthCredentialsSaved = false
+
+  const abort = (): never => {
+    throw new WizardAbortedError({ oauthCredentialsSaved })
+  }
 
   const onResult = <T>(currentStep: StepId, result: StepResult<T>): StepResult<T> => {
     if (result.kind === 'back') {
-      if (pendingBackOrigin === currentStep) throw new WizardAbortedError()
+      if (pendingBackOrigin === currentStep) abort()
       pendingBackOrigin = currentStep
     } else if (!result.auto) {
       pendingBackOrigin = null
@@ -410,7 +461,32 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
         }
         state.authMethod = result.value
         if (result.value === 'oauth') {
-          state.llmAuth = prompts.buildOAuthAuth(provider)
+          // Run the browser login eagerly so the user sees the OAuth URL the
+          // moment they pick "OAuth (browser login)" — not at the end of the
+          // wizard. On failure we ask the user how to recover (retry / fall
+          // back to API key / abort) instead of dumping them back into the
+          // auth method picker with no guidance.
+          const login = await runOAuthLoginSafely(prompts, provider, cwd, state.model!.ref)
+          if (!login.ok) {
+            const recovery = await prompts.askOAuthFailureRecovery(
+              provider,
+              login.reason,
+              providerSupportsApiKey(provider),
+            )
+            // The recovery prompt is a fresh user decision, so it must clear
+            // any back-token left over from an earlier step. Without this, a
+            // sequence like `enter-api-key → back → autoValue('oauth') →
+            // OAuth fails → recovery=api-key → enter-api-key` would treat the
+            // user's NEXT back press as a double-back and abort the wizard.
+            pendingBackOrigin = null
+            if (recovery === 'abort') abort()
+            state.authMethod = recovery === 'api-key' ? 'api-key' : undefined
+            state.llmAuth = undefined
+            step = recovery === 'api-key' ? 'enter-api-key' : 'pick-auth-method'
+            break
+          }
+          oauthCredentialsSaved = true
+          state.llmAuth = { kind: 'oauth-completed' }
           step = stepAfterDefaultAuth(state)
         } else {
           step = 'enter-api-key'
@@ -498,7 +574,25 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
         }
         state.visionAuthMethod = result.value
         if (result.value === 'oauth') {
-          state.visionLlmAuth = prompts.buildOAuthAuth(provider)
+          // Same eager-login + recovery-prompt rationale as the default-provider branch above.
+          const login = await runOAuthLoginSafely(prompts, provider, cwd, state.visionModel!.ref)
+          if (!login.ok) {
+            const recovery = await prompts.askOAuthFailureRecovery(
+              provider,
+              login.reason,
+              providerSupportsApiKey(provider),
+            )
+            // See the matching pendingBackOrigin reset in the default-provider
+            // branch above — same reasoning applies to vision auth recovery.
+            pendingBackOrigin = null
+            if (recovery === 'abort') abort()
+            state.visionAuthMethod = recovery === 'api-key' ? 'api-key' : undefined
+            state.visionLlmAuth = undefined
+            step = recovery === 'api-key' ? 'enter-vision-api-key' : 'pick-vision-auth-method'
+            break
+          }
+          oauthCredentialsSaved = true
+          state.visionLlmAuth = { kind: 'oauth-completed' }
           step = 'pick-channel'
         } else {
           step = 'enter-vision-api-key'
@@ -570,6 +664,25 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
   }
 }
 
+// Belt-and-suspenders wrapper: `makeOAuthLoginRunner` already catches the
+// upstream pi-ai login flow and returns `{ ok: false, reason }`, but the
+// wizard cannot afford ANY uncaught throw from a custom runner (test seam,
+// future plugin-contributed runner) — it would bubble out of
+// `collectWizardInputs` and exit the whole init. Coerce unexpected throws to
+// the normal failure path so the recovery prompt always fires.
+async function runOAuthLoginSafely(
+  prompts: WizardPrompts,
+  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+  cwd: string,
+  model: KnownModelRef,
+): Promise<OAuthLoginResult> {
+  try {
+    return await prompts.runOAuthLogin(provider, cwd, model)
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+}
+
 function finalize(state: WizardState, channelSecrets: CollectedInputs['channelSecrets']): CollectedInputs {
   return {
     model: state.model!,
@@ -768,6 +881,28 @@ async function askApiKey(provider: (typeof KNOWN_PROVIDERS)[KnownProviderId]): P
   return value(apiKey)
 }
 
+async function askOAuthFailureRecovery(
+  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+  reason: string,
+  apiKeyAvailable: boolean,
+): Promise<OAuthFailureRecovery> {
+  note(reason, `${provider.name} OAuth login failed`)
+  const options: Array<{ value: OAuthFailureRecovery; label: string; hint?: string }> = [
+    { value: 'retry', label: 'Retry OAuth login' },
+  ]
+  if (apiKeyAvailable) {
+    options.push({ value: 'api-key', label: `Use a ${provider.name} API key instead` })
+  }
+  options.push({ value: 'abort', label: 'Abort init', hint: 'you can re-run `typeclaw init` later' })
+  const choice = await select<OAuthFailureRecovery>({
+    message: 'What next?',
+    options,
+    initialValue: 'retry',
+  })
+  if (isCancel(choice)) return 'abort'
+  return choice
+}
+
 async function pickChannel(initial: ChannelChoice | undefined): Promise<StepResult<ChannelChoice>> {
   const choice = await select<ChannelChoice>({
     message: 'Pick a channel to wire (you can add more later by editing typeclaw.json + secrets.json)',
@@ -870,50 +1005,7 @@ async function runSlackFlow(): Promise<StepResult<CollectedInputs['channelSecret
   let sub: SubStep = 'bot'
   let botToken: string | undefined
 
-  note(
-    [
-      '1. https://api.slack.com/apps → Create New App → From a manifest.',
-      '   Pick your workspace, then paste this JSON manifest:',
-      '',
-      '   {',
-      '     "display_information": { "name": "TypeClaw" },',
-      '     "features": {',
-      '       "bot_user": { "display_name": "TypeClaw", "always_online": true }',
-      '     },',
-      '     "oauth_config": {',
-      '       "scopes": {',
-      '         "bot": [',
-      '           "app_mentions:read", "chat:write", "users:read", "files:read",',
-      '           "channels:history", "channels:read",',
-      '           "groups:history",   "groups:read",',
-      '           "im:history",       "im:read",',
-      '           "mpim:history",     "mpim:read"',
-      '         ]',
-      '       }',
-      '     },',
-      '     "settings": {',
-      '       "event_subscriptions": {',
-      '         "bot_events": [',
-      '           "app_mention",',
-      '           "message.channels", "message.groups",',
-      '           "message.im",       "message.mpim"',
-      '         ]',
-      '       },',
-      '       "socket_mode_enabled": true',
-      '     }',
-      '   }',
-      '',
-      '2. Install to Workspace, then OAuth & Permissions →',
-      '   copy the Bot User OAuth Token (xoxb-...).',
-      '3. Basic Information → App-Level Tokens → Generate Token and',
-      '   Scopes, add the connections:write scope, and copy the',
-      '   token (xapp-...). Socket Mode needs this; the manifest',
-      '   cannot grant it.',
-      '4. Invite the bot to any private channel or DM you want it in:',
-      '   /invite @TypeClaw',
-    ].join('\n'),
-    'Get a Slack bot',
-  )
+  printSlackAppManifestSetup()
 
   while (true) {
     if (sub === 'bot') {
@@ -1261,37 +1353,6 @@ export async function decideExistingApiKeyReuse(
   return reuse === true ? 'reuse' : 'prompt'
 }
 
-// Wraps the OAuth lifecycle into the same clack idiom the rest of the wizard
-// uses: a spinner over the "waiting for login" period, with onAuth printing
-// the URL the user needs to open and onPrompt falling back to a `text`
-// prompt for the manual code path. The spinner is started by onAuth and
-// stopped by the caller (runInit) — we don't try to manage it here because
-// the spinner lifecycle has to span emit('start') -> emit('done').
-function buildOAuthCallbacks(providerName: string) {
-  return {
-    onAuth: (url: string, instructions?: string) => {
-      // Don't put the URL inside note(): clack wraps long lines with the box
-      // border `│` on each wrapped segment, which corrupts the URL when the
-      // user copy-pastes it. Keep instructional text in the box, but print
-      // the URL itself as a bare console.log line that any terminal will
-      // hyperlink intact.
-      const preamble = [`Open this URL in your browser to authorize ${providerName}.`]
-      if (instructions) preamble.push('', instructions)
-      note(preamble.join('\n'), 'Browser login')
-      console.log(url)
-      console.log('')
-    },
-    onProgress: (message: string) => {
-      log.info(message)
-    },
-    onPrompt: async (message: string, placeholder?: string): Promise<string | null> => {
-      const value = await text({ message, ...(placeholder !== undefined ? { placeholder } : {}) })
-      if (isCancel(value)) return null
-      return value
-    },
-  }
-}
-
 function uniqueProviders(options: ModelOption[]): KnownProviderId[] {
   const seen = new Set<KnownProviderId>()
   const out: KnownProviderId[] = []

package/src/cli/model.ts

@@ -25,7 +25,7 @@ const ADD_PROVIDER_SENTINEL = '__add-provider__'
 const setSub = defineCommand({
   meta: {
     name: 'set',
-    description: 'set or update a model profile (default | fast | vision | <custom>)',
+    description: 'set or update a model profile (default | fast | deep | vision | <custom>)',
   },
   args: {
     profile: {
@@ -157,15 +157,23 @@ const listSub = defineCommand({
     }
 
     const profileWidth = Math.max(7, ...entries.map((e) => e.profile.length))
-    const refWidth = Math.max(3, ...entries.map((e) => e.ref.length))
+    const refDisplay = (e: (typeof entries)[number]): string =>
+      e.refs.length > 1 ? `${e.ref} ${c.dim(`(+${e.refs.length - 1} fallback)`)}` : e.ref
+    const refWidth = Math.max(3, ...entries.map((e) => e.ref.length + (e.refs.length > 1 ? 14 : 0)))
 
     const header = `${'PROFILE'.padEnd(profileWidth)}  ${'REF'.padEnd(refWidth)}  PROVIDER  STATUS`
     console.log(c.dim(header))
     for (const e of entries) {
       const star = e.isDefault ? c.cyan('*') : ' '
       const status = e.credentialStatus === 'available' ? c.green('ok') : c.yellow('missing-credentials')
-      const line = `${star}${e.profile.padEnd(profileWidth - 1)}  ${e.ref.padEnd(refWidth)}  ${e.providerId.padEnd(12)}  ${status}`
+      const line = `${star}${e.profile.padEnd(profileWidth - 1)}  ${refDisplay(e).padEnd(refWidth)}  ${e.providerId.padEnd(12)}  ${status}`
       console.log(line)
+      if (e.refs.length > 1) {
+        for (let i = 1; i < e.refs.length; i++) {
+          const fb = e.refs[i]!
+          console.log(`${' '.padEnd(profileWidth + 2)}↳ ${c.dim(fb)}`)
+        }
+      }
     }
   },
 })
@@ -198,6 +206,7 @@ async function pickProfileName(): Promise<string> {
     options: [
       { value: 'default', label: 'default', hint: 'active model for new sessions' },
       { value: 'fast', label: 'fast', hint: 'optional alias used by some subagents' },
+      { value: 'deep', label: 'deep', hint: 'optional alias used by some subagents' },
       { value: 'vision', label: 'vision', hint: 'optional alias used by some subagents' },
     ],
     initialValue: 'default',

package/src/cli/oauth-callbacks.ts

@@ -0,0 +1,49 @@
+import { isCancel, log, note, text } from '@clack/prompts'
+
+import type { OAuthCallbacks } from '@/init/oauth-login'
+
+// Shared between `typeclaw init` (src/cli/init.ts) and `typeclaw provider
+// add/set` (src/cli/provider.ts). Both call into the same OAuth runner, so
+// they need to render the same UX: a note() box with the URL + cross-device
+// guidance, a `text()` prompt for the post-callback manual fallback, and a
+// concurrent `onManualCodeInput` prompt for users whose browser is on a
+// different host than the CLI. See src/init/oauth-login.ts for the contract
+// on each callback and why onManualCodeInput is required for cross-device.
+export function buildOAuthCallbacks(providerName: string): OAuthCallbacks {
+  return {
+    onAuth: (url, instructions) => {
+      // Don't put the URL inside note(): clack wraps long lines with the box
+      // border `│` on each wrapped segment, which corrupts the URL when the
+      // user copy-pastes it. Keep instructional text in the box, but print
+      // the URL itself as a bare console.log line that any terminal will
+      // hyperlink intact.
+      const preamble = [
+        `Open this URL in your browser to sign in to ${providerName}.`,
+        '',
+        'If your browser shows "this site can\'t be reached" after you sign in,',
+        'copy the full address from the top of the browser and paste it below.',
+      ]
+      if (instructions) preamble.push('', instructions)
+      note(preamble.join('\n'), 'Browser login')
+      console.log(url)
+      console.log('')
+    },
+    onProgress: (message) => {
+      log.info(message)
+    },
+    onPrompt: async (message, placeholder) => {
+      const value = await text({ message, ...(placeholder !== undefined ? { placeholder } : {}) })
+      if (isCancel(value)) return null
+      return value
+    },
+    onManualCodeInput: async () => {
+      const value = await text({
+        message:
+          'If your browser shows "this site can\'t be reached" after you sign in, copy the full address from the top of the browser and paste it here:',
+        placeholder: 'http://localhost:1455/auth/callback?code=...&state=...',
+      })
+      if (isCancel(value)) throw new Error('Login cancelled by user')
+      return value
+    },
+  }
+}

package/src/cli/provider.ts

@@ -1,4 +1,4 @@
-import { cancel, intro, isCancel, log, note, password, select, text } from '@clack/prompts'
+import { cancel, intro, isCancel, log, password, select } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
 import {
@@ -17,6 +17,7 @@ import {
 import { findAgentDir, isInitialized } from '@/init'
 import { makeOAuthLoginRunner } from '@/init/oauth-login'
 
+import { buildOAuthCallbacks } from './oauth-callbacks'
 import { c, done, errorLine } from './ui'
 
 const addSub = defineCommand({
@@ -366,25 +367,7 @@ async function runOAuthLogin(cwd: string, providerId: KnownProviderId): Promise<
   }
   const modelRef = `${providerId}/${ref}` as const
 
-  const callbacks = {
-    onAuth: (url: string, instructions?: string) => {
-      const preamble = [`Open this URL in your browser to authorize ${provider.name}.`]
-      if (instructions) preamble.push('', instructions)
-      note(preamble.join('\n'), 'Browser login')
-      console.log(url)
-      console.log('')
-    },
-    onProgress: (message: string) => {
-      log.info(message)
-    },
-    onPrompt: async (message: string, placeholder?: string): Promise<string | null> => {
-      const value = await text({ message, ...(placeholder !== undefined ? { placeholder } : {}) })
-      if (isCancel(value)) return null
-      return value
-    },
-  }
-
-  const runner = makeOAuthLoginRunner(callbacks)
+  const runner = makeOAuthLoginRunner(buildOAuthCallbacks(provider.name))
   const result = await runner({ cwd, model: modelRef as Parameters<typeof runner>[0]['model'] })
   if (!result.ok) return { ok: false, reason: result.reason }
   return { ok: true }

package/src/cli/ui.ts

@@ -124,3 +124,98 @@ export function errorLine(reason: string): string {
 export function successLine(message: string): string {
   return `${c.green('●')} ${message}`
 }
+
+// The exact JSON manifest a user pastes into
+// https://api.slack.com/apps → From a manifest. Kept as a typed object so
+// the file stays a single source of truth and `JSON.stringify` guarantees
+// the rendered text is always valid JSON — no risk of a stray comma or
+// quote slipping in through hand-formatting.
+export const SLACK_APP_MANIFEST = {
+  display_information: { name: 'TypeClaw' },
+  features: {
+    bot_user: { display_name: 'TypeClaw', always_online: true },
+    // Enable the Messages tab so users can DM the bot from its app profile,
+    // and disable the Home tab — TypeClaw does not publish a custom App Home
+    // view, and leaving it enabled would surface an empty default tab.
+    app_home: {
+      home_tab_enabled: false,
+      messages_tab_enabled: true,
+      messages_tab_read_only_enabled: false,
+    },
+  },
+  oauth_config: {
+    scopes: {
+      // Ordered alphabetically so the manifest stays a stable diff target.
+      // Read scopes cover every conversation type the agent might observe;
+      // write scopes (chat, files, im/mpim/groups, pins, reactions) let the
+      // agent post replies, upload attachments, open DMs, pin messages, and
+      // react to messages. `channels:join` lets the bot self-join public
+      // channels it's invited to discuss in.
+      bot: [
+        'app_mentions:read',
+        'channels:history',
+        'channels:join',
+        'channels:read',
+        'chat:write',
+        'emoji:read',
+        'files:read',
+        'files:write',
+        'groups:history',
+        'groups:read',
+        'groups:write',
+        'im:history',
+        'im:read',
+        'im:write',
+        'mpim:history',
+        'mpim:read',
+        'mpim:write',
+        'pins:read',
+        'pins:write',
+        'reactions:read',
+        'reactions:write',
+        'users:read',
+      ],
+    },
+  },
+  settings: {
+    event_subscriptions: {
+      bot_events: ['app_mention', 'message.channels', 'message.groups', 'message.im', 'message.mpim'],
+    },
+    socket_mode_enabled: true,
+  },
+} as const
+
+// Prints the "create a Slack app from a manifest" walkthrough so the JSON
+// payload is **flush-left and copy-pasteable**. Clack's `note()` wraps
+// content inside a box with `│` borders on both sides, and `log.message()`
+// still prefixes every line with a `│  ` guide column — neither survives a
+// click-and-drag copy. This helper splits the walkthrough into three
+// segments: a boxed prose intro, a raw-stdout JSON block, and a boxed
+// follow-up. The JSON block is emitted via `process.stdout.write` so it
+// carries zero terminal decoration.
+export function printSlackAppManifestSetup(output: NodeJS.WritableStream = process.stdout): void {
+  note(
+    [
+      '1. https://api.slack.com/apps → Create New App → From a manifest.',
+      '   Pick your workspace, then paste the JSON manifest printed below',
+      `   (it is rendered flush-left so you can ${c.bold('click-drag and copy')} cleanly).`,
+    ].join('\n'),
+    'Get a Slack bot',
+  )
+  output.write('\n')
+  output.write(`${JSON.stringify(SLACK_APP_MANIFEST, null, 2)}\n`)
+  output.write('\n')
+  note(
+    [
+      '2. Install to Workspace, then OAuth & Permissions →',
+      '   copy the Bot User OAuth Token (xoxb-...).',
+      '3. Basic Information → App-Level Tokens → Generate Token and',
+      '   Scopes, add the connections:write scope, and copy the',
+      '   token (xapp-...). Socket Mode needs this; the manifest',
+      '   cannot grant it.',
+      '4. Invite the bot to any private channel or DM you want it in:',
+      '   /invite @TypeClaw',
+    ].join('\n'),
+    'Finish Slack setup',
+  )
+}