Gallery catalog format
The gallery is a folder of items that anyone can add to by pull request to 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.
item.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
"access": { "reads": ["email", "calendar"], "writes": ["sends email"], "runs_code": false, "computer": false, "credits": "low" }readsandwrites: 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_codeandcomputer: whether it runs code and needs the bot's computer. A skill that brings scripts (.py,.sh,.jsand similar files) always gets both, and sayingfalseis an error.credits:none,low,mediumorhigh, 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
"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:
"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:
{
"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:
{ "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:
{
"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
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:
{
"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:
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 itGALLERY_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
- Plugins
- Build with AI agents: the
casama-galleryskill adds items for you