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

# ekanos.json Configuration

> Complete reference for ekanos.json configuration file fields and structure.

The `ekanos.json` file declares your integration's entry point and publishing target.

## Single-integration project

```json theme={null}
{
  "slug": "my-integration",
  "entry": "src/integration.ts"
}
```

## Multi-integration project

```json theme={null}
{
  "integrations": [
    { "slug": "acme-crm", "entry": "src/crm.ts" },
    { "slug": "acme-billing", "entry": "src/billing.ts" }
  ]
}
```

Declare one form or the other, never both. `validate` cross-checks multiple integrations for colliding slugs, widget ids, and tool names.

## All fields

<ParamField body="slug" type="string" required>
  Kebab-case identifier (e.g., `"my-integration"`). Must match the definition's
  `slug` field. Only used in the **single-integration** form.
</ParamField>

<ParamField body="entry" type="string" required>
  Path to the module exporting your `defineIntegration(...)` result (default
  export, or any named export that is an object with a string `slug` field).
  Only used in the **single-integration** form.
</ParamField>

<ParamField body="integrations" type="array" required>
  Array of `{ slug, entry }` objects for multi-integration projects. Each slug must be unique, and each `entry` must export a definition with a matching `slug`. Only used in the **list** form.
</ParamField>

<ParamField body="sourceGlobs" type="string[]">
  Extra Tailwind `@source` globs to include in the dev harness. Project-relative, no `..` allowed, restricted character set (validated strictly since they're written verbatim into generated CSS).

  **Top level only** — not per-integration, because Tailwind scans one content set for the whole shell.

  ```json theme={null}
  {
    "slug": "acme-crm",
    "entry": "src/integration.ts",
    "sourceGlobs": ["vendor/acme/**/*.{ts,tsx}"]
  }
  ```

  The harness already points at: `src/`, `app/`, `lib/`, `components/`, `integrations/`, `packages/`. Add globs here only for integration sources outside those locations.
</ParamField>

<ParamField body="source" type="string">
  Ekanos source slug this project publishes to (e.g., `"my-source"`). Written by
  `ekanos use` and by every successful `publish` whose source differs. Read by
  `publish` when no `--source` flag is passed, and by `status` to list the
  project's submissions.
</ParamField>

<ParamField body="host" type="string">
  Ekanos host origin (e.g., `"https://your-ekanos-host"`). Written by a
  successful `publish` or `ekanos use` only when the field is absent — an
  existing `host` is never overwritten. Read by every host-taking verb except
  `login` (see [Authentication](/cli/authentication#host-resolution)).
</ParamField>

<ParamField body="$schema" type="string">
  Ignored — provided for editor tooling only.
</ParamField>

<ParamField body="docs" type="string[]">
  One or more http(s) URLs or project-relative paths to the target API's documentation. Created by `ekanos init --docs` if provided, but you can add or edit this field anytime.

  Optional. URLs are never fetched; a project-relative path that doesn't exist produces a `docs/missing-file` warning from `validate`.
</ParamField>

## Slug consistency

The `slug` in `ekanos.json` **must** equal the `slug` in the definition it points at. If they disagree, `validate` reports a `project.slug-agreement` error naming both values.

## Strictness

The file is **strict**: an unrecognised key is an error naming the key, not a silent no-op. Given:

```json theme={null}
{
  "slug": "my-integration",
  "entry": "src/integration.ts",
  "typo": "value"
}
```

every verb that loads the project fails with `precondition_failed` (exit 9):

```
Error: ekanos.json is invalid at "(root)": Unrecognized key(s) in object: 'typo'
```

## Auto-generated fields

A successful `publish` writes `source` (and `host`, if absent) to `ekanos.json`. This lets later verbs find the same deployment without needing flags:

```bash theme={null}
# First time
ekanos publish --host https://your-ekanos-host --source my-source

# Now ekanos.json has been updated with those values

# Later, no flags needed
ekanos publish
ekanos status
ekanos sources
```

`ekanos use <slug>` also writes `source`, and optionally `host` if not already set.

## Where it lives

`ekanos.json` lives at the root of your project directory — the current working directory, or `--dir`. `validate`, `dev`, `test`, `use`, `publish`, and `upgrade` require it and fail with `not_found` (exit 6) when it is missing; `status` and `sources` read it when present.

## Troubleshooting

### Unrecognized key

Check your field names against the reference above. Remember:

* Single projects use `slug` + `entry`
* Multi projects use `integrations` (array of objects)
* Never mix both forms

### Slug mismatch

`validate` reports `ekanos.json declares slug "<a>" for this entry, but the definition says "<b>".` Edit either `ekanos.json` or the definition so they agree.

### Missing required fields

* Single-integration projects must have `slug` and `entry`
* Multi-integration projects must have `integrations` with at least one entry
* `entry` must be a path, relative to the project, to a file that exists (otherwise `not_found`, exit 6)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.