# Core concepts

The terms you need to choose an extension surface, storage model, agent, and deployment path.

Source: https://docs.vampikez.fun/start/concepts/

Use this glossary to identify the contract you need. Follow its link for a
working example; you do not need to read every guide before starting.

## Extension

The installable unit: a directory with `extension.json`. Its directory name is
its id; `name` in the manifest is the display label. A tool pack, a skill pack,
a page, and an application use the same package and lifecycle.

An extension can contain UI (`ui/index.tsx`), Node code (`main/activate.ts`),
a headless entry (`server`), and declarative agents, skills, or MCP servers.
Create only the parts you use. [Extension anatomy](/build/extensions-and-apps/).

## Manifest

`extension.json` declares contributions, permissions, entry points, and
activation events. Only `name` and a numeric `MAJOR.MINOR.PATCH` version are
required to load. `compat.pluginApi` is the compatibility range the loader
enforces.

The root and some contribution objects discard unknown fields; strict objects
such as pages reject them. Do not assume a successfully parsed manifest means
every key had an effect. [Manifest reference](/reference/manifest/).

## App, and window ownership

An app is an extension with a page whose `presentation` is `app`. On Desktop
that page opens in its own window. A `docked` page uses the main shell. In the
Cloud web workspace, eligible pages appear as panels; `app` does not create a
native window there. [Pages and windows](/build/pages-and-windows/).

## Contributions

Declarations that make your extension reachable: pages, slot views, commands,
agents, skills, settings, services, MCP servers, agent runtimes, and IPC
namespaces. A declaration does not replace an implementation: commands need
handlers, and tools are registered in code with `ctx.api.tools.register`.

A `session.dock` view joins the workbench. The shell owns layout and view
instances; your component receives session and workspace authority, visibility,
and its selected resource tab. [Slot views](/build/pages-and-windows/#views-in-slots).

## Permissions and capabilities

Some permissions withhold an API namespace (`cron`, `process`, `auth.identity`),
while others are primarily install-time disclosures (`network`, `filesystem`).
`database` is a legacy no-op retained so published 1.x manifests still parse;
the extension API has no hosted document store. `ai` also gates an ACP runtime's
`modelAccess: "host"` credential.

Capabilities are a separate list for webview navigation, scripts, interception,
and header rewriting. Extensions execute trusted JavaScript; these declarations
are not a sandbox. [Permissions](/build/permissions/).

## The plugin API

Node code receives `ctx.api` in `activate(ctx)`. UI code imports `pluginAPI`
from `@wamp/plugin-api`. They have different members and signatures. Both can
use typed data, AI, and extension-owned tools; processes, cron, and service
registration belong to the Node half.

Use `pluginAPI.ipc.invoke` and `subscribe` to reach your Node half from either
Desktop or the Cloud web host. [API guide](/build/plugin-api/) ·
[Signature reference](/reference/plugin-api/).

## Typed data

`data.defineSchema(schema)` opens an extension-owned SQLite store on the engine
machine. Both halves share the schema; collection calls are asynchronous.
Use `q.gte`, `q.in`, and the other query builders for comparisons. Plain objects
such as `{ gte: value }` are not predicates.

For records that have to leave the machine, use your own backend. The extension
API does not expose a remote document store. [Typed data](/build/typed-data/).

## Tools

Named functions with JSON-Schema inputs. Names contain letters, numbers,
underscores, or hyphens; use a prefix such as `notes_search`. Registration does
not add a namespace for you.

Agent `tools:` lists are intended equipment, not a security boundary. Session
filters can narrow the model's tool list using exact names or a trailing `*`.
Enforce sensitive operations at the tool's own boundary.
[Contributing tools](/build/tools/).

## Agents and skills

An agent definition combines a prompt, model selection, tools, and limits in
`agents/<id>.md`. A runtime contributes an external process speaking ACP.
Choose the definition to configure WAMP's loop; choose a runtime to run a
different harness.

A skill is a portable directory containing `SKILL.md` plus optional resources.
The model sees routable skill descriptions and loads bodies when needed.
Extension skills have publisher-qualified identities; a short name is usable
only when it is unambiguous. [Agents and skills](/build/agents-and-skills/).

## Runs

An engine run records one execution and its outcome, usage, and child runs.
An extension has no multi-turn session primitive of its own: `pluginAPI.ai`
is one-shot (the extension keeps its own history and resends it), and
`pluginAPI.agents.delegate` runs a configured agent — with its own tool
loop — to completion in one call. [The plugin API](/build/plugin-api/).

Cloud's HTTP Session, Turn, and Run resources are a separate integration
contract. Use the [Cloud documentation](https://docs.cloud.vampikez.fun/)
when calling that API.

## Products

`product.json` configures a branded Desktop build: name, app id, icons, bundled
extensions, update feed, and optional root page. Every branded Desktop uses
WAMP sign-in; identity is not a product-file option. Your extension artifact
stays the same. [Branded product](/ship/branded-product/).

## Where to go next

[Quickstart](/start/quickstart/) gets a page running.
[Choosing a path](/ship/choosing-a-path/) separates extensions, branded builds,
and HTTP integrations.