The package system

Neuralis is built around one architectural rule: every capability is a package. The host stays generic — it provides identity, project boundaries, the workspace shell, package routing, configuration, and deployment plumbing. Everything the product actually does — agents, filesystem, memory, terminal, admin, machine automation, tools, skills, connectors, hooks, policies, UI — arrives as a package that the host discovers, validates, and loads at bootstrap.

Treat this contract as a protocol, not an internal plugin format. It is deliberately aligned with what the AI ecosystem already produces — skills follow the agentskills.io standard and load unchanged, contribution folders mirror the layouts of Claude Code, Cursor, and friends, and a repository's existing .claude/ or .cursor/ directory is recognized as a package without modification. The long-term claim is simple: any AI capability bundle, from any tool, should be expressible through — or adapt into — this one contract.

The contract is file-first. A package declares what it contributes through files and manifest entries, never by registering code against the host: tool schemas are JSON files, skills and rules are markdown, routes and tool handlers are discovered from compiled modules by convention. The host reads the package's directory, merges it with the neuralis manifest block in package.json, and builds a typed PackageDefinition — the single canonical shape every runtime surface consumes.

Three ways a package reaches the platformCopy Anchor Link

The first two are the installed classes the rest of this section documents in depth. The third needs no install step at all: sync a mounted repository or an agent's data tree, and its markdown contributions group into packages agents can use — the import path for every .claude/, .cursor/, and .github/ folder you already have.

Trust is assigned by source, not by self-declaration. A dependency the admin added to the host is the trust act itself, so the host overwrites its trust to first-party. A project-dropped package can never claim first-party, can never use the in-process node runtime, and runs sandboxed. Declarative-only packages (tool schemas and markdown, no runtime code) need no runtime type at all and are safe at any trust tier.

Trust then shapes everything downstream: dispatch timeouts and rate limits (see lifecycle and execution), filesystem and network permissions in the manifest, which UI renderers a surface may use, and whether bundled skill scripts may run on the host shell.

What a package can contributeCopy Anchor Link

• Tools — strict JSON-Schema tool definitions in tools/*.json, callable by the model in-stream and over MCP. See Tools.
• Commands — commands/*.json prompt commands, served as static prompt text to external protocol clients. See Directory contract.
• Skills — agentskills.io-aligned SKILL.md bundles with scripts, references, and assets. See Skills.
• Instructions, rules, agents, docs — markdown that reaches the system prompt or becomes a spawnable delegate persona. See Contributions.
• Workflow templates — workflows/*.json scheduled and triggered job definitions, instantiated into a project as editable workflows. Structured JSON, never prompt-injected. See Workflow templates.
• Routes — feature-gated HTTP handlers served under /api/packages/<id>/.... See Routes.
• Connectors — filesystem-like source kinds and external service bindings. See Connectors.
• Sources — concrete source instances of an already-registered connector kind, seeded into a project or offered for on-demand add. See Declared sources.
• Resources — MCP resource entries (uri, name, mimeType) advertised to external protocol clients alongside the package's tools.
• Hooks — declarative lifecycle hooks (hooks.json) validated at load time.
• Policies — declared safety, permission, and trust entries the runtime compiles into tool allowlists, blocklists, and per-tool timeouts.
• App surfaces — widgets, dock entries, and chat cards under app.surfaces[]. See App surfaces.
• Team members — ready-made agent characters under team/.
• Features and role grants — capability ids the package provides, with per-role defaults. See Features and access.
• Credentials — the external secret ids the package needs, surfaced as rows in the admin credential catalog for an owner to fill in. Declaring one grants nothing and stores nothing. See Credentials.
• Config settings — the platform tunables the package owns, registered into the admin config surface; the host hardcodes no config schema of its own. See Config settings.
• URI policies — path-protection baselines for the package's own namespace. See URI policies.

Every contribution is scoped by the caller's real identity: package enable/disable state, role and feature grants, and project membership are evaluated deny-by-default before anything is advertised to a model or a user.

Section mapCopy Anchor Link

This section mirrors the @neuralis/package-system source layout, so the docs group the same way the contract kernel does. The sidebar is grouped into the same five areas:

Where to go nextCopy Anchor Link