> ## 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.

# Root

> Complete field reference for the .hyperterse root configuration file.

The root configuration file (`.hyperterse`) defines service-level settings and discovery settings. Adapter and tool definitions are discovered from the filesystem, and prompts/resources can be configured through discovery directories or optional inline lists.

## Full schema

```yaml .hyperterse theme={null}
name: my-service
version: 1.0.0

root: app

tools:
  directory: tools
  search:
    limit: 10
  cache:
    enabled: true
    ttl: 60

adapters:
  directory: adapters

prompts:
  directory: prompts

resources:
  directory: resources

resource_templates: []

agents:
  directory: agents
  tool_access:
    mode: allow_none

server:
  port: 8080
  log_level: 3

build:
  out: dist
  clean_dir: false
```

## Field reference

<ParamField body="name" type="string" required>
  Service identifier. Used in logging, tracing, and manifest metadata. Must
  match `^[a-z][a-z0-9_-]*$`.
</ParamField>

<ParamField body="version" type="string">
  Service version. Informational. Included in manifest metadata and startup
  logs.
</ParamField>

<ParamField body="root" type="string" default="app">
  Base directory for adapter/tool discovery. Relative to the root config path.
</ParamField>

<ParamField body="tools" type="object">
  Tool discovery and global tool cache defaults.

  <Expandable title="properties">
    <ParamField body="directory" type="string" default="tools">
      Tools directory relative to `root`.
    </ParamField>

    <ParamField body="cache" type="object">
      Global cache defaults for DB-backed tools.

      <Expandable title="properties">
        <ParamField body="enabled" type="boolean" default="false">
          Enable in-memory tool result caching globally.
        </ParamField>

        <ParamField body="ttl" type="integer" default="120">
          Default TTL in seconds for cached tool results.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="search" type="object">
      Global search defaults for MCP `search` results.

      <Expandable title="properties">
        <ParamField body="limit" type="integer" default="10">
          Maximum number of ranked tools returned from a single MCP `search` call.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="adapters" type="object">
  Adapter discovery settings.

  <Expandable title="properties">
    <ParamField body="directory" type="string" default="adapters">
      Adapters directory relative to `root`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="prompts" type="object | array">
  Prompt configuration:

  <Expandable title="object mode (discovery)">
    <ParamField body="directory" type="string" default="prompts">
      Prompts directory relative to `root`.
    </ParamField>
  </Expandable>

  <Expandable title="array mode (inline definitions)">
    Inline prompt definitions as an array of prompt objects (`name`, optional
    `arguments`, and required `messages`).
  </Expandable>
</ParamField>

<ParamField body="resources" type="object | array">
  Resource configuration:

  <Expandable title="object mode (discovery)">
    <ParamField body="directory" type="string" default="resources">
      Resources directory relative to `root`.
    </ParamField>
  </Expandable>

  <Expandable title="array mode (inline concrete resources)">
    Inline concrete resources as an array of objects (`uri`, metadata, and one
    of `text` or `file`).
  </Expandable>
</ParamField>

<ParamField body="resource_templates" type="array">
  Optional inline URI-template resources. Each item defines `uri_template`,
  metadata, template content (`text_template` or `file_template`), and optional
  `arguments`.
</ParamField>

<ParamField body="agents" type="object">
  Agent discovery settings and project-level default tool access policy.

  <Expandable title="properties">
    <ParamField body="directory" type="string" default="agents">
      Agents directory relative to `root`.
    </ParamField>

    <ParamField body="tool_access" type="object">
      Default tool access policy for agents. Individual agents can override this
      in `config.terse`.

      <Expandable title="properties">
        <ParamField body="mode" type="string" default="allow_none">
          One of `allow_all`, `allow_none`, `allow_list`.
        </ParamField>

        <ParamField body="tools" type="string[]">
          Required when `mode=allow_list`. Contains the allowed project tool
          names.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<Tip>
  For file-based prompt/resource configs, see [Prompt configuration](/reference/prompt-config) and [Resource configuration](/reference/resource-config).
</Tip>

<ParamField body="server" type="object">
  Server runtime settings.

  <Expandable title="properties">
    <ParamField body="port" type="integer | string" default="8080">
      TCP port for the HTTP/MCP server.

      Resolution order: `--port` flag → `server.port` config → `PORT` env → `8080`
    </ParamField>

    <ParamField body="log_level" type="integer" default="3">
      Log verbosity. `1` = error, `2` = warn, `3` = info, `4` = debug.

      Resolution order: `--verbose` (4) → `--log-level` flag → `server.log_level` config → `3`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="build" type="object">
  Build output settings.

  <Expandable title="properties">
    <ParamField body="out" type="string" default="dist">
      Output directory for build artifacts. `out_dir` is an equivalent alias.

      Resolution order: `--out` flag → `build.out` config → `dist`
    </ParamField>

    <ParamField body="clean_dir" type="boolean" default="false">
      Remove output directory before building.
    </ParamField>
  </Expandable>
</ParamField>

## Environment variable substitution

String values support `{{ env.VAR_NAME }}` placeholders, resolved at runtime:

```yaml theme={null}
server:
  port: '{{ env.PORT }}'
```

<Warning>
  Missing variables cause a startup failure. Verify all referenced variables are
  set before deploying.
</Warning>

## JSON Schema

Editor validation: `schema/root.terse.schema.json`. See [Configuration schemas](/reference/configuration-schemas).

## Examples

<Tabs>
  <Tab title="Minimal">
    ```yaml .hyperterse theme={null}
    name: my-service
    ```

    All other fields use defaults: port `8080`, log level `3`, caching disabled.
  </Tab>

  <Tab title="Production">
    ```yaml .hyperterse theme={null}
    name: production-service
    version: 2.1.0

    server:
      port: "{{ env.PORT }}"
      log_level: 2

    tools:
      cache:
        enabled: true
        ttl: 300

    build:
      out: release
      clean_dir: true
    ```
  </Tab>
</Tabs>