- Create
extensions/<id>/where<id>is your extension's reverse-DNS-style manifest id (letters, digits, dots, dashes, underscores; 2-128 chars). - Add
extension.json, a schema-2 manifest following the panel's rules (id,name,versionx.y.z,permissions,ui.module+ui.mount, and — because it's schema 2 — anintegritymap). Theintegritymap only needs to exist and be non-empty when you first write the file;tools/build.pyrecomputes and rewrites it from the files actually on disk every time it runs, so don't hand-maintain the hashes. - Add every other file your extension ships (JS modules,
README.md, ...) under the same folder. Don't add dotfiles —build.pyrefuses to package them. Start fromtemplates/extension/. - Draw
glyph.svg, the one-colour icon the panel colours from the active theme, and declare it as"glyph": "glyph.svg"inextension.json; the build lists it inintegrity. The panel never shows a colour you supply."icon": "icon.svg"is deprecated and only for panels older than themed icons. The rules and a drawing guide are in docs/icons.md;tools/build.pyrefuses a non-theme package without a conforming glyph. Preview it withpython tools/glyph_sheet.py --png. - Add
listing.jsonnext to it with the store-catalog fields the manifest doesn't carry:{ "publisher": "Your name or org", "category": "games | utilities | productivity | media | developer-tools | communication | themes | other", "featured": false, "reviewed": true, "features": ["3 to 6 short bullets"], "requirements": ["plain-language requirement strings, catalog-entry shape"], "release_notes": "What's new in this version." }listing.jsonis never shipped inside the extension's ZIP — it's registry metadata only. - Build locally and fix anything
tools/build.pyrejects:This validates every extension's manifest, rebuilds its integrity map, and writespip install -r tools/requirements.txt python tools/build.pydist/<id>-<version>.zipplusdist/registry.json. - If you have a checkout of the Tend core, validate against its real
install-path checks before opening a PR — this needs a Go toolchain on
PATHfor the checkout's owngo run(a checkout from before the core'sbackend/was retired has nocmd/tend-validate-extensionand is refused with a clear error rather than silently skipped):TEND_CORE_CHECKOUT=/path/to/tend.host python tools/validate_with_panel.py - Run the tests:
pytest tests/. - If your extension ships its own pure (no DOM, no host) JS modules with
real logic — date maths, parsing, id/schedule computation — add
bun:testunit tests next to a mirror of the extension undertests/js/<extension-id>/*.test.js(never insideextensions/<id>/itself —tools/build.pyships every file it finds there, tests included, so they stay out). Run them with:bun test tests/jsextensions/host.tend.calendar'sreminders.jsandics.jsare the reference example. - Open a PR. A public check on the PR (see What happens to your pull request) re-runs the build and the tests; after approval, the maintainers' pipeline validates against the pinned core commit.
A theme pack is an extension with category: "themes" and a declarative theme block instead of code
(no .js/.mjs/.html/.css/.svg/.wasm files, so no glyph or icon either, no ui/runtime/widgets,
no permissions). Its store card is the wallpaper thumbnail.
- Copy
templates/theme-pack/toextensions/<id>/(the folder name must equal the manifestid) and editextension.jsonandlisting.json(categoryisthemesin both). - Every pack needs a thumbnail,
theme.wallpaper.thumb:.webp,.jpg,.jpegor.png(no AVIF), exactly 480 px wide and 240-320 px tall. The store card and the wallpaper picker show it. For a photo pack downscale the wallpaper to 480 px wide; for a gradient pack render it or screenshot the shell in your theme (the template ships one to replace). A photo pack also addswallpaper.webp(1600-4096 px wide, 900-2560 px tall, landscape) and references it astheme.wallpaper.image. - Run
python tools/build.pyandpytest tests/; the build enforces the colour grammar, numeric ranges, image checks and the WCAG 4.5:1primary/primaryContentcontrast. - Open a PR with one pack. The full reference is docs/themes.md.
A recipe describes how a panel installs one app from a container image: image, port, environment hints, volumes
and databases. Merged recipes are published in the signed Tend Community catalog, which panels show by default
as "Community · reviewed by Tend". That never means tested or certified; only Tend's own first-party catalog
carries those, and a pull request here does not ask for it.
- Copy
templates/recipe/example-notestorecipes/<slug>/(the folder name is the recipe'sslug) and editrecipe.jsonandlisting.json. Nothing else goes in the folder. - Pin an exact image version (never
latest), declare every state-holding path as a volume, ship no default passwords, one container per recipe. The full rules are in docs/recipes.md. - Install the app on a panel you administer and say in
listing.json(tested_with) what you actually did. - Validate:
python tools/validate_recipe.py recipes/<slug>, thenpython tools/build.pyandpytest tests/. - Open a PR with one recipe.
- Edit the extension's files under
extensions/<id>/. - Bump
extension.json'sversion(strictx.y.z, must increase). - Update
listing.json'srelease_notesto describe what changed in this version — it is registry metadata, not a changelog list. - Re-run
tools/build.pyand the tests, then open a PR as above.
Contributions arrive as GitHub pull requests. Only extensions/<id>/, recipes/<slug>/ and tests/js/ can be
changed by a contributor pull request; everything else (tooling, workflows, keys, templates, docs, the Python tests)
is maintainer-only and is reported as an error.
- Public checks.
validate-pr.ymlruns on GitHub-hosted runners with no secrets and a read-only token:tools/build.py(manifests, integrity maps, glyphs, themes, recipes),tools/validate_recipe.py,pytest,bun test tests/js, and reviewer hints (tools/review_hints.py) that point a human ateval, network calls, remote imports, minified files, new permissions and similar. Hints are not failures. The validators come from the base branch, so a pull request cannot change how it is graded. - Human review. A maintainer reads the diff and the checks and approves one exact commit. Pushing again voids the approval, so push your final version before asking for review.
- Import. The maintainers' pipeline takes the approved commit (rebased onto
main, your authorship kept), revalidates it against the real panel installer, and releases it. The pull request is closed with a comment naming theregistry-Nrelease.
The details, and what the maintainers set up, are in docs/community-review.md.
main is fast-forward-only. Every push to main runs the full build and
validation again, mirrors the verified commit to the public GitHub mirror,
then signs registry.json and creates (or updates) a GitHub release tagged
registry-<sequence> with the built ZIPs and the signed envelope attached.
Panels pick up the new registry on their next scheduled or manual check. If the release includes recipes, it also
carries the signed community catalog (community-catalog.json, its .sig and tend-catalog-pubkey).
You may use one; you do not have to. This repository ships a kit for agents:
developers/AGENTS.md and the skills (extension, theme
pack, Dockerfile, compose, deploy, recipe, Git and PR, API and MCP, review before PR). Point your agent at them, and
this repository's own AGENTS.md for the rules here.
- Every extension, theme pack, App Store recipe and listing is inspected by humans before it is published.
- The AI kit is a convenience, not the default.
- You are responsible for inspecting, testing, fixing and patching AI-generated code (and Dockerfiles, compose
files and recipes) before you open a PR. Run
python tools/build.pyandpytest tests/yourself and read the diff line by line. - Reviewers reject code its author can't explain. Be ready to answer questions about every file in your PR.
- Extension ids are unique and never reused for a different extension.
- Every shipped file except
extension.jsonitself must be covered by the manifest'sintegritymap —tools/build.pyenforces this both ways (no uncovered file, no stale entry for a file that no longer exists). - Only permissions and runtime modules the panel already knows about are
allowed (
tools/build.pyandtools/validate_with_panel.pyboth check this — the second one by running the real core's owncmd/tend-validate-extension). - Every non-theme extension ships a conforming
glyph.svg(monochrome, no colour of its own); the panel draws the icon tile from the theme. See docs/icons.md. - Recipes: one folder per slug under
recipes/, onlyrecipe.jsonandlisting.json, an exact pinned image version, no default secrets (tools/validate_recipe.pyenforces it; see docs/recipes.md). - Keep ZIPs deterministic: no dotfiles, no directory entries, sorted member
order.
tools/build.pydoes this for you; don't hand-build the ZIP.