---
title: Package and manifest
description: The self-contained files and versioned contracts Hay accepts.
group: Reference
---

# Package and manifest

A source project contains `manifest.json`, `index.html`, and optionally `initial-data.json`. The SDK builds these into a `.hay-plugin.json` bundle. Project metadata and build output are not installed.

## Manifest fields

| Field | Contract |
| --- | --- |
| `schemaVersion` | Exactly `hay.app/1`. |
| `id` | Stable lower-case identity with dot or hyphen-separated segments, up to 80 characters. |
| `name`, `description`, `author` | Display metadata. Author names are self-reported, not verified. |
| `version` | Three non-negative numeric components, such as `0.1.0`. No prerelease labels in this format. |
| `entrypoint` | Exactly `index.html`. |
| `icon`, `color` | Icon name and six-digit hex color. |
| `capabilities` | Requested host capabilities. Duplicates and unknown values are refused. |
| `views` | 1–12 named views with unique IDs, titles and descriptions. |
| `intents` | Up to 16 prompt suggestions, each pointing to a declared view. |
| `defaultTask` | Optional initial task title and declared view ID. |
| `agent.instructions` | Optional domain guidance, up to 6,000 characters; cannot grant permissions. |

See the [quickstart manifest](quickstart/) and the public [TypeScript contract](https://github.com/use-hay/app/blob/main/packages/sdk/index.ts) for complete field types.

## Bundle format

```json
{
  "schemaVersion": "hay.bundle/1",
  "manifest": {"...": "complete hay.app/1 manifest"},
  "html": "<!doctype html>...",
  "initialData": {
    "state": {"welcome": "Example record"},
    "documents": [{"id": "example", "name": "Example.txt", "text": "Fictional content"}]
  }
}
```

This is a shape illustration; replace `manifest` with a complete valid manifest. `initialData` is optional. Hay’s installed-plugin exports intentionally omit it and omit live workspace data.

## Resources and limits

HTML, CSS, and JavaScript must be self-contained. External scripts, resource directories, remote styles, CSS imports, and referenced assets are not supported by version 1. No plugin Node.js process runs in the desktop host.

Source files must be plain files without symlinks and fit within the packager’s 1 MB file limit. HTML is bounded at 1,000,000 characters; the final serialized bundle must fit in 2,000,000 bytes. Registries bound each catalog page or legacy index at 1,000,000 bytes and each bundle at 2,000,000 bytes. Paged browsing has additional [aggregate limits](registry-reference/).

Unknown package fields, duplicate view or intent IDs, and references to missing views are refused. Validation of structure does not prove that plugin code is safe or useful; review the code you distribute.

## Sample data

`initial-data.json` can seed JSON state and up to 100 sample documents. Document IDs must be unique and stable. Hay labels imported sample documents as samples. Initial data applies only to a fresh namespace; reinstall and update never replace saved user records with samples.

Keep secrets, credentials, installation metadata, workspace paths, and real user records out of distributable bundles.