> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuração

> Referência completa para kazzle.config.ts — o manifesto do app.

# Configuração

Todo app Kazzle tem um `kazzle.config.ts` na raiz do projeto. Este arquivo define o que seu app contém — componentes, skills e metadados.

## Início rápido

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  components: [
    { name: 'My App', type: 'ui', path: '.' }
  ]
});
```

O helper `defineConfig` fornece autocompletar e validação do TypeScript. Os tipos vêm do pacote `@kazzle/app` incluído em cada template.

## Campos de nível superior

| Campo          | Tipo                         | Obrigatório | Descrição                                                                                                                                                                                                      |
| -------------- | ---------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | `string`                     | não         | Nome de exibição para marketing mostrado no catálogo de apps. Volta para o slug quando omitido.                                                                                                                |
| `subtitle`     | `string`                     | não         | Tagline curta de uma linha mostrada sob o nome do app no catálogo (ex: "Controle apps Mac do Kazzle"). Obrigatório para publicar — omitir e a publicação falha.                                                |
| `version`      | `string`                     | não         | Rótulo de versão definido pelo autor (ex: "1.2.0"). Apenas para exibição; capturado na publicação e mostrado em clones como a versão de origem.                                                                |
| `icon`         | `string`                     | não         | Caminho para o arquivo de ícone do app relativo à raiz do repositório (png, jpg, svg, webp, ico). Enviado para CDN na publicação.                                                                              |
| `accentColor`  | `string`                     | não         | Cor de destaque de marca opcional como string hexadecimal (ex: "#3b82f6"). Tinta o chip de ícone do app e o hero de detalhes. Quando omitido, o destaque é amostrado automaticamente do ícone.                 |
| `kazzleAuth`   | `"optional"` \| `"required"` | não         | Restrição de identidade para a superfície de lançamento do app — "optional" (identidade fornecida se um usuário Kazzle estiver presente) ou "required" (deve ser um usuário Kazzle conectado para visualizar). |
| `launchUrl`    | `string`                     | não         | URL absoluta literal aberta dentro do Kazzle quando o app é clicado, usada literalmente. Quando omitido, a superfície de lançamento é a URL de visualização implantada do componente UI.                       |
| `webhookUrl`   | `string`                     | não         | Endpoint do publicador que Kazzle faz POST em app.installed / app.uninstalled (entrega a chave de instalação).                                                                                                 |
| `components`   | object\[]                    | não         | Componentes executáveis — frontends UI ou processos em background                                                                                                                                              |
| `skills`       | object\[]                    | não         | Definições de skill de IA — arquivos markdown que a IA lê para conhecimento de domínio                                                                                                                         |
| `capabilities` | `object`                     | não         | Recursos opcionais de integração desktop como hotkeys, notificações e presença na barra de status                                                                                                              |

## Campos de componente

Cada entrada em `components[]`:

| Campo                  | Tipo                     | Obrigatório  | Descrição                                                                                     |
| ---------------------- | ------------------------ | ------------ | --------------------------------------------------------------------------------------------- |
| `name`                 | `string`                 | sim          | Nome único do componente dentro do app                                                        |
| `type`                 | `"ui"` \| `"process"`    | sim          | Tipo de componente — ui (máx 1) ou process                                                    |
| `path`                 | `string`                 | sim          | Caminho de entrada dentro do diretório do app                                                 |
| `runtime`              | object                   | não          | Comandos e overrides de env opcionais: `{ dev?, prod? }`                                      |
| `runtime.dev.command`  | `string`                 | não          | Comando para iniciar o servidor de dev (ex: `"bun run dev"`)                                  |
| `runtime.dev.env`      | object                   | não          | Override de env apenas para dev. Volta para o `env` do componente.                            |
| `runtime.prod.command` | `string`                 | não          | Comando para iniciar em produção (ex: `"bun run start"`)                                      |
| `runtime.prod.build`   | `string`                 | não          | Comando para compilar para produção (ex: `"vite build"`)                                      |
| `runtime.prod.env`     | object                   | não          | Override de env apenas para produção. Volta para o `env` do componente.                       |
| `schedule`             | `string`                 | não          | Agendamento cron para componentes de processo (ex: `"*/5 * * * *"`)                           |
| `trigger`              | `"webhook"` \| `"event"` | não          | Modo de acionamento para componentes de processo                                              |
| `env`                  | object                   | não          | Coleção de segredos + ambiente para injeção de variável de env                                |
| `env.collection`       | `string`                 | sim (se env) | Slug da coleção de segredos                                                                   |
| `env.environment`      | `string`                 | sim (se env) | Slug do ambiente                                                                              |
| `env.include`          | `string[]`               | não          | Injetar apenas estes nomes de variável de env. Se omitido, injetar todos da coleção+ambiente. |

## Campos de skill

Cada entrada em `skills[]`:

| Campo  | Tipo     | Obrigatório | Descrição                                              |
| ------ | -------- | ----------- | ------------------------------------------------------ |
| `name` | `string` | sim         | Nome do skill                                          |
| `path` | `string` | sim         | Caminho para o arquivo SKILL.md relativo à raiz do app |

## Restrições

* **Máx 1 componente UI** por app
* Valores de `name` do componente devem ser únicos dentro do app

## Exemplos de template

### ai app

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  /** Tagline de catálogo de uma linha. Obrigatório para publicar. */
  subtitle: 'My App',
  icon: 'components/ui/public/favicon.svg',
  components: [
    { name: 'ui', type: 'ui', path: './components/ui' },
    { name: 'server', type: 'process', path: './components/server/index.ts', runtime: { dev: { command: 'bun run dev' }, prod: { command: 'bun run start' } } },
  ],
});
```

### ui db app

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  /** Tagline de catálogo de uma linha. Obrigatório para publicar. */
  subtitle: 'My App',
  icon: 'components/ui/public/favicon.svg',
  components: [
    { name: 'ui', type: 'ui', path: './components/ui' },
    { name: 'server', type: 'process', path: './components/server/index.ts', runtime: { dev: { command: 'bun run dev' }, prod: { command: 'bun run start' } } },
  ],
});
```

### ui app

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  /** Tagline de catálogo de uma linha. Obrigatório para publicar. */
  subtitle: 'My App',
  /** Caminho para o ícone do app relativo à raiz do repositório. Enviado para CDN na publicação. */
  icon: 'components/ui/public/favicon.svg',
  /** Componentes do app — cada entrada define uma unidade implantável. Máx 1 componente UI. */
  components: [
    { name: 'My App', type: 'ui', path: './components/ui' },
  ],
});
```