# Sources (https://docs.neuralisapp.com/package-system/sources)

Registering a [connector](https://docs.neuralisapp.com/package-system/connectors.md) adds a source **kind**; it
does not create any source. A `sources[]` entry declares a concrete source
**instance** of an already-registered kind, which the platform either seeds into
every new project (`seed: "auto"`) or offers for on-demand add
(`seed: "discoverable"`). Like workflow templates, declared sources are a typed
array on the package definition, never a markdown category and never injected
into the prompt.

## Declaring a source [#declaring-a-source]

```json
"sources": [
  {
    "source": "data",
    "label": "Project Data",
    "kind": "host",
    "root": "data",
    "scope": "project",
    "description": "The project's shared working directory.",
    "sync": { "trigger": "auto", "exclude": ["_pending/**"], "alwaysActive": true },
    "permissions": { "default": { "read": true, "write": true, "exec": true } },
    "seed": "auto"
  },
  {
    "source": "notion",
    "label": "Notion Workspace",
    "kind": "notion",
    "root": "data",
    "scope": "project",
    "description": "A connected Notion workspace, browsable as files.",
    "seed": "discoverable"
  }
]
```

- **`source`** is the canonical slug (project scope; user- and agent-scoped
  clones re-qualify it at attach time). Duplicate slugs within one manifest are
  rejected.
- **`kind`** must be a registered connector kind. That a kind exists is checked
  at runtime when the source is created, not at manifest validation.
- **`root`** is the connector root token: project-relative (`data`,
  `_packages`) or the host-resolved platform token `${appRoot}`. Omit it for
  rootless kinds such as the vector index or a container-backed desktop.
- **`scope`** picks project-, user-, or agent-ownership for the seeded or added
  source.
- **`description`** is required — it is rendered into the agent's runtime-stack
  system-prompt block so the model knows what the source is. It also prefills
  the discoverable-add form.
- **`seed`** is `auto` (created at project initialization) or `discoverable`
  (offered in the "add a source" surface, never created automatically).
- **`permissions`** seeds the source's permission tree; the package's
  [URI policy](https://docs.neuralisapp.com/package-system/uri-policies.md) baselines still union on top.
- **`visibility.seeRequires`** is an optional feature hint for who sees the
  discoverable card — a UX default only; the authoritative see/add gate stays
  server-side.

A package may declare a source on a kind it does **not** own — for example a
privileged package declaring the platform application zone on the built-in
`host` kind.

The declaring package's id becomes the source's origin attribution, surfaced on
the source listing and tagged in the runtime-stack block. For rooted local
sources the attribution requires both the slug and the resolved root to match,
so a user-created mount that merely reuses a declared slug is not mis-attributed.

## Trust gate [#trust-gate]

Source declarations are gated at manifest load, deny-by-default:

- `seed: "auto"` requires `trusted` or `native` trust — auto sources are
  seeded into every project with no human in the loop.
- A platform root token (`${appRoot}`) requires `native` trust.
- Untrusted and sandboxed packages may only declare `seed: "discoverable"` with
  a project-relative root.

The root token allow-list is `data`, `_packages`, or `${appRoot}`; absolute OS
paths, `..` segments, and unknown `${…}` tokens are rejected.


The sources the shipped packages declare are listed on
[brain-core sources](https://docs.neuralisapp.com/brain-core/sources.md) and [machine-core sources](https://docs.neuralisapp.com/machine-core/sources.md).
