Manifest reference

defineApp() returns a twl-tool.app.v1 manifest. The TypeScript input has this top-level shape.

Field	Type	Required	Purpose
key	string	yes	Stable lowercase app slug
name	string	yes	User-facing app name
version	string	yes	Installable app version
description	string | null	no	Catalog and installation copy
permissions	string[]	no	Requested platform permissions
catalog	object	no	Category, runtime, tags, and featured state
ui	object	no	Icon, color, default surface, and surfaces
extension	object	no	Contextual browser-extension actions
source	object	no	Provenance for a cloned Space Template
spaces	Record<string, SpaceDefinition>	no	Explicit Space hierarchy and placement
resources	AppResources	yes	Durable app resources

Generated fields

The SDK adds:

{
  "format": "twl-tool.app.v1"
}

It also deduplicates permissions, creates the default root Space when needed, and selects the first surface when ui.defaultSurface is omitted.

Catalog values

Categories:

chrome-tools | browser-agents | automation | data | forms | other

Runtime values:

chrome-extension | browser-agent | server

For the server's current JSON schema and node catalog, request GET /api/v1/apps-layer/platform-schema.

Chat preset fields

A chat surface reuses the host AI chat and requires preset.workflow. Its optional preset fields include space, outputDocumentFolder, allowedTools, display-control flags, app instructions, and contextSources.

contextSources is an array of app-scoped @ mention providers. A Data Workspace row source has this shape:

{
  key: string,
  label: string,
  type: 'dataWorkspaceRows',
  table: ResourceReference<'dataWorkspaceTables'>,
  workflowContextKey: string,
  labelField: string,
  descriptionFields?: string[],
  filter?: {
    field: string,
    equals: string | number | boolean,
  },
}

See Scoped AI chat for a complete example and workflow binding.