kimaki 0.10.2 → 0.11.0

package/dist/interaction-handler.js

@@ -45,7 +45,7 @@ import { handleScreenshareCommand, handleScreenshareStopCommand, } from './comma
 import { handleVscodeCommand } from './commands/vscode.js';
 import { handleModelVariantSelectMenu } from './commands/model.js';
 import { handleModelVariantCommand, handleVariantQuickSelectMenu, handleVariantScopeSelectMenu, } from './commands/model-variant.js';
-import { hasKimakiBotPermission } from './discord-utils.js';
+import { hasKimakiAdminPermission, hasKimakiBotPermission } from './discord-utils.js';
 import { createLogger, LogPrefix } from './logger.js';
 import { notifyError } from './sentry.js';
 const interactionLogger = createLogger(LogPrefix.INTERACTION);
@@ -178,6 +178,13 @@ export function registerInteractionHandler({ discordClient, appId, }) {
                         await handleUnsetModelCommand({ interaction, appId });
                         return;
                     case 'login':
+                        if (!hasKimakiAdminPermission(interaction.member, interaction.guild)) {
+                            await interaction.reply({
+                                content: `Only server admins or users with the **Kimaki** role can configure login credentials.`,
+                                flags: MessageFlags.Ephemeral,
+                            });
+                            return;
+                        }
                         await handleLoginCommand({ interaction, appId });
                         return;
                     case 'agent':
@@ -223,6 +230,13 @@ export function registerInteractionHandler({ discordClient, appId, }) {
                         });
                         return;
                     case 'transcription-key':
+                        if (!hasKimakiAdminPermission(interaction.member, interaction.guild)) {
+                            await interaction.reply({
+                                content: `Only server admins or users with the **Kimaki** role can configure API keys.`,
+                                flags: MessageFlags.Ephemeral,
+                            });
+                            return;
+                        }
                         await handleTranscriptionApiKeyCommand({
                             interaction,
                             appId,
@@ -269,6 +283,13 @@ export function registerInteractionHandler({ discordClient, appId, }) {
                 }
                 const customId = interaction.customId;
                 if (customId.startsWith('transcription_apikey:')) {
+                    if (!hasKimakiAdminPermission(interaction.member, interaction.guild)) {
+                        await interaction.reply({
+                            content: `Only server admins or users with the **Kimaki** role can configure API keys.`,
+                            flags: MessageFlags.Ephemeral,
+                        });
+                        return;
+                    }
                     await handleTranscriptionApiKeyButton(interaction);
                     return;
                 }
@@ -283,14 +304,35 @@ export function registerInteractionHandler({ discordClient, appId, }) {
                     return;
                 }
                 if (customId.startsWith('login_text_btn:')) {
+                    if (!hasKimakiAdminPermission(interaction.member, interaction.guild)) {
+                        await interaction.reply({
+                            content: `Only server admins or users with the **Kimaki** role can configure login credentials.`,
+                            flags: MessageFlags.Ephemeral,
+                        });
+                        return;
+                    }
                     await handleLoginTextButton(interaction);
                     return;
                 }
                 if (customId.startsWith('login_apikey_btn:')) {
+                    if (!hasKimakiAdminPermission(interaction.member, interaction.guild)) {
+                        await interaction.reply({
+                            content: `Only server admins or users with the **Kimaki** role can configure login credentials.`,
+                            flags: MessageFlags.Ephemeral,
+                        });
+                        return;
+                    }
                     await handleLoginApiKeyButton(interaction);
                     return;
                 }
                 if (customId.startsWith('login_oauth_code_btn:')) {
+                    if (!hasKimakiAdminPermission(interaction.member, interaction.guild)) {
+                        await interaction.reply({
+                            content: `Only server admins or users with the **Kimaki** role can configure login credentials.`,
+                            flags: MessageFlags.Ephemeral,
+                        });
+                        return;
+                    }
                     await handleOAuthCodeButton(interaction);
                     return;
                 }
@@ -362,6 +404,13 @@ export function registerInteractionHandler({ discordClient, appId, }) {
                     return;
                 }
                 if (customId.startsWith('login_select:')) {
+                    if (!hasKimakiAdminPermission(interaction.member, interaction.guild)) {
+                        await interaction.reply({
+                            content: `Only server admins or users with the **Kimaki** role can configure login credentials.`,
+                            flags: MessageFlags.Ephemeral,
+                        });
+                        return;
+                    }
                     await handleLoginSelect(interaction);
                     return;
                 }
@@ -377,18 +426,46 @@ export function registerInteractionHandler({ discordClient, appId, }) {
                 }
                 const customId = interaction.customId;
                 if (customId.startsWith('login_apikey:')) {
+                    if (!hasKimakiAdminPermission(interaction.member, interaction.guild)) {
+                        await interaction.reply({
+                            content: `Only server admins or users with the **Kimaki** role can configure credentials.`,
+                            flags: MessageFlags.Ephemeral,
+                        });
+                        return;
+                    }
                     await handleApiKeyModalSubmit(interaction);
                     return;
                 }
                 if (customId.startsWith('login_text:')) {
+                    if (!hasKimakiAdminPermission(interaction.member, interaction.guild)) {
+                        await interaction.reply({
+                            content: `Only server admins or users with the **Kimaki** role can configure credentials.`,
+                            flags: MessageFlags.Ephemeral,
+                        });
+                        return;
+                    }
                     await handleLoginTextModalSubmit(interaction);
                     return;
                 }
                 if (customId.startsWith('login_oauth_code:')) {
+                    if (!hasKimakiAdminPermission(interaction.member, interaction.guild)) {
+                        await interaction.reply({
+                            content: `Only server admins or users with the **Kimaki** role can configure credentials.`,
+                            flags: MessageFlags.Ephemeral,
+                        });
+                        return;
+                    }
                     await handleOAuthCodeModalSubmit(interaction);
                     return;
                 }
                 if (customId.startsWith('transcription_apikey_modal:')) {
+                    if (!hasKimakiAdminPermission(interaction.member, interaction.guild)) {
+                        await interaction.reply({
+                            content: `Only server admins or users with the **Kimaki** role can configure credentials.`,
+                            flags: MessageFlags.Ephemeral,
+                        });
+                        return;
+                    }
                     await handleTranscriptionApiKeyModalSubmit(interaction);
                     return;
                 }

package/dist/session-handler/thread-session-runtime.js

@@ -1859,7 +1859,7 @@ export class ThreadSessionRuntime {
             await this.persistEventBufferDebounced.flush();
             return;
         }
-        const errorMessage = formatSessionErrorFromProps(properties.error);
+        const errorMessage = truncateSessionErrorMessage(formatSessionErrorFromProps(properties.error));
         logger.error(`Sending error to thread: ${errorMessage}`);
         await sendThreadMessage(this.thread, `✗ opencode session error: ${errorMessage}`, { flags: NOTIFY_MESSAGE_FLAGS });
         await this.persistEventBufferDebounced.flush();
@@ -3541,3 +3541,10 @@ function formatSessionErrorFromProps(error) {
     }
     return parts.length > 0 ? parts.join(' ') : error.name || 'Unknown error';
 }
+function truncateSessionErrorMessage(message) {
+    const maxLength = 400;
+    if (message.length <= maxLength) {
+        return message;
+    }
+    return `${message.slice(0, maxLength - 1)}…`;
+}

package/dist/store.js

@@ -11,6 +11,7 @@ export const store = createStore(() => ({
     critiqueEnabled: true,
     enabledSkills: [],
     disabledSkills: [],
+    allowAllUsers: false,
     discordBaseUrl: 'https://discord.com',
     gatewayToken: null,
     registeredUserCommands: [],

package/dist/system-message.js

@@ -317,6 +317,22 @@ To upload files to the Discord thread (images, screenshots, long files that woul
 
 kimaki upload-to-discord --session ${sessionId} <file1> [file2] ...
 
+## generating audio from text
+
+When the user asks you to generate audio of some text so they can listen instead of reading, use \`kimaki tts\` to create a speech file and \`kimaki upload-to-discord\` to send it to the thread. Only use this when the user explicitly asks for audio.
+
+\`\`\`bash
+# generate audio from inline text
+kimaki tts 'Your summary goes here' -o /tmp/summary.mp3
+kimaki upload-to-discord --session ${sessionId} /tmp/summary.mp3
+
+# generate audio from a file (pipe via stdin)
+cat docs/explanation.md | kimaki tts -o /tmp/explanation.mp3
+kimaki upload-to-discord --session ${sessionId} /tmp/explanation.mp3
+\`\`\`
+
+see --help for options like voice, speed, etc.
+
 ## requesting files from the user
 
 To ask the user to upload files from their device, use the \`kimaki_file_upload\` tool. This shows a native file picker dialog in Discord. The files are downloaded to the project's \`uploads/\` directory and the tool returns the local file paths.

package/dist/voice-handler.js

@@ -9,10 +9,11 @@ import path from 'node:path';
 import { Transform } from 'node:stream';
 import * as prism from 'prism-media';
 import dedent from 'string-dedent';
-import { Events, ActionRowBuilder, ButtonBuilder, ButtonStyle, } from 'discord.js';
+import { Events, } from 'discord.js';
 import { createGenAIWorker } from './genai-worker-wrapper.js';
 import { getVoiceChannelDirectory, getGeminiApiKey, getTranscriptionApiKey, findTextChannelByVoiceChannel, } from './database.js';
-import { sendThreadMessage, escapeDiscordFormatting, SILENT_MESSAGE_FLAGS, NOTIFY_MESSAGE_FLAGS, hasKimakiBotPermission, } from './discord-utils.js';
+import { sendThreadMessage, escapeDiscordFormatting, NOTIFY_MESSAGE_FLAGS, hasKimakiBotPermission, } from './discord-utils.js';
+import { showApiKeyRequiredButton } from './commands/gemini-apikey.js';
 import { transcribeAudio } from './voice.js';
 import { FetchError } from './errors.js';
 import { store } from './store.js';
@@ -420,15 +421,10 @@ export async function processVoiceAttachment({ message, thread, projectDirectory
     }
     if (!transcriptionApiKey) {
         if (appId) {
-            const button = new ButtonBuilder()
-                .setCustomId(`transcription_apikey:${appId}`)
-                .setLabel('Set Transcription API Key')
-                .setStyle(ButtonStyle.Primary);
-            const row = new ActionRowBuilder().addComponents(button);
-            await thread.send({
-                content: 'Voice transcription requires an API key (OpenAI or Gemini). Set one to enable voice message transcription.',
-                components: [row],
-                flags: SILENT_MESSAGE_FLAGS,
+            await showApiKeyRequiredButton({
+                thread,
+                appId,
+                message: 'Voice transcription requires an API key (OpenAI or Gemini). Set one to enable voice message transcription.',
             });
         }
         else {

package/dist/voice.js

@@ -13,7 +13,7 @@ import { Readable } from 'node:stream';
 import prism from 'prism-media';
 import * as errore from 'errore';
 import { createLogger, LogPrefix } from './logger.js';
-import { ApiKeyMissingError, InvalidAudioFormatError, TranscriptionError, EmptyTranscriptionError, NoResponseContentError, NoToolResponseError, } from './errors.js';
+import { ApiKeyMissingError, InvalidAudioFormatError, TranscriptionError, EmptyTranscriptionError, NoResponseContentError, NoToolResponseError, SpeechGenerationError, } from './errors.js';
 const voiceLogger = createLogger(LogPrefix.VOICE);
 // OpenAI input_audio only supports wav and mp3. Other formats (OGG Opus, etc)
 // must be converted before sending.
@@ -456,3 +456,128 @@ Note: "critique" is a CLI tool for showing diffs in the browser.`;
         provider: resolvedProvider,
     });
 }
+/** Default voices per provider. OpenAI uses short names, Google uses prebuilt voice names. */
+const DEFAULT_VOICES = {
+    openai: 'alloy',
+    gemini: 'Kore',
+};
+/** Available OpenAI TTS models. gpt-4o-mini-tts supports instructions for style control. */
+const OPENAI_TTS_MODEL = 'gpt-4o-mini-tts';
+/** Gemini TTS model ID. Uses language model interface with AUDIO response modality. */
+const GEMINI_TTS_MODEL = 'gemini-2.5-flash-preview-tts';
+/**
+ * Create an OpenAI SpeechModelV3 for TTS.
+ * Uses gpt-4o-mini-tts which supports instructions for voice style control.
+ */
+function createOpenAISpeechModel({ apiKey }) {
+    const openai = createOpenAI({ apiKey });
+    return openai.speech(OPENAI_TTS_MODEL);
+}
+/**
+ * Generate speech via OpenAI SpeechModelV3.
+ * Returns mp3 audio by default.
+ */
+async function generateSpeechOpenAI({ text, voice, apiKey, instructions, speed, }) {
+    const model = createOpenAISpeechModel({ apiKey });
+    const response = await Promise.resolve(model.doGenerate({
+        text,
+        voice: voice || DEFAULT_VOICES.openai,
+        outputFormat: 'mp3',
+        instructions,
+        speed,
+        providerOptions: {
+            openai: {
+                ...(instructions ? { instructions } : {}),
+                ...(speed ? { speed } : {}),
+            },
+        },
+    })).catch((e) => new SpeechGenerationError({ reason: `OpenAI TTS API call failed: ${String(e)}`, cause: e }));
+    if (response instanceof Error)
+        return response;
+    const audioData = typeof response.audio === 'string'
+        ? Buffer.from(response.audio, 'base64')
+        : Buffer.from(response.audio);
+    if (audioData.length === 0) {
+        return new SpeechGenerationError({ reason: 'OpenAI TTS returned empty audio' });
+    }
+    return { audio: audioData, mediaType: 'audio/mp3' };
+}
+/**
+ * Generate speech via Google Gemini TTS model.
+ * Uses the language model interface with responseModalities: ['AUDIO'].
+ * Returns PCM WAV audio at 24kHz.
+ */
+async function generateSpeechGemini({ text, voice, apiKey, }) {
+    const google = createGoogleGenerativeAI({ apiKey });
+    const model = google(GEMINI_TTS_MODEL);
+    const resolvedVoice = voice || DEFAULT_VOICES.gemini;
+    const options = {
+        prompt: [
+            {
+                role: 'user',
+                content: [{ type: 'text', text }],
+            },
+        ],
+        providerOptions: {
+            google: {
+                responseModalities: ['AUDIO'],
+                speechConfig: {
+                    voiceConfig: {
+                        prebuiltVoiceConfig: {
+                            voiceName: resolvedVoice,
+                        },
+                    },
+                },
+            },
+        },
+    };
+    const response = await Promise.resolve(model.doGenerate(options)).catch((e) => new SpeechGenerationError({ reason: `Gemini TTS API call failed: ${String(e)}`, cause: e }));
+    if (response instanceof Error)
+        return response;
+    // Gemini returns audio as LanguageModelV3File parts with inlineData
+    const filePart = response.content.find((c) => c.type === 'file');
+    if (!filePart) {
+        return new SpeechGenerationError({ reason: 'Gemini TTS returned no audio content' });
+    }
+    const audioData = typeof filePart.data === 'string'
+        ? Buffer.from(filePart.data, 'base64')
+        : Buffer.from(filePart.data);
+    if (audioData.length === 0) {
+        return new SpeechGenerationError({ reason: 'Gemini TTS returned empty audio' });
+    }
+    // Gemini TTS returns raw PCM at 24kHz mono 16-bit LE; wrap it in a WAV header
+    // so Discord and other players can handle it directly.
+    const mediaType = filePart.mediaType || 'audio/wav';
+    const needsWavHeader = mediaType === 'audio/L16' ||
+        mediaType === 'audio/pcm' ||
+        mediaType.startsWith('audio/l16');
+    if (needsWavHeader) {
+        const wavHeader = createWavHeader({
+            dataLength: audioData.length,
+            sampleRate: 24000,
+            numChannels: 1,
+            bitsPerSample: 16,
+        });
+        return { audio: Buffer.concat([wavHeader, audioData]), mediaType: 'audio/wav' };
+    }
+    return { audio: audioData, mediaType };
+}
+/**
+ * Generate speech audio from text using OpenAI or Google TTS.
+ * Calls the provider's TTS API directly via AI SDK without the `ai` npm package.
+ *
+ * Provider auto-detection: sk-* prefix → OpenAI, otherwise → Gemini.
+ * OpenAI returns mp3, Gemini returns WAV (24kHz mono).
+ */
+export async function generateSpeech({ text, voice, apiKey: apiKeyParam, provider, instructions, speed, }) {
+    const apiKey = apiKeyParam || process.env.OPENAI_API_KEY || process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+        return new ApiKeyMissingError({ service: 'OpenAI or Gemini' });
+    }
+    const resolvedProvider = provider || (apiKey.startsWith('sk-') ? 'openai' : 'gemini');
+    voiceLogger.log(`Generating speech with ${resolvedProvider}, text length: ${text.length}`);
+    if (resolvedProvider === 'openai') {
+        return generateSpeechOpenAI({ text, voice, apiKey, instructions, speed });
+    }
+    return generateSpeechGemini({ text, voice, apiKey });
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "kimaki",
   "module": "index.ts",
   "type": "module",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "repository": "https://github.com/remorses/kimaki",
   "bin": "bin.js",
   "files": [
@@ -26,8 +26,8 @@
     "undici": "^8.0.2",
     "discord-digital-twin": "^0.1.0",
     "opencode-cached-provider": "^0.0.1",
-    "db": "^0.0.0",
-    "opencode-deterministic-provider": "^0.0.1"
+    "opencode-deterministic-provider": "^0.0.1",
+    "db": "^0.0.0"
   },
   "dependencies": {
     "@ai-sdk/google": "^3.0.53",
@@ -63,8 +63,8 @@
     "zod": "^4.3.6",
     "zustand": "^5.0.11",
     "errore": "^0.14.1",
-    "traforo": "^0.5.0",
     "libsqlproxy": "^0.1.0",
+    "traforo": "^0.5.0",
     "opencode-injection-guard": "^0.2.1"
   },
   "optionalDependencies": {

package/skills/goke/SKILL.md

@@ -38,6 +38,14 @@ npm install goke # or bun, pnpm, etc
 
 The README is the source of truth for rules, examples, testing patterns, JustBash integration, and API details.
 
+If the README or this skill mentions a `goke` export that is missing from the installed package, upgrade `goke` to latest first before adding workarounds or custom local detection code:
+
+```bash
+pnpm update goke --latest
+```
+
+Use the project package manager for the repo you are editing. After upgrading, re-check the export from the installed package and continue with the documented API.
+
 ## Terminal Colors
 
 **Never install a separate color library.** goke vendors picocolors and exports it as `colors`:
@@ -75,6 +83,37 @@ if (isAgent || !process.stdin.isTTY) {
 
 Supported agents: `cursor`, `claude`, `devin`, `replit`, `gemini`, `codex`, `auggie`, `opencode`, `kiro`, `goose`, `pi`. Set `AI_AGENT` env var to override.
 
+## Long-Running Interactive Commands
+
+Commands that start a browser/device login flow or any other long-running TTY-only interaction must fail fast in non-TTY shells. Do not start the flow and hope the agent notices the URL. The process must stay alive while the user approves the browser prompt, so agents need to launch it in a persistent terminal session like tuistory or tmux.
+
+Always guard these commands with `!process.stdout.isTTY` before making network requests, opening the browser, or starting spinners. Do not fail just because an agent is running the command if the command has a real TTY.
+
+```ts
+import dedent from 'string-dedent'
+import { goke } from 'goke'
+
+cli.command('login', 'Authenticate with browser login').action((options, { console, process }) => {
+  if (!process.stdout.isTTY) {
+    console.error(dedent`
+      mycli login needs an interactive terminal and must stay alive while you approve the browser login.
+
+      Run it in a background terminal session like tuistory or tmux, then wait for the URL/code:
+
+        bunx tuistory launch "mycli login" -s mycli-login
+        bunx tuistory -s mycli-login wait "/code:|https?:\\/\\//i" --timeout 15000
+
+      The login command exits by itself after successful browser approval.
+    `)
+    process.exit(1)
+  }
+
+  // Start device/browser login only after the guard.
+})
+```
+
+Use `tuistory wait` for the handoff point that needs user interaction. It returns nearby lines around the match, so agents can show the URL/code without a separate `tuistory read` call. Do not add `tuistory close` to login instructions when the CLI exits by itself after success.
+
 ## Shell Completions
 
 **Always add `.completions()` next to `.help()` in every CLI.** This gives users Tab completion for free.

package/skills/new-skill/SKILL.md

@@ -128,6 +128,7 @@ There is no rigid template. Structure the content in whatever way communicates t
 - **Use code blocks with language hints.** The agent uses these to generate correct code.
 - **Keep prose short between code blocks.** One or two sentences of explanation, then an example.
 - **Call out common mistakes.** If there is a gotcha the agent will likely hit, warn about it explicitly.
+- **Do not add HTML comments.** Skills are instructions, not generated files. Avoid comments like `<!-- Skill instructions for agents using ... -->`.
 
 ## What makes a good skill
 

package/skills/npm-package/SKILL.md

@@ -293,6 +293,29 @@ Resolution flow when `tsc` sees `import db from '#sqlite'`:
 - **Bun / browser runtime conditions can still point at `src`**, because
   those runtimes execute `.ts` directly and skip the build step.
 
+### Excluding heavy dependencies from server/client bundles
+
+`imports` conditions can swap a heavy client-only dependency for a lightweight
+noop stub on the server (or vice versa). This keeps the SSR bundle small
+without changing application code.
+
+```json
+{
+  "imports": {
+    "#prism": {
+      "types": "./dist/prism.d.ts",
+      "ssr": "./dist/prism-noop.js",
+      "browser": "./dist/prism.js",
+      "default": "./dist/prism.js"
+    }
+  }
+}
+```
+
+`src/prism.ts` imports the real library (~500KB). `src/prism-noop.ts` exports
+the same interface with stub implementations that return input unchanged.
+Application code imports from `#prism` and gets the right version automatically.
+
 ### Requirements
 
 This only works when:
@@ -608,6 +631,28 @@ dist
 
 Workspace packages inside a monorepo inherit the root `.gitignore`, so this only applies to standalone packages.
 
+## Peer dependencies
+
+Peer dependencies are installed by default by npm and pnpm. Use them to prevent a dependency from being duplicated in the consumer's `node_modules` tree. Common examples: `react`, `react-dom`, framework packages that must be singletons.
+
+To make peer dependencies optional, add `peerDependenciesMeta`:
+
+```json
+{
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "sass": "^1.70.0",
+    "tsx": "^4.8.1"
+  },
+  "peerDependenciesMeta": {
+    "sass": { "optional": true },
+    "tsx": { "optional": true }
+  }
+}
+```
+
+`react` above is required (no meta entry), so consumers must install it. `sass` and `tsx` are optional; the package works without them but can use them if present.
+
 ## common mistakes
 
 - if you need to use zod always use latest version

package/skills/spiceflow/SKILL.md

@@ -35,6 +35,8 @@ Reference examples for real-world usage:
 
 Always import and use `Link` from `spiceflow/react` for navigational links in Spiceflow apps. Do not render raw `<a>` elements for links. `Link` enables client-side navigation while preserving normal anchor behavior for external URLs, hashes, `target`, `rel`, styling, and event handlers. `Link` supports external URLs too, so it is fine to use for ambiguous or user-provided links when you do not know ahead of time whether they are internal or external.
 
+**`Link` auto-prepends the Vite `base` path.** Never manually prepend the base path to `Link` href values. `<Link href="/dashboard" />` automatically renders as `<a href="/my-app/dashboard">` when the Vite base is `/my-app/`. Manually prepending causes double-prefixing. This only applies to `Link`; raw `fetch()` calls, `Response.redirect()`, and other non-Link URL construction still need manual base path handling.
+
 ## OpenTelemetry instrumentation
 
 Spiceflow supports automatic route instrumentation when you pass an OpenTelemetry-compatible tracer to the constructor:

package/skills/tuistory/SKILL.md

@@ -1,23 +1,21 @@
 ---
 name: tuistory
 description: |
-  Control and monitor terminal applications. Supports running TUI processes in background. TMUX replacement for agents. Can control fully interactive TUI apps like claude or opencode.
+  tmux for AI agents. Run dev servers and TUIs in named background sessions that agents can read, wait on, snapshot, and type into. Replaces tmux with reactive waiting instead of blind `sleep`. Projects wrap their dev script with tuistory (`"dev": "tuistory -- next dev"`) so agents get a background session and humans get auto-attached.
 
-  Use tuistory and read the skill when you need to:
-  - Run background processes for agents like dev servers. prefer it over `tmux` because it waits for real output instead of guessing with `sleep`
-  - Control interactive CLIs and TUIs by typing, pressing keys, clicking, waiting, and taking snapshots
-  - Write Playwright-style tests for terminal apps with `vitest` or `bun:test`
+  Use tuistory when you need to:
+  - Run background dev servers or long-lived processes
+  - Control interactive CLIs and TUIs (type, press keys, click, wait, snapshot)
+  - Write Playwright-style tests for terminal apps
 
-  It has **2 modes**:
-  - **CLI** (`tuistory`) for persistent background sessions and terminal automation. **Run `tuistory --help` first.**
-  - **JS/TS API** (`launchTerminal`) for writing tests (like playwright for TUIs) and programmatic control in scripts.
+  **CLI** (`tuistory`) for background sessions. **JS/TS API** (`launchTerminal`) for programmatic control and tests.
 ---
 
 # tuistory
 
-Playwright for terminal apps. Use it to run background processes for agents, drive interactive TUIs, and write Playwright-style tests for CLIs and TUIs.
+Run dev servers and terminal commands that AI agents can read, wait on, and type into. Wrap any command in a named background session. Humans get auto-attached; agents get a session they can inspect with `read`, `snapshot`, `wait`, and `type`.
 
-Prefer tuistory over `tmux` for agent automation. It is better because it reacts to terminal output with `wait` and `wait-idle` instead of wasting time on blind `sleep` calls. That makes scripts both faster and more reliable.
+Prefer tuistory over `tmux` for agent automation. It reacts to terminal output with `wait` and `wait-idle` instead of wasting time on blind `sleep` calls. That makes scripts both faster and more reliable.
 
 Every time you use tuistory, you MUST run these two commands first. NEVER pipe to head/tail, read the full output:
 
@@ -29,14 +27,45 @@ tuistory --help
 curl -s https://raw.githubusercontent.com/remorses/tuistory/refs/heads/main/README.md
 ```
 
+## Dev script pattern
+
+When a project has `"dev": "tuistory -- next dev"` in package.json, running `pnpm dev` gives agents a background session. The session name is auto-derived from `<cwd-basename>-<command>` in kebab-case. If the session is already running, agents get a message like:
+
+```
+Session "myapp-next-dev" already running
+  with command: `next dev`
+  read output with: `tuistory read -s x --all`
+```
+
+Agents can then use `tuistory read -s x`, `tuistory -s x wait "ready"`, etc. to inspect the running process.
+
+## Dev script convention for projects
+
+Projects should wrap their dev server command with `tuistory --` in `package.json` scripts. This ensures agents never hang on an interactive long-lived process, and dev servers started by humans are automatically shared with agents.
+
+```json
+{
+  "scripts": {
+    "dev": "tuistory -- next dev",
+    "dev:api": "tuistory -- node api/server.js"
+  }
+}
+```
+
+When a human runs `pnpm dev`, they get auto-attached to the terminal (same experience as running the command directly). When an agent runs `pnpm dev`, the process launches in the background and the command returns immediately. If the session is already running, both humans and agents reuse it instead of fighting over ports.
+
+**Agents MUST never stop or close a session started by another user or agent.** Dev server sessions are shared resources. Only close them when the user explicitly asks to stop the dev server. Default to leaving sessions running. Use `read`, `wait`, and `snapshot` to inspect them without disrupting them.
+
 ## Key rules
 
+- **Options before `--`, command after.** Everything after `--` is passed verbatim to the child process. `tuistory -s myserver --cols 150 -- node server.js` is correct. `tuistory -- node server.js -s myserver` is wrong.
+- Session names are auto-derived from `<cwd-basename>-<command>`. You usually don't need `-s` when launching.
 - Always run `snapshot --trim` after every CLI action to see the current terminal state
 - Always set a timeout on `waitForText` for async operations
 - String patterns are case-sensitive by default. Use regex like `/ready/i` when casing may vary.
 - Use `trimEnd: true` in `session.text()` to avoid trailing whitespace in snapshots
 - Close sessions in test teardown to avoid leaked processes
-- Use `--cols` and `--rows` to control terminal size — affects TUI layout
+- Use `--cols` and `--rows` to control terminal size, they affect TUI layout
 - Use `--pixel-ratio 2` for sharp screenshot images
 
 ## Feedback loop
@@ -46,21 +75,21 @@ Use an **observe → act → observe** loop, like Playwright but for terminals.
 ### Background process instead of tmux
 
 ```bash
-# start a server in the background
-tuistory -s dev -- bun run dev
+# start a server in the background (session name auto-derived)
+tuistory -- bun run dev
 
 # wait for actual output instead of sleep 5
 # use regex so this still matches Ready, READY, etc.
-tuistory -s dev wait "/ready/i" --timeout 30000
+tuistory -s x wait "/ready/i" --timeout 30000
 
 # read everything the process printed
-tuistory read -s dev
+tuistory read -s x
 
 # later, read only the new output
-tuistory read -s dev
+tuistory read -s x
 
 # restart the server (sends Ctrl+C, waits, relaunches same command/cwd/env)
-tuistory -s dev restart
+tuistory -s x restart
 ```
 
 Why this is better than `tmux`: