@overcrow/mcp 0.0.0 → 0.1.1

package/dist/content/docs/fr/package.md

@@ -0,0 +1,139 @@
+# Le paquet
+
+Un widget PlayerVox OverCrow est distribué en un seul fichier,
+`<id>-<version>.ocpkg` : une archive qui réunit le manifeste, la vue
+compilée, le style, un script, les messages, les images et la licence.
+`overcrow-widget package` la construit, et OverCrow la lit avec le code
+même qui l’a construite.
+
+```sh
+overcrow-widget package
+overcrow-widget inspect dist/com.example.my-widget-0.1.0.ocpkg
+```
+
+`package` vérifie le projet, écrit l’archive dans `dist/` et affiche sa
+taille et son SHA-256. `inspect` montre ce qu’un paquet contient et ce
+qu’il demande, tel que le voit un relecteur.
+
+## Ce qu’il contient
+
+<!-- generated:package-files -->
+| Chemin | Obligatoire | Limite | Signification |
+| --- | --- | --- | --- |
+| `manifest.json` | oui | 64 Kio | Le manifeste, tel qu’il a été écrit. |
+| `ledger.json` | oui | 64 Kio | Registre canonique du SHA-256 et de la taille de chaque autre entrée, écrit par la CLI. |
+| `logic.js` | oui | 512 Kio | Le seul contenu exécutable : un script ES2023 sans import, expressions compilées de la vue comprises. UTF-8, non vide. |
+| `view.json` | oui | 512 Kio | La vue compilée. Le source `view.ocml` n’est pas embarqué. |
+| `style.ocss` | non | 128 Kio | Source de la feuille de style, analysée par l’hôte au démarrage du widget. UTF-8. |
+| `locales/en.json` | non | 256 Kio | Messages en anglais ; présent si et seulement si `locales/fr.json` l’est, avec les mêmes clés. |
+| `locales/fr.json` | non | 256 Kio | Messages en français. |
+| `LICENSE` | oui | 64 Kio | Texte de la licence du paquet. UTF-8, non vide. |
+| `assets/<path>.{png,jpg,jpeg,webp}` | non | 2 Mio | Images dont la signature correspond à l’extension ; segments en minuscules `[a-z0-9_-]`, au plus 4 sous `assets/`. |
+<!-- /generated:package-files -->
+
+Toute autre entrée fait refuser le paquet : un second script, un fichier
+HTML, un module WebAssembly, du code natif, un fichier caché, une autre
+langue. Les fichiers texte sont en UTF-8, sans marque d’ordre d’octets.
+
+Tout ce que vous écrivez n’est pas empaqueté tel quel :
+
+| Dans le projet | Dans le paquet |
+| --- | --- |
+| `manifest.json` | les mêmes octets |
+| `view.ocml` | `view.json`, la vue compilée ; le fichier source n’est pas livré |
+| `logic.ts` ou `logic.js` | `logic.js` : votre module, le SDK et les expressions compilées de la vue, en un seul script |
+| `style.ocss`, `locales/`, `assets/`, `LICENSE` | les mêmes octets |
+| `package.json`, `tsconfig.json`, `node_modules/`, `listing.json`, `tests/` | non empaquetés |
+
+Les images sont des fichiers PNG, JPEG ou WebP placés sous `assets/`, à des
+chemins en minuscules, et le contenu de chaque fichier doit correspondre à
+son extension. La vue en désigne une par `src="assets/logo.png"`, et
+l’aperçu (`preview`) d’une [fiche](publishing.md#la-fiche) est l’une de ces
+images empaquetées.
+
+## Le script
+
+`logic.js` est le seul contenu exécutable d’un paquet. L’outil le construit
+à partir de votre module de logique, du SDK qu’il embarque et d’une
+fonction par expression et par gestionnaire de la vue, puis retire ce qui
+ne sert pas et raccourcit les noms locaux. Deux conséquences :
+
+- le SDK de votre `node_modules` ne sert qu’à la vérification des types :
+  celui qui s’exécute est celui de l’outil, et `inspect` affiche sa
+  version ;
+- la vue elle-même ne contient aucun code : `view.json` désigne les
+  fonctions de `logic.js` par leur numéro.
+
+Un paquet contient des sources qu’OverCrow peut lire et vérifier, jamais de
+bytecode compilé.
+
+## Les mêmes octets à chaque fois
+
+L’empaquetage est déterministe : les mêmes sources et la même version de
+l’outil donnent la même archive, octet pour octet, à chaque exécution et
+sur chaque système. C’est ce qui permet à un relecteur de reconstruire
+votre paquet à partir des sources que vous soumettez, puis de comparer.
+C’est aussi ce qui permet au catalogue de désigner un paquet par son
+SHA-256.
+
+Pour cela, l’archive n’admet qu’une seule structure, exacte : un zip non
+compressé, aux entrées triées, aux dates fixes et sans champ
+supplémentaire. Écrivez-la avec `overcrow-widget package` ; une archive
+produite par un autre outil zip est refusée.
+
+## Le registre
+
+`ledger.json`, écrit par l’outil, liste tous les autres fichiers avec leur
+taille et leur SHA-256. OverCrow le recalcule à partir de l’archive et
+exige les mêmes octets. C’est lui qui lie chaque fichier au paquet : un
+fichier modifié, ajouté ou retiré après l’empaquetage ne correspond plus.
+
+## Comment OverCrow vérifie un paquet
+
+OverCrow valide un paquet en entier lors de son admission au catalogue,
+lors de son installation, puis **à chaque démarrage du widget** :
+
+1. la taille de l’archive, sa structure exacte et la somme de contrôle de
+   chaque entrée ;
+2. chaque chemin, comparé à la liste de fichiers ci-dessus et à leurs
+   limites de taille, ainsi que la présence des fichiers obligatoires ;
+3. le registre, octet pour octet ;
+4. le manifeste, le script, le style, la paire de langues, la licence,
+   chaque image et la vue compilée : des éléments connus à des emplacements
+   autorisés, des attributs connus dont les valeurs ont le bon type, des
+   événements propres à leur élément, des composants utilisés comme ils
+   sont déclarés, les limites de la vue, et la présence dans le paquet de
+   chaque image statique.
+
+Pour un paquet du catalogue, la taille et le SHA-256 de l’archive doivent
+d’abord être ceux qu’indique le catalogue signé, et le manifeste doit être
+identique à celui que liste le catalogue. Un widget dont le paquet échoue à
+l’une de ces vérifications ne démarre pas. `overcrow-widget check` et
+`package` exécutent les mêmes vérifications : vous voyez donc un problème
+avant qu’un utilisateur ne le rencontre.
+
+## Installé depuis le catalogue, ou localement
+
+- Un paquet **issu du catalogue signé** est vérifié : c’est ainsi que les
+  utilisateurs obtiennent les widgets. Voir
+  [publication et revue](publishing.md).
+- Un paquet envoyé par `overcrow-widget dev` est un **paquet de
+  développement** : marqué « Unverified », pour la durée de la session
+  seulement. Voir [le canal de développement](dev-channel.md).
+
+Un paquet qui ne vient pas du catalogue ne peut pas utiliser un ID sous
+`com.playervox`.
+
+## Limites d’un paquet
+
+Les tailles de chaque fichier et de l’archive figurent dans les
+[limites](limits.md#fichiers-du-projet-et-paquet). Quand un paquet dépasse
+une limite, `check` indique laquelle :
+
+| Code | Problème |
+| --- | --- |
+| `project.file_size` | Un fichier source dépasse sa limite. |
+| `project.entry_limit` | Le projet compte plus de fichiers qu’un paquet ne peut en contenir. |
+| `project.asset_path` | Le chemin d’une image n’est pas en minuscules, est trop profond ou porte une autre extension. |
+| `package.file_size` | Un fichier construit (`logic.js`, `view.json`) dépasse sa limite. |
+| `package.archive_size` | L’archive dépasse 16 Mio. |

package/dist/content/docs/fr/publish-a-widget.md

@@ -0,0 +1,101 @@
+# Publier un widget
+
+Dans l’espace créateurs de PlayerVox OverCrow, à l’adresse
+`creators.playervox.com`, un widget arrive aux joueurs en quatre
+étapes : vous envoyez ses sources, elles sont contrôlées automatiquement,
+PlayerVox les relit, puis la version est publiée dans le catalogue. Cette
+page couvre les deux premières et l’écran qui envoie une version en revue ;
+la [revue](widget-review.md) et la [fiche](widget-listing.md) ont leur
+propre page.
+
+## Avant d’envoyer
+
+- L’identifiant de votre widget est réservé dans l’espace créateurs
+  ([démarrer](creator-space.md)), et `manifest.json` l’utilise.
+- `overcrow-widget check` passe dans le dossier du widget.
+- La version de `manifest.json` est plus récente que la dernière approuvée :
+  `1.2.1` ou plus après `1.2.0`.
+
+## Envoyer les sources
+
+Ouvrez le widget dans **Widgets**, puis **Envoyer une version**.
+
+- Sur un ordinateur, déposez le dossier du widget sur la page, ou
+  choisissez-le. Vous pouvez aussi envoyer un `.zip` du dossier.
+- Sur un téléphone ou une tablette, qui ne savent pas choisir un dossier,
+  choisissez le `.zip`.
+
+L’espace créateurs lit un dossier avec les mêmes règles que
+`overcrow-widget submit`, sur votre ordinateur, et envoie les mêmes
+fichiers. Il laisse de côté les fichiers et dossiers cachés (`.env`,
+`.git/`…), `node_modules/`, `dist/`, `tests/output/`, `__MACOSX/`, les
+paquets déjà construits, les fichiers de clés, les fichiers système et les
+noms qui ne sont pas en ASCII portable ; la page liste ce qu’il a laissé de
+côté. Un `.zip` est envoyé tel quel. Les bornes et les refus sont ceux des
+[archives de sources](cli.md#archives-de-sources) : 32 Mio pour l’archive,
+64 Mio et 2 000 fichiers une fois décompressé, 16 niveaux de dossiers, des
+chemins de 255 octets au plus, aucun nom qui ne diffère d’un autre que par
+la casse.
+
+- Un `.zip` fait par Windows PowerShell 5.1 (`Compress-Archive`) sépare les
+  dossiers par `\` et est refusé aussitôt : déposez plutôt le dossier.
+- Un nom de fichier ou de dossier avec `\ : * ? " < > |` est refusé avant
+  tout envoi : Windows ne peut pas l’utiliser. Renommez-le.
+- Un navigateur lit le fichier vers lequel pointe un lien, là où l’outil en
+  ligne de commande laisse le lien de côté. Gardez les liens hors du dossier
+  du widget.
+- Vos sources restent privées : seuls les relecteurs PlayerVox les lisent,
+  et chaque consultation apparaît dans l’espace créateurs.
+
+Un éditeur fait au plus 20 envois en 24 heures ; la page dit quand le
+suivant est possible. Si la page se ferme ou si la connexion se coupe
+pendant l’envoi, déposez à nouveau le même dossier : l’envoi reprend, et
+rien n’est compté deux fois.
+
+## Les contrôles
+
+Les contrôles prennent environ une minute : le manifeste, le numéro de
+version, le code, la construction du paquet, les permissions, la taille.
+Vous pouvez quitter la page : un e-mail vous prévient quand ils sont finis.
+
+- Quand un contrôle échoue, chaque problème est montré dans vos propres
+  fichiers, avec la ligne et la correction. Corrigez et envoyez à nouveau ;
+  rien n’arrive aux relecteurs.
+- « Problème de notre côté » signifie que PlayerVox n’a pas pu faire les
+  contrôles : votre code n’est pas en cause. PlayerVox est prévenu et les
+  relance.
+
+## Soumettre pour revue
+
+Quand les contrôles passent, la page de la version dit ce qui change pour
+les joueurs :
+
+- **Permissions.** Expliquez pourquoi le widget a besoin de chaque
+  permission nouvelle ou élargie, avec des mots que les joueurs comprennent.
+  Une première version les explique toutes.
+- **Politique de confidentialité.** Obligatoire dès que le widget utilise
+  le réseau. L’adresse tapée ici est aussi enregistrée dans la fiche.
+- **Fiche.** Une première version part en revue avec sa fiche, qui demande
+  une description en anglais, une licence et un contact d’assistance.
+- **Notes de version**, visibles par les joueurs : facultatives. L’anglais
+  vient d’abord ; **Ajouter une langue** en ajoute d’autres, 16 au plus. Dès
+  que vous en écrivez, écrivez-les aussi en anglais.
+- **Message pour la revue**, lu seulement par PlayerVox : un compte de test,
+  un contexte utile.
+
+La page dit aussi quelle revue la version reçoit (rapide ou complète) et ce
+qui a changé depuis la dernière version approuvée. **Soumettre pour revue**
+l’envoie.
+
+## Depuis un terminal ou une CI
+
+`overcrow-widget submit` envoie une version avec une clé de publication, et
+s’arrête au même écran quand il manque quelque chose : voir
+[`submit`](cli.md#submit) et [clés de publication et CI](publish-keys.md).
+
+## Après la revue
+
+Une version approuvée est publiée sous 24 heures ouvrées. Dans l’espace
+créateurs, vous pouvez ensuite la retirer, ou retirer le widget entier
+(**Réglages**) : il sort du catalogue à la prochaine publication, et les
+copies installées continuent de fonctionner.

package/dist/content/docs/fr/publish-keys.md

@@ -0,0 +1,97 @@
+# Clés de publication et CI
+
+Une clé de publication permet à `overcrow-widget submit` d’envoyer les
+versions d’un widget PlayerVox OverCrow depuis un terminal ou une CI, sans
+votre mot de passe.
+Elle ne permet rien d’autre.
+
+## Ce qu’une clé permet
+
+- Soumettre des versions d’**un seul** widget, et suivre leurs contrôles.
+  Chaque version passe toujours par la revue avant d’arriver aux joueurs.
+- Elle ne permet ni de publier, ni de modifier la fiche, ni d’accéder à
+  votre compte ou à vos autres widgets.
+- Elle dure de 1 à 365 jours (90 par défaut). Nous vous prévenons par e-mail
+  et dans l’espace créateurs 14 jours avant son expiration.
+- PlayerVox n’en garde qu’une empreinte : la clé est affichée **une seule
+  fois**, à sa création.
+
+## Créer une clé
+
+Dans l’espace créateurs, **Clés de publication**, **Créer une clé** :
+
+1. Nommez-la d’après l’endroit où elle servira (`GitHub Actions`,
+   `Portable`).
+2. Choisissez le widget et la durée.
+3. Confirmez avec un code récent de votre application d’authentification.
+
+Copiez aussitôt la clé dans les secrets de votre CI : elle commence par
+`ocw_pub_` et ne sera plus jamais affichée. Si vous la perdez, révoquez-la et
+créez-en une autre. Un widget a au plus dix clés actives.
+
+## L’utiliser
+
+`overcrow-widget submit` lit la clé dans la variable d’environnement
+`OVERCROW_PUBLISH_KEY`, et seulement là : ne la mettez jamais dans un fichier
+du projet ni dans une ligne de commande.
+
+```sh
+export OVERCROW_PUBLISH_KEY=ocw_pub_…
+overcrow-widget submit
+```
+
+La [commande submit](cli.md#submit) contrôle la version comme le fera
+l’espace créateurs, l’envoie, puis suit ses contrôles, environ une minute.
+
+## Dans GitHub Actions
+
+Gardez la clé comme secret du dépôt, `OVERCROW_PUBLISH_KEY`. Ce workflow
+soumet le widget à chaque tag de version :
+
+<!-- source: docs/content/examples/weather/.github/workflows/submit.yml -->
+```yaml
+# Sends the widget to the OverCrow creator space when a version tag is
+# pushed. The publish key is a secret of the repository, and the OverCrow
+# release whose creator tools to use is a variable of the repository.
+name: Submit to OverCrow
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  submit:
+    runs-on: ubuntu-24.04
+    env:
+      OVERCROW_VERSION: ${{ vars.OVERCROW_VERSION }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install overcrow-widget
+        run: |
+          tools="overcrow-creator-tools-$OVERCROW_VERSION-linux-x86_64"
+          curl --fail --location --silent --show-error --remote-name \
+            "https://github.com/Valhallab/playervox-overcrow-releases/releases/download/v$OVERCROW_VERSION/$tools.zip"
+          unzip -q "$tools.zip"
+          (cd "$tools" && sha256sum --check --quiet SHA256SUMS)
+          install -D -m 755 "$tools"/overcrow-widget-*-linux-x86_64 "$HOME/.local/bin/overcrow-widget"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - name: Submit to OverCrow
+        run: overcrow-widget submit --submission submission.json
+        env:
+          OVERCROW_PUBLISH_KEY: ${{ secrets.OVERCROW_PUBLISH_KEY }}
+```
+
+La tâche échoue quand les contrôles échouent, avec chaque problème sur la
+ligne de votre fichier. Une version que l’espace créateurs a déjà n’est pas
+renvoyée : `submit` donne son état, et la même tâche peut aussi tourner à
+chaque push sur votre branche principale.
+
+## Révoquer une clé
+
+**Révoquer** arrête la clé aussitôt : un envoi en cours avec elle échoue.
+Les versions qu’elle a déjà envoyées restent, mais n’entrent plus seules en
+revue : envoyez-les en revue depuis l’espace créateurs. Révoquez une clé dès
+que vous pensez qu’elle a fuité, puis créez-en une nouvelle.

package/dist/content/docs/fr/publishing.md

@@ -0,0 +1,177 @@
+# Publication et revue
+
+> **Les pull requests sont fermées.** Les widgets ne sont plus proposés par
+> pull request : ceux de PlayerVox passent déjà par l’espace créateurs
+> OverCrow, et le vôtre y passera à son ouverture. D’ici là, cette page
+> décrit l’admission, la revue et le catalogue que suit un widget.
+
+Les widgets atteignent les utilisateurs de PlayerVox OverCrow par le
+catalogue signé des widgets : OverCrow n’installe que ce que liste ce
+catalogue. Cette page va du dossier de sources d’un widget à une version
+listée. Ni une pull request ni une fusion ne publient quoi que ce soit : la
+publication est une étape distincte des mainteneurs, hors de la CI.
+
+## La soumission
+
+Une soumission est le dossier de sources d’un widget, placé sous
+`widgets/<dir>/` du
+[dépôt public](https://github.com/Valhallab/playervox-overcrow-releases),
+dans une pull request vers sa branche `candidate` :
+
+```text
+widgets/<dir>/
+  manifest.json   view.ocml   style.ocss?   logic.ts | logic.js
+  locales/en.json + locales/fr.json?   assets/**?   LICENSE
+  listing.json    (marketplace text, never packaged)
+```
+
+Vous soumettez des sources, pas un paquet : le catalogue livre toujours le
+paquet reconstruit à partir des sources relues.
+
+Les IDs de paquet sous `com.playervox` sont réservés aux widgets publiés
+par PlayerVox. Utilisez un ID en DNS inversé sous un domaine que vous
+contrôlez, et gardez-le : l’ID est l’identité du widget dans le catalogue.
+
+## La fiche
+
+`listing.json` contient ce qu’affiche la marketplace :
+
+<!-- source: docs/content/examples/weather/listing.json -->
+```json
+{
+  "author": "Example Studio",
+  "spdxLicense": "MIT",
+  "sourceUrl": "https://github.com/example/weather-widget",
+  "defaultLocale": "en",
+  "localizations": [
+    { "locale": "en", "name": "Weather", "description": "The temperature of a city, refreshed every 30 minutes." },
+    { "locale": "fr", "name": "Météo", "description": "La température d’une ville, actualisée toutes les 30 minutes." }
+  ]
+}
+```
+
+<!-- generated:listing-fields -->
+| Champ | Type | Obligatoire | Signification |
+| --- | --- | --- | --- |
+| `author` | texte ≤ 128 octets | oui | Texte brut, sans espaces en début ni en fin, sans `<` ni `>`. |
+| `spdxLicense` | texte ≤ 64 octets | oui | Expression SPDX, faite des caractères `[A-Za-z0-9.+-]`. |
+| `sourceUrl` | texte ≤ 2 Kio | oui | URL HTTPS canonique des sources relues, sans port, requête ni fragment. |
+| `defaultLocale` | `locale` | oui | L’une des localisations. |
+| `localizations` | liste de `Localization` ≤ 16 | oui | `{ locale, name, description }` avec des locales distinctes de la forme `xx` ou `xx-YY` ; nom ≤ 128 octets, description ≤ 512 octets. |
+<!-- /generated:listing-fields -->
+
+- `author`, les noms et les descriptions sont du texte brut, sans espace au
+  début ni à la fin, sans `<` ni `>` ; les langues sont de la forme `xx` ou
+  `xx-YY`, l’une d’elles étant `defaultLocale`.
+- `spdxLicense` est une expression SPDX ; le `LICENSE` du paquet en
+  contient le texte. Les widgets PlayerVox sont sous MIT. La politique pour
+  les licences des tiers n’est pas encore arrêtée : une expression valide
+  est relue, pas approuvée par les métadonnées
+  ([licences](../../../LICENSING.md)).
+- `sourceUrl` est une URL HTTPS canonique des sources relues, sans port,
+  requête ni fragment.
+- `preview` (facultatif) désigne un PNG empaqueté sous `assets/`, de
+  256 Kio au plus, par exemple `"preview": "assets/preview.png"`. Le
+  Centre de contrôle et la marketplace le montrent entier dans un cadre
+  4:3, centré sur la couleur `#1e242e`, à 1,5 pixel par point d’écran au
+  plus : rendez le widget à 150 % (`"scale": 1500` dans un scénario) et
+  donnez à l’image un format 4:3, il apparaît à sa taille réelle, jamais
+  recadré ni agrandi.
+
+## L’admission : lancez-la vous-même
+
+```sh
+overcrow-widget admit widgets/<dir>
+overcrow-widget admit widgets/<dir> --package dist/<id>-<version>.ocpkg
+overcrow-widget admit widgets/<dir> --format json
+```
+
+`admit` est exactement l’admission statique de la marketplace. Elle
+n’exécute jamais votre code ni `tsc` :
+
+1. elle construit le dossier comme le fait `package` : toutes les
+   vérifications des sources, du style, de la logique et du paquet, puis le
+   lecteur de paquets d’OverCrow lui-même ;
+2. avec `--package`, la vue compilée de votre archive doit être, octet pour
+   octet, le résultat de la compilation de `view.ocml` ;
+3. elle vérifie les limites du schéma, les IDs réservés, `listing.json`,
+   l’aperçu et, pour les widgets PlayerVox, la licence MIT ;
+4. elle liste pour le relecteur l’autorité que demande le widget :
+   capabilities sensibles, chaque route réseau, écritures dans le
+   presse-papiers, stockage et événements de jeu.
+
+La commande se termine avec le code de sortie 1 quand la soumission serait
+refusée. Ses codes sont listés avec la [commande `admit`](cli.md#admit).
+
+Sur une pull request, l’outil d’admission est construit depuis la branche
+de base relue, jamais depuis votre révision, et il lit vos fichiers comme
+des données : votre JavaScript, votre TypeScript, vos commandes de build,
+vos tests et vos scripts n’y sont jamais exécutés. Une pull request ne peut
+pas modifier les outils de l’admission eux-mêmes.
+
+## La revue
+
+Un mainteneur lit le rapport d’admission et les sources, puis fusionne dans
+`candidate`. Les relecteurs vérifient :
+
+- **L’identité.** Un nouvel ID sous un domaine que l’auteur contrôle. Une
+  nouvelle version pour tout changement : les versions publiées sont
+  immuables, et une version inférieure à une version listée est refusée.
+- **La reproductibilité.** Le paquet est reconstruit à partir des sources
+  relues.
+- **L’autorité.** Chaque capability, surtout les sensibles ; chaque route
+  réseau, qui doit servir l’objet annoncé du widget ; les écritures dans le
+  presse-papiers, le stockage et les événements de jeu. Voir
+  [services et permissions](services.md).
+- **La fiche.** Un texte exact et brut dans chaque langue, une URL de
+  sources canonique, un aperçu qui montre le widget.
+- **La licence.** `LICENSE` correspond à `spdxLicense`, et chaque
+  ressource, police ou code tiers embarqué garde sa mention.
+
+À la fusion, la révision exacte est admise de nouveau, et un reçu lie le
+paquet admis au commit relu. Accepter une soumission ne signe et ne publie
+rien.
+
+## Le catalogue
+
+Les mainteneurs préparent le catalogue suivant à partir des révisions
+admises et le signent hors de la CI avec la clé du catalogue, dont la moitié
+publique est dans [`keys/`](../../../keys/). Le catalogue :
+
+- liste chaque version avec le SHA-256 et la taille de son paquet ; une
+  version publiée ne change jamais, et un changement est une nouvelle
+  version ;
+- porte un numéro de séquence strictement croissant et expire au bout de
+  90 jours au plus : OverCrow refuse une séquence plus ancienne et un
+  catalogue expiré ;
+- marque `built-in` les widgets de référence PlayerVox (IDs
+  `com.playervox.*` uniquement) : ils sont installés sur un nouveau profil
+  avec leurs permissions déclarées accordées, sauf pour une mise à jour qui
+  en demande davantage.
+
+OverCrow vérifie la signature, l’empreinte du paquet, son registre et sa
+vue compilée avant l’installation, puis à chaque démarrage du widget. Voir
+[le paquet](package.md#comment-overcrow-vérifie-un-paquet).
+
+## Mises à jour
+
+Une nouvelle version de votre widget est une nouvelle soumission, avec une
+`version` plus élevée : une version publiée n’est jamais remplacée. Une
+mise à jour dont le manifeste demande plus que la version installée (une
+règle réseau, un événement de jeu, une capability, le stockage ou le
+presse-papiers) exige l’accord de l’utilisateur, dans le Centre de
+contrôle, avant de s’exécuter.
+
+## Statuts des versions
+
+Chaque version listée a un statut :
+
+| Statut | Signification |
+| --- | --- |
+| `verified` | Installable. |
+| `security-suspended` | Soupçonnée de compromission : ni installée ni proposée en mise à jour, et une copie installée est arrêtée. Réversible dans un catalogue ultérieur. |
+| `revoked` | Définitif : plus jamais installée, et une copie installée est arrêtée. |
+
+Omettre une version dans un catalogue ne change jamais son statut. La
+signature d’un catalogue ne contourne jamais la validation du paquet, le
+consentement de l’utilisateur ni le sandbox.

package/dist/content/docs/fr/reference.md

@@ -0,0 +1,59 @@
+# Référence
+
+La référence des widgets PlayerVox OverCrow liste chaque élément, chaque
+propriété de style, chaque service et chaque fonction du SDK de l’API
+widget v1. Cette page indique où trouver chaque réponse. Les pages de la
+rubrique « Écrire un widget » expliquent comment les parties fonctionnent
+ensemble ; celles qui suivent sont à garder ouvertes pendant que vous
+écrivez.
+
+| Question | Page |
+| --- | --- |
+| Que contient `manifest.json` ? | [Le manifeste](manifest.md) |
+| Quels éléments, attributs et événements une vue peut-elle utiliser ? | [Éléments et attributs](elements.md) |
+| Quelles propriétés de style et quelles valeurs sont acceptées ? | [Propriétés de style et tokens](style-properties.md) |
+| Quels tokens du design system et quelles icônes existent ? | [Tokens du design system](style-properties.md#tokens-du-design-system), [icônes](style-properties.md#icônes) |
+| Quelles fonctions `@overcrow/sdk` exporte-t-il ? | [Référence du SDK](sdk.md) |
+| Comment formater les heures, les dates et les nombres ? | [Heure, dates et nombres](sdk.md#heure-dates-et-nombres) |
+| Qu’autorise chaque permission et chaque capability ? | [Services et permissions](services.md) |
+| Quels sont les paramètres et le résultat d’un service ? | [Référence des services](service-reference.md), [formes de résultat](result-shapes.md) |
+| Que signifie un code d’erreur ? | [Erreurs](services.md#erreurs) |
+| Quels champs un intent d’écriture prend-il ? | [Les intents](forms.md#les-intents) |
+| Quelles sont les limites (tailles, nombres, budgets) ? | [Limites](limits.md) |
+| Que fait chaque commande et chaque diagnostic de la CLI ? | [L’outil en ligne de commande](cli.md) |
+| Comment écrire un scénario de test ? | [Tester un widget](testing.md#scénarios) |
+| Que contient un `.ocpkg` ? | [Le paquet](package.md) |
+
+## Comment la référence reste exacte
+
+- Les tableaux des éléments, des attributs, des propriétés de style, des
+  tokens, des services, des formes de résultat et des limites sont
+  **générés à partir du schéma des widgets**, les mêmes tables qu’OverCrow
+  et l’outil en ligne de commande compilent dans leurs validateurs. Une
+  vérification échoue dès qu’une page diffère du schéma, en anglais ou en
+  français.
+- Les **types du SDK** sont générés à partir du même schéma : un élément,
+  une icône, une capability ou un paramètre de service erroné est donc une
+  erreur TypeScript dans votre logique.
+- La **référence du SDK** est vérifiée par les tests du SDK : chaque export
+  de `@overcrow/sdk` y figure.
+- Chaque **exemple de code** de ces pages est un extrait d’un projet que
+  l’outil en ligne de commande vérifie, empaquette et admet à chaque
+  changement : un template, un widget de référence ou l’un des deux
+  exemples.
+
+## Versions
+
+Ces pages décrivent l’API widget v1 (`"apiVersion": 1` dans le manifeste)
+et `@overcrow/sdk` 1.0.
+
+## Spécifications pour les implémenteurs
+
+Trois spécifications, dans le dépôt public, s’adressent à ceux qui
+implémentent un hôte ou un autre outil plutôt qu’un widget : la
+[référence complète du schéma, générée](../../widget-schema-v1.md), qui
+couvre aussi le protocole entre OverCrow et le processus du widget ainsi que
+les données du catalogue ; le
+[protocole du canal de développement](../../dev-channel.md) ; et le
+[format de l’archive et du catalogue](../../widget-package-v1.md). L’auteur
+d’un widget n’en a pas besoin.