@overcrow/mcp 0.0.0 → 0.1.0

package/dist/content/docs/en/manifest.md

@@ -0,0 +1,381 @@
+# The manifest
+
+`manifest.json` tells PlayerVox OverCrow what a widget is before any of its
+code runs: its identity and version, its names, the sizes it supports, the
+permissions it asks for and the rows it adds to its options menu. You write
+it by hand; it is packaged exactly as written.
+
+The file is one strict JSON object. A byte-order mark, a duplicate key,
+trailing data or an unknown field rejects it: there is no field that
+OverCrow ignores.
+
+## A complete example
+
+<!-- source: templates/counter/manifest.json -->
+```json
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "{{id}}",
+  "version": "0.1.0",
+  "name": {
+    "en": "{{name}}",
+    "fr": "{{name}}"
+  },
+  "sizing": {
+    "fit": "none",
+    "preferred": { "width": 200, "height": 96 },
+    "min": { "width": 140, "height": 72 },
+    "max": { "width": 640, "height": 640 }
+  }
+}
+```
+
+`overcrow-widget init` writes this file; `{{id}}` and `{{name}}` are the
+values it fills in. A manifest with permissions and a menu:
+
+<!-- source: docs/content/examples/countdown/manifest.json -->
+```json
+{
+  "schemaVersion": 1,
+  "apiVersion": 1,
+  "id": "com.example.countdown",
+  "version": "1.0.0",
+  "name": { "en": "Countdown", "fr": "Compte à rebours" },
+  "sizing": {
+    "fit": "none",
+    "preferred": { "width": 220, "height": 190 },
+    "min": { "width": 180, "height": 160 },
+    "max": { "width": 480, "height": 400 }
+  },
+  "permissions": {
+    "storage": true
+  },
+  "wrapper": {
+    "menu": [
+      {
+        "type": "toggle",
+        "id": "show-rounds",
+        "label": { "en": "Show finished rounds", "fr": "Afficher les tours terminés" },
+        "icon": "circle-check",
+        "default": true
+      },
+      {
+        "type": "action",
+        "id": "reset-rounds",
+        "label": { "en": "Reset the rounds", "fr": "Remettre les tours à zéro" },
+        "icon": "rotate-ccw",
+        "visibleWhen": "show-rounds"
+      }
+    ]
+  }
+}
+```
+
+## Fields
+
+<!-- generated:manifest-fields -->
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `schemaVersion` | integer 1 to 1 | yes | Manifest document version. |
+| `apiVersion` | integer 1 to 1 | yes | Widget API version; selects this schema. |
+| `id` | `widget ID` | yes | Reverse-DNS ID, from 3 bytes to 128 bytes: at least two dot-separated segments of `[a-z0-9-]`, each at most 63 bytes and not starting or ending with `-`. `com.playervox` and `com.playervox.*` are reserved for packages signed by PlayerVox. |
+| `version` | `version` | yes | SemVer 2.0.0 `MAJOR.MINOR.PATCH[-PRERELEASE]` in canonical form, at most 64 bytes; build metadata is rejected. |
+| `name` | `WidgetName` | yes | Localized widget name shown by the host. |
+| `sizing` | `Sizing` | yes | Size and fit rules applied by the widget's frame. |
+| `vm` | `VmRequest` | no | VM budget request; absent means the defaults. |
+| `permissions` | `Permissions` | no | Requested permissions; absent means none. |
+| `wrapper` | `wrapper` | no | Widget rows of the host options menu. |
+| `requires` | `host features` | no | Distinct host data sources the widget cannot work without, as in a `wrapper.menu` row's `requires`. On a machine that lacks one, the host neither starts nor shows the widget and keeps its layout; the widget comes back when the source does. |
+<!-- /generated:manifest-fields -->
+
+### Identity and version
+
+- **`id`** is the widget's identity everywhere: in the catalog, in the
+  user's profile, in its storage. Choose a reverse-DNS ID under a domain you
+  control and keep it. IDs under `com.playervox` are reserved for widgets
+  published by PlayerVox.
+- **`version`** is a semantic version. A published version never changes:
+  any change to a published widget is a new, higher version.
+- **`schemaVersion`** and **`apiVersion`** are both `1`.
+
+### Names
+
+`name` gives the name OverCrow shows in its widget list and menus, in
+English and in French. Both are required.
+
+<!-- generated:manifest-name -->
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `en` | `name text` | yes | English name. |
+| `fr` | `name text` | yes | French name. |
+<!-- /generated:manifest-name -->
+
+## Sizes
+
+`sizing` says how large the widget is when the user adds it, how small and
+how large the user may resize it, and whether OverCrow can fit its frame to
+its content. Lengths are logical pixels at 100 % scale; the user's content
+scale (50 % to 175 %) multiplies them.
+
+<!-- generated:manifest-sizing -->
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `fit` | `none` \| `both` \| `height` | yes | Content fitting the widget supports: `both` axes, `height` only, or `none`. Manual resizing is always available. |
+| `defaultMode` | `fit` \| `manual` | no | Mode of a newly placed widget; default `fit` when `fit` is not `none`, else `manual`. `fit` with `fit: none` is rejected. |
+| `preferred` | `Dimensions` | yes | Initial size; within `min` and `max`. |
+| `min` | `Dimensions` | yes | Smallest size. |
+| `max` | `Dimensions` | yes | Largest size. |
+<!-- /generated:manifest-sizing -->
+
+Each of `preferred`, `min` and `max` is a pair of dimensions, with
+`min` ≤ `preferred` ≤ `max` on both axes:
+
+<!-- generated:manifest-dimensions -->
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `width` | integer 1 to 4096 | yes | Logical pixels. |
+| `height` | integer 1 to 4096 | yes | Logical pixels. |
+<!-- /generated:manifest-dimensions -->
+
+With `fit: "both"`, OverCrow sizes the frame to what the view needs, in
+both directions: the Clock grows when the user turns the seconds on. With
+`fit: "height"`, the user chooses the width and the height follows the
+content. With `fit: "none"`, the frame keeps the size the user gave it and
+the view fills it. The user can always resize by hand.
+
+<!-- source: widgets/clock/manifest.json -->
+```json
+  "sizing": {
+    "fit": "both",
+    "preferred": { "width": 110, "height": 60 },
+    "min": { "width": 40, "height": 24 },
+    "max": { "width": 480, "height": 240 }
+  },
+```
+
+## Permissions
+
+A widget gets nothing it has not declared here, and a declaration grants
+nothing by itself: the user consents first, in the Control Center.
+[Services and permissions](services.md) explains each permission and what
+it allows.
+
+<!-- generated:manifest-permissions -->
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `network` | list of `NetworkRule` ≤ 32 | no | Distinct network rules. |
+| `storage` | boolean | no | Host key-value storage; default `false`. |
+| `clipboardWrite` | boolean | no | Clipboard text writes; default `false`. |
+| `gameEvents` | list of `game event` ≤ 32 | no | Distinct `overcrow.game.<name>.v1` event names. |
+| `capabilities` | `capability names` | no | Distinct capabilities of the schema. |
+<!-- /generated:manifest-permissions -->
+
+<!-- source: widgets/stopwatch/manifest.json -->
+```json
+  "permissions": {
+    "capabilities": ["stopwatch.read", "stopwatch.control"]
+  }
+```
+
+A network rule is an object of its own; its fields are described with
+[network rules](services.md#network-rules).
+
+## The options menu
+
+Every widget has an options menu, opened from its frame. OverCrow puts its
+own rows first: opacity, content size, fit to content and, when the widget
+needs one, its account. Visibility in Passive mode is the eye in the
+widget's toolbar, not a menu row. `wrapper.menu` adds yours below them:
+toggles, sliders, choices, actions and groups, each with a label in both
+languages.
+
+The menu is as wide as its widest row, from 248 to 320 points. Beyond, a
+label ends with "…" and shows whole in a tooltip; a choice shows its
+current value on at most 120 points. Keep labels short, in both languages.
+
+<!-- source: widgets/clock/manifest.json -->
+```json
+  "wrapper": {
+    "menu": [
+      {
+        "type": "toggle",
+        "id": "show-seconds",
+        "label": { "en": "Show seconds", "fr": "Afficher les secondes" },
+        "default": false
+      },
+      {
+        "type": "toggle",
+        "id": "show-date",
+        "label": { "en": "Show date", "fr": "Afficher la date" },
+        "default": true
+      },
+      {
+        "type": "choice",
+        "id": "date-format",
+        "label": { "en": "Date format", "fr": "Format de date" },
+        "visibleWhen": "show-date",
+        "choices": [
+          { "value": "day-month-year", "label": { "en": "dd/mm/yyyy", "fr": "jj/mm/aaaa" } },
+          { "value": "year-month-day", "label": { "en": "yyyy-mm-dd", "fr": "aaaa-mm-jj" } },
+          { "value": "month-day-year", "label": { "en": "mm/dd/yyyy", "fr": "mm/jj/aaaa" } }
+        ],
+        "default": "day-month-year"
+      }
+    ]
+  }
+```
+
+OverCrow draws the rows, stores their values in the user's profile and
+gives them to the logic: read a value with `option(id, fallback)`, and
+follow changes with `onHost`. An `action` row has no value: it calls the
+handler you registered with `onMenu`. See
+[the options menu in the logic](logic.md#the-options-menu).
+
+A menu row can set one of its declared values or send its action, nothing
+else: it cannot grant a permission or open a link, and choosing a row is
+not a [user action](services.md#calls-that-need-a-user-action) that allows
+a protected service call.
+
+### Fields of every row
+
+<!-- generated:menu-row-fields -->
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `type` | `toggle` \| `slider` \| `choice` \| `action` \| `group` | yes | Row type. |
+| `id` | identifier ≤ 48 bytes | yes | Unique among all rows of the widget; key of the stored value. |
+| `label` | `MenuLabel` | yes | Localized row label. |
+| `icon` | Lucide icon name | no | Leading icon from the host list, drawn by the host. |
+| `visibleWhen` | identifier ≤ 48 bytes | no | ID of a `toggle` row declared earlier; this row is shown only while that toggle is on. |
+| `requires` | `fps` \| `telemetry.cpuTemperature` \| `telemetry.gpuTemperature` | no | Host data source; the host hides the row when it cannot supply it. |
+<!-- /generated:menu-row-fields -->
+
+A row with `visibleWhen` shows only while the named toggle is on: the
+Clock's date format appears when the date does. A row with `requires` is
+hidden on a machine that cannot supply that data, as the Performance
+widget's temperature rows are:
+
+<!-- source: widgets/performance/manifest.json -->
+```json
+            "requires": "telemetry.cpuTemperature",
+```
+
+A `group` row opens a side flyout with its own rows; the Performance
+widget keeps its five metric toggles under one row:
+
+<!-- source: widgets/performance/manifest.json -->
+```json
+        "type": "group",
+        "id": "shown-values",
+        "label": { "en": "Shown values", "fr": "Valeurs affichées" },
+        "rows": [
+```
+
+### Row types
+
+<!-- generated:menu-row-types -->
+### `toggle`
+
+Boolean switch.
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `default` | boolean | yes | Initial value. |
+
+### `slider`
+
+Bounded number; `step` > 0, `step` ≤ `max - min`, at most 10000 steps, `default` within range.
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `min` | number -1000000 to 1000000 | yes | Lower bound. |
+| `max` | number -1000000 to 1000000 | yes | Upper bound, greater than `min`. |
+| `step` | number -1000000 to 1000000 | yes | Increment. |
+| `default` | number -1000000 to 1000000 | yes | Initial value. |
+
+### `choice`
+
+One value among declared choices.
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `choices` | list of `MenuChoice` ≤ 16 | yes | At least 2 choices. |
+| `default` | identifier ≤ 48 bytes | yes | Value of one declared choice. |
+
+### `action`
+
+Calls the handler registered with `onMenu`, with the row ID. Not a user action.
+
+### `group`
+
+Side flyout holding non-group rows.
+
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `rows` | list of `MenuRow` ≤ 16 | yes | At least one row; a `group` is not allowed here. |
+<!-- /generated:menu-row-types -->
+
+### Labels and choices
+
+A `label` is an object with both languages:
+
+<!-- generated:menu-label -->
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `en` | `label text` | yes | English label. |
+| `fr` | `label text` | yes | French label. |
+<!-- /generated:menu-label -->
+
+Each entry of `choices` is a value and its label:
+
+<!-- generated:menu-choice -->
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `value` | identifier ≤ 48 bytes | yes | Stored value; unique within the row. |
+| `label` | `MenuLabel` | yes | Localized choice label. |
+<!-- /generated:menu-choice -->
+
+## Required data sources
+
+`requires` at the top level lists data sources the widget cannot work
+without, with the same names as a row's `requires`. On a machine that lacks
+one, OverCrow neither starts nor shows the widget and keeps its place in the
+layout; the widget comes back when the source does. Use it for a widget
+that has nothing to show otherwise, such as a frame-rate counter without a
+frame-rate source. For a single optional value, prefer a row's `requires`.
+
+## A larger memory budget
+
+The logic runs with a heap of 16 MiB. A widget that needs more asks for it
+with `vm`; nothing else about the VM's budgets can be changed.
+
+<!-- generated:manifest-vm -->
+| Field | Type | Required | Meaning |
+| --- | --- | --- | --- |
+| `heapMiB` | integer 16 to 48 | yes | QuickJS heap ceiling in MiB, from 16 MiB to 48 MiB. The VM process ceiling (64 MiB) does not change. |
+<!-- /generated:manifest-vm -->
+
+The memory ceiling of the widget's process stays the same, so a larger heap
+leaves less room for everything else. Ask for it only when
+`overcrow-widget dev` shows the widget stopping with `resource_limit`.
+
+## How the manifest is checked
+
+`overcrow-widget check` validates the manifest with the validator OverCrow
+itself runs, and points at the member it refuses:
+
+```text
+error[manifest.sizing]: `sizing` is out of bounds or inconsistent
+  --> manifest.json:7:3
+   |
+ 7 |   "sizing": {
+   |   ^
+   = help: `min` <= `preferred` <= `max`, each within the schema's widget size bounds
+check: 1 error(s), 0 warning(s)
+```
+
+OverCrow validates it again when the package is admitted to the catalog,
+when it is installed and each time the widget starts. A new version whose
+manifest asks for more than the previous one (a network rule, a game event,
+a capability, storage or the clipboard) waits until the user approves it
+in the Control Center before it replaces the installed version.

package/dist/content/docs/en/mcp.md

@@ -0,0 +1,165 @@
+# MCP
+
+PlayerVox OverCrow has a server for AI assistants: `@overcrow/mcp`. Add it
+to Claude Code, Claude Desktop, Cursor, VS Code or Codex, and your
+assistant can create a widget, check it, test it, audit it, package it and
+prepare its submission. You need Node.js 22.18 or later, nothing else: the
+server installs the OverCrow tools it needs by itself.
+
+```sh
+claude mcp add overcrow -- npx -y @overcrow/mcp
+```
+
+Then ask: "Create an OverCrow widget that shows…".
+
+## Add the server
+
+Open your widgets folder in the assistant, then add the server.
+
+### In one command
+
+**Claude Code**, from that folder:
+
+```sh
+claude mcp add overcrow -- npx -y @overcrow/mcp
+```
+
+**Codex**:
+
+```sh
+codex mcp add overcrow -- npx -y @overcrow/mcp
+```
+
+**VS Code**: [install in VS Code](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522overcrow%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540overcrow%252Fmcp%2522%255D%257D), or:
+
+```sh
+code --add-mcp '{"name":"overcrow","command":"npx","args":["-y","@overcrow/mcp"]}'
+```
+
+### With a configuration file
+
+**Cursor**: a `.cursor/mcp.json` file in the folder.
+
+<!-- source: mcp/examples/cursor-mcp.json -->
+```json
+{
+  "mcpServers": {
+    "overcrow": {
+      "command": "npx",
+      "args": ["-y", "@overcrow/mcp"]
+    }
+  }
+}
+```
+
+**VS Code**: a `.vscode/mcp.json` file in the folder.
+
+<!-- source: mcp/examples/vscode-mcp.json -->
+```json
+{
+  "servers": {
+    "overcrow": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@overcrow/mcp"]
+    }
+  }
+}
+```
+
+**Claude Desktop** starts its servers outside your folders: name your
+widgets folder with `--root` in `claude_desktop_config.json` (Settings,
+Developer, Edit Config), then restart Claude Desktop.
+
+<!-- source: mcp/examples/claude_desktop_config.json -->
+```json
+{
+  "mcpServers": {
+    "overcrow": {
+      "command": "npx",
+      "args": ["-y", "@overcrow/mcp", "--root", "C:\\Users\\you\\Documents\\widgets"]
+    }
+  }
+}
+```
+
+## What the server does
+
+- **The first time**, it downloads the OverCrow creator tools of your
+  computer (the [command-line tool](cli.md) and the runtime that plays the
+  [tests](testing.md), about 15 MB) from OverCrow's GitHub release. It
+  checks every file against the digests written in the server, then keeps
+  them in its own folder (`~/.cache/overcrow-mcp`, or
+  `%LOCALAPPDATA%\overcrow-mcp` on Windows). Nothing goes on your `PATH`,
+  and no administrator right is needed.
+- **Then** your assistant works with its tools, in this order: create the
+  widget from a template, install the SDK (it asks you first), check, test
+  (it sees the images that differ), audit, package, prepare the
+  submission.
+- **The widget ID** is final. Your assistant asks you for it: your
+  publisher handle in the OverCrow creator space and a name
+  (`nova.lol-timers`), or a domain you can verify
+  (`gg.nova.lol-timers`).
+- **The submission**: the server checks everything the creator space asks
+  for, then writes the ZIP of your widget's sources to `dist/`, without
+  `node_modules`, `dist`, hidden files or keys, and lists what it left out.
+  It also lists the texts to write: why the widget needs each permission,
+  the release notes and the description in English and French. Your
+  assistant drafts them with you.
+- **The audit** scores the widget out of 100 for security and for
+  lightness, with a fix and an example from a
+  [reference widget](widgets.md) for each finding: unused permissions,
+  network rules that are too broad, secrets, clipboard writes without a
+  user action, fast timers, network polling, lists that never stop
+  growing, large responses read in one turn, heavy images.
+- **The documentation** of this site, in English and French, and the
+  sources of the reference widgets come with the server: your assistant
+  reads them without network access.
+
+## What it does not do
+
+- It never sends, signs or publishes anything. You send the ZIP and the
+  texts in the OverCrow creator space on overcrow.playervox.com.
+- It does not install your widget in OverCrow: trying it in a game is the
+  [development channel](dev-channel.md) of the command-line tool.
+- It sends nothing about you: no telemetry, no account.
+
+## Security
+
+- **Your folders only.** The server works in the folder open in your
+  assistant (or the ones given with `--root`). It refuses a system folder,
+  your whole home folder, hidden folders, and links that lead outside.
+- **No command of its own choice.** The server runs the OverCrow
+  command-line tool and npm, nothing else, never through a shell.
+- **Checked downloads.** It downloads only the pinned files from GitHub,
+  and checks them before use. npm installs only `@overcrow/sdk` and
+  TypeScript, with install scripts disabled, and their integrity is
+  checked against the published packages.
+- **You confirm.** Installing packages and replacing reference images
+  need your agreement.
+- **Your files are data.** What the tools return from your files is
+  marked as data: a text inside a widget cannot give orders to your
+  assistant through the server. Still read what your assistant changes,
+  and approve its actions as you usually do.
+
+## Offline
+
+Download `overcrow-creator-tools-VERSION-PLATFORM.zip` of your platform
+from OverCrow's GitHub release once, put it in your widgets folder, and ask
+your assistant to run `setup` with it (`zipPath`). Or start the server with
+`--tools-zip` and the path of the file. The file must be exactly the one
+the server pins.
+
+## Supported computers
+
+Checking, testing and packaging need Windows x64 or Linux x86-64. On
+macOS and on ARM, the server still gives the documentation, the
+explanations and the audit.
+
+## If something goes wrong
+
+- **"not tied to a published OverCrow release"**: update the server with
+  `npx -y @overcrow/mcp@latest`.
+- **Behind a proxy**: set `HTTPS_PROXY` in the server's environment.
+- **"cannot work in /"** (often Claude Desktop): add `--root` and your
+  widgets folder.

package/dist/content/docs/en/package.md

@@ -0,0 +1,131 @@
+# The package
+
+A PlayerVox OverCrow widget is distributed as one file, `<id>-<version>.ocpkg`:
+an archive of the manifest, the compiled view, the style, one script, the
+messages, the images and the license. `overcrow-widget package` builds it,
+and OverCrow reads it with the same code that built it.
+
+```sh
+overcrow-widget package
+overcrow-widget inspect dist/com.example.my-widget-0.1.0.ocpkg
+```
+
+`package` checks the project, writes the archive to `dist/` and prints its
+size and its SHA-256. `inspect` shows what a package holds and what it asks
+for, as a reviewer sees it.
+
+## What goes in
+
+<!-- generated:package-files -->
+| Path | Required | Limit | Meaning |
+| --- | --- | --- | --- |
+| `manifest.json` | yes | 64 KiB | The manifest, as written. |
+| `ledger.json` | yes | 64 KiB | Canonical SHA-256 and byte ledger of every other entry, written by the CLI. |
+| `logic.js` | yes | 512 KiB | The only executable content: one ES2023 script without imports, compiled expressions of the view included. UTF-8, not empty. |
+| `view.json` | yes | 512 KiB | Compiled view. The `view.ocml` source is not shipped. |
+| `style.ocss` | no | 128 KiB | Style sheet source, parsed by the host when the widget starts. UTF-8. |
+| `locales/en.json` | no | 256 KiB | English messages; present if and only if `locales/fr.json` is, with the same keys. |
+| `locales/fr.json` | no | 256 KiB | French messages. |
+| `LICENSE` | yes | 64 KiB | License text of the package. UTF-8, not empty. |
+| `assets/<path>.{png,jpg,jpeg,webp}` | no | 2 MiB | Images whose signature matches the extension; lowercase `[a-z0-9_-]` segments, at most 4 below `assets/`. |
+<!-- /generated:package-files -->
+
+Any other entry rejects the package: a second script, an HTML file, a
+WebAssembly module, native code, a hidden file, another locale. Text files
+are UTF-8, without a byte-order mark.
+
+What you write is not all packaged as it is:
+
+| In the project | In the package |
+| --- | --- |
+| `manifest.json` | the same bytes |
+| `view.ocml` | `view.json`, the compiled view; the source is not shipped |
+| `logic.ts` or `logic.js` | `logic.js`: your module, the SDK and the compiled expressions of the view, in one script |
+| `style.ocss`, `locales/`, `assets/`, `LICENSE` | the same bytes |
+| `package.json`, `tsconfig.json`, `node_modules/`, `listing.json`, `tests/` | not packaged |
+
+Images are PNG, JPEG or WebP files under `assets/`, in lowercase paths, and
+the content of each file must match its extension. The view names one as
+`src="assets/logo.png"`, and the `preview` of a
+[listing](publishing.md#the-listing) is one of those packaged images.
+
+## The script
+
+`logic.js` is the only executable content of a package. The tool builds it
+from your logic module, the SDK it embeds and one function per expression
+and handler of the view, then removes what is unused and shortens local
+names. Two consequences:
+
+- the SDK in your `node_modules` is used for type checking only: the one
+  that runs is the tool's, and `inspect` shows its version;
+- the view itself carries no code: `view.json` refers to the functions of
+  `logic.js` by number.
+
+A package holds source that OverCrow can read and check, never compiled
+bytecode.
+
+## The same bytes every time
+
+Packaging is deterministic: the same sources and the same version of the
+tool give the same archive, byte for byte, on every run and every system.
+That is what lets a reviewer rebuild your package from the sources you
+submit and compare, and what lets the catalog name a package by its
+SHA-256.
+
+For that, the archive has one exact layout: an uncompressed zip, with its
+entries sorted, fixed dates and no extra field. Use `overcrow-widget
+package` to write it; an archive made with another zip tool is refused.
+
+## The ledger
+
+`ledger.json`, written by the tool, lists every other file with its size
+and its SHA-256. OverCrow recomputes it from the archive and requires the
+same bytes. It is what ties each file to the package: a file changed,
+added or removed after packaging no longer matches.
+
+## How OverCrow checks a package
+
+OverCrow validates a package in full when it is admitted to the catalog,
+when it is installed, and again **each time the widget starts**:
+
+1. the size of the archive, its exact layout and the checksum of each
+   entry;
+2. every path, against the list of files above and their size limits, and
+   the required files;
+3. the ledger, byte for byte;
+4. the manifest, the script, the style, the pair of locales, the license,
+   each image, and the compiled view: known elements in allowed places,
+   known attributes with values of the right type, events of their element,
+   components used as declared, the bounds of the view, and each static
+   image present in the package.
+
+For a package of the catalog, the size and the SHA-256 of the archive must
+first equal what the signed catalog says, and the manifest must equal the
+one the catalog lists. A widget whose package fails any of these does not
+start. `overcrow-widget check` and `package` run the same checks, so you
+see a problem before a user does.
+
+## Installed from the catalog, or locally
+
+- A package **from the signed catalog** is verified: this is how users get
+  widgets. See [publishing and review](publishing.md).
+- A package sent by `overcrow-widget dev` is a **development package**:
+  marked "Unverified", for the session only. See
+  [the development channel](dev-channel.md).
+
+A package that does not come from the catalog cannot use an ID under
+`com.playervox`.
+
+## Limits of a package
+
+The sizes of each file and of the archive are in
+[limits](limits.md#project-files-and-package). When a package is over a
+bound, `check` says which:
+
+| Code | Problem |
+| --- | --- |
+| `project.file_size` | A source file is larger than its limit. |
+| `project.entry_limit` | The project has more files than a package may hold. |
+| `project.asset_path` | An image's path is not lowercase, is too deep or has another extension. |
+| `package.file_size` | A built file (`logic.js`, `view.json`) is larger than its limit. |
+| `package.archive_size` | The archive is larger than 16 MiB. |