The publish checklist
This page lists everything an app must pass before Brydio publishes it (A8-F04-S03). It covers Brydio's own apps and everyone else's, with no exceptions.
brydio validate runs these checks on your own machine. brydio publish runs brydio build and brydio validate before it uploads anything. Then the app registry (POST /v1/apps/:key/versions on registry.brydio.com) checks the upload again, because an older or edited command line is still just a client, and Brydio checks it once more when it pulls the version from the registry. Every check reports a code and one sentence, one item per failure. Warnings don't stop a build or a publish; errors do.
The columns:
- validate: whether
brydio validate(and sobrydio publish, before uploading) runs the check. - server: whether it is run again. "publish" means the registry refuses the version (Brydio's own publish route used the same codes and words, and the registry keeps them). "runtime" means Brydio refuses the thing when a screen does it, but still publishes the version. "no" means only the command line checks it.
- Refused with: the sentence you see.
<angle brackets>stand for your app's names. Where the server runs the same check, it uses the same sentence unless the row says otherwise.
packages/cli/test/checklist-doc.test.ts fails if a code exists in the SDK and not on this page, or the other way round.
1. The manifest parses, and every placement names a screen
The manifest is .brydio/app.json (or app.json), read with Brydio's own schema (@brydio/manifest). validate and the publish route refuse the same way: the check's own code (manifest_invalid for a field of the wrong shape) and the sentence behind app.json: "<path>": , or behind app.json: when the problem isn't about one field. The sentences below are what follows that prefix. validate lists every problem; the route answers with the first.
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
manifest_missing | There is no manifest. Put one at .brydio/app.json. | yes | publish, as bundle_manifest_missing | Add .brydio/app.json. |
manifest_not_json | app.json is not valid JSON. (validate adds where the parser stopped.) | yes | publish, as manifest_invalid | Fix the JSON. |
manifest_invalid | The schema's sentence for the field at <path>. For example, the name must be lowercase letters, digits and dashes; the version must look like 1.2.0; "Custom tools are not available yet." | yes | publish | Change the field the path names. |
placement_key_taken | Two placements use the key "<key>"; each independently addable placement needs its own key. | yes | publish | Give each placement a distinct key, or omit it when that placement kind opens only one screen. |
placement_screen_unknown | A <kind> placement opens "<screen>", which is not one of the app's screens. | yes | publish | Declare the screen under screens, or point the placement at one that is declared. |
placement_home_sizes | The Home card "<screen>" must say which sizes it draws at: small, medium or large. | yes | publish | Give the home placement sizes, such as ["medium"]. |
placement_widget_sizes | The project widget "<screen>" must say which sizes it draws at: small, medium or large. | yes | publish | Give the project-widget placement sizes, such as ["medium", "large"]. |
placement_sizes_not_home | Only a Home card or a project widget has sizes; the <kind> placement "<screen>" cannot. | yes | publish | Take sizes off the sidebar placement. |
placement_tab_retired | Project tabs are retired; declare a project-widget with sizes instead. | yes | publish | Change "kind": "project-tab" to "project-widget" and add sizes. A published version with a tab keeps working, drawn as a large widget. |
placement_chat_card_shape | The chat card "<screen>" cannot have sizes, children or settings. | yes | publish | Take sizes, children and settings off the chat-card placement: it is drawn at the message's own size. |
placement_person_profile_shape | The profile panel "<screen>" cannot have sizes, children or settings. | yes | publish | Take sizes, children and settings off the person-profile placement: it is drawn on every profile, at the profile's width. |
grant_tool_cross_app_self | <slug>__<tool> names this app's own tool: ask for <tool> instead. | yes | publish | Another app's tool is <its slug>__<tool>; this app's own tools are granted by their plain names. |
placement_public_shape | The public page "<screen>" can have no children or settings: it is one screen at its own address. | yes | publish | Take children and settings off the public-page placement (and sizes, which is placement_sizes_not_home). |
placement_public_nothing | A public page needs something a visitor may use: mark a collection publicRead or publicSubmit, or a custom tool public. | yes | publish | Give a collection publicRead or publicSubmit, or a custom tool public: true, so the page has something to read or send. |
placement_children_too_deep | The "<screen>" folder nests <n> levels deep; a sidebar folder may nest at most 4. | yes | publish | Declare at most three levels under children.nested. |
placement_create_tool_unknown | The "<screen>" folder creates with <tool>, which is not one of the app's tools. | yes | publish | Name a generated create_… tool or one of tools.custom in children.create.tool. |
placement_create_not_write | The "<screen>" folder creates with <tool>, which only reads: name a tool that makes records, or mark a custom one write: true. | yes | publish | Point create.tool at a tool that makes records, or give the custom tool write: true. |
data_too_many_collections | An app may keep at most <n> collections. | yes | publish | Keep fewer collections. |
data_collection_name_format | <collection> is not a collection name: lower-case letters, digits and _, starting with a letter, at most 40 characters. | yes | publish | Rename the collection. |
data_label_format | <collection>'s label must be one lower-case word the tools can be named with, at most 40 characters. | yes | publish | Give label one lower-case word. |
data_label_taken | <collection> and <other> would both make tools called <label>. | yes | publish | Give one of them a different label. |
data_too_many_fields | A collection may have at most <n> fields. | yes | publish | Split the collection or drop fields. |
data_field_reserved | <collection>.<field>: Brydio keeps <field> on every record itself. | yes | publish | Rename the field; Brydio already keeps it. |
data_field_name_format | <collection>.<field> is not a field name: letters, digits and _, starting with a lower-case letter, at most 40 characters. | yes | publish | Rename the field. |
data_project_field_twice | <collection> links to a project twice (<a> and <b>); keep one. | yes | publish | Keep one project field. |
data_field_type_unknown | <collection>.<field>: "<type>" is not a field type. | yes | publish | Use one of the field types in the README. |
data_enum_empty | <collection>.<field>: A choice needs at least one allowed value. | yes | publish | List at least one value. |
data_enum_too_many | <collection>.<field>: A choice may have at most <n> values. | yes | publish | Allow fewer values. |
data_enum_value_invalid | <collection>.<field>: Each allowed value is a word or two of text, at most <n> characters. | yes | publish | Shorten or fix the value. |
data_enum_duplicate | <collection>.<field>: A choice names the same value twice. | yes | publish | Take out the duplicate. |
data_default_not_allowed | <collection>.<field>: Only a choice or a boolean may have a default, not a <type>. | yes | publish | Take the default out, or make the field a choice or a boolean. |
data_default_on_required | <collection>.<field>: A field with a default is one a create may leave out: add "optional": true (or write "boolean?"). | yes | publish | Make the field optional, or take the default out. |
data_default_invalid | <collection>.<field>: The default must be one of the choice's values (or true or false for a boolean). | yes | publish | Use one of the allowed values. |
data_labels_not_allowed | <collection>.<field>: Only a choice may label its values, not a <type>. | yes | publish | Take labels out, or make the field a choice. |
data_label_invalid | <collection>.<field>: The label for "<value>" is 1 to <n> characters of text. | yes | publish | Give each label 1 to <n> characters. |
data_label_unknown_value | <collection>.<field>: "<value>" is not one of the choice's values, so it can't have a label. | yes | publish | Label only values the choice allows. |
data_field_key_unknown | <collection>.<field>: "<key>" is not something a field may say; use type, optional, default, labels and coedit. | yes | publish | Keep to type, optional, default, labels and coedit. |
data_coedit_not_text | <collection>.<field>: Only a text or canvas field may be co-edited, not a <type>. | yes | publish | Take coedit out, or make the field text. |
custom_name_taken | tools.custom: <name> is already a tool this app has: give the custom tool another name, or switch generated tools off. | yes | publish | Rename the custom tool. |
custom_collection_unknown | tools.custom: <name> works on <collection>, which the app does not keep. | yes | publish | Name a collection in data, or leave collection out. |
custom_input_invalid | tools.custom: <name>'s input <field>: not a field type. | yes | publish | Write the input in the field-type grammar. |
secret_name_taken | secrets: The secret <name> is declared twice; keep one. | yes | publish | Declare each secret once. |
instances_needs_sidebar | instances: An app kept once per workspace is added from the workspace sidebar: add a "workspace-sidebar" placement. | yes | publish | Add a workspace-sidebar placement, or leave out instances. |
data_search_unknown_field | <collection> searches <field>, which is not one of its fields. | yes | publish | Search only declared fields. |
data_search_not_text | <collection>.<field> cannot be searched: only text fields can. | yes | publish | Search only text fields. |
data_open_fields_unknown | <collection>.openSchema.fields names <companion>, which must be another collection of this app. Also when the companion is open itself, or already defines another collection's fields. | yes | publish | Name a collection of its own that holds the field definitions. |
data_open_fields_shape | <companion>.<field> is read by Brydio as <kind>; declare it so. Also <companion> defines <collection>'s fields, so it needs <field>: "<kind>". when key, name or type is missing, and <companion>.type offers "<value>", which is not an open field type; use some of <types>. | yes | publish | Declare key: "string?", name: "string", type as a choice of open types, and the optional fields with the kinds Brydio reads. |
data_open_table_unknown | <collection>.openSchema.table is <field>, so <name> needs <field>: "string", naming each record's table. | yes | publish | Declare the table field as a required string on both collections, or leave table out. |
data_confirm_submit | <collection> sends a confirmation email but visitors can't submit to it: mark it publicSubmit. | yes | publish | Mark the collection publicSubmit, or take confirmEmail out. |
data_confirm_field | <collection>.confirmEmail.field must name one of its string fields; <field> is not. | yes | publish | Point field at a string field holding the visitor's address. |
data_anonymous_group | <collection>.anonymous.group must name one of its structured fields (a number, choice, date, boolean, token or project); <field> is not. | yes | publish | Group by a number, a choice or a date: words are never kept in plain, and a member names a person. |
data_anonymous_member | <collection> is anonymous, so it can't name a member: <field> would. | yes | publish | Take the member field out, or keep it in another collection. |
data_anonymous_coedit | <collection> is anonymous, so its answers can't be written together: <field> would be. | yes | publish | Drop coedit: true or the canvas field. |
data_anonymous_minimum | <collection>.anonymous.minimum is at least 5: fewer answers than that can be told apart. | yes | publish | Leave minimum out (5) or raise it. |
data_readers_field | "<collection>" names "<field>" as its readers, which must be one of its own string[] fields holding user ids. | yes | publish | Add a string[] field for the ids ("readers": "string[]") and name it. |
data_readers_anonymous | "<collection>" can't be anonymous and name its readers. | yes | publish | Keep anonymous answers and named readers in different collections. |
data_editors_field | "<collection>" names "<field>" as its editors, which must be one of its own string[] fields holding user ids. | yes | publish | Add a string[] field for the ids ("editors": "string[]") and name it. |
data_editors_anonymous | "<collection>" can't be anonymous and name its editors. | yes | publish | Keep anonymous answers and named editors in different collections. |
data_confirm_text | <collection>.confirmEmail.<subject or message> is plain text: no links, addresses or markup. | yes | publish | Say it in plain words; link: true adds the one link back to the page. |
manifest_sdk_overwritten (warning, from brydio build) | The manifest says "sdk": <value>, which brydio build writes itself. The build says <version>; take the line out of the manifest. | build | no | Delete sdk from the manifest. |
1a. The app has a logo and an icon, and gives the assistant something to call
Two rules the owner set for every app (22 September 2026). Both are read from .brydio/app.json and the files beside it, and both are refused by the publish route in the same words, with no app.json: in front.
A logo and an icon, in colour and in one colour (ADR-A20). The manifest names four image files, ./-prefixed paths inside the app:
"logo": { "color": "./brand/logo.svg", "mono": "./brand/logo-mono.svg" },
"icon": { "color": "./brand/icon.svg", "mono": "./brand/icon-mono.svg" }
brydio build copies them into the bundle beside the code; they are the only files that aren't scripts a bundle may hold, and Brydio keeps them with the version rather than as code. The coloured icon is drawn on tiles, the coloured logo on the app's own page, and the one-colour icon in the sidebar, tinted by the theme. The rules:
- Each file is a PNG, JPEG, WebP or SVG of at most 512 KB, with no script, event handler or outside link in an SVG.
- The icon is square: 48 to 1024 pixels across, or a square view box.
- The logo is 48 to 1024 pixels tall, at most 2048 wide, and from as wide as it is tall to four times as wide. An SVG's view box is held to the same proportions.
- A one-colour image is a PNG with transparency whose visible pixels are all one colour (anti-aliased edges of that colour are fine), or an SVG that paints with one colour or
currentColor. An SVG's colours are read fromfill,stroke,stop-color,flood-colorandcolor, in attributes and instyle; a shape with no fill paints in black unless the<svg>or a<g>sets one; an embedded<image>can't be read, so it is refused. A JPEG has no transparency and a WebP isn't decoded, so neither can be the one-colour image.
An app from before these rules has "icon": "./icon.png". Brydio still reads that, and still draws the one image wherever the app appears, but it is not enough to publish a new version.
Something for the assistant to call (ADR-A19): a collection with generated tools (on unless tools.generated is false), a custom tool in tools.custom, an MCP server in servers.json or requires.servers, or an integration in integrations/ or requires.integrations.
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
brand_logo_missing | An app needs a logo: set "logo" to { "color": "./…", "mono": "./…" }, one image in colour and one in a single colour. | yes | publish | Add logo with both images. |
brand_icon_missing | An app needs an icon: set "icon" to { "color": "./…", "mono": "./…" }, one square image in colour and one in a single colour. (For one path: An icon is now two images: set "icon" to { "color": "./…", "mono": "./…" } instead of one path.) | yes | publish | Add icon with both images. |
brand_path_invalid | <field> must be a path inside the package that starts with ./ and ends in .png, .jpg, .webp or .svg. | yes | publish | Write the path as ./brand/icon.svg. |
brand_file_missing | <field> names <path>, which is not in the package. | yes | publish | Add the file, or fix the path. |
brand_file_too_large | <field> is <n> KB. A logo or icon file is at most 512 KB. | yes | publish | Make the image smaller, or use an SVG. |
brand_file_unreadable | <field> is not a PNG, JPEG, WebP or SVG that Brydio can read. (Or: <field> carries a script, an event handler or a link to somewhere else, which a logo or icon cannot.) | yes | publish | Export the image again as a plain PNG or SVG. |
brand_icon_shape | <field> is <width>×<height>. An icon is square, from 48 to 1024 pixels across. | yes | publish | Make the icon square and of that size. |
brand_logo_shape | <field> is <width>×<height>. A logo is 48 to 1024 pixels tall, at most 2048 wide, and from as wide as it is tall to four times as wide. | yes | publish | Crop or resize the logo. |
brand_mono_type | <field> is a <JPEG or WebP>. A one-colour image is a PNG with transparency, or an SVG. | yes | publish | Save the one-colour image as a PNG or an SVG. |
brand_mono_colours | <field> paints in <n> colours (<colours>). A one-colour image paints in one colour, or in currentColor, on transparency. (Or: <field> has pixels of more than one colour; has no transparent pixels, so it would draw as a solid block; or embeds an image, so it can't be read as one colour.) | yes | publish | Paint the whole mark in one colour, or currentColor, on a transparent ground. |
app_has_no_tools | This app gives the assistant nothing to call. Keep a collection with generated tools, add a custom tool, or bundle an MCP server or an integration. | yes | publish | Keep a collection with generated tools, add a custom tool, or bundle a server or an integration. |
2. Screens use only catalogue elements and the settings each one takes
Checked by reading each screen's source with TypeScript's parser, against @brydio/ui's catalogue, which is a copy of Brydio's own. Only what the source writes out is checked: a value or an element name worked out while the screen runs isn't guessed at. Brydio refuses anything that gets past this check, node by node, while drawing (tree/refused), using the same sentences. The publish route can't check compiled code for this.
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
element_unknown | Brydio has no element called "<name>". A screen draws with <the catalogue>. | yes | runtime | Use a catalogue element. |
prop_unknown | <element> has no setting called "<name>". | yes | runtime | Remove the setting, or use one the element takes (see the README's table). |
prop_value_invalid | <element> <setting> must be one of <values>. (Or: must be text of at most <n> characters; must be true or false; must be a whole number from <min> to <max>; a list or a record names the path, as in bry-table columns[0].align must be one of start, end.) | yes | runtime | Use an allowed value. |
prop_required | <element> needs a <setting>. | yes | runtime | Add the setting. |
event_unknown | <element> raises <events>, not "<event>". Or: <element> raises no events, so it takes no <onEvent>. | yes | runtime | Remove the handler. |
children_not_allowed | <element> can’t hold other nodes. | yes | runtime | Give the element its words as a setting (text="…", label="…"). |
source_syntax | This does not parse: <TypeScript's words> | yes | no | Fix the syntax. |
screen_source_missing (from brydio build) | The "<screen>" screen is built from src/<entry>.tsx (or .ts, .jsx, .js), and there is no such file. | build | no | Add the source file, or fix the entry. |
screen_build_failed (from brydio build) | The "<screen>" screen did not build: <the bundler's words> | build | no | Fix what the bundler names. |
handler_source_missing (from brydio build) | The "<tool>" tool is built from src/<handler>.ts (or .js), and there is no such file. | build | no | Add the source file, or fix the handler's path. |
handler_build_failed (from brydio build) | The "<tool>" tool did not build: <the bundler's words> | build | no | Fix what the bundler names. |
3. A style keeps to the safe list, and no element carries a class or raw HTML
Every element takes style (PB22): sizes, spacing, colours, borders, rounding, shadow, type size and weight, opacity, flex and grid layout, and position inside the app's own area. Brydio refuses anything else at the node, with the rule that refuses it. The same rules run in brydio validate, in the registry's checks of the screenshots, and in Brydio when it draws. See the design guide for what fits.
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
style_forbidden | The element's own refusal, naming the property and the rule. For a style: <element> style position can’t be fixed or sticky: an app draws only inside its own area, …; <element> style zIndex can be at most 10: …; <element> style backgroundImage can only be one of the app’s own uploaded files: …; url() and outside images aren’t allowed; <element> style fontFamily isn’t allowed: every app uses Brydio’s own font, …; <element> style animation isn’t allowed: animations that never stop aren’t allowed, …; <element> style background is a plain colour with no dark-mode value; give both: …; <element> style <property> isn’t allowed: it is not on the list of properties a style may set. For class and className: There are no classes in a Brydio app; choose a setting the element offers. For color and colour as settings: A colour is set in style ({ "color": "brydio.text" }) or through a setting like tone, never as a setting of its own. For dangerouslySetInnerHTML and innerHTML: A Brydio app has no HTML to set. | yes | runtime, as the element's refusal | Keep to the safe list; give a plain colour both values, { "light": "#…", "dark": "#…" }, or name it in the theme. |
The manifest's theme (PB21) is read with the manifest:
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
theme_invalid | The theme is a record: accent, colors, rounding, density. (Or: The theme has no setting called "<key>".) | yes | publish | Use only accent, colors, rounding and density. |
theme_font | There is no font setting: every app uses Brydio’s own font. | yes | publish | Take the font out. |
theme_colour_pair | <The accent or The colour "<name>"> needs both a light and a dark value: { "light": "#…", "dark": "#…" }. | yes | publish | Give the colour its dark value too. |
theme_colour_format | <…>'s <light or dark> value is a colour like #0e7490. | yes | publish | Write the colour as #rgb or #rrggbb. |
theme_colour_name | "<name>" is not a colour name: lower-case letters, digits and dashes, starting with a letter, at most 32. | yes | publish | Rename the colour. |
theme_colours_too_many | A theme holds at most 24 named colours. | yes | publish | Keep fewer colours. |
theme_density | The density is one of compact, normal, roomy. | yes | publish | Choose one of the three. |
theme_rounding | The rounding is one of none, small, normal, large, round. | yes | publish | Choose one of the five. |
theme_contrast_low | Warning. Text on <the accent or "<name>"> in <mode> mode reads at <ratio>:1, below the 4.5:1 WCAG AA asks for. | yes | publish, as a warning | Choose a darker or lighter value for that mode. |
A screen also runs in a worker with no page, no network, no storage and no other workers, and it may import only @brydio/*, Preact and its own files:
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
dom_global | <name>: A screen has no page: it runs in a worker and draws only with the catalogue. | yes | runtime (the worker has none) | Draw with elements. |
network_global | <name>: A screen has no network; call the app’s tools instead. | yes | runtime | Call the app's tools. |
storage_global | <name>: A screen has no storage; keep records in the app’s collections. | yes | runtime | Keep records in a collection. |
worker_global | <name>: A screen is one module in one worker; there is nothing else to start or load. | yes | runtime | Build everything into the screen. |
eval_forbidden | eval is refused in a Brydio app’s worker; write the code out. | yes | runtime | Write the code out. |
import_not_allowed | import "<specifier>": a screen imports only its own files, @brydio packages and Preact. Anything else it needs belongs in the SDK. | yes | no | Import only @brydio/*, preact, preact/hooks, preact/jsx-runtime and your own files. |
4. Every collection has a schema, and a version that changes one declares its migration
Every collection must have a schema; the manifest checks in section 1 refuse one without. A version whose collections differ from the version published before it must list migrations steps for its own version number (add, rename, drop, dropCollection, replace), in Brydio's A3-F07 shape.
validate compares against the previous version when it can see it:
--previous <app.json or folder>, pointing at the manifest of the version published before this one, or- a
dist/app.jsonbuilt from a lower version, when no--previousis given.
When neither is there, only the publish route runs this check. It compares against the highest version already published below this one.
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
migration_missing | <why> (<version> against <previous>, the version before it.) <why> is one of the sentences in the next table. validate lists every one; the route stops at the first. | with a previous version: --previous <app.json>, an older dist/, or, in brydio publish, the highest version below this one on the registry (GET /v1/apps/:key/versions/:version), checked before uploading | publish | Add the step to migrations under this version's number. brydio version writes a first draft of it. |
previous_unreadable | There is no manifest at <path> to compare this version with. Or: <path> is not valid JSON, so this version can't be compared with it. | yes | no | Point --previous at the published version's app.json. |
previous_not_older | <path> is version <v>, not one before <version>, so it can't say what this version changes. | yes | no | Point --previous at an earlier version. |
The reasons behind migration_missing, from @brydio/manifest's copy of Brydio's migrations.ts:
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
migration_unexplained | <collection>.<field> is new; add it with a step (and a default, when the field is required). Or: <collection>.<field> is gone; drop it or rename it with a step. Or: <collection> is no longer declared; say dropCollection to remove its records. | with a previous version | publish | { "op": "add" }, "rename", "drop" or "dropCollection". |
migration_type_changed | <collection>.<field> changed type; drop ` <field> and add it again under a new name. Or: <collection>.<field>` became required, and records without it would not be readable; add a new field with a default instead. | with a previous version | publish | Drop the field and add a new one. |
migration_anonymous_changed | <collection> already keeps records with their writers, so it can't become anonymous; keep anonymous answers in a new collection. Also <collection> keeps anonymous answers, so it stays anonymous. and <collection>'s anonymous answers stay grouped by <field>. | with a previous version | publish | Declare a new collection for anonymous answers; keep an anonymous one as it is. |
migration_value_removed | <collection>.<field> no longer allows "<value>"; say which value replaces each. | with a previous version | publish | { "op": "replace", "from": …, "to": … }. |
migration_default_missing | add <collection>.<field>: a required field needs a default for the records already kept. | with a previous version | publish | Give the add step a default. |
migration_default_invalid | add <collection>.<field>: the default is not valid; <why> | with a previous version | publish | Fix the default. |
migration_step_invalid | <op> <collection>.<field>: there is no such field (or collection, or value). | with a previous version | publish | Fix the step so it names what the previous version had. |
migration_step_pointless | <op> <collection>.<field>: the new version still declares it (or does not declare it). | with a previous version | publish | Remove the step. |
5. Every tool the manifest exposes is generated or has a handler
An app's tools are the ones Brydio generates for its collections (create_, update_, get_, list_, search_, delete_). tools.custom must be empty until handler scripts arrive (Phase 3), so a declared tool with no handler is manifest_invalid ("Custom tools are not available yet."). Screens may call only tools that exist:
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
tool_unknown | "<tool>" is not one of this app's tools. Its tools are <list>. | yes | runtime | Call a generated tool, or declare the collection that generates it. |
collection_unknown | "<collection>" is not one of this app's collections. It keeps <list>. | yes | runtime | Read a declared collection. |
6. The bundle is under the cap, and holds only scripts and the manifest
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
bundle_not_built | There is no dist/ yet. Run brydio build first. | yes | no | Run brydio build. |
screen_not_built | The "<screen>" screen names "<entry>", which is not a script in this bundle. Run brydio build. | yes | publish | Run brydio build, or fix the entry. |
handler_not_built | The "<tool>" tool runs "<handler>", which is not a script in this bundle. Run brydio build. | yes | publish (handler_missing) | Run brydio build, or fix the handler's path. |
bundle_stale (warning) | The built manifest is not the manifest as it is now. Run brydio build again. | yes | no | Run brydio build. |
bundle_too_large | That bundle is <size>, over the 1.00 MB cap. The largest file is "<file>" at <size>. | yes | publish | Make the screens smaller; start with the largest file. |
bundle_file_not_code | "<file>" is not a script. A bundle holds only .js files and app.json (and the logo and icon files the manifest names). (From brydio build: The "<screen>" screen brings in "<file>", which a bundle cannot hold. A Brydio app has no CSS, HTML or images: Brydio draws every element itself.) | yes | publish | Remove the import of CSS, HTML or images. |
runtime_too_large | The "<screen>" screen carries <n> KB of Brydio's runtime, over the 30 KB a screen may carry. Something in @brydio is being bundled that this screen does not use. | no: brydio build (minified) refuses it, and validate reads a build | no | Import what the screen uses from @brydio/app, not a schema or checking library; say so on the channel if the SDK itself leaks. |
bundle_path_invalid | "<path>" is not a path a bundle can hold. | yes | publish | Use plain ASCII names with no hidden segments. |
bundle_manifest_missing | That bundle has no app.json at its root. | yes | publish | Run brydio build. |
bundle_empty | That bundle has no screens in it, only a manifest. | yes | publish | Declare and build a screen. |
A bundle with a frame screen (PB27) may also hold that screen's page (its entry, .html), stylesheets, images and media (.css, .png, .jpg, .gif, .webp, .avif, .svg, .mp4, .webm, .mp3, .ogg, .wav), up to 4 MB of them, counted apart from the 1 MB of code. No fonts: every app uses Brydio's own. brydio build copies the page from src/<entry> and anything under src/assets/ to assets/, and builds src/<entry name>.ts(x) beside the page when there is one; brydio pack shows both totals.
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
screen_kind_entry | A frame screen’s entry is an .html page inside the bundle. (Or: An .html entry is a frame screen: give the screen "kind": "frame".) | yes | publish | Give a frame screen "kind": "frame" and an .html entry; give a tree screen a .js one. |
bundle_file_not_code (frame screens) | "<file>" is not a script, a frame screen's page, a stylesheet, an image or media. A bundle holds only those and app.json. | yes | publish | Take the file out (a font, for instance), or rename an extra page. |
bundle_too_large (frame screens) | The frame screens' pages, styles, images and media are <size>, over the 4.00 MB cap. The largest is "<file>" at <size>. | yes | publish | Make the pictures or media smaller. |
frame_password_field (warning) | The "<screen>" frame screen has a password field (<file>). An app never asks for a Brydio password or sign-in; a reviewer will ask why it is there. | yes | publish, as a warning | Take it out; outside services are reached through the app's connections. |
frame_font (warning) | <file> declares a font of its own. A frame screen loads no fonts; every app uses Brydio's own, so this one is never shown. | yes | publish, as a warning | Take the @font-face out. |
archive_unreadable, archive_too_large, archive_uncompressed_too_large, archive_too_many_entries, archive_member_path_absolute, archive_member_path_has_parent_segment, archive_member_path_has_backslash, archive_member_path_invalid, archive_member_type_unsupported, skill_directory_hidden | The archive reader's sentence, at bundle scale ("That upload is larger than 2 MB. A bundle is at most 1 MB of code."). | no: brydio publish writes the zip itself | publish | Publish with brydio publish rather than a zip made by hand. |
7. No secret-looking string in the bundle
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
secret_in_bundle | That package contains a secret. Header values and client secrets are entered here, never shipped in a file — remove it and import again. | yes | publish | Remove the value, and treat it as leaked. |
developer_key_in_bundle | That package contains a Brydio developer API key. A key belongs on your own server, never in an app: revoke it in Settings › Developer, and call Brydio’s model from a handler with the model grant instead. | yes | publish | Revoke the key in Settings › Developer, remove it, and use the handler's model grant. |
This is Brydio's existing scan (extensions/apps/secret-scan.ts), copied exactly. It looks at the value keys (value, secret, token, apiKey, …) anywhere in the bundle's app.json, and in servers.json and integrations/*.json, and skips placeholders like ${user_config.key} or <your key>. app.json is served to every screen that opens the app, so it holds nothing private. Scripts aren't scanned, on purpose: a pattern scan of minified code misses real keys and refuses innocent strings.
A Brydio developer API key (bry_live_, 12 hex characters, _, 43 base64url characters) is the one exception. Its shape is exact, so every file is read for it: the manifest, every source under src/, and every built file, scripts included. No part of an app is given a Brydio credential (ADR-A24), so a key inside one is always a leak. validate also refuses importing @brydio/api/ai, the key's client, from a screen or handler (import_not_allowed). docs/ai.md has the whole of it.
8. The grants list everything the screens call, and nothing they don't
A tool counts as granted when its name, *, or its collection's name is in grants.tools, as long as its collection is also granted. That is how Brydio reads grants (apps/api/src/apps/manifest/grants.ts). validate checks the calls a screen writes out: tools.call('…'), tools.result('…'), data.get('…'), data.list('…'), useList('…'), the bridge's callTool, getDocument and listDocuments, and navigate(…). Asking for too little is an error. Asking for too much is a warning: a tool grant may be meant for the assistant rather than a screen.
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
grant_collection_missing | app.json: "grants.collections": <collection> is kept but not asked for: add it to grants.collections. | yes | publish | Add the collection, or *, to grants.collections. |
grant_tool_missing | "<tool>" is called here but not asked for: add it, or its collection <collection>, to grants.tools. | yes | runtime | Add the tool or its collection to grants.tools. |
grant_host_missing | navigate is called here but not asked for: add "navigate" to grants.host. | yes | runtime | Add navigate to grants.host. |
grant_unknown | app.json asks for "<grant>", which Brydio does not grant. An app may ask for navigate, message, members, projects, files, chats, model, secrets or connection:<name>. | yes | publish | Ask only for navigate, message, members, projects, files, chats, model, secrets or connection:<name>. |
grant_secrets_missing | grants.host: The app declares secrets but does not ask to read them: add "secrets" to grants.host. | yes | publish | Add secrets to grants.host. |
grant_tool_unknown (warning) | grants.tools asks for "<name>", which is neither one of this app's tools nor one of its collections. | yes | no | Remove the name, or fix its spelling. |
grant_collection_unknown (warning) | grants.collections asks for "<name>", which this app does not keep. | yes | no | Remove the name. |
grant_host_unused (warning) | grants.host asks for "<grant>", which no screen uses. Ask only for what the app does. | yes | no | Remove the grant, or use it. |
Only at publish
The publish route runs these; the command line can't, or checks them in its own step.
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
sdk_below_minimum | This app was built with SDK <v>, below <minimum>, the oldest SDK the registry takes a new version from. Run brydio upgrade-sdk, then publish again. | no: brydio publish checks it before uploading, against the registry's GET /v1/sdk | publish (422) | Run brydio upgrade-sdk. A higher minimum announced for later is a warning until its date. |
screenshot_failed | <screen>, <narrow or wide>, <light or dark>: the screen stopped, had a node refused, threw, or drew nothing, when pictured in the fake host with .brydio/samples.json. (Or: pictures need @brydio/fake-host in the app's devDependencies.) | no: brydio publish pictures every screen before uploading | publish, as screenshot_invalid for a picture the server refuses | Fix the screen so it draws with the sample records, or fix .brydio/samples.json. |
version_exists | The registry's sentence: <app> <version> is already published with a different bundle. A version is never replaced. | no | publish (409) | Raise the version number with brydio version patch. Exactly the same bundle again is not an error. |
version_lower | <app> <version> is lower than <highest>, the highest version on <registry>. Give this build a higher number with brydio version patch, and publish again. | no: brydio publish checks it before building, against GET /v1/apps/:key | publish (409) | Raise the version number above the highest published. |
retired | <app> is retired on <registry>, so no new version of it can be published. | no: brydio publish checks it before building | publish (423) | A retired app takes no new versions, ever. Publish under a new name. |
not_publisher | The registry's sentence: <app> is published by another publisher. | no | publish (403) | Ask an owner of that publisher to add you, or publish under your own name. |
manifest_unreadable | app.json is not valid JSON. (Or: app.json is not a JSON object.) | no: manifest_not_json covers it | publish | Fix the JSON. |
The version number
The manifest is the one place an app's version lives. brydio version patch|minor|major|<x.y.z> writes it there, and nowhere else.
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
version_mismatch (from brydio build) | package.json says version <v> and the manifest says <w>. An app's version lives in the manifest alone. | build | no | Take "version" out of package.json, and change the number with brydio version. |
version_in_package_json (from brydio version) | package.json says "version": <v>. An app's version lives in .brydio/app.json alone: take the line out of package.json, then run brydio version again. | no: brydio version | no | Take "version" out of package.json. |
version_not_higher (from brydio version) | <v> is not higher than <current>, the manifest's version now. A version number only goes up. | no: brydio version | no | Give a higher number, or say patch, minor or major. |
Publishing from GitHub Actions
In a GitHub Actions job with no login on the runner, brydio publish signs in with GitHub's OIDC token instead (PB05): it asks GitHub for a token with the audience brydio-registry and trades it at the registry's POST /v1/oidc/exchange for a fifteen-minute token that publishes one app. The publisher links the workflow once with brydio trust <app> --repo <owner>/<name> --workflow <file>. The version records the repository, workflow and commit.
| Code | Refused with | validate | server | How to fix |
|---|---|---|---|---|
tag_version_mismatch (from brydio publish) | This run is for the tag <tag>, but the manifest says version <v>. Tag the commit v<v>, or raise the version with brydio version and tag that. | no: brydio publish in GitHub Actions | no | Tag the commit v<version>. |
oidc_unavailable (from brydio publish) | This GitHub Actions job can’t ask GitHub for an OIDC token. Give the publish job permissions: id-token: write (and contents: read), then run it again. (Or: GitHub did not give this job an OIDC token: <why>.) | no: brydio publish in GitHub Actions | no | Add permissions: id-token: write to the publish job. |
not_trusted, trust_mismatch, oidc_invalid | The registry's sentence, after: <registry> does not trust this workflow to publish <app>. A publisher's owner links it once, from their own computer: brydio trust <app> --repo <owner>/<name> --workflow <file> | no | publish (403, 401) | Run the brydio trust line it prints. |