# Features and access (https://docs.neuralisapp.com/package-system/features)

Features are the access currency of the package system. A package declares the
capability classes it provides, project roles receive grants of those ids, and
every surface a caller can see or invoke — tools, skills, routes, widgets, dock
entries, commands, workflow templates — is checked against the caller's grants
through one shared predicate. There is no second authorization vocabulary.

## Declaring features [#declaring-features]

Features live in the manifest's `requires` block:

```json
"requires": {
  "providesFeatures": [
    "my-pkg.read",
    { "id": "my-pkg.admin", "title": "Administration", "description": "Manage package settings." }
  ],
  "defaultRoleGrants": {
    "owner":  ["my-pkg.read", "my-pkg.admin"],
    "admin":  ["my-pkg.read", "my-pkg.admin"],
    "member": ["my-pkg.read"],
    "viewer": []
  }
}
```

- **`providesFeatures`** entries are a bare id or a
  `{ id, title?, description? }` object, whose metadata the admin roles UI shows
  without changing the id. Duplicate ids fail manifest validation.
- **The id prefix is the tier**, so the boundary can never drift from a
  hand-kept list. `platform.*` marks a decision that **crosses the project
  boundary** — another tenant, a platform-global file, cross-user records, the
  global credential scope. Every other id, `project.*` included, acts inside
  the caller's own `session.projectId`. The tier is a **label, never a gate**:
  `hasFeature` stays the one predicate, with no tier branch. The label governs
  defaults — a `platform.*` id carries no default role grant and reaches nobody
  until an operator grants it. Use `platform.*` only for a capability that
  genuinely reaches outside the project.
- **`defaultRoleGrants`** maps role names to the ids each role receives at
  install; admins adjust grants per project afterwards. It cannot reach the
  strongest roles: for any non-builtin package the merge skips every `'*'`
  holder and every role at or stronger than the `admin` priority anchor, so an
  `owner` or `admin` entry in a project-dropped or third-party manifest is
  silently ignored and those ids are grantable only by hand in Admin → Roles.
  Declare grants for `manager`, `member`, `viewer` and custom roles; `owner`
  holds the wildcard already.
- The **consumers** — which tools, skills, commands and App surfaces a feature
  gates — are never stored on the manifest; they are derived from the loaded
  definitions at boot, so they cannot drift from the code.

## The one visibility predicate [#the-one-visibility-predicate]

Every `requires: { features: [...] }` declaration is evaluated by one shared
function, `meetsRequires(session, requires)`, built on `hasFeature`; surfaces
never inline a copy.

| Declaration | Result |
| --- | --- |
| No `requires` / empty `features` | Visible to everyone (ungated) |
| Caller's `grantedFeatures` contains `'*'` | Passes every check (the `'*'` wildcard; the seeded `owner` role holds it, `admin` does not) |
| Multiple features listed | **Every** listed feature must be granted (AND semantics) |
| Feature id that no package provides | Never granted to any role except `'*'` holders. It cannot appear in a derived grant list either, so it is wildcard-holder-only by construction |
| Caller has no `grantedFeatures` at all | Denied |

A failing check **hides the surface entirely**: a gated skill is not injected,
not in the packages overview or any catalog, never shown locked or disabled —
a caller lacking the feature cannot infer it exists. The same holds for gated
tools (catalog and dispatch), commands, widgets and dock entries.

Visibility and execution are gated independently. Hiding happens at the
advertisement boundary; execution is enforced server-side too — the dispatcher
checks a route's `feature` before the handler runs
([Routes](https://docs.neuralisapp.com/package-system/routes.md)), tool dispatch rejects callers failing
`requires.features`, and filesystem access goes through
[URI policies](https://docs.neuralisapp.com/package-system/uri-policies.md).

## Where `requires` appears [#where-requires-appears]

| Surface | Field | Notes |
| --- | --- | --- |
| Markdown contributions (`PackageFile`) | `requires.features` | Authored via the flat `requiredFeatures: [a, b]` frontmatter key — see [Instructions](https://docs.neuralisapp.com/package-system/instructions.md) |
| Tools (`PackageTool`) | `requires.features`, `requires.escalations` | `features` gates catalog visibility and dispatch; `escalations` is catalog metadata for input-dependent checks the handler makes itself |
| Commands (`PackageCommand`) | `requires.features` | Same semantics |
| Workflow templates (`PackageWorkflow`) | `requires.features` | Gates every template-listing surface — see [Workflows](https://docs.neuralisapp.com/package-system/workflows.md) |
| Widgets and dock entries | `requires.features` | Gated surfaces are omitted from the workspace snapshot ([App surfaces](https://docs.neuralisapp.com/package-system/app-surfaces.md)); a widget's `requires.tools` is catalog metadata, not a gate |
| Routes | `export const feature = '...'` | One feature per route file, enforced by the dispatcher before the handler runs |
| Whole package | `requires.accessFeature` | A single feature id that gates the ENTIRE package — see below |

For imperative checks inside a handler, the same building blocks are exported
from `@neuralis/package-system/access`:

```ts
import { hasFeature, requireFeature, meetsRequires } from '@neuralis/package-system/access';

hasFeature(session, 'my-pkg.read');        // boolean
requireFeature(session, 'my-pkg.admin');   // throws a 403-status error when missing
meetsRequires(session, { features: ['a', 'b'] }); // AND over the list
```

## Base-access feature — gating a whole package [#base-access-feature--gating-a-whole-package]

Beyond per-tool, -skill and -widget features, a package can gate its
**entire** surface with one declaration:

```json
"requires": { "accessFeature": "labs.access" }
```

A caller lacking `labs.access` sees none of the package — no tools, skills,
widgets or `<packages>` overview entry; hidden, not locked, so its existence
can't be inferred. Without `accessFeature` the package is visible to everyone,
so packages imported from other ecosystems load unchanged.

This is the clean way to **build and test a package in isolation**: declare an
access feature with no default role grant, and until you grant it only a `'*'`
holder (owner-strength) sees the package — a project `admin` does not, because
the seeded `admin` role holds an enumerated list rather than the wildcard. The
feature is grantable in Admin → Roles. An administrator can also attach a
required feature to an installed package in Admin → Packages (or
`neuralis package access <package> <feature>`), picking from the project's
existing features: a **restrict-only** override that tightens visibility, never
grants access, and is grantable in Admin → Roles too.

## Scope — who a loaded package reaches [#scope--who-a-loaded-package-reaches]

Package consumption is governed by three orthogonal axes:

| Axis | Question | Mechanism |
| --- | --- | --- |
| **uri-policy** | Which paths may the package touch? | [URI policies](https://docs.neuralisapp.com/package-system/uri-policies.md) |
| **feature** | Which roles may use a capability? | `requires` (above) |
| **scope** | Which user/agent is a loaded package advertised to? | source scope + `canAccessScope` |

A package contributed by a **user-scoped** or **agent-scoped** source loads for
the project but is advertised only to that user or agent — its tools, skills and
widgets never reach another member's stream, MCP catalog or workspace. One
predicate, `canAccessScope`, decides both file access and package visibility at
every advertise boundary; that is what makes per-person and per-agent
capabilities possible on a shared, multi-tenant project.

## Role priority [#role-priority]

Feature grants answer *"what can this caller do"*; role **priority** answers
*"what strength of role may this caller hand out"*. Priority is one ordinal per
role, **lower = stronger**; the five built-in roles anchor the scale and custom
roles declare their own (anchors and range: [roles](https://docs.neuralisapp.com/enterprise/roles.md)). The
name is cosmetic, the number is enforced, and an unknown label with no declared
priority resolves to the weakest value, so it can never escalate.

The assignment rule, implemented once in `canAssignRole` /
`validateRoleAssignment`: **a caller may assign a role only when the target's
priority is equal to or weaker than their own** (`targetPriority >=
callerPriority`). An `undefined` caller priority means a system session with no
membership identity, which bypasses the check. The caller's priority travels as
`SessionContext.priority` ([sessions](https://docs.neuralisapp.com/package-system/sessions.md)). It is enforced
at every role-handling boundary: invitations, member role changes, role
definition edits, and agent provisioning from package team members. The same
priority decides a uri-policy rule's `priority` subject
([URI policies](https://docs.neuralisapp.com/package-system/uri-policies.md#naming-the-requester)).

## Deny by default [#deny-by-default]

One posture: undeclared means ungated, ungranted means invisible, unknown means
denied. Referencing a feature id nothing provides is a legitimate technique — it
makes a contribution reachable only by a `'*'` holder. Administering roles and
grants across projects: [Roles and features](https://docs.neuralisapp.com/enterprise/roles.md).
