SDK Manifest Schema

2026-11-15

Field-level reference for the biglazycat manifest; for the project-setup workflow see Plugin Development Process.

Manifest fields (biglazycat in package.json)

The manifest is the biglazycat object in package.json; unknown fields are rejected. Top-level fields:

Field Type Required Notes
apiVersion 1 yes SDK major version, currently fixed at 1; mismatch reports API_MISMATCH
minimumApiRevision integer no Minimum API revision required; the host refuses to install when lower
displayName string yes Display name, 1–200 characters
description string no Plugin description
main string no Backend entry relative path; must not start with /, contain .., \ or :; page-only plugins may omit it
mainView string no Main view id, matching ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,99}$
settingsView string no Settings view id
platforms string[] yes Targets from windows/amd64, windows/arm64, darwin/amd64, darwin/arm64, linux/amd64, linux/arm64, 1–256 items
activation string[] no Auto-activation events: startup, workspace.opened, document.committed
dependencies object[] no Runtime plugin-service dependencies, each with plugin, service, version, optional; 0–256 items
contributes object yes Contribution points, see below

Beyond the schema the host also validates platforms, engines, path existence, references and duplicate ids.

contributes

Key Fields (bold = required) Notes
commands id, title, description, contexts, aiCallable, externalEffect, visibility, inputSchema Commands. contexts: workspace, editor.document, editor.selection, resource — where the command applies; aiCallable exposes it to external AI; externalEffect marks outside side effects; visibility: "internal" (revision 2) hides the command from the palette, shortcuts and toolbar while pages can still call it — independent of aiCallable; inputSchema is a restricted JSON Schema supporting type, description, properties, required, additionalProperties, items, enum, minimum, maximum, minLength, maxLength, minItems, maxItems
views id, title, entry, defaultLocation, route, multiple, commandPalette Pages. entry points to an HTML file in the build output; defaultLocation: tab, panel, window; multiple allows several instances; commandPalette: false (revision 2) avoids duplicating the page with its open command; route starts with /
menus location, command Menu entries. location: editor.selection, editor.document, resource, toolbar; command references a declared command id
services id, version, methods Services offered to other plugins; methods holds 1–256 method names
providers id, contract, version, service Export providers; contract is currently export.text, version fixed at 1, service references a declared service
editors id, title, extensions, view Custom file editors; extensions like .catnote, 1–256 items; view references a declared page
schedules id, command, intervalSeconds, catchUp Scheduled tasks; intervalSeconds 10–31536000; catchUp: skip, once

Service dependencies

dependencies is unrelated to npm dependencies; it declares other plugins' services you call at runtime:

"dependencies": [
  { "plugin": "@scope/text-tools", "service": "text", "version": "^1.0.0", "optional": true }
]

Missing required dependencies, version mismatches or dependency cycles are rejected at enable/startup; optional dependencies never auto-start incompatible versions — callers handle unavailability.