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
settings	object	no	Friendly, installation-scoped workflow controls
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.

Workflow settings

Workflow settings are discovered automatically from every installed workflow and its Actions catalog metadata. Optional settings.workflows entries customize labels, descriptions, grouping, and stable field keys for particular bindings; omitted safe inputs remain visible. Each field binds to an existing Actions catalog property and does not define a second form schema.

settings: {
  workflows: [{
    key: 'write-post',
    label: 'Write a Social Post',
    workflow: ref('workflowDefinitions', 'writePost'),
    fields: [{
      key: 'emoji-policy',
      stepKey: 'generate_post',
      property: 'emoji',
      section: 'Writing preferences',
    }],
  }],
}

See Workflow settings for validation, persistence, and upgrade behavior.