genaicode 2.18.3 → 2.20.0

package/docs/llm.md

@@ -0,0 +1,460 @@
+# LLM layer (`genaicode`, `genaicode/providers`)
+
+[← README](../README.md)
+
+Besides driving agents, GenAIcode is a small TypeScript toolkit for calling LLMs from backend
+code. It sits between raw provider SDKs and full agent frameworks: one prompt representation,
+thin provider adapters, a convenient request API, and lightweight conversation chains. This
+layer does not inspect repositories, execute shell commands, edit files, or run an agent UI.
+
+**Like jQuery**, the common case starts with one small function and becomes more specific
+through chaining—configure a request, follow up across multiple prompts, and keep history
+portable without adopting a full agent framework.
+
+## A prompt in three lines
+
+```ts
+import { genaicode } from 'genaicode';
+import { openai } from 'genaicode/providers';
+
+const ai = genaicode(openai({ model: 'your-model-name' }));
+const answer = await ai('Explain why the sky is blue in two sentences.').text();
+```
+
+The client is callable on purpose. Configuration is ordinary method chaining—system
+instructions, temperature, token limits, and more—without a separate options object or
+framework setup:
+
+```ts
+const result = await ai('Create a release note from these commits')
+  .system('You are a concise technical writer.')
+  .temperature(0.2)
+  .maxOutputTokens(500)
+  .text();
+```
+
+Builders are immutable, so a configured base request can be safely reused:
+
+```ts
+const releaseNote = ai('Create a release note from these commits')
+  .system('You are a concise technical writer.')
+  .temperature(0.2);
+
+const short = await releaseNote.maxOutputTokens(200).text();
+const long = await releaseNote.maxOutputTokens(800).text();
+```
+
+## Why this vs a raw SDK
+
+Provider SDKs are the right tool when you call one vendor and own every request shape
+yourself. The cost shows up when the same backend needs a second provider, a test double,
+or shared policy (timeouts, JSON parsing, rate limits, fallback) without copying glue.
+
+GenAIcode is that thin shared layer:
+
+- One portable prompt/tool IR (`PromptItem`) instead of OpenAI messages vs Anthropic
+  blocks vs Gemini contents.
+- One request API (`.text()`, `.json()`, `.stream()`, chains) over those adapters.
+- A tiny `ModelProvider` seam so tests and custom gateways do not mock vendor HTTP.
+- Opt-in middleware and retry helpers—no hidden tool runners, no silent retries, no
+  agent loop.
+
+If you are happy importing one SDK and never swapping models or providers, stay on the
+SDK. If you want the call site to look the same while the edge stays replaceable, use
+GenAIcode.
+
+## Chaining prompts
+
+A chain remembers successful user and assistant turns. Each new prompt sees the complete
+history, so multi-step work stays in ordinary application code:
+
+```ts
+import { system } from 'genaicode';
+
+const chain = ai.chain(system('You are helping refine an API design.'));
+
+const answer1 = await chain.text('Prompt 1: propose a minimal endpoint.');
+const answer2 = await chain.text('Prompt 2: add idempotency to that design.');
+const answer3 = await chain.text('Prompt 3: summarize the final contract.');
+```
+
+This is `prompt1 → response1 → prompt2 → response2 → prompt3 → response3`. The history
+is available as portable `PromptItem[]` through `chain.history()`.
+
+## Using a chain in a loop
+
+A chain is ordinary application state, so normal control flow works:
+
+```ts
+const chain = ai.chain(system('Improve the draft while preserving its meaning.'));
+let draft = 'The deployment had a problem and we fixed it.';
+
+for (const instruction of ['Make it specific.', 'Make it concise.', 'Use a professional tone.']) {
+  draft = await chain.text(`${instruction}\n\nCurrent draft:\n${draft}`);
+}
+```
+
+Calls on one chain are serialized, even if application code starts them concurrently.
+Failed provider calls are not added to history.
+
+Validation and repair are also plain loops rather than a special agent abstraction:
+
+```ts
+import { parseJsonResult, resultText, system } from 'genaicode';
+
+const repair = ai.chain(system('Return only valid JSON with a non-negative count.'));
+let count: number | undefined;
+
+for (let attempt = 1; attempt <= 3; attempt += 1) {
+  const result = await repair.ask(
+    attempt === 1 ? 'Count the actionable items in this text: ...' : 'Correct the previous response.',
+  );
+
+  try {
+    const value = parseJsonResult<{ count: number }>(result);
+    if (value.count < 0) throw new Error('count must be non-negative');
+    count = value.count;
+    break;
+  } catch (error) {
+    if (attempt === 3) throw error;
+    console.warn('Invalid model response:', resultText(result));
+  }
+}
+```
+
+The application owns validation, attempt limits, and failure policy.
+
+## Schema adapters
+
+`json(...)` and `parseJsonResult(...)` accept either a parser function or a schema adapter
+with a `parse(value)` method. This keeps schema validation library-agnostic:
+
+```ts
+const value = await ai('Return {"count": 3}.').json({
+  parse(input) {
+    if (typeof input !== 'object' || input === null || typeof input.count !== 'number') {
+      throw new Error('Invalid shape');
+    }
+    return input;
+  },
+});
+```
+
+Calling `.json()` also sets `responseFormat: { type: 'json' }` on the request when you have
+not already chosen a format, so providers that support JSON mode (OpenAI, Gemini/Vertex)
+are asked for JSON rather than free text.
+
+## Response format and thinking
+
+Portable request fields cover the two knobs backends usually poke through provider-specific
+config:
+
+```ts
+const verdict = await ai(promptText)
+  .responseFormat({ type: 'json' })
+  .thinking({ level: 'minimal' }) // or { budgetTokens: 0 } / false to disable
+  .temperature(0)
+  .json((value) => VerdictSchema.parse(value));
+```
+
+- `responseFormat`: `{ type: 'text' | 'json' }` or
+  `{ type: 'json_schema', name, schema, strict? }`.
+- `thinking`: `false` to disable, or `{ budgetTokens?, level? }` (`minimal` |
+  `low` | `medium` | `high`). Prefer one of budget or level — some providers reject both.
+  On Google/Gemini, `false` and `budgetTokens: 0` map to `thinkingLevel: MINIMAL`
+  (or `LOW` for models like Gemini 3.7 and Gemini 3 Pro where `MINIMAL` is unsupported)
+  because Gemini 3 rejects `thinkingBudget: 0`. JSON `responseFormat` without an
+  explicit `thinking` setting or provider `generationConfig.thinkingConfig` default also
+  defaults Google thinking to `MINIMAL` (or `LOW` on Gemini 3.7 / Pro).
+  On Anthropic, `level` becomes `output_config.effort` with adaptive thinking (Opus and
+  Sonnet 4.6+), and `false` uses whatever the model accepts: `disabled`, `between_tools`
+  (Sonnet 5.5), or effort `low` where thinking is always on (Opus 5.5, Fable). Budgets
+  become adaptive thinking on models that removed them.
+
+Providers map what they support and ignore the rest. `ProviderCapabilities.jsonResponse`
+and `ProviderCapabilities.thinking` advertise support. Vendor-specific escapes such as
+Vertex `generationConfig` remain available for anything not covered here.
+
+## PromptItem: the portable prompt IR
+
+`PromptItem` is GenAIcode's provider-neutral intermediate representation:
+
+```ts
+import { image, prompt, system, toolResults, user } from 'genaicode';
+
+const items = prompt(
+  system('Return a one-sentence caption.'),
+  user('Describe this image.', {
+    images: [image(base64Png, 'image/png')],
+  }),
+  toolResults({
+    callId: 'lookup-1',
+    name: 'lookup',
+    content: JSON.stringify({ locale: 'pl-PL' }),
+  }),
+);
+
+const caption = await ai(items).text();
+```
+
+Applications can make domain objects prompt-aware without coupling them to a provider:
+
+```ts
+import { asPrompt, system, user } from 'genaicode';
+
+const supportTicket = (ticket: Ticket) =>
+  asPrompt(() => [system('Triage support tickets.'), user(JSON.stringify(ticket))]);
+
+await ai(supportTicket(ticket)).text();
+```
+
+## Tools
+
+```ts
+const calls = await ai('What is the weather in Warsaw?')
+  .tools([
+    {
+      name: 'weather',
+      description: 'Get current weather',
+      parameters: {
+        type: 'object',
+        properties: { city: { type: 'string' } },
+        required: ['city'],
+        additionalProperties: false,
+      },
+    },
+  ])
+  .toolCalls();
+```
+
+GenAIcode normalizes tool calls but deliberately does not execute them. The application
+owns permissions, retries, and side effects.
+
+## Streaming
+
+Providers that support native streaming expose a provider-neutral `StreamEvent` IR.
+Request builders and chains offer `.stream()` and `.streamText()`. If a provider has no
+`stream` method, GenAIcode synthesizes a short stream from `generate`.
+
+```ts
+for await (const event of ai('Write a haiku about queues.').stream()) {
+  if (event.type === 'text-delta') process.stdout.write(event.text);
+  if (event.type === 'done') console.log('\n', event.result.usage);
+}
+```
+
+Built-in adapters declare capability metadata:
+
+```ts
+ai.provider.capabilities;
+// { streaming: true, tools: true, images: 'input', systemPrompt: true }
+```
+
+## Middleware
+
+Hook-style plugins remain the extension point. Built-in helpers cover common backend
+needs without restoring a global registry:
+
+```ts
+import { cachePlugin, fallbackPlugin, genaicode, rateLimitPlugin, timingPlugin } from 'genaicode';
+import { anthropic, openai } from 'genaicode/providers';
+
+const ai = genaicode(openai({ model: 'your-model-name' }), {
+  plugins: [
+    timingPlugin(),
+    rateLimitPlugin({ concurrency: 2, minIntervalMs: 50 }),
+    cachePlugin({ maxEntries: 64 }),
+    fallbackPlugin({ providers: [anthropic({ model: 'your-claude-model' })] }),
+  ],
+});
+```
+
+## Retries
+
+Retries stay in application code. Use `classifyError`, `isRetryable`, and `withRetry`
+when you want shared classification without hidden policy:
+
+```ts
+import { withRetry } from 'genaicode';
+
+const text = await withRetry(() => ai('Summarize the deploy notes.').text(), {
+  attempts: 3,
+  delayMs: 250,
+});
+```
+
+See [retry guidance](retry.md), [semver policy](semver.md), and the
+[provider package evaluation](provider-packages.md).
+
+## Providers
+
+Models are provided in the adapter, through `.model(...)`, or with environment variables:
+
+| Adapter                | Factory              | Environment defaults                                               |
+| ---------------------- | -------------------- | ------------------------------------------------------------------ |
+| OpenAI                 | `openai()`           | `OPENAI_API_KEY`, `OPENAI_MODEL`                                   |
+| Anthropic              | `anthropic()`        | `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`                             |
+| Gemini API / AI Studio | `gemini()`           | `GEMINI_API_KEY` or `API_KEY`, `GEMINI_MODEL`                      |
+| Vertex AI              | `vertexAI()`         | `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, `VERTEX_AI_MODEL` |
+| OpenAI-compatible      | `openaiCompatible()` | Explicit options; OpenAI defaults also work                        |
+
+```ts
+import { anthropic, gemini, openai, vertexAI } from 'genaicode/providers';
+
+const viaOpenAI = genaicode(openai({ model: 'your-openai-model' }));
+const viaClaude = genaicode(anthropic({ model: 'your-claude-model' }));
+const viaGemini = genaicode(gemini({ model: 'your-gemini-model' }));
+const viaVertex = genaicode(
+  vertexAI({
+    project: 'my-google-cloud-project',
+    location: 'global',
+    model: 'your-vertex-model',
+  }),
+);
+```
+
+Provider-specific options stay at provider construction. For example, Anthropic exposes
+thinking and output-token defaults, while Gemini and Vertex expose SDK HTTP, auth, API
+version, and generation configuration options.
+
+GitHub Models, Ollama, vLLM, and other compatible gateways use the OpenAI-compatible
+adapter:
+
+```ts
+import { openaiCompatible } from 'genaicode/providers';
+
+const local = genaicode(
+  openaiCompatible({
+    name: 'local',
+    baseURL: 'http://localhost:11434/v1',
+    apiKey: 'local',
+    model: 'qwen3',
+  }),
+);
+```
+
+Implementing a provider directly is intentionally small:
+
+```ts
+import type { ModelProvider } from 'genaicode';
+
+const provider: ModelProvider = {
+  name: 'internal-gateway',
+  async generate(request) {
+    // Convert request.prompt to your API and normalize the response.
+    return { parts: [{ type: 'text', text: 'response' }] };
+  },
+};
+```
+
+All Anthropic, Google, and OpenAI conversion functions are public from
+`genaicode/providers`, so gateways and tests can reuse them without instantiating clients.
+
+## Provider E2E tests
+
+Run real-provider E2E tests locally with:
+
+```bash
+npm run test:e2e
+```
+
+These tests are credential-gated and run only when provider-specific environment variables
+are set:
+
+- OpenAI: `OPENAI_API_KEY`, `OPENAI_MODEL`
+- Anthropic: `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL`
+- Gemini: `GEMINI_API_KEY`, `GEMINI_MODEL`
+
+Beyond the smoke call, E2E also covers portable `responseFormat: { type: 'json' }`
+(OpenAI, Gemini) and `thinking` (Anthropic disable; Gemini disable / `level: 'minimal'`).
+
+CI/CD is configured in `.github/workflows/provider-e2e.yaml`. Each provider runs in its own
+job and only starts when both required secrets are configured in GitHub Actions.
+
+## Plugins and hooks
+
+A provider plugin no longer needs registration in global configuration. It exports the
+same small `ModelProvider` contract as a built-in adapter:
+
+```ts
+// @acme/genaicode-bedrock
+import type { ModelProvider } from 'genaicode';
+
+export const bedrock = (options: BedrockOptions): ModelProvider => ({
+  name: 'bedrock',
+  capabilities: { streaming: false, tools: true, systemPrompt: true },
+  async generate(request) {
+    // Convert PromptItem[], call Bedrock, and return GenerationResult.
+    return { parts: [{ type: 'text', text: 'response' }] };
+  },
+});
+```
+
+Hook-style plugins use middleware. They can observe or rewrite requests and results,
+handle errors, implement caches or fallbacks, and intentionally short-circuit a call.
+Optional `stream` middleware follows the same registration order.
+
+```ts
+import { definePlugin, genaicode } from 'genaicode';
+import { openai } from 'genaicode/providers';
+
+const timing = definePlugin({
+  name: 'timing',
+  async generate(request, next) {
+    const startedAt = performance.now();
+    try {
+      return await next(request);
+    } finally {
+      console.log('LLM request took', performance.now() - startedAt, 'ms');
+    }
+  },
+});
+
+const ai = genaicode(openai({ model: 'your-model-name' }), {
+  plugins: [timing],
+});
+```
+
+Plugins run in registration order, and each plugin may call `next()` once. This keeps the
+extension mechanism compatible with npm packages and ordinary imports without restoring
+the 1.x runtime TypeScript loader or process-global plugin registry.
+
+Framework-shaped examples live under [`docs/examples/`](examples/) (`http-handler`, `queue-worker`,
+`cron-job`).
+
+## Design boundaries
+
+- Backend library, not a coding agent. `genaicode/agents` drives external agent CLIs; it
+  adds no agent loop, prompts, or repository tools of its own.
+- Provider-neutral core with no global configuration.
+- Explicit models and credentials; environment variables are only provider defaults.
+- Immutable request builders.
+- Conversation history is explicit; loops remain ordinary application code.
+- No hidden tool execution or hidden retries.
+- Third-party providers and middleware use stable TypeScript contracts.
+- Provider SDKs stay behind the `genaicode/providers` subpath; process spawning stays
+  behind `genaicode/agents`.
+
+## Migration from 1.x
+
+GenAIcode 1.x was a coding agent. Version 2.0 deliberately replaces that product with a
+small backend LLM toolkit: a jQuery-like layer for portable prompts, provider adapters,
+conversation chains, and plugins.
+
+The 1.x coding agent, browser UI, repository tools, and shell execution are not
+deprecated compatibility features; they have been removed from 2.0. The 2.x
+`genaicode` command only drives external agent CLIs (see [the CLI docs](cli.md)). The GenAIcode name, `PromptItem` model, provider converters, and extensibility
+continue here in a smaller and more focused form.
+
+The original coding agent remains available from the preserved
+[`1.x` branch](https://github.com/gtanczyk/genaicode/tree/1.x) and the 1.x npm releases:
+
+```bash
+npx genaicode@1
+```
+
+In 2.x, `npx genaicode` opens a chat with the coding-agent CLIs you have installed
+(Claude Code, Codex, opencode...) instead of the 1.x built-in agent.
+
+See [the pivot plan](pivot.md) for the full scope, migration decisions, and the
+roadmap.

package/docs/react.md

@@ -0,0 +1,134 @@
+# React components (`genaicode/react`)
+
+[← README](../README.md)
+
+`genaicode/react` is the same chat as a component. It draws a `SessionState` your app gives
+it and calls you back; it runs, fetches and stores nothing, so your server owns the session,
+its MCP servers and its prompts. React 18 or newer comes from your app: genaicode does not
+declare or install it.
+
+```ts
+// server (Node): one session, streamed to the page
+import { createAgentSession, claude } from 'genaicode/agents';
+
+const session = createAgentSession({
+  agent: claude(),
+  cwd: process.cwd(),
+  task: { mcpServers: [{ name: 'ops', url: 'http://127.0.0.1:4000/mcp' }] },
+  // The agent gets the context; the transcript keeps what the user typed.
+  transformPrompt: (text) => `${briefing}\n\nOperator message:\n${text}`,
+});
+
+app.get('/api/agent/events', (req, res) => {
+  res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store' });
+  const push = (state) => res.write(`data: ${JSON.stringify(state)}\n\n`);
+  push(session.get());
+  res.on('close', session.subscribe(push));
+});
+app.post('/api/agent/send', (req, res) => {
+  session.send(req.body.text);
+  res.json({ ok: true });
+});
+app.post('/api/agent/stop', (req, res) => {
+  session.stop();
+  res.json({ ok: true });
+});
+app.post('/api/agent/approve', (req, res) => res.json({ ok: session.approve(req.body.id, req.body.decision) }));
+```
+
+```tsx
+// page
+import { useEffect, useState } from 'react';
+import { AgentChat, type SessionState } from 'genaicode/react';
+import 'genaicode/react/styles.css';
+
+const post = (path: string, body: object = {}) =>
+  fetch(path, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+
+export function AgentDrawer() {
+  const [state, setState] = useState<SessionState | null>(null);
+  useEffect(() => {
+    const events = new EventSource('/api/agent/events');
+    events.onmessage = (event) => setState(JSON.parse(event.data));
+    return () => events.close();
+  }, []);
+  return (
+    <AgentChat
+      state={state}
+      onSend={(text) => post('/api/agent/send', { text })}
+      onStop={() => post('/api/agent/stop')}
+      onApprove={(id, decision) => post('/api/agent/approve', { id, decision })}
+      formatToolName={(name) => name.replace(/^mcp__ops__/, '')}
+      renderFooter={() => <MyApprovalCards />}
+      headerExtras={<button onClick={() => post('/api/agent/reset')}>New</button>}
+    />
+  );
+}
+```
+
+`<AgentChat>` fills its container's height. It shows turns with streaming Markdown (no raw
+HTML; links open in a new tab; GFM tables, strikethrough and task lists), collapsible tool calls, edited files, errors, the agent's
+own approval requests, queued prompts and a working indicator, and an input where Enter
+sends, Shift+Enter adds a line and Esc stops. Props:
+
+| Prop                                                                           |                                                                  |
+| ------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
+| `state`                                                                        | `SessionState`, or null before there is a session                |
+| `onSend(text)`, `onStop()`                                                     | Enter or Send; Stop or Esc. No `onStop`, no Stop button          |
+| `onApprove(id, decision)`                                                      | answers `state.approvals`; without it they show as waiting       |
+| `renderPrompt(text, turn?)`                                                    | how a sent prompt shows (return null to hide it)                 |
+| `renderAfterTurn(turn, i)`, `renderFooter()`                                   | your content after a turn, or at the end                         |
+| `notices`                                                                      | `{ id, afterTurn, text, tone? }[]`: your own lines between turns |
+| `foldSteps`                                                                    | fold each turn's tools and edits into one "N steps" line         |
+| `header`, `headerExtras`                                                       | replace the header (null for none), or add to its right end      |
+| `emptyState`, `placeholder`, `hint`                                            | text before the first turn, in and under the input               |
+| `formatToolName(name)`, `disabled`, `autoFocus`, `theme`, `className`, `style` |                                                                  |
+
+Theme it with CSS custom properties on the component or any ancestor: `--gc-bg`,
+`--gc-panel`, `--gc-border`, `--gc-text`, `--gc-muted`, `--gc-accent`, `--gc-accent-text`,
+`--gc-error`, `--gc-font`, `--gc-mono`, `--gc-font-size`, `--gc-radius`, `--gc-max-width`
+(and `--gc-ok`, `--gc-warn`, plus soft shades mixed from these unless set). Unset ones keep
+the `genaicode ui` look, light or dark by `prefers-color-scheme`, or by `theme="light"` /
+`"dark"`. `genaicode ui` and the Vite panel draw this same component.
+
+Two smaller pieces come along for hosts that build their own panels around a transcript:
+
+```ts
+import { installResizeHandle, storedSize, useFollowScroll } from 'genaicode/react';
+
+// A log that stays at its newest line until the user scrolls up (and again after follow()).
+const { ref, onScroll, follow } = useFollowScroll(lines);
+
+// A drag handle on a panel's left edge; the width survives reloads.
+const stored = storedSize('panel-width', [300, 900]);
+let width = stored.get();
+const handle = installResizeHandle(edge, {
+  axis: 'x',
+  direction: () => -1, // dragging left makes the panel wider
+  bounds: () => [300, Math.min(900, innerWidth - 24)],
+  read: () => width ?? 390,
+  write: (next, commit) => {
+    width = next;
+    panel.style.setProperty('--width', `${width}px`);
+    if (commit) stored.set(width);
+  },
+  reset: () => {
+    width = undefined;
+    panel.style.removeProperty('--width');
+    stored.clear();
+  },
+});
+// The CSS caps the shown width, so the saved one comes back when the window grows again:
+// .panel { width: min(var(--width, 390px), calc(100vw - 24px)); }
+window.addEventListener('resize', handle.sync);
+```
+
+The handle keeps its `aria-value*` range current and takes the arrow keys (Shift for bigger
+steps), Home and End, Escape to undo a drag, and Enter or double-click to reset. While a drag
+runs, `document.body` (or `root`) has `data-resizing="true"`, so the page can keep the cursor
+and turn off pointer events on iframes. `read()` must return what `write` or `reset` just set,
+so keep the size in a variable or a ref rather than only in React state.
+
+To show the whole `genaicode ui` page in a frame instead, `startEmbeddedWeb` from
+`genaicode/ui` serves it on 127.0.0.1 with your `task` (`mcpServers`, `timeoutMs`...), `env`
+and `transformPrompt`, and returns its tokenized `url` and a `controller` to send prompts.

package/{skills → docs/skills}/genaicode-embed/SKILL.md

@@ -80,7 +80,8 @@ allow, batch what must run into few commands, and do not run the dev server just
    you created that the project does not track.
 6. **Report**, starting with how to see it, before anything else: one line with the exact
    command to run and what happens next, e.g. "Run `npm run agent`: the game opens in your
-   browser with the genaicode wolf in the bottom-right corner." The developer may not know
+   browser with the genaicode wolf in the bottom-right corner. You can also type
+   `!npm run agent` right here." The developer may not know
    the project's scripts or that a new one exists, so never leave this for the end of a
    long summary. Then what you changed, file by file, briefly. Say that the agent uses its
    own CLI login and billing.

package/docs/vite.md

@@ -0,0 +1,42 @@
+# Dev overlay (`genaicode/vite`, `createDevOverlay`)
+
+[← README](../README.md)
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import genaicode from 'genaicode/vite';
+
+export default defineConfig({ plugins: [genaicode()] });
+```
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="media/screenshots/vite-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="media/screenshots/vite-light.png">
+    <img alt="The genaicode panel over a Vite app: the agent fixed the page's two errors." src="media/screenshots/vite-light.png" width="80%">
+  </picture>
+</p>
+
+In `vite dev`, the app gets the wolf in its corner. It opens the same chat as `genaicode ui`
+in a panel, with the agent working in the project root. The wolf counts the page's errors
+(build errors, uncaught exceptions, unhandled rejections, `console.error`), and "Fix N
+errors" sends them to the agent as one prompt. Options: `agent`, `model`, `effort`,
+`approveAll`, `agents`, `port`, and `captureErrors: false` to leave the page's errors alone.
+Builds are untouched. The chat runs on its own port on 127.0.0.1 even when Vite runs with
+`--host`, lets only the app's origins frame it, and hands its token (and takes "fix" requests)
+only from the app's own pages on this machine.
+
+Any other Node dev server (Express, webpack-dev-server, a script that serves static files)
+gets the same overlay from `createDevOverlay` in `genaicode/ui`:
+
+```ts
+import { createDevOverlay } from 'genaicode/ui';
+
+const overlay = createDevOverlay(); // same options as the plugin, plus `cwd`
+app.use(overlay.middleware); // Express; or `if (await overlay.handle(req, res)) return;`
+// ...and in the HTML it serves: overlay.injectHtml(html), or the overlay.script tag.
+```
+
+Development only. The token goes only to pages opened at `localhost`, `*.localhost`,
+`127.0.0.1` or `[::1]`, and without an agent CLI the overlay stays off.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genaicode",
-  "version": "2.18.3",
+  "version": "2.20.0",
   "description": "Drive the coding-agent CLIs you already have (Claude Code, Codex, Copilot, Cursor, Gemini, opencode...) behind one API and one CLI, plus a thin provider-neutral LLM layer.",
   "author": "Grzegorz Tańczyk",
   "repository": {
@@ -35,7 +35,6 @@
     "docs",
     "!docs/examples",
     "!docs/media",
-    "skills",
     "README.md",
     "LICENSE"
   ],