# File conventions

File conventions produce Discovered Definitions. Discovery Identity comes from the discovery location, not from arbitrary inline Definition Options.

## Definition files

| Definition | Directory convention | Suffix convention | Discovery Identity |
| --- | --- | --- | --- |
| Agent | `server/agents/<name>.ts`, `server/agents/<name>/agent.ts`, or `server/agents/<name>/index.ts` | `<path>.agent.ts` outside `server/` | Relative file or directory path. A leading `src/` is removed from suffix identities. |
| Auth | `server/auth.ts` | `server.auth.ts` | `default`. Only one Auth Definition is allowed. |
| Browser | `server/browsers/<path>.ts` | `<path>.browser.ts` | Normalized relative path. A leading `src/` is removed from suffix identities. |
| Channel | `server/channels/<path>.ts` | `<path>.channel.ts` | Normalized relative path. A leading `src/` is removed from suffix identities. |
| Connection | `server/connections/<path>.ts` | None | Normalized relative path. |
| Database | `server/databases/config.ts` for one default database, or `server/databases/<name>/config.ts` for named databases | `src/database.ts` for the default database, or `<path>.database.ts` for a named database | `default` or the normalized relative path. Default and named modes cannot be mixed. |
| Queue | `server/queues/<path>.ts` | `<path>.queue.ts` | Normalized relative path. A leading `src/` is removed from suffix identities. |
| Realtime | `server/realtime/<path>.ts` | None | Normalized relative path. |
| Workflow | `server/workflows/<path>.ts` or a folder containing `index.ts` or numbered step files | `<path>.workflow.ts` | Normalized relative file or folder path. Agent Definitions contribute their Agent identity by default, `workflow(...)` can override it, and `runtime: false` opts out. |
| Schedule | `server/schedules/<path>.ts` | `<path>.schedule.ts` | Normalized relative path. A leading `src/` is removed from suffix identities. |
| Sandbox | `server/sandboxes/<path>/{package.json,index.ts}` | `<path>.sandbox.ts` outside `server/sandboxes/` | Normalized folder or suffix path, without a trailing `.sandbox` segment. |
| Workspace | `server/workspaces/<path>.ts`, `server/workspaces/<name>/config.ts`, or `server/agents/<name>/agent.ts` when the Agent declares a Workspace | `<path>.workspace.ts` | Normalized relative path or the colocated Agent name. |

The table uses `.ts` for brevity. Directory and suffix patterns accept JavaScript and TypeScript module variants where the owning package permits them. `src/database.ts` is the exact default Database suffix-mode file.

Rate Limit deliberately has no file convention. Call `requireRateLimit(event, id, options)` inside ordinary H3 handlers; its explicit ID is the provider identity.

## Export shape

Most discovered Definition files default-export the package-owned Definition Boundary Helper. This keeps Build-Extracted Definition Options limited to the direct discovered default export.

Canonical Sandbox package projects are the exception: `server/sandboxes/<path>/index.ts` default-exports an async `(payload, context) => result` function. The adjacent `package.json` must set `"type": "module"`. Local TypeScript uses explicit relative ESM imports, while bare dependencies must expose runtime-ready JavaScript; CommonJS source and package-local import aliases are not compiled. The folder supplies the Definition identity, and optional static wall-clock policy comes from `vitehub.sandbox.timeout`. Free-form `<path>.sandbox.ts` files still default-export `defineSandbox(...)`.

```ts [server/queues/welcome-email.ts]
import { defineQueue } from '@vite-hub/queue'

export default defineQueue<{ email: string }>(async (job) => {
  await sendWelcomeEmail(job.payload.email)
})
```

Avoid aggregate named exports for discovered Definitions. The generated Runtime Registry expects one discovered boundary per file convention.

## Colocated Workspace files

Agent folders can colocate Workspace content beside the Agent Definition. When a folder contains `workspace/`, that folder becomes the Workspace Source Root for the colocated Workspace Definition.

```txt [File tree]
server/
  agents/
    docs/
      agent.ts
      workspace/
        README.md
        guides/
          setup.md
```

## Colocated Agent Skills

An Agent folder can own Skills in an adjacent `skills/` directory. ViteHub recursively embeds every file during discovery and materializes the directory into the Provider Workspace at `.agents/skills/`. Existing files remain in place, and files below a `scripts/` directory become executable.

```txt [File tree]
server/
  agents/
    review/
      agent.ts
      skills/
        code-review/
          SKILL.md
          scripts/
            review.sh
```

This convention needs no `skills()` Capability declaration. Use [`skills()`](https://vitehub.dev/docs/agents/capabilities/skills) when the Skill comes from a Workspace or external Source instead of the Agent folder.

## Markdown templates

Use ordinary `.md` files for Markdown templates and fragments. Pass a file path or file URL to `renderMarkdownFile()`. For example, `server/agents/review/agent.ts` can render `new URL('./reply.md', import.meta.url)`.

A local `templates/` directory can group several files, but it has no discovery or recursive import behavior. References such as `@./fragment.md` remain literal; compose additional Markdown explicitly before rendering. See [Markdown templates](https://vitehub.dev/docs/reference/markdown-templates) for rendering, deployment, and migration examples.

## Email templates

Markdown files under `server/emails` become typed email renderers. ViteHub
removes the directory prefix and `.md` extension, so
`server/emails/welcome.md` becomes `#vitehub/emails/welcome` and
`server/emails/monthly/recap.md` becomes `#vitehub/emails/monthly/recap`.

Email template names must use non-empty path segments and cannot contain `.` or
`..` segments, query strings, fragments, backslashes, or a trailing `.md`.
ViteHub rejects duplicate names across configured server directories.

## Generated files

Generated files live under `.vitehub/**` and host output directories.
They prove discovery and Provider Output, but the source Definition files remain the authoring surface.

## Related

- [Generated files](https://vitehub.dev/docs/development/generated-files)
- [Definitions and discovery](https://vitehub.dev/docs/development/definition-discovery)
- [Import paths](https://vitehub.dev/docs/reference/import-paths)