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

# Project structure

> Filesystem conventions and directory layout for Hyperterse projects.

Hyperterse uses the filesystem as the source of truth. You define database connections, tools, prompts, and resources in role-based directories. File and directory names become identifiers. Hyperterse discovers everything from your project layout—you do not register tools or agents in code.

## Directory layout

A typical project looks like this:

<Card>
  <Tree>
    <Tree.File name=".hyperterse" />

    <Tree.File name="package.json" />

    <Tree.Folder name="app" defaultOpen>
      <Tree.Folder name="adapters" defaultOpen>
        <Tree.File name="primary-db.terse" />

        <Tree.File name="cache-store.terse" />
      </Tree.Folder>

      <Tree.Folder name="tools" defaultOpen>
        <Tree.Folder name="get-user" defaultOpen>
          <Tree.File name="config.terse" />

          <Tree.File name="input-validator.ts" />

          <Tree.File name="data-mapper.ts" />
        </Tree.Folder>

        <Tree.Folder name="get-weather" defaultOpen>
          <Tree.File name="config.terse" />

          <Tree.File name="handler.ts" />
        </Tree.Folder>
      </Tree.Folder>

      <Tree.Folder name="prompts" defaultOpen>
        <Tree.File name="summarize-release.terse" />
      </Tree.Folder>

      <Tree.Folder name="resources" defaultOpen>
        <Tree.Folder name="release-notes" defaultOpen>
          <Tree.File name="config.terse" />

          <Tree.File name="release-notes.md" />
        </Tree.Folder>

        <Tree.Folder name="order-by-id" defaultOpen>
          <Tree.File name="config.terse" />
        </Tree.Folder>
      </Tree.Folder>

      <Tree.Folder name="agents" defaultOpen>
        <Tree.Folder name="support" defaultOpen>
          <Tree.File name="config.terse" />
        </Tree.Folder>
      </Tree.Folder>
    </Tree.Folder>
  </Tree>
</Card>

## Root configuration

The `.hyperterse` file contains service-level settings: name, version, server port, log level, cache defaults, build options, and discovery settings for adapters, tools, prompts, resources, and agents. Adapter, tool, prompt, resource, and agent definitions live under `app/` (or inline for prompts/resources via root arrays). Inline `prompts`, `resources`, and `resource_templates` arrays are optional alternatives to filesystem discovery.

When you run `hyperterse start` or `hyperterse build` without arguments, the CLI looks for `.hyperterse` in the current directory. See [Root configuration reference](/reference/root-config) for the complete field specification.

## Adapter discovery

When you build or start the server, Hyperterse loads adapter definitions from `app/adapters/*.terse`. Each file defines one adapter. The filename (without extension) becomes the adapter's identifier, unless the file sets a `name` field.

See [Adapters](/concepts/adapters) for how adapters work, and [Adapter configuration reference](/reference/adapter-config) for the field specification.

## Tool discovery

Hyperterse discovers tools from `app/tools/*/config.terse` when you build or start. Each `config.terse` defines one MCP tool. The directory name becomes the tool name unless the file sets `name`.

Every tool must define either a database connection (`use`) or a handler script (`handler`). Tools with neither are rejected during validation.

See [Tools](/concepts/tools) for execution models, and [Tool configuration reference](/reference/tool-config) for the field specification.

## Prompt discovery

Prompt definitions come from `app/prompts/**/*.terse`. Each file is one MCP prompt. The filename is the prompt name unless you set `name`.

See [Prompts](/concepts/prompts) and [Prompt configuration reference](/reference/prompt-config).

## Resource discovery

Resources are defined under `app/resources/**/config.terse`. Each folder is one concrete resource (`uri`) or one template (`uri_template`), with optional content files alongside.

See [Resources](/concepts/resources) and [Resource configuration reference](/reference/resource-config).

## Agent discovery

Agent definitions live in `app/agents/*/config.terse`. Each file is one declarative agent served over A2A. The directory name is the agent name unless you set `name`.

Agent files define:

* instruction and model provider config
* tool access policy (`inherit`, `allow_all`, `allow_none`, `allow_list`)

See [Overview](/agents/overview) and [Agent configuration reference](/reference/agent-config).

## Script resolution

Script paths in tool configs are resolved relative to the tool directory. You can declare them explicitly, or rely on convention-based discovery. Common conventions include `handler.ts`, `input.ts`, and `output.ts`.

See [Scripts](/concepts/scripts) for the full script model.

## Vendor dependencies

If your tool scripts import npm packages, add a `package.json` at the project root and install your dependencies. Build output includes everything needed to run scripts, so deployment does not depend on `node_modules/` being present.