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

# Folder convention

> Which folders @waniwani/kit reads, what each one becomes on the MCP server, and how tool names are derived from the filesystem.

```text theme={null}
oney/
├── waniwani.config.ts          defineApp({ name, title, overview })
├── tools/
│   └── check-eligibility.ts    export default defineTool({ ..., run })
├── widgets/
│   └── select-plan/
│       ├── widget.ts           export default defineWidget({ ..., data })
│       └── ui.tsx              export default function Component()
├── flows/
│   └── split-payment.ts        export default createFlow(...).compile()   ← SDK
├── api/
│   └── cal/slots.ts            export default defineEndpoint({ ..., handler })
├── well-known/
│   └── openai-apps-challenge.ts   ditto, served at the root of the domain
└── lib/                        anything else is just modules
```

Names come from the filesystem, verbatim. `tools/check-eligibility.ts` registers as `check-eligibility`, and `widgets/select-plan/` registers as `select-plan`. Nothing has to be listed in a registry, so no widget can sit defined and unwired.

| Folder                 | Becomes                                         | Notes                                                               |
| ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------- |
| `tools/<name>.ts`      | one MCP tool                                    | `.ts`, `.tsx` and `.mts` are picked up                              |
| `widgets/<name>/`      | one MCP tool plus a `ui://` resource            | needs `widget.ts` and `ui.tsx`                                      |
| `flows/<name>.ts`      | one MCP tool, registered from the SDK unchanged | whatever `.compile()` returns                                       |
| `api/<path>.ts`        | one HTTP endpoint at `/api/<path>`              | for the browser, invisible to the model                             |
| `well-known/<path>.ts` | the same endpoint at `/.well-known/<path>`      | for whoever asked the app to prove itself; the folder loses its dot |
| anything else          | plain modules                                   | the CLI leaves it alone                                             |

The app folder imports `@waniwani/kit`, plus `@waniwani/sdk` when it uses flows, and nothing else. Skybridge, transports and build configuration all stay outside it.

## Each folder in depth

<CardGroup cols={2}>
  <Card title="App config" icon="gear" href="/kit/app-config">
    `waniwani.config.ts`: name, title, the overview the host reads at connect, search and tracking options.
  </Card>

  <Card title="Tools" icon="wrench" href="/kit/tools">
    One file per tool, with Zod shapes for input and output.
  </Card>

  <Card title="Widgets" icon="window" href="/kit/widgets">
    Why a widget is two files, and the hooks `ui.tsx` gets.
  </Card>

  <Card title="Flows" icon="diagram-project" href="/kit/flows">
    A compiled SDK flow, default-exported and registered as is.
  </Card>

  <Card title="Endpoints" icon="globe" href="/kit/endpoints">
    `api/` for the widget's own server calls, `well-known/` for the root of the domain.
  </Card>

  <Card title="Styling" icon="palette" href="/kit/styling">
    Tailwind utilities in `ui.tsx`, with the tokens coming from the template's stylesheet.
  </Card>
</CardGroup>

## What lives outside the folder

`.waniwani/` is build output, the way `.next/` is. Every command regenerates it and it stays out of git. Your `.env` and `.env.local` sit next to `waniwani.config.ts` and are read before any command runs; see [Deploy](/kit/deploy#secrets-and-environment-variables).