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:

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.

CodeRefused withvalidateserverHow to fix
manifest_missingThere is no manifest. Put one at .brydio/app.json.yespublish, as bundle_manifest_missingAdd .brydio/app.json.
manifest_not_jsonapp.json is not valid JSON. (validate adds where the parser stopped.)yespublish, as manifest_invalidFix the JSON.
manifest_invalidThe 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."yespublishChange the field the path names.
placement_key_takenTwo placements use the key "<key>"; each independently addable placement needs its own key.yespublishGive each placement a distinct key, or omit it when that placement kind opens only one screen.
placement_screen_unknownA <kind> placement opens "<screen>", which is not one of the app's screens.yespublishDeclare the screen under screens, or point the placement at one that is declared.
placement_home_sizesThe Home card "<screen>" must say which sizes it draws at: small, medium or large.yespublishGive the home placement sizes, such as ["medium"].
placement_widget_sizesThe project widget "<screen>" must say which sizes it draws at: small, medium or large.yespublishGive the project-widget placement sizes, such as ["medium", "large"].
placement_sizes_not_homeOnly a Home card or a project widget has sizes; the <kind> placement "<screen>" cannot.yespublishTake sizes off the sidebar placement.
placement_tab_retiredProject tabs are retired; declare a project-widget with sizes instead.yespublishChange "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_shapeThe chat card "<screen>" cannot have sizes, children or settings.yespublishTake sizes, children and settings off the chat-card placement: it is drawn at the message's own size.
placement_person_profile_shapeThe profile panel "<screen>" cannot have sizes, children or settings.yespublishTake 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.yespublishAnother app's tool is <its slug>__<tool>; this app's own tools are granted by their plain names.
placement_public_shapeThe public page "<screen>" can have no children or settings: it is one screen at its own address.yespublishTake children and settings off the public-page placement (and sizes, which is placement_sizes_not_home).
placement_public_nothingA public page needs something a visitor may use: mark a collection publicRead or publicSubmit, or a custom tool public.yespublishGive a collection publicRead or publicSubmit, or a custom tool public: true, so the page has something to read or send.
placement_children_too_deepThe "<screen>" folder nests <n> levels deep; a sidebar folder may nest at most 4.yespublishDeclare at most three levels under children.nested.
placement_create_tool_unknownThe "<screen>" folder creates with <tool>, which is not one of the app's tools.yespublishName a generated create_… tool or one of tools.custom in children.create.tool.
placement_create_not_writeThe "<screen>" folder creates with <tool>, which only reads: name a tool that makes records, or mark a custom one write: true.yespublishPoint create.tool at a tool that makes records, or give the custom tool write: true.
data_too_many_collectionsAn app may keep at most <n> collections.yespublishKeep 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.yespublishRename the collection.
data_label_format<collection>'s label must be one lower-case word the tools can be named with, at most 40 characters.yespublishGive label one lower-case word.
data_label_taken<collection> and <other> would both make tools called <label>.yespublishGive one of them a different label.
data_too_many_fieldsA collection may have at most <n> fields.yespublishSplit the collection or drop fields.
data_field_reserved<collection>.<field>: Brydio keeps <field> on every record itself.yespublishRename 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.yespublishRename the field.
data_project_field_twice<collection> links to a project twice (<a> and <b>); keep one.yespublishKeep one project field.
data_field_type_unknown<collection>.<field>: "<type>" is not a field type.yespublishUse one of the field types in the README.
data_enum_empty<collection>.<field>: A choice needs at least one allowed value.yespublishList at least one value.
data_enum_too_many<collection>.<field>: A choice may have at most <n> values.yespublishAllow fewer values.
data_enum_value_invalid<collection>.<field>: Each allowed value is a word or two of text, at most <n> characters.yespublishShorten or fix the value.
data_enum_duplicate<collection>.<field>: A choice names the same value twice.yespublishTake out the duplicate.
data_default_not_allowed<collection>.<field>: Only a choice or a boolean may have a default, not a <type>.yespublishTake 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?").yespublishMake 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).yespublishUse one of the allowed values.
data_labels_not_allowed<collection>.<field>: Only a choice may label its values, not a <type>.yespublishTake labels out, or make the field a choice.
data_label_invalid<collection>.<field>: The label for "<value>" is 1 to <n> characters of text.yespublishGive 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.yespublishLabel 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.yespublishKeep 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>.yespublishTake coedit out, or make the field text.
custom_name_takentools.custom: <name> is already a tool this app has: give the custom tool another name, or switch generated tools off.yespublishRename the custom tool.
custom_collection_unknowntools.custom: <name> works on <collection>, which the app does not keep.yespublishName a collection in data, or leave collection out.
custom_input_invalidtools.custom: <name>'s input <field>: not a field type.yespublishWrite the input in the field-type grammar.
secret_name_takensecrets: The secret <name> is declared twice; keep one.yespublishDeclare each secret once.
instances_needs_sidebarinstances: An app kept once per workspace is added from the workspace sidebar: add a "workspace-sidebar" placement.yespublishAdd a workspace-sidebar placement, or leave out instances.
data_search_unknown_field<collection> searches <field>, which is not one of its fields.yespublishSearch only declared fields.
data_search_not_text<collection>.<field> cannot be searched: only text fields can.yespublishSearch 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.yespublishName 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>.yespublishDeclare 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.yespublishDeclare 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.yespublishMark the collection publicSubmit, or take confirmEmail out.
data_confirm_field<collection>.confirmEmail.field must name one of its string fields; <field> is not.yespublishPoint 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.yespublishGroup 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.yespublishTake 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.yespublishDrop coedit: true or the canvas field.
data_anonymous_minimum<collection>.anonymous.minimum is at least 5: fewer answers than that can be told apart.yespublishLeave 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.yespublishAdd a string[] field for the ids ("readers": "string[]") and name it.
data_readers_anonymous"<collection>" can't be anonymous and name its readers.yespublishKeep 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.yespublishAdd a string[] field for the ids ("editors": "string[]") and name it.
data_editors_anonymous"<collection>" can't be anonymous and name its editors.yespublishKeep anonymous answers and named editors in different collections.
data_confirm_text<collection>.confirmEmail.<subject or message> is plain text: no links, addresses or markup.yespublishSay 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.buildnoDelete 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:

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.

CodeRefused withvalidateserverHow to fix
brand_logo_missingAn app needs a logo: set "logo" to { "color": "./…", "mono": "./…" }, one image in colour and one in a single colour.yespublishAdd logo with both images.
brand_icon_missingAn 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.)yespublishAdd 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.yespublishWrite the path as ./brand/icon.svg.
brand_file_missing<field> names <path>, which is not in the package.yespublishAdd the file, or fix the path.
brand_file_too_large<field> is <n> KB. A logo or icon file is at most 512 KB.yespublishMake 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.)yespublishExport 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.yespublishMake 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.yespublishCrop 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.yespublishSave 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.)yespublishPaint the whole mark in one colour, or currentColor, on a transparent ground.
app_has_no_toolsThis 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.yespublishKeep 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.

CodeRefused withvalidateserverHow to fix
element_unknownBrydio has no element called "<name>". A screen draws with <the catalogue>.yesruntimeUse a catalogue element.
prop_unknown<element> has no setting called "<name>".yesruntimeRemove 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.)yesruntimeUse an allowed value.
prop_required<element> needs a <setting>.yesruntimeAdd the setting.
event_unknown<element> raises <events>, not "<event>". Or: <element> raises no events, so it takes no <onEvent>.yesruntimeRemove the handler.
children_not_allowed<element> can’t hold other nodes.yesruntimeGive the element its words as a setting (text="…", label="…").
source_syntaxThis does not parse: <TypeScript's words>yesnoFix 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.buildnoAdd the source file, or fix the entry.
screen_build_failed (from brydio build)The "<screen>" screen did not build: <the bundler's words>buildnoFix 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.buildnoAdd 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>buildnoFix 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.

CodeRefused withvalidateserverHow to fix
style_forbiddenThe 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.yesruntime, as the element's refusalKeep 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:

CodeRefused withvalidateserverHow to fix
theme_invalidThe theme is a record: accent, colors, rounding, density. (Or: The theme has no setting called "<key>".)yespublishUse only accent, colors, rounding and density.
theme_fontThere is no font setting: every app uses Brydio’s own font.yespublishTake the font out.
theme_colour_pair<The accent or The colour "<name>"> needs both a light and a dark value: { "light": "#…", "dark": "#…" }.yespublishGive the colour its dark value too.
theme_colour_format<…>'s <light or dark> value is a colour like #0e7490.yespublishWrite 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.yespublishRename the colour.
theme_colours_too_manyA theme holds at most 24 named colours.yespublishKeep fewer colours.
theme_densityThe density is one of compact, normal, roomy.yespublishChoose one of the three.
theme_roundingThe rounding is one of none, small, normal, large, round.yespublishChoose one of the five.
theme_contrast_lowWarning. Text on <the accent or "<name>"> in <mode> mode reads at <ratio>:1, below the 4.5:1 WCAG AA asks for.yespublish, as a warningChoose 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:

CodeRefused withvalidateserverHow to fix
dom_global<name>: A screen has no page: it runs in a worker and draws only with the catalogue.yesruntime (the worker has none)Draw with elements.
network_global<name>: A screen has no network; call the app’s tools instead.yesruntimeCall the app's tools.
storage_global<name>: A screen has no storage; keep records in the app’s collections.yesruntimeKeep records in a collection.
worker_global<name>: A screen is one module in one worker; there is nothing else to start or load.yesruntimeBuild everything into the screen.
eval_forbiddeneval is refused in a Brydio app’s worker; write the code out.yesruntimeWrite the code out.
import_not_allowedimport "<specifier>": a screen imports only its own files, @brydio packages and Preact. Anything else it needs belongs in the SDK.yesnoImport 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:

When neither is there, only the publish route runs this check. It compares against the highest version already published below this one.

CodeRefused withvalidateserverHow 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 uploadingpublishAdd the step to migrations under this version's number. brydio version writes a first draft of it.
previous_unreadableThere 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.yesnoPoint --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.yesnoPoint --previous at an earlier version.

The reasons behind migration_missing, from @brydio/manifest's copy of Brydio's migrations.ts:

CodeRefused withvalidateserverHow 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 versionpublish{ "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 versionpublishDrop 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 versionpublishDeclare 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 versionpublish{ "op": "replace", "from": …, "to": … }.
migration_default_missingadd <collection>.<field>: a required field needs a default for the records already kept.with a previous versionpublishGive the add step a default.
migration_default_invalidadd <collection>.<field>: the default is not valid; <why>with a previous versionpublishFix the default.
migration_step_invalid<op> <collection>.<field>: there is no such field (or collection, or value).with a previous versionpublishFix 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 versionpublishRemove 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:

CodeRefused withvalidateserverHow to fix
tool_unknown"<tool>" is not one of this app's tools. Its tools are <list>.yesruntimeCall a generated tool, or declare the collection that generates it.
collection_unknown"<collection>" is not one of this app's collections. It keeps <list>.yesruntimeRead a declared collection.

6. The bundle is under the cap, and holds only scripts and the manifest

CodeRefused withvalidateserverHow to fix
bundle_not_builtThere is no dist/ yet. Run brydio build first.yesnoRun brydio build.
screen_not_builtThe "<screen>" screen names "<entry>", which is not a script in this bundle. Run brydio build.yespublishRun brydio build, or fix the entry.
handler_not_builtThe "<tool>" tool runs "<handler>", which is not a script in this bundle. Run brydio build.yespublish (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.yesnoRun brydio build.
bundle_too_largeThat bundle is <size>, over the 1.00 MB cap. The largest file is "<file>" at <size>.yespublishMake 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.)yespublishRemove the import of CSS, HTML or images.
runtime_too_largeThe "<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 buildnoImport 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.yespublishUse plain ASCII names with no hidden segments.
bundle_manifest_missingThat bundle has no app.json at its root.yespublishRun brydio build.
bundle_emptyThat bundle has no screens in it, only a manifest.yespublishDeclare 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.

CodeRefused withvalidateserverHow to fix
screen_kind_entryA frame screen’s entry is an .html page inside the bundle. (Or: An .html entry is a frame screen: give the screen "kind": "frame".)yespublishGive 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.yespublishTake 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>.yespublishMake 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.yespublish, as a warningTake 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.yespublish, as a warningTake 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_hiddenThe 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 itselfpublishPublish with brydio publish rather than a zip made by hand.

7. No secret-looking string in the bundle

CodeRefused withvalidateserverHow to fix
secret_in_bundleThat package contains a secret. Header values and client secrets are entered here, never shipped in a file — remove it and import again.yespublishRemove the value, and treat it as leaked.
developer_key_in_bundleThat 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.yespublishRevoke 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.

CodeRefused withvalidateserverHow to fix
grant_collection_missingapp.json: "grants.collections": <collection> is kept but not asked for: add it to grants.collections.yespublishAdd 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.yesruntimeAdd the tool or its collection to grants.tools.
grant_host_missingnavigate is called here but not asked for: add "navigate" to grants.host.yesruntimeAdd navigate to grants.host.
grant_unknownapp.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>.yespublishAsk only for navigate, message, members, projects, files, chats, model, secrets or connection:<name>.
grant_secrets_missinggrants.host: The app declares secrets but does not ask to read them: add "secrets" to grants.host.yespublishAdd 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.yesnoRemove the name, or fix its spelling.
grant_collection_unknown (warning)grants.collections asks for "<name>", which this app does not keep.yesnoRemove the name.
grant_host_unused (warning)grants.host asks for "<grant>", which no screen uses. Ask only for what the app does.yesnoRemove 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.

CodeRefused withvalidateserverHow to fix
sdk_below_minimumThis 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/sdkpublish (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 uploadingpublish, as screenshot_invalid for a picture the server refusesFix the screen so it draws with the sample records, or fix .brydio/samples.json.
version_existsThe registry's sentence: <app> <version> is already published with a different bundle. A version is never replaced.nopublish (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/:keypublish (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 buildingpublish (423)A retired app takes no new versions, ever. Publish under a new name.
not_publisherThe registry's sentence: <app> is published by another publisher.nopublish (403)Ask an owner of that publisher to add you, or publish under your own name.
manifest_unreadableapp.json is not valid JSON. (Or: app.json is not a JSON object.)no: manifest_not_json covers itpublishFix 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.

CodeRefused withvalidateserverHow 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.buildnoTake "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 versionnoTake "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 versionnoGive 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.

CodeRefused withvalidateserverHow 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 ActionsnoTag 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 ActionsnoAdd permissions: id-token: write to the publish job.
not_trusted, trust_mismatch, oidc_invalidThe 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>nopublish (403, 401)Run the brydio trust line it prints.