# Registry rules and checks

The community package registry: naming rules, limits, the automatic checks, the signed index, the publisher panel, its API and Markdown for agents.

_Last updated: 2026-11-19_

Every version uploaded to the AI Game Dev community registry is checked automatically before anyone can install it; there is no manual review queue. This page lists the rules a package must follow, what each check refuses and why, how a published version reaches users through a signed index, the publisher panel, the registry's API and the Markdown pages AI agents read.

## Names

- **Publisher ids** are 2 to 40 lowercase letters, digits and single hyphens, first come, first served. Reserved: `aigd`, the engine names `unity`, `godot`, `unreal`, `brutal`, `bevy` and `threejs`, trademarks and role words (`anthropic`, `claude`, `openai`, `official`, `admin`, `samples` …), look-alikes after folding digits to letters (`un1ty`), and any id that uses a reserved name as a word or prefix (`unity-tools`, `my-godot`). A reserved name can be assigned to its real holder by AI Game Dev.
- **Package ids** are `<publisher>.<name>` and must match the manifest. App-reserved ids such as `aigd.image` are refused.
- **Precedence:** the app ignores a community entry for an `aigd.*` id or any id AI Game Dev's own index lists, so nobody can shadow an official package.

## Limits

| Limit | Value |
| --- | --- |
| Archive (gzip) | 50 MiB compressed, 200 MiB unpacked |
| Files | 5,000 per archive, 64 MiB per file |
| Publishers per account | 3 |
| Uploads | 20 per hour (per account, or per publisher for token uploads) |
| Versions waiting for checks | 5 per publisher |
| Active publisher tokens | 10 per publisher, each valid up to 365 days |
| Trusted publishers | 10 per package |
| Release notes | 20 KB of Markdown per version |
| Channels | 5 per package |

## The automatic checks

The archive is treated as untrusted data: it is unpacked in memory under a size cap and read as bytes, never executed. The checks run in this order, and the report lists each with its result:

| Check | Refuses |
| --- | --- |
| `archive` | Anything but gzip; archives over the limits; symlinks, hard links, devices, absolute paths, `..`, control characters, names invalid on Windows, case-insensitive duplicates, `.git/` |
| `manifest` | A manifest the app would not load, checked with the app's own validator: schema, owned ids, game engine rules |
| `registry-rules` | A publisher you do not hold; a reserved id; any `enabledApiProposals` entry; a `main` that is not in the archive; an icon that is not a real PNG, JPEG, GIF, WebP or ICO, or an SVG with scripts, styles, external references or event handlers |
| `secrets` | Private keys and credentials (cloud, GitHub, GitLab, Slack, Stripe, Google, Anthropic, OpenAI, npm, PyPI, Hugging Face, ai-game.dev keys), JWTs, files such as `.env`, `.npmrc` or `id_rsa`. The report names the file and line, never the value |
| `prompt-injection` | Text that tries to instruct the agent (below) |
| `native-code` | Nothing: native binaries are allowed and flagged, and users see "native code" on the package |
| `virus-scan` | Anything the virus scanner flags, including archives nested too deep to scan |

A version that fails is `rejected` with every reason; fix it and upload the same version again. When a scanner is briefly unreachable the version waits and is retried; it never passes unscanned.

### Prompt injection

A package's text reaches the agent: tool descriptions, skills, READMEs, release notes. The registry reads every manifest string, `README*`, Markdown and text files, `SKILL.md`, `CLAUDE.md`, `AGENTS.md` and the files under `skills/`, `agents/`, `commands/` and `prompts/` with every rule, and your code files with the high-confidence rules. Text is normalized first (HTML entities, Unicode look-alikes, invisible characters, Markdown emphasis), so disguises do not help. It rejects:

- instructions to ignore or override previous instructions, or to reveal the system prompt;
- chat role markers (`<|im_start|>`, `[INST]`, `<system>` …);
- hidden characters: zero-width and bidirectional control characters, Unicode tag characters;
- long base64 runs that decode to readable text;
- HTML comments or hidden elements that address the AI;
- requests to send keys, tokens, credentials or the conversation anywhere;
- jailbreak phrases, requests to hide actions from the user, and requests to auto-approve tools or bypass permission checks.

Ordinary game words ("god mode"), emoji, badges and API docs pass. If a check flags text that is harmless, reword it, or report the false positive to AI Game Dev.

## The signed index

A published version is written to its own storage (`community-packages.ai-game.dev`) and listed in a community index that the registry signs with Ed25519. Every app checks the signature against keys built into the app, refuses an index that has expired or is older than one it already accepted, and verifies each archive's `sha512` integrity before unpacking and its tree hash after. Besides each version's archive, the index carries per package its publisher, rating, README, icon, channels and deprecation, and per version its release notes (first 4 KB), deprecation, provenance and the native-code flag.

A version AI Game Dev revokes is listed in the index's `revoked` list: every app turns it off on its next read (a running app reads the index about every 30 minutes) and never installs it again.

## The publisher panel

The publisher panel at [ai-game.dev/publisher](https://ai-game.dev/publisher) is where signed-in owners and maintainers manage what they publish:

- your publishers, your role in each, and their members;
- each package's versions with their state and full check report;
- release notes, channels, deprecation and yanking;
- publisher tokens (create, list, revoke);
- trusted publishers for GitHub and GitLab, with copyable workflow snippets;
- the status of uploads still being checked.

## Routes of the registry API

Everything the CLI and the panel do goes through `https://ai-game.dev/api/registry/v1`. Errors use one envelope, `{"error": {"code", "message", "fields"}}`.

| Route | Who | What |
| --- | --- | --- |
| `POST /publishers`, `GET /publishers`, `GET /publishers/{slug}` | signed in, members | Claim a publisher; list yours; one publisher with its packages and versions |
| `GET /me/publishers` | signed in | Your publishers with your role |
| `GET /publishers/{slug}/members` | member | The members (emails only for the owner) |
| `POST /publishers/{slug}/members`, `DELETE …/members/{userId}` | owner | Add or remove a maintainer |
| `POST /publishers/{slug}/tokens`, `GET …/tokens`, `DELETE …/tokens/{id}` | member | Publisher tokens |
| `POST /uploads` (multipart `tarball`, optional `notes`) | member or token | Upload a version |
| `GET /packages/{id}/versions/{version}` | member or token | State, check report and release notes |
| `PATCH /packages/{id}/versions/{version}` | member | Edit release notes |
| `POST /packages/{id}/versions/{version}/yank` | member or token | Yank or restore |
| `POST`, `DELETE /packages/{id}/deprecate` and `…/versions/{version}/deprecate` | member | Deprecate or undeprecate |
| `GET /packages/{id}/dist-tags` | public | Channels |
| `PUT`, `DELETE /packages/{id}/dist-tags/{tag}` | member | Set or remove a channel |
| `GET`, `POST /packages/{id}/trusted-publishers`, `DELETE …/{tpId}` | member to read, owner to change | Trusted publishers |
| `POST /oidc/token` | CI | Exchange a CI identity token for an upload credential |
| `GET /packages/{id}/ratings`, `PUT` and `DELETE …/rating` | public, signed in | Ratings (members of the package's publisher cannot rate it) |

## Markdown pages for agents

AI agents read the site as Markdown, so everything about packages has a Markdown twin:

- **The catalog.** The package catalog at `ai-game.dev/packages` (rolling out) lists every official and community package, and each package has its own page at `/packages/<id>`. Add `.md` to either path, or request it with `Accept: text/markdown`, for the same content as Markdown: name, id, version, publisher, description and the install command.
- **These docs.** Every page of this wiki has a Markdown mirror under `/docs-md/` (this one is `/docs-md/wiki-app-package-registry.md`), linked from **View as Markdown** at the top of the page. The mirrors keep every screenshot as an image link.
- **The site index for LLMs.** `https://ai-game.dev/llms.txt` lists these pages, so an agent asked to write a package can find the manifest reference and the package API directly.

**Tip**

To have an agent write a package for you, point it at the [package API](https://ai-game.dev/docs/wiki/app/package-api) and [manifest reference](https://ai-game.dev/docs/wiki/app/package-manifest) Markdown mirrors, and let it run `gamedev pkg validate` after every change.

## Related pages

- [Publishing packages](https://ai-game.dev/docs/wiki/app/publishing-packages) for the publishing workflow.
- [Trusted Publishing](https://ai-game.dev/docs/wiki/app/trusted-publishing) for CI and provenance.
- [Lifecycle, hosts and permissions](https://ai-game.dev/docs/wiki/app/package-lifecycle#permissions) for what a package may do once installed.

---

Source (HTML): https://ai-game.dev/docs/wiki/app/package-registry
