@package-system

Sources

sources[] — concrete source instances of a registered connector kind, seeded into every project or offered for add.

Registering a connector 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

"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 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

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 and machine-core sources.

On this page