# Gallery catalog format

The [gallery](https://gallery.casama.ai) is a folder of items that anyone can add to by pull request
to [stackwares/casama-gallery](https://github.com/stackwares/casama-gallery). A checker turns the
folders into a few JSON files that Casama servers, the app and the web gallery read. This page
describes the folders, every `item.json` field, skill tests, starter sets and the files the checker
writes. Any folder laid out the same way is a valid catalog, so you can run your own.

## Folders

Each item is a folder named by its id (lowercase letters, digits and dashes):

| Kind | Folder | Files next to `item.json` | Licenses |
| --- | --- | --- | --- |
| Theme | `themes/<id>/` | `theme.json` | CC0-1.0, CC-BY-4.0 |
| Color scheme | `schemes/<id>/` | `scheme.json` | CC0-1.0, CC-BY-4.0 |
| Wallpaper | `wallpapers/<id>/` | `wallpaper.json`, its image | CC0-1.0, CC-BY-4.0 |
| Skill | `skills/<id>/` | `SKILL.md`, any files it uses, optional `tests.json` | MIT, Apache-2.0 |
| App | `apps/<id>/` | `app.json`, optional `logo.svg` | CC0-1.0 |
| Starter bot | `bots/<id>/` | `bot.json` | MIT, Apache-2.0, CC0-1.0, CC-BY-4.0 |
| Routine idea | `routines/<id>/` | `routine.json` | MIT, Apache-2.0, CC0-1.0, CC-BY-4.0 |
| Plugin | `plugins/<id>/` | `plugin.json` | CC0-1.0 |
| Starter set | `sets/<id>/` | `set.json` | CC0-1.0, CC-BY-4.0 |

The documents for each kind (`theme.json`, `app.json`, `bot.json` and the rest) are described in the
catalog's [README](https://github.com/stackwares/casama-gallery#readme).

## item.json

```json
{
  "name": "Morning plan",
  "author": { "name": "Casama", "url": "https://casama.ai", "handle": "casama" },
  "license": "Apache-2.0",
  "tags": ["planning", "calendar"],
  "featured": true,
  "pick": "Five lines each morning: meetings, deadlines, weather, and where to start.",
  "version": 1,
  "added": "2026-11-13",
  "access": { "reads": ["calendar", "tickets", "memory", "the web"], "credits": "low" },
  "inputs": [
    { "key": "time", "label": "What time should it arrive?", "type": "time", "default": "07:30" },
    { "key": "city", "label": "Your city, for the weather", "type": "text", "default": "my city" }
  ]
}
```

| Field | Shape | Rule |
| --- | --- | --- |
| `name` | string | 1 to 60 characters. |
| `author` | `{ name, url?, handle? }` | `name` up to 80 characters, `url` https. `handle` (`[a-z0-9-]`, up to 39) groups the author's items on one author page; without it, items group by a slug of the name. |
| `license` | string | One of the kind's licenses above. |
| `tags` | string[] | Up to 8, each `[a-z0-9-]` up to 24 characters. |
| `category`, `icon` | string | A skill's catalog category (required for skills) and a Lucide icon name. |
| `featured` | boolean | Shown as a pick. |
| `pick` | string | Up to 140 characters: why it's a pick. Only with `featured: true`. |
| `retired` | boolean | Hidden from lists; people who added it keep it. |
| `replaced_by` | `{ type, id }` | For a retired item, what to use instead. Must exist. |
| `version` | integer | Starts at 1. Raise it when the item changes in a way people should update to. |
| `added` | `YYYY-MM-DD` | **Required.** The day it joined the gallery. |
| `updated` | `YYYY-MM-DD` | Optional. Defaults to the newest changelog date, else `added`. |
| `changelog` | `[{ version, date, note, breaking? }]` | Newest first, versions going down, the top one equal to `version`. Required once `version` is above 1. `note` up to 160 characters. `breaking: true` makes the app ask before updating. |
| `examples` | string[] | 1 to 3 prompts up to 160 characters people can try. Skills, apps and bots. |
| `access` | object | What the item can touch. Skills, apps, routines, bots and plugins. See below. |
| `needs` | `{ apps?, skills? }` | What a routine or bot needs first. See below. |
| `inputs` | question[] | Up to 6 questions asked when a routine or bot is added. See below. |
| `remix_of` | `{ type, id }` | The gallery item it's based on. Must exist. |
| `min_app`, `min_server` | `x.y.z` | Lowest app or server version that can use it. Older apps hide it; older servers leave it out. |
| `season` | `{ from: "MM-DD", to: "MM-DD" }` | Shown in the seasonal row between these days. May wrap the year end (`12-01` to `01-06`). |

### access

```json
"access": { "reads": ["email", "calendar"], "writes": ["sends email"], "runs_code": false, "computer": false, "credits": "low" }
```

- `reads` and `writes`: up to 8 plain phrases of at most 40 characters each, written for the person
  adding it ("files you share", "creates and edits Word files").
- `runs_code` and `computer`: whether it runs code and needs the bot's computer. A skill that brings
  scripts (`.py`, `.sh`, `.js` and similar files) always gets both, and saying `false` is an error.
- `credits`: `none`, `low`, `medium` or `high`, a rough guide to what a run costs.

When an update grows `access` (a new read or write, or code where there was none), the app shows the
difference and asks before updating.

### needs

```json
"needs": { "apps": ["google_calendar"], "skills": ["meeting-notes"] }
```

`apps` are gallery app ids or built-in app ids (`gmail`, `google_calendar`, `slack`, `github` and
the rest). `skills` are gallery skill ids. Installing the item installs the skills too, and walks the
person through connecting each app.

### inputs

Questions asked when a routine or bot is added. Each answer fills `{{key}}` in a routine's
`instructions_md` or a bot's `persona` and `starters`.

| Field | Rule |
| --- | --- |
| `key` | `^[a-z][a-z0-9_]{0,31}$`, unique. |
| `label` | 1 to 60 characters. |
| `type` | `text`, `choice`, `time` (`HH:MM`, 24-hour) or `timezone` (`Europe/Berlin`, `UTC`). |
| `options` | `choice` only: 2 to 8 options of at most 60 characters. |
| `default` | Required, 1 to 120 characters, fitting the type. The form starts with it, and servers from before inputs use it. |
| `help` | Optional, up to 120 characters. |

A `time` input named `time` can also set a routine's schedule:

```json
"schedule_cron": "{{time.minute}} {{time.hour}} * * 1-5"
```

Every placeholder needs an input, and every input has to be used. Answers can't contain `{` or `}`.

## Skill tests

A skill folder may hold `tests.json` with 1 to 5 cases:

```json
{
  "cases": [
    {
      "prompt": "Proofread this: 'Their going to the meeting tomorow.'",
      "expect": "Fixes they're and tomorrow, keeps the meaning and voice, and lists what changed."
    }
  ]
}
```

`prompt` is up to 500 characters and `expect`, a plain-words rubric, up to 300. The file is part of
the skill like any other. In the Casama repo, `node scripts/gallery-skill-tests.mts` runs each prompt
with the skill loaded and has a model check the answer against `expect` (it needs
`OPENROUTER_API_KEY`; `GALLERY_TEST_MODEL` and `GALLERY_JUDGE_MODEL` pick the models). It writes
`tested.json`:

```json
{ "proofread": { "version": 1, "passed": true, "date": "2026-11-16" } }
```

A skill that passed on its current version gets `tested: { version, date }` in its record, which the
app shows as **Reviewed**.

## Starter sets

`sets/<id>/set.json` bundles items people often add together:

```json
{
  "description": "Decide, plan and report without a chief of staff.",
  "icon": "rocket",
  "items": [
    { "type": "skill", "id": "decision-memo" },
    { "type": "routine", "id": "weekly-review" },
    { "type": "app", "id": "todoist" }
  ]
}
```

`description` up to 200 characters, `icon` a Lucide name, and 2 to 12 items of type `app`, `skill`,
`routine`, `bot`, `theme`, `scheme`, `wallpaper` or `plugin`. Each must be in the gallery and not
retired.

## Files the checker writes

```sh
node check.mjs          # write the files
node check.mjs --check  # fail when an item is wrong or a file is out of date
```

| File | Holds |
| --- | --- |
| `index.json` | Themes, color schemes, wallpapers and skills. |
| `apps.json`, `bots.json`, `routines.json`, `plugins.json`, `sets.json` | The other kinds, one file each. |
| `authors.json` | `{ schema: 1, authors: [{ handle, name, url?, items: [{ type, id }] }] }`. |
| `manifest.json` | `{ schema: 1, created, files: { "<file>": "<sha256 hex>" } }` over every file above. `created` is the newest `updated` date in the catalog. |
| `manifest.sig` | Written in CI by `node sign.mjs`, never committed. |

`index.json` only ever holds the four original types, because apps and servers from before the other
kinds can't read them; every new kind gets its own file. Every list file is
`{ "schema": 1, "items": [...] }`, and each record looks like this:

```json
{
  "id": "morning-plan",
  "type": "routine",
  "name": "Morning plan",
  "author": { "name": "Casama", "url": "https://casama.ai", "handle": "casama" },
  "license": "Apache-2.0",
  "tags": ["planning", "calendar"],
  "featured": true,
  "retired": false,
  "version": 1,
  "added": "2026-11-13",
  "updated": "2026-11-13",
  "sha256": "…",
  "size": 1343,
  "description": "Each weekday morning: today's meetings, deadlines and the one thing to get done first.",
  "pick": "Five lines each morning: meetings, deadlines, weather, and where to start.",
  "access": { "reads": ["calendar", "tickets", "memory", "the web"], "credits": "low" },
  "inputs": [{ "key": "time", "label": "What time should it arrive?", "type": "time", "default": "07:30" }],
  "document": { "instructions_md": "… today's weather in my city …", "schedule_cron": "30 7 * * 1-5" },
  "template": { "instructions_md": "… today's weather in {{city}} …", "schedule_cron": "{{time.minute}} {{time.hour}} * * 1-5" },
  "files": ["routines/morning-plan/item.json", "routines/morning-plan/routine.json"]
}
```

Fields appear only when the item has them: `category`, `icon`, `description`, `requires` (what a
look needs from the app), `changelog`, `pick`, `examples`, `access`, `needs`, `inputs`, `remix_of`,
`replaced_by`, `min_app`, `min_server`, `season` and `tested`. `document` is what a card or install
needs without another request; for a routine or bot with inputs it has the defaults filled in, and
`template` keeps the fields with their placeholders. `sha256` covers every file in the folder
(sorted path, length and bytes), and installs check it.

## Signing

A Casama server checks `manifest.sig`, a base64 Ed25519 signature over the exact bytes of
`manifest.json`, with the catalog's public key, then checks each JSON file it reads against the
hashes in the manifest. To sign your own catalog:

```sh
node sign.mjs --gen-key                          # prints a private key (PEM) and a public key
GALLERY_SIGNING_KEY="$(cat key.pem)" node sign.mjs  # writes manifest.sig
node sign.mjs --verify <base64 public key>        # checks it
```

`GALLERY_SIGNING_KEY` is a PKCS8 PEM or a base64 raw 32-byte seed; the public key is the base64 raw
32 bytes. Keep the private key in your CI's secrets, never in the repository.

## Related

- [Bot template format](https://docs.casama.ai/develop/bot-templates.md)
- [Plugins](https://docs.casama.ai/develop/plugins.md)
- [Build with AI agents](https://docs.casama.ai/develop/agents.md): the `casama-gallery` skill adds items for you
