The contract examples

The package contract has three example packages, one for each way a package reaches the platform. Each exercises the surfaces its own install class can actually carry, once, and nothing it cannot. Together they are the contract in machine-readable form: what the prose on this site describes, the examples declare.

Three examples, one per install classCopy Anchor Link

The install class is how a package of that shape reaches a real host; the identity is how you read the example itself — see Where to get them.

Where to get themCopy Anchor Link

First-party package source is not published — the built-in packages ship as installed artifacts, never as a source tree you can browse. The examples reach you through the package registry (neuralweb) instead, which is also the only rail that serves a single element rather than a whole tree.

How you read an element depends on its serving tier, and only two of the three tiers are readable on their own:

Everything else is Tier C: hook command resource source policy widget dock card, plus any tool whose contract carries a handler-shaped key and any connector that is not a plain mcp/http URL. Those elements need their owning package's runtime, so per-element serving answers 409 TIER_C_NOT_STANDALONE with a deep link to the parent package instead of handing back something that could not work. Read the parent package's docs/ elements for what they do, or install the whole package.

/document on a Tier-A kind returns metadata only — the host's PackageFile projection (id, path, category, title, description, overwrite, plus files/activation/requires/metadata when present). The body is what /content serves.

# Tier A — the authoring walk-through that ships inside example-builtin,
# as plain text in one request. Omit the version and the CLI resolves the
# latest listed one.
neuralweb read '@neuralis/example-builtin#docs/docs.create-package'
# ...or just the first forty lines
neuralweb read '@neuralis/example-builtin#docs/docs.create-package' --line-start 1 --line-end 40

# Tier B — a tool schema, verbatim, in one self-verifying JSON envelope
neuralweb info '@neuralis/example-builtin#tool/example_query'

Every read is verified end to end: bytes against the digest header, the bundle's files against its manifest as an exact set, a Tier-B contract against its canonical hash. A single mismatched byte fails.

Installing follows the platform's own paths, not the registry's: neuralweb install <ref> --channel project drops a verified Tier-A element into a project's _packages/ directory; --channel builtin prints the command an admin runs and executes nothing, because installing builtin-class code is the platform admin's trust act.

What each tree demonstratesCopy Anchor Link

example-builtin — the full contractCopy Anchor Link

The builtin class is the only one that carries every surface, so this tree is the reference for all of them.

package.json                    # the manifest — the `neuralis` key holds everything
README.md                       # package-meta — NOT a contribution
hooks.json                      # declarative lifecycle hooks
tools/example_query.json        # strict JSON Schema + one x-neuralis extension
tools/example_health.json
workflows/sample-workflow.json  # a workflow TEMPLATE — typed JSON, never prompt-injected
skills/example-skill/SKILL.md   # agentskills.io-shaped skill (category: skill)
rules/guardrails.md             # safety rules (category: rule)
agents/example-agent.md         # a delegation target (category: agent)
docs/create-package.md          # authoring walk-through (category: docs)
team/example-member/member.json # a team member + its identity prose
team/example-member/identity/persona.md
src/lifecycle.ts                # init / start / stop / api + hook callbacks
src/routes/health.ts            # file-discovered HTTP routes
src/routes/query.ts
src/tools/example_query.ts      # handler paired with tools/example_query.json (default-exported)
src/tools/example_health.ts
app/surfaces/{kind}/{id}/       # one canonical root per asset-backed surface
app/shared/example-theme.css    # package-public assets — bundle-mode surfaces only
assets/example-icon.svg         # static icons, images

• Manifest. Identity and model-facing description, the source/runtime/access/meta operational blocks, requires (two declared features with their default role grants and an accessFeature base gate), credentials[], a declared sources[] instance, configSettings[], uriPolicies, policies[], connectors[], resources[] and app.surfaces[]. See Manifest.
• Tools. example_query and example_health show the strict schema shape — $schema, title, root additionalProperties: false, and a single canonical x-neuralis extension with dotted operation, explicit transport, full annotations (including the mandatory risk category), and a card-presentation ui block. Each paired handler lives at src/tools/<name>.ts and is bound by its default export — a named-only export is silently skipped at load. See Tools.
• Markdown contributions. A folder-per-skill SKILL.md, a rules file, a delegation agent, a docs walk-through, and a team/ member with its identity prose — each lands in its first-class array with the category set from its folder. Package-root loose markdown (the README) is package-meta, never a contribution. See Skills and Contributions. (Contributor note: the registry's own test corpus pins the published examples' prose — docs/create-package.md in particular is snapshot- and content-hash-locked there, so an edit to a shipped example file must regenerate those fixtures in the same change, never hand-patch them.)
• Workflow template. workflows/*.json is a parallel typed JSON array like tools, not a sixth file category: declared inputs, manual + webhook + schedule triggers with maxRuns/endAt guardrails, a delivery block, an execution policy, and a feature gate.
• Lifecycle and routes. src/lifecycle.ts exports init/start/stop plus a typed api() for cross-package calls; src/routes/*.ts are file-discovered, feature-gated handlers. First-party runtime providers, services and realtime channels use the same kernel contracts described on the lifecycle page; they are optional and are not required by this example. See Lifecycle and Routes.
• Hooks. hooks.json declares PreToolUse/PostToolUse hooks whose callback handlers reference named exports of the lifecycle module, conditioned on specific tool names.
• URI policies. Baselines for data://<self>/** and packages://<self>/**, including a nested path rule that keeps src/** read-only. See URI policies.
• App surfaces. Two widgets, one standalone dock entry, and two tool-matched cards — so all three kind values appear, and widget and card twice each. The first widget and the first card omit assetMode and ship a self-contained HTML entry inside their own canonical root (app/surfaces/widget/example_workspace/index.html and app/surfaces/card/example_result.card/index.html), the worked example of the default mode. The second card, example_approval.card, matches the same tool with "state": "approval-required" — the approval-time presentation of a call the user has not yet allowed. The second widget, app/surfaces/widget/example_bundle_workspace/index.html, declares "assetMode": "bundle" and ships a stylesheet, a classic script, a module script that fetches a JSON sibling, an image, and a link to the package-public app/shared/example-theme.css — the worked example of the multi-file mode. It carries no dock entry of its own (it declares "dock": {"show": false}, the explicit opt-out a widget needs when nothing else opens it). See App surfaces.
• Connectors, resources, policies. An in-process host gateway connector and an OAuth-configured HTTP gateway, an MCP resource entry, and policy entries — the optional capability arrays in their full shapes. Of the policy kinds, safety (tool blocklist plus a per-tool timeout), permission (tool allowlist) and trust (input validation on or off) are evaluated before any handler runs, and a deny is absolute; a kind: "access" entry is accepted and does nothing — tool feature gating comes only from each tool's x-neuralis.requires.features. The safety kind is the one with a trust condition: its blocklist and timeout are evaluated across every loaded package, so they are honoured only from a first-party manifest and dropped from anything else. permission and trust restrict the declaring package alone and apply at every trust level.

No example ships a commands/ folder. The array still exists in the contract for imported packages; new packages ship skills instead.

example-project — the sandboxed project dropCopy Anchor Link

The same contract, narrowed to what a _packages/ drop can hold: one tool with its handler, one route, one skill, one rule, one docs file, and one iframe widget with its dock entry — an untrusted package has exactly one renderer. Its manifest declares a single feature id that gates every surface it contributes — the tool, the route, the widget, the dock entry, and the feature-gated markdown — so one grant is visibly several enforcement points. Two things it deliberately does not do are as instructive as what it does; both are covered on WASM build.

example-source — markdown only, no manifestCopy Anchor Link

No package.json, no code, no install step: the folder layout is the whole declaration. It ships skills/, rules/, instructions/, docs/ and a root AGENTS.md, and demonstrates the default-ON / opt-in split that source packages apply.

Deliberately never loadableCopy Anchor Link

The examples pass every validator and are still never auto-loaded. Three independent gates hold that:

• Neither package is a dependency of the host, and builtin discovery iterates only the host's own dependencies.
• Both manifests carry neuralis.referenceOnly: true, a separate exclusion in the same loop. (example-source has no manifest to opt out with — it is markdown in a source, and a source contributes no code by construction.)
• Their ids sit in the host's explicit reference-only set as defence in depth, so a manifest that lost its flag still could not be promoted: the exclusion runs before the host's first-party trust assignment.

No gate relies on a deliberately invalid manifest: these are valid, loadable packages that simply are not installed. The opt-out flag is available to any documentation-only package:

{ "neuralis": { "referenceOnly": true } }

A dependency carrying this flag can sit in the host's dependencies so authors can read it, but it never auto-loads.

Because they never load, their tools, skills, and routes are authoring examples, not a callable or smoke-test surface — nothing here is invoked at runtime, and the descriptions do not promise a working endpoint.

What this costs an agentCopy Anchor Link

Everything a package contributes competes for the model's context, and the categories differ sharply: rules and instructions are injected into every system prompt automatically, agents are read when a delegation resolves, skills contribute only their description until activated, and docs are read purely on demand. The examples lean on that: the skill declares invocation: manual, the agent gates itself behind a declared feature, and the docs walk-through — by far the longest file in any of the three trees — costs an agent nothing until something opens it. When you copy a shape, copy that discipline too. Contributions has the per-category table.

Reading order for new authorsCopy Anchor Link

1. Skim example-builtin's package.json top to bottom with the manifest reference open.
2. Read tools/example_query.json next to Tools — the schema rules are where most first packages fail validation.
3. Read skills/example-skill/SKILL.md and Skills for the activation model.
4. Read the example that matches how your package will reach the platform, and validate early: the load-time checks in Testing and validation are the same ones that will run against your package at bootstrap.