@microteia/console 2.20.0 → 2.22.1

package/CONSOLE-VERSIONS.md

@@ -22,6 +22,49 @@
 - fix(command): what was broken, and what it did to whoever hit it.
 -->
 
+#### [2.22.1] — 2026-09-19
+
+- fix(cli/publish): the release notes now carry every changelog entry since the last PUBLISHED version,
+  not only the one being packaged. A version can be packaged and never published — the catalog is what
+  says what went up, and the package being published contains all of them. Publishing 9.66.0 over a
+  catalog whose newest entry was 9.64.0 created a release that carries 9.65.0 and did not quote a line
+  of it, and a release is immutable: no later release goes back to tell what those versions changed.
+  The cut now starts at `publishedBefore(index, version)`, so it happens after the catalog is read
+  rather than while the package is; the first publish, which has no interval, still cuts its own entry
+  alone. The command prints which versions the notes carry, in the dry run too.
+
+#### [2.22.0] — 2026-09-10
+
+- feat(deploy): the reachability check now covers HTTP endpoints, not only callables.
+  `callableFunctionNames` matches `onRequest` as well, because the list means "what the outside world
+  calls" and an HTTP endpoint depends on public invocation even more than a callable does — a blocked
+  invoker grant answers 403 with no CORS header, and the client reports a connection error. Without
+  this, the platform's first `onRequest` would have gone up unverified.
+- fix(deploy): the `functions-invoker` prerequisite no longer promises that every reachable function
+  rejects a caller with no signed-in user. That is true of a callable and false of an endpoint that
+  authenticates by token, and the sentence was about to be read by whoever installs the agent access.
+
+#### [2.21.0] — 2026-09-09
+
+- fix(cli/pack): reading-only examples are left out of the first-party backend accounting.
+  `extension-templates/` holds two kinds of package with the same shape and different owners — the
+  first-party extensions, whose Cloud Functions this kernel compiles and deploys, and the examples,
+  whose backend belongs to whoever installs them. The pack derives its baseline as
+  `all functions − claimed`, so the first example to teach Cloud Functions would have aborted every
+  publish by claiming a name that is not here, and a name that WAS here would have been taken out of
+  the kernel baseline by a mere template. `firstPartyTemplates` is now the single door onto that
+  directory, and `READING_ONLY_EXAMPLES` is derived from where an example's source lives rather than
+  kept as a second list.
+- feat(cli/vendor): `stageExamples` carries `functions/` and `scripts/` beside `views/`, and an
+  example whose source is a DIRECTORY takes `plugin.ts` as its entry. Without both, an example could
+  not teach a Cloud Function or a sandbox script — the two files simply would not travel.
+- fix(cli/vendor): `rewriteImports` sends the node-only modules to `@microteia/sdk/node` instead of to
+  the isomorphic barrel, which is where `transpileScriptSource` deliberately is not. The symptom
+  would have been in the office of whoever installed, not here.
+- fix(cli/vendor): the `MICROTEIA.md` it writes derives its build command from the examples actually
+  present. It named `examples/pessoa`, which left the repository with the office extensions — a
+  generated document telling the reader to compile something that is not there.
+
 #### [2.20.0] — 2026-09-01
 
 - feat(cli/export-catalog): the snapshot carries what each installed extension declares in `manifest.exports` — the artifacts another extension may reference as `<extension-id>/<source-id>`. Whoever authors outside the office knew an extension was installed and had no way to learn the name of anything inside it, so the reference could be written by hand and never discovered. Each entry carries the id, the artifact's name, and its `kind`, which is the part that decides where the reference fits: a script goes in `scriptId`, an automation in `targetWorkflowId`. What the artifact DOES still never travels — the steps and the code are behaviour, and the snapshot is shape.

package/README.md

@@ -1,4 +1,4 @@
-# Microteia Console 2.20.0
+# Microteia Console 2.22.1
 
 Installs and updates Microteia in a Firebase project you own. It has no npm dependencies of its own —
 what it needs are command-line tools that are already on the machine, listed at the bottom.

package/lib/kernel/channel.d.ts

@@ -70,6 +70,17 @@ export declare const entryOf: (manifest: KernelManifest, urls: {
  * `9.8.2` significa. Um número novo custa um minuto.
  */
 export declare const withEntry: (index: ChannelIndex, entry: ChannelEntry) => ChannelIndex;
+/**
+ * A última versão publicada ABAIXO desta — o começo do intervalo que o release novo cobre.
+ *
+ * É "abaixo desta" e não "o topo do catálogo" porque publicar fora de ordem é possível, e o que o
+ * release precisa descrever é o que ele acrescenta a quem já tinha a anterior. Quem já tinha a anterior
+ * está na maior versão MENOR que esta.
+ *
+ * Nada publicado ainda é `undefined`, e não a menor versão do histórico: o arquivo de histórico começa
+ * antes do catálogo, e a primeira publicação não descreve o que veio antes dela.
+ */
+export declare const publishedBefore: (index: ChannelIndex, version: string) => string | undefined;
 /**
  * Resolve o que foi pedido — `latest` ou um número — nomeando o que existe quando não acha.
  *

package/lib/kernel/channel.js

@@ -126,6 +126,20 @@ export const withEntry = (index, entry) => {
         kernel: [entry, ...index.kernel].sort(byVersionDescending),
     };
 };
+/**
+ * A última versão publicada ABAIXO desta — o começo do intervalo que o release novo cobre.
+ *
+ * É "abaixo desta" e não "o topo do catálogo" porque publicar fora de ordem é possível, e o que o
+ * release precisa descrever é o que ele acrescenta a quem já tinha a anterior. Quem já tinha a anterior
+ * está na maior versão MENOR que esta.
+ *
+ * Nada publicado ainda é `undefined`, e não a menor versão do histórico: o arquivo de histórico começa
+ * antes do catálogo, e a primeira publicação não descreve o que veio antes dela.
+ */
+export const publishedBefore = (index, version) => [...index.kernel]
+    .sort(byVersionDescending)
+    .find((entry) => compareVersions(entry.version, version) < 0)
+    ?.version;
 /**
  * Resolve o que foi pedido — `latest` ou um número — nomeando o que existe quando não acha.
  *

package/lib/kernel/manifest.d.ts

@@ -127,10 +127,20 @@ export declare const MANUAL_PREREQUISITES: KernelPrerequisite[];
  */
 export declare const exportedFunctionNames: (indexSource: string) => string[];
 /**
- * As callables são as functions que o NAVEGADOR chama. Elas se distinguem das de gatilho por uma
- * razão prática: só elas podem ser verificadas de fora, e só nelas a permissão de invocação pública
- * importa. Sem ela a aplicação abre e toda chamada ao servidor falha — parecendo erro de CORS, que
- * manda procurar no lugar errado.
+ * As functions que o mundo de FORA chama — e é isso que a lista significa, não o construtor delas.
+ *
+ * Elas se distinguem das de gatilho por uma razão prática: só elas podem ser verificadas de fora, e
+ * só nelas a permissão de invocação pública importa. Sem ela a aplicação abre e toda chamada ao
+ * servidor falha — parecendo erro de CORS, que manda procurar no lugar errado.
+ *
+ * `onRequest` entra pela MESMA razão, e não por generosidade: um endpoint HTTP é ainda mais
+ * dependente da invocação pública que uma callable, porque quem o consome pode não ser um navegador
+ * nosso — é o caso do endpoint MCP, que um cliente de IA chama. O preflight de `callableAccess`
+ * serve os dois sem mudar uma linha: ele pergunta `OPTIONS` e confere o cabeçalho de CORS, que um
+ * `onRequest` com `cors: true` responde igual.
+ *
+ * O que NÃO se confunde com isto é o portão de instalação (`functionGate`): lá a distinção entre
+ * `onCall` e `onRequest` importa muito, porque uma tem escritório no chamador e a outra não.
  */
 export declare const callableFunctionNames: (source: string) => string[];
 /**

package/lib/kernel/manifest.js

@@ -86,7 +86,9 @@ export const MANUAL_PREREQUISITES = [
             + 'CORS error. The fix is one command per function, and the deploy prints the exact list: gcloud '
             + 'run services add-iam-policy-binding <function-name-in-lowercase> --region=<region> '
             + '--project=<projectId> --member=allUsers --role=roles/run.invoker. Unauthenticated invocation '
-            + 'is not open access: every callable still rejects callers with no signed-in user.',
+            + 'is not open access: reaching a function is not the same as being allowed to use it. A callable '
+            + 'rejects any caller with no signed-in user, and an HTTP endpoint authenticates every request '
+            + 'with the credential it was given and refuses everything else.',
         optional: true,
     },
     {
@@ -107,12 +109,23 @@ export const exportedFunctionNames = (indexSource) => [...indexSource.matchAll(/
     .map((name) => name.trim())
     .filter((name) => name !== '');
 /**
- * As callables são as functions que o NAVEGADOR chama. Elas se distinguem das de gatilho por uma
- * razão prática: só elas podem ser verificadas de fora, e só nelas a permissão de invocação pública
- * importa. Sem ela a aplicação abre e toda chamada ao servidor falha — parecendo erro de CORS, que
- * manda procurar no lugar errado.
+ * As functions que o mundo de FORA chama — e é isso que a lista significa, não o construtor delas.
+ *
+ * Elas se distinguem das de gatilho por uma razão prática: só elas podem ser verificadas de fora, e
+ * só nelas a permissão de invocação pública importa. Sem ela a aplicação abre e toda chamada ao
+ * servidor falha — parecendo erro de CORS, que manda procurar no lugar errado.
+ *
+ * `onRequest` entra pela MESMA razão, e não por generosidade: um endpoint HTTP é ainda mais
+ * dependente da invocação pública que uma callable, porque quem o consome pode não ser um navegador
+ * nosso — é o caso do endpoint MCP, que um cliente de IA chama. O preflight de `callableAccess`
+ * serve os dois sem mudar uma linha: ele pergunta `OPTIONS` e confere o cabeçalho de CORS, que um
+ * `onRequest` com `cors: true` responde igual.
+ *
+ * O que NÃO se confunde com isto é o portão de instalação (`functionGate`): lá a distinção entre
+ * `onCall` e `onRequest` importa muito, porque uma tem escritório no chamador e a outra não.
  */
-export const callableFunctionNames = (source) => [...source.matchAll(/export\s+const\s+([a-zA-Z0-9_]+)\s*=\s*onCall\b/g)].map((match) => match[1]);
+export const callableFunctionNames = (source) => [...source.matchAll(/export\s+const\s+([a-zA-Z0-9_]+)\s*=\s*(?:onCall|onRequest)\b/g)]
+    .map((match) => match[1]);
 /**
  * Os parâmetros que o backend declara com `defineString`. O `firebase-functions` os valida
  * GLOBALMENTE, e não por function: um parâmetro sem valor e sem default recusa o deploy de TODAS as

package/lib/shared/paths.d.ts

@@ -87,4 +87,4 @@ export declare const consoleRoot: string;
  * de código nunca chegou a quem instala. Este bloco fica sendo o que ele já era antes de crescer: a
  * política de semver da ferramenta, mais o registro do que motivou as versões até a `2.5.0`.
  */
-export declare const CLI_VERSION = "2.20.0";
+export declare const CLI_VERSION = "2.22.1";

package/lib/shared/paths.js

@@ -94,4 +94,4 @@ export const consoleRoot = resolve(here, '..', '..');
  * de código nunca chegou a quem instala. Este bloco fica sendo o que ele já era antes de crescer: a
  * política de semver da ferramenta, mais o registro do que motivou as versões até a `2.5.0`.
  */
-export const CLI_VERSION = '2.20.0';
+export const CLI_VERSION = '2.22.1';

package/lib/vendor/changelogs.d.ts

@@ -38,16 +38,28 @@ export declare const changelogProblems: (file: string, contents: string, version
  */
 export declare const readChangelog: (directory: string, file: string, version: string) => Promise<string>;
 /**
- * A entrada de UMA versão, para ser o corpo do release publicado.
+ * As entradas que o release publicado carrega: a da versão que está saindo, e a de TODA versão entre ela
+ * e a última já publicada.
  *
  * O texto do release não é escrito à mão em lugar nenhum: ele é o mesmo parágrafo que já foi conferido
  * pelo `pack`, recortado daqui. Dois textos sobre a mesma versão divergem — e o que divergiria é
  * justamente o que fica visível para quem procura o que mudou.
  *
- * Recorta do cabeçalho da versão até o próximo cabeçalho, e não até o fim: o que vem depois é o
- * histórico anterior, e ele já está publicado nos releases dele.
+ * O recorte de uma entrada só perdia o intervalo. Publicar a 9.66.0 quando a última publicada é a
+ * 9.64.0 — porque a 9.65.0 foi empacotada e não subiu — entrega um release que CONTÉM a 9.65.0 e não
+ * menciona uma linha dela: para quem procura o que mudou, aquelas alterações nunca existiram, e não há
+ * release posterior que as traga de volta. O release descreve o que ele leva, e ele leva tudo desde a
+ * última publicação.
+ *
+ * Sem `since` é a primeira publicação, e aí o recorte é só da própria versão: o histórico do arquivo é
+ * anterior ao catálogo, e despejá-lo inteiro não seria descrever o que subiu.
  */
-export declare const changelogEntry: (contents: string, version: string) => string;
+export interface ChangelogNotes {
+    body: string;
+    /** As versões recortadas, da mais recente para a mais antiga — o que o release diz que cobre. */
+    versions: string[];
+}
+export declare const changelogEntries: (contents: string, version: string, since?: string) => ChangelogNotes;
 export interface ChangelogRefresh {
     written: string[];
     missing: string[];

package/lib/vendor/changelogs.js

@@ -83,26 +83,25 @@ export const readChangelog = async (directory, file, version) => {
     }
     return contents;
 };
-/**
- * A entrada de UMA versão, para ser o corpo do release publicado.
- *
- * O texto do release não é escrito à mão em lugar nenhum: ele é o mesmo parágrafo que já foi conferido
- * pelo `pack`, recortado daqui. Dois textos sobre a mesma versão divergem — e o que divergiria é
- * justamente o que fica visível para quem procura o que mudou.
- *
- * Recorta do cabeçalho da versão até o próximo cabeçalho, e não até o fim: o que vem depois é o
- * histórico anterior, e ele já está publicado nos releases dele.
- */
-export const changelogEntry = (contents, version) => {
+export const changelogEntries = (contents, version, since) => {
     const body = withoutTemplates(contents);
     const headings = [...body.matchAll(ENTRY)];
-    const index = headings.findIndex((match) => match[1] === version);
-    if (index === -1) {
+    const first = headings.findIndex((match) => match[1] === version);
+    if (first === -1) {
         throw new Error(`The changelog has no entry for ${version}.`);
     }
-    const start = headings[index].index;
-    const end = index + 1 < headings.length ? headings[index + 1].index : body.length;
-    return `${body.slice(start, end).trim()}\n`;
+    let last = first;
+    while (since !== undefined
+        && last + 1 < headings.length
+        && compareVersions(headings[last + 1][1], since) > 0) {
+        last += 1;
+    }
+    const start = headings[first].index;
+    const end = last + 1 < headings.length ? headings[last + 1].index : body.length;
+    return {
+        body: `${body.slice(start, end).trim()}\n`,
+        versions: headings.slice(first, last + 1).map((match) => match[1]),
+    };
 };
 /**
  * Põe os dois históricos na raiz da instalação, SOBREPONDO — pela mesma razão que o `MICROTEIA.md` é

package/lib/vendor/exampleSources.d.ts

@@ -1,19 +1,33 @@
 /**
- * As extensões de primeira parte, empacotadas como FONTE — `plugin.ts` e as views em `.tsx` —, uma pasta
- * por extensão.
+ * Arquivo distribuído → módulo de origem, relativo a `src/plugins/marketplace/`. O nome da pasta do
+ * exemplo é o do `.json`, sem extensão.
  *
- * Viajavam como `.json`. Um `.json` de 90 KB não ensina nada: é o artefato, e quem abre não vê como se
- * chega nele. O que ensina é a fonte, e ela já viaja de qualquer forma — o código das views está dentro
- * do `.json`, em string. Passar a mandar o `.ts` não expõe nada novo; expõe de forma legível o que já ia.
+ * Há DUAS formas de origem, e a diferença não é de estilo: é de quem o módulo é.
  *
- * A única transformação é de IMPORT: neste repositório um plugin importa `../../domain/entities/...` e
- * `../contributionBuilders`; do lado do escritório, tudo isso é `@microteia/sdk`. Todo símbolo usado
- * pelos doze está no barril do SDK — e é por isso que a conferência é possível: `exampleSources.test.ts`
- * COMPILA cada exemplo reescrito e exige que o `.json` saia byte a byte igual ao versionado. Um símbolo
- * que faltasse no barril reprovaria ali, e não no escritório de alguém.
+ * - **Um arquivo** (`automation.ts`) — a extensão mora na raiz do marketplace porque ela é, ou já foi,
+ *   uma extensão de PRIMEIRA PARTE do catálogo embutido. Os vizinhos que ela importa são descobertos
+ *   por `siblingModules`, e as views dela ficam em `views/<módulo>/`.
+ * - **Um diretório** (`examples/report-example`) — a extensão existe SÓ para ser lida. Nada dela entra
+ *   no `MARKETPLACE_CATALOG`, então ela não tem por que ocupar a raiz do marketplace junto das que
+ *   entram: ali as cinco de primeira parte se perderiam no meio de doze moldes. Tudo o que é dela mora
+ *   na pasta dela — o `plugin.ts`, os catálogos de mensagem e as `views/`.
  */
-/** Arquivo distribuído → módulo de origem. O nome da pasta do exemplo é o do `.json`, sem extensão. */
 export declare const EXAMPLE_SOURCES: Record<string, string>;
+/**
+ * Os exemplos que existem SÓ para ser lidos — os que não estão no catálogo embutido.
+ *
+ * A pergunta que eles respondem é do `pack`: de quem é o backend que este repositório sobe. Uma
+ * extensão de primeira parte que declare `manifest.backend` reivindica uma function que o kernel
+ * compila e deploya, e o `pack` confere isso — reivindicar um nome que não existe aborta o
+ * empacotamento, e reivindicar um que existe o TIRA da baseline. Um exemplo não é nada disso: o
+ * `functions/` dele viaja como fonte para ser lido, e quem o instalar de verdade constrói o próprio.
+ * Sem esta distinção, o primeiro exemplo a ensinar Cloud Functions reprovaria toda publicação.
+ *
+ * É DERIVADA da forma da origem, e não uma segunda lista a manter: morar em `examples/` é
+ * exatamente o que significa não estar no catálogo embutido. As cinco de primeira parte moram na raiz
+ * do marketplace porque o bundle as carrega, e é por isso que elas continuam sendo cobradas.
+ */
+export declare const READING_ONLY_EXAMPLES: ReadonlySet<string>;
 /**
  * Reescreve os imports de um plugin para a forma que o escritório usa.
  *

package/lib/vendor/exampleSources.js

@@ -10,19 +10,71 @@ import { join } from 'node:path';
  *
  * A única transformação é de IMPORT: neste repositório um plugin importa `../../domain/entities/...` e
  * `../contributionBuilders`; do lado do escritório, tudo isso é `@microteia/sdk`. Todo símbolo usado
- * pelos doze está no barril do SDK — e é por isso que a conferência é possível: `exampleSources.test.ts`
+ * por eles está no barril do SDK — e é por isso que a conferência é possível: `exampleSources.test.ts`
  * COMPILA cada exemplo reescrito e exige que o `.json` saia byte a byte igual ao versionado. Um símbolo
  * que faltasse no barril reprovaria ali, e não no escritório de alguém.
  */
-/** Arquivo distribuído → módulo de origem. O nome da pasta do exemplo é o do `.json`, sem extensão. */
+/** A pasta, dentro do marketplace, em que mora um exemplo que existe só para ser lido. */
+const EXAMPLES_DIR = 'examples';
+/**
+ * Arquivo distribuído → módulo de origem, relativo a `src/plugins/marketplace/`. O nome da pasta do
+ * exemplo é o do `.json`, sem extensão.
+ *
+ * Há DUAS formas de origem, e a diferença não é de estilo: é de quem o módulo é.
+ *
+ * - **Um arquivo** (`automation.ts`) — a extensão mora na raiz do marketplace porque ela é, ou já foi,
+ *   uma extensão de PRIMEIRA PARTE do catálogo embutido. Os vizinhos que ela importa são descobertos
+ *   por `siblingModules`, e as views dela ficam em `views/<módulo>/`.
+ * - **Um diretório** (`examples/report-example`) — a extensão existe SÓ para ser lida. Nada dela entra
+ *   no `MARKETPLACE_CATALOG`, então ela não tem por que ocupar a raiz do marketplace junto das que
+ *   entram: ali as cinco de primeira parte se perderiam no meio de doze moldes. Tudo o que é dela mora
+ *   na pasta dela — o `plugin.ts`, os catálogos de mensagem e as `views/`.
+ */
 export const EXAMPLE_SOURCES = {
-    'automation-example': 'automation.ts',
+    'automation-example': 'examples/automation-example',
+    agent: 'agent.ts',
     brasil: 'brasil.ts',
     calendar: 'calendar.ts',
     dashboard: 'dashboard.ts',
     'locale-pt-br': 'localePtBr',
     news: 'news.ts',
+    'report-example': 'examples/report-example',
+    'widget-example': 'examples/widget-example',
+    'access-example': 'examples/access-example',
+    'backend-example': 'examples/backend-example',
+    'library-example': 'examples/library-example',
+    'consumer-example': 'examples/consumer-example',
+    'patch-example': 'examples/patch-example',
+    'theme-example': 'examples/theme-example',
+    'auth-example': 'examples/auth-example',
+    'command-example': 'examples/command-example',
+    'settings-example': 'examples/settings-example',
 };
+/**
+ * Os exemplos que existem SÓ para ser lidos — os que não estão no catálogo embutido.
+ *
+ * A pergunta que eles respondem é do `pack`: de quem é o backend que este repositório sobe. Uma
+ * extensão de primeira parte que declare `manifest.backend` reivindica uma function que o kernel
+ * compila e deploya, e o `pack` confere isso — reivindicar um nome que não existe aborta o
+ * empacotamento, e reivindicar um que existe o TIRA da baseline. Um exemplo não é nada disso: o
+ * `functions/` dele viaja como fonte para ser lido, e quem o instalar de verdade constrói o próprio.
+ * Sem esta distinção, o primeiro exemplo a ensinar Cloud Functions reprovaria toda publicação.
+ *
+ * É DERIVADA da forma da origem, e não uma segunda lista a manter: morar em `examples/` é
+ * exatamente o que significa não estar no catálogo embutido. As cinco de primeira parte moram na raiz
+ * do marketplace porque o bundle as carrega, e é por isso que elas continuam sendo cobradas.
+ */
+export const READING_ONLY_EXAMPLES = new Set(Object.entries(EXAMPLE_SOURCES)
+    .filter(([, origin]) => origin.startsWith(`${EXAMPLES_DIR}/`))
+    .map(([id]) => id));
+/**
+ * Os módulos do kernel cuja casa, para quem escreve de fora, é `@microteia/sdk/node` — a entrada de
+ * FERRAMENTA do pacote, e não o barril isomórfico.
+ *
+ * `scriptSource` está aqui porque um `Script` viaja com `sourceTs` E `compiledJs`, e o sandbox nunca
+ * transpila: quem empacota precisa produzir o segundo, com o MESMO transpilador que o runtime usa.
+ */
+const NODE_ONLY_MODULES = ['sdk/node/', 'domain/services/scriptSource'];
 /**
  * Reescreve os imports de um plugin para a forma que o escritório usa.
  *
@@ -31,6 +83,14 @@ export const EXAMPLE_SOURCES = {
  * extensão tem a sua pasta — aqui elas moram num diretório comum, com um nível a mais.
  */
 export const rewriteImports = (source) => source.replace(/from '(\.[^']*)'/g, (match, specifier) => {
+    // A FERRAMENTA vem antes da superfície, e a ordem é o ponto: estes caminhos também casariam com as
+    // regras genéricas abaixo, que os mandariam para o barril isomórfico — onde `transpileScriptSource`
+    // NÃO está, de propósito, porque ele arrasta o `sucrase` e `@microteia/sdk` é a superfície que não
+    // arrasta nada. Do lado do escritório ele vem de `@microteia/sdk/node`, que é outra entrada do
+    // mesmo pacote. O sintoma seria no escritório de quem instalou, não aqui, se o round-trip byte a
+    // byte não compilasse cada exemplo reescrito.
+    if (NODE_ONLY_MODULES.some((one) => specifier.includes(one)))
+        return "from '@microteia/sdk/node'";
     if (/(^|\/)contributionBuilders$/.test(specifier)
         || specifier.includes('domain/')
         || specifier.includes('sdk/')) {
@@ -81,9 +141,18 @@ const siblingModules = async (marketplace, entry) => {
     }
     return collected;
 };
-const viewFiles = async (viewsDir) => {
+/**
+ * Os arquivos de uma pasta do exemplo — `views/` ou `functions/` —, e o teste deles COM eles, de
+ * propósito. Pasta ausente é lista vazia, nunca erro: nem todo exemplo tem as duas.
+ *
+ * O `.rules.test.ts` ao lado de um `.rules.ts` é material didático: é onde se vê que a regra de uma
+ * view pode ser extraída e exercitada sem montar React nenhum, que é exatamente o que o `AGENTS.md`
+ * pede de quem escreve aqui. O `.test.ts` da RAIZ do módulo é outra coisa — aquele é nosso, sobre a
+ * nossa extensão — e é por isso que só ele é filtrado, no laço de baixo.
+ */
+const sourceFilesIn = async (folder) => {
     try {
-        return (await readdir(viewsDir)).filter((name) => name.endsWith('.tsx') || name.endsWith('.ts'));
+        return (await readdir(folder)).filter((name) => name.endsWith('.tsx') || name.endsWith('.ts'));
     }
     catch {
         return [];
@@ -107,7 +176,7 @@ export const stageExamples = async (repo, target) => {
             }
             const plugin = origin.replace(/\.ts$/, '');
             const views = join(marketplace, 'views', plugin);
-            const files = await viewFiles(views);
+            const files = await sourceFilesIn(views);
             if (files.length > 0)
                 await mkdir(join(directory, 'views'), { recursive: true });
             for (const name of files) {
@@ -115,14 +184,34 @@ export const stageExamples = async (repo, target) => {
             }
         }
         else {
-            // Extensão que é um DIRETÓRIO (o pacote de idioma, com um arquivo por namespace). O `index.ts`
-            // vira `plugin.ts`; os demais são vizinhos dele e os imports relativos seguem valendo.
-            for (const name of await readdir(join(marketplace, origin))) {
+            // Extensão que é um DIRETÓRIO: o exemplo de leitura, cuja entrada é `plugin.ts`, e o pacote de
+            // idioma, cuja entrada é `index.ts` porque ele é um módulo de primeira parte antes de ser um
+            // exemplo. A entrada vira `plugin.ts` no destino nos dois casos — é o nome que o autor compila —
+            // e os demais `.ts` são vizinhos dela, com os imports relativos seguindo valendo.
+            const source = join(marketplace, origin);
+            const names = await readdir(source);
+            const entry = names.includes('plugin.ts') ? 'plugin.ts' : 'index.ts';
+            for (const name of names) {
                 if (!name.endsWith('.ts') || name.endsWith('.test.ts'))
                     continue;
-                const source = rewriteImports(await readFile(join(marketplace, origin, name), 'utf8'));
-                const isEntry = name === 'index.ts';
-                await writeFile(join(directory, isEntry ? 'plugin.ts' : name), isEntry ? HEADER(id) + source : source);
+                const text = rewriteImports(await readFile(join(source, name), 'utf8'));
+                const isEntry = name === entry;
+                await writeFile(join(directory, isEntry ? 'plugin.ts' : name), isEntry ? HEADER(id) + text : text);
+            }
+            // As views, as Cloud Functions e os scripts de um exemplo moram DENTRO dele, e não em
+            // `views/<módulo>/`: a pasta é o pacote, exatamente como do lado do escritório. `functions/` e
+            // `scripts/` viajam VERBATIM — a primeira já é escrita contra `microteia-functions/office` e
+            // `firebase-functions`, que são os nomes que valem lá, e a segunda não importa nada: o script
+            // roda no sandbox, contra globais que só existem lá dentro.
+            for (const folder of ['views', 'functions', 'scripts']) {
+                const from = join(source, folder);
+                const files = await sourceFilesIn(from);
+                if (files.length === 0)
+                    continue;
+                await mkdir(join(directory, folder), { recursive: true });
+                for (const name of files) {
+                    await writeFile(join(directory, folder, name), await readFile(join(from, name), 'utf8'));
+                }
             }
         }
         written.push(id);

package/lib/vendor/firstPartyTemplates.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Os `extension-templates/*.json` cujo backend é DESTE repositório — a única porta para essa pergunta.
+ *
+ * `extension-templates/` guarda duas coisas com a mesma forma e donos diferentes: as extensões de
+ * primeira parte, que viajam no bundle e cujas Cloud Functions o kernel compila e deploya, e os
+ * exemplos, que viajam como fonte para serem lidos e cujo backend pertence a quem os instalar. A conta
+ * do `pack` — baseline = todas as functions menos as reivindicadas — só faz sentido sobre as primeiras.
+ *
+ * A porta é única porque a pergunta já estava em dois lugares: o `pack` e o teste que guarda o `pack`.
+ * Dois leitores do mesmo diretório com filtros diferentes é como um portão passa a aprovar o que ele
+ * existe para reprovar — aqui, o exemplo que ensina Cloud Functions abortando toda publicação, ou uma
+ * function saindo da baseline do kernel porque um MOLDE a reivindicou.
+ */
+export declare const firstPartyTemplates: <T>(root: string) => T[];

package/lib/vendor/firstPartyTemplates.js

@@ -0,0 +1,23 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { READING_ONLY_EXAMPLES } from './exampleSources.js';
+/**
+ * Os `extension-templates/*.json` cujo backend é DESTE repositório — a única porta para essa pergunta.
+ *
+ * `extension-templates/` guarda duas coisas com a mesma forma e donos diferentes: as extensões de
+ * primeira parte, que viajam no bundle e cujas Cloud Functions o kernel compila e deploya, e os
+ * exemplos, que viajam como fonte para serem lidos e cujo backend pertence a quem os instalar. A conta
+ * do `pack` — baseline = todas as functions menos as reivindicadas — só faz sentido sobre as primeiras.
+ *
+ * A porta é única porque a pergunta já estava em dois lugares: o `pack` e o teste que guarda o `pack`.
+ * Dois leitores do mesmo diretório com filtros diferentes é como um portão passa a aprovar o que ele
+ * existe para reprovar — aqui, o exemplo que ensina Cloud Functions abortando toda publicação, ou uma
+ * function saindo da baseline do kernel porque um MOLDE a reivindicou.
+ */
+export const firstPartyTemplates = (root) => {
+    const dir = join(root, 'extension-templates');
+    return readdirSync(dir)
+        .filter((file) => file.endsWith('.json'))
+        .filter((file) => !READING_ONLY_EXAMPLES.has(basename(file, '.json')))
+        .map((file) => JSON.parse(readFileSync(join(dir, file), 'utf8')));
+};

package/lib/vendor/installationDocs.js

@@ -254,7 +254,7 @@ ${examples.length === 0 ? '_None in this package._' : examples.map((id) => `- \`
 Each is the real source of an extension that ships with Microteia. Build any of them and you get the
 same \`.json\` the platform installs:
 
-    npx microteia-plugin build examples/pessoa/plugin.ts
+    npx microteia-plugin build examples/${examples[0] ?? '<example>'}/plugin.ts
 
 ## 6. An AI assistant in this directory
 

package/lib/vendor/pack.js

@@ -13,6 +13,7 @@ import { KERNEL_CHANGELOG, readChangelog } from './changelogs.js';
 import { assertInsideRepository } from './repository.js';
 import { SDK_TARBALL } from './pluginWorkspaceTemplates.js';
 import { stageExamples } from './exampleSources.js';
+import { firstPartyTemplates } from './firstPartyTemplates.js';
 import { packageCustomIndexTs, packageCustomTsconfig, packageFirebaseJson, packageFunctionsIndexJs, packageFunctionsPackageJson, } from './packageTemplates.js';
 /**
  * `dist` é um modo do Vite para o qual NÃO existe `.env.dist`. É isso que garante um bundle sem
@@ -23,13 +24,13 @@ const DISTRIBUTION_TARGET = 'dist';
  * As exigências de backend das extensões de PRIMEIRA PARTE saem dos `extension-templates/*.json`, que
  * são gerados dos `.ts` e conferidos pelo `verify-extensions` que o gate de qualidade acima já roda.
  * Ler o `.json` gerado em vez do `.ts` evita carregar o Vite aqui só para avaliar um módulo.
+ *
+ * Os exemplos que só viajam para ser lidos ficam de FORA (`READING_ONLY_EXAMPLES`), e o motivo está
+ * escrito lá: o backend de um exemplo não é deste repositório. Cobrá-lo aqui faria o exemplo que
+ * ensina Cloud Functions abortar toda publicação — e, se a function existisse, a reivindicação a
+ * tiraria da baseline do kernel, que é o oposto exato do que um exemplo deve provocar.
  */
-const firstPartyClaims = async (root) => {
-    const dir = join(root, 'extension-templates');
-    const files = (await readdir(dir)).filter((file) => file.endsWith('.json'));
-    const templates = await Promise.all(files.map((file) => readJson(join(dir, file))));
-    return claimsFromTemplates(templates);
-};
+const firstPartyClaims = (root) => claimsFromTemplates(firstPartyTemplates(root));
 const readJson = async (path) => JSON.parse(await readFile(path, 'utf8'));
 /**
  * Os `defineString` e as callables estão espalhados pelos handlers, não num arquivo só — então a
@@ -131,7 +132,7 @@ export const pack = async (args) => {
     // ausência que é só do parser.
     const callables = scan.callables.filter((name) => functionNames.includes(name));
     const rootIndexes = await readJson(join(root, 'firestore.indexes.json'));
-    const claims = await firstPartyClaims(root);
+    const claims = firstPartyClaims(root);
     const problems = claimProblems(claims, functionNames, rootIndexes.indexes);
     if (problems.length > 0) {
         throw new Error('An extension declares backend artifacts that do not add up, so the package would be wrong:\n'

package/lib/vendor/publish.js

@@ -6,8 +6,8 @@ import { CLI_VERSION, repoRoot } from '../shared/paths.js';
 import { capture, captureOrThrow, run } from '../shared/run.js';
 import { blank, bullets, heading, info, pending, step, success, warn } from '../shared/ui.js';
 import { digestMismatch, digestOfFile } from '../shared/digest.js';
-import { emptyIndex, entryOf, kernelTarballName, parseIndex, serializeIndex, withEntry, } from '../kernel/channel.js';
-import { CONSOLE_CHANGELOG, KERNEL_CHANGELOG, changelogEntry, readChangelog } from './changelogs.js';
+import { emptyIndex, entryOf, kernelTarballName, parseIndex, publishedBefore, serializeIndex, withEntry, } from '../kernel/channel.js';
+import { CONSOLE_CHANGELOG, KERNEL_CHANGELOG, changelogEntries, readChangelog } from './changelogs.js';
 import { CONSOLE_PACKAGE_NAME } from './packageTemplates.js';
 import { assertInsideRepository } from './repository.js';
 /**
@@ -170,20 +170,30 @@ const readKernelPackage = async (root, version) => {
             + 'One of the two was rebuilt without the other. Run "npm run pack:kernel" again.');
     }
     const changelog = await readChangelog(root, KERNEL_CHANGELOG, version);
-    return { manifest, tarball, entry: changelogEntry(changelog, version) };
+    return { manifest, tarball, changelog };
 };
 const publishKernel = async (root, version, repo, dryRun) => {
     await assertGitHubCli();
-    const { manifest, tarball, entry } = await readKernelPackage(root, version);
+    const { manifest, tarball, changelog } = await readKernelPackage(root, version);
     const directory = join(root, 'distributions', 'kernel', version);
     const manifestPath = join(directory, 'manifest.json');
     const published = await readPublishedIndex(repo);
+    /**
+     * O corpo do release cobre o INTERVALO, e não só a versão que está saindo. Um pacote leva tudo o que
+     * veio antes dele; um release que só cita a própria entrada esconde as versões que foram empacotadas e
+     * não publicadas, e nenhum release posterior volta para contá-las.
+     */
+    const since = publishedBefore(published.index, version);
+    const notes = changelogEntries(changelog, version, since);
     const next = withEntry(published.index, entryOf(manifest, {
         tarball: assetUrl(repo, version, kernelTarballName(version)),
         manifest: assetUrl(repo, version, 'manifest.json'),
     }, new Date().toISOString()));
     success(`kernel ${version} verified: ${manifest.tarball?.bytes} bytes, sha256 ${manifest.tarball?.sha256.slice(0, 12)}…`);
     info(`  tag ${tagOf(version)} in ${repo}, and ${INDEX_PATH} promoting it to "latest"`);
+    info(notes.versions.length === 1
+        ? `  release notes: the ${version} entry of ${KERNEL_CHANGELOG}`
+        : `  release notes: ${notes.versions.join(', ')} — every entry since ${since ?? 'the first one'}`);
     if (dryRun) {
         if (published.empty)
             info(`  ${repo} has no commits, so it would be seeded with a README first`);
@@ -192,9 +202,9 @@ const publishKernel = async (root, version, repo, dryRun) => {
     }
     if (published.empty)
         await seedRepository(repo);
-    const notes = await mkdtemp(join(tmpdir(), 'microteia-publish-'));
-    const notesFile = join(notes, 'notes.md');
-    await writeFile(notesFile, entry);
+    const notesRoot = await mkdtemp(join(tmpdir(), 'microteia-publish-'));
+    const notesFile = join(notesRoot, 'notes.md');
+    await writeFile(notesFile, notes.body);
     try {
         if (await releaseExists(repo, version)) {
             /**
@@ -224,7 +234,7 @@ const publishKernel = async (root, version, repo, dryRun) => {
         success(`${INDEX_PATH} updated — "microteia unpack --version latest" now takes ${version}`);
     }
     finally {
-        await rm(notes, { recursive: true, force: true });
+        await rm(notesRoot, { recursive: true, force: true });
     }
 };
 const publishedConsoleVersion = async (version) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microteia/console",
-  "version": "2.20.0",
+  "version": "2.22.1",
   "description": "Install and update Microteia in a Firebase project you own.",
   "license": "UNLICENSED",
   "type": "module",