@meada/meada 0.1.0 → 1.0.0

package/CHANGELOG.md

@@ -6,6 +6,155 @@ All notable changes to Meada are recorded here. The format follows
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-10-30
+
+The tree declares `1.0.0`: this release raises the workspace, the `meada-core` pin, the Dockerfile,
+the compose defaults and the Helm chart from `0.1.0`, and the `v1.0.0` tag follows its merge on
+main. Publication is still ahead and belongs to the maintainer under
+[#154](https://github.com/ClaudioMascaro/meada/issues/154): `cargo publish` of the crates (core
+first), approval of the staged npm package with 2FA, and publication of the GitHub draft release,
+which triggers the OCI image and Helm chart workflow.
+Release notes and the scope evidence checklist are available in
+[pt-BR](https://github.com/ClaudioMascaro/meada/blob/main/docs/releases/1.0.0.md),
+[English](https://github.com/ClaudioMascaro/meada/blob/main/docs/releases/1.0.0.en.md) and
+[Spanish](https://github.com/ClaudioMascaro/meada/blob/main/docs/releases/1.0.0.es.md).
+The [1.x stability promise](https://github.com/ClaudioMascaro/meada/blob/main/docs/site/en/stability.md)
+starts at publication. The [#32 tracking checklist](https://github.com/ClaudioMascaro/meada/issues/32)
+still needs the post-publication evidence.
+
+### Added
+
+- Public fixture benchmark (issue #149): release-profile index/reindex timings, root and
+  workspace index sizes, and default-answer/tool-list token estimates in every PR/main CI
+  summary and retained JSON/Markdown artifact. Timings are informational.
+
+- The English user guide and README (#150, spec #32): `docs/user-guide.en.md` translates both
+  halves of the pt-BR guide section by section (sections 1 to 11) with the same neutral examples
+  and links the English stability page; `README.en.md` now links it instead of the pt-BR guide.
+  No code, default dependency or golden changed.
+- The Spanish user guide (#151, spec #32): `docs/user-guide.es.md`, sections 1 to 11 of the pt-BR
+  guide with the same structure and neutral names, linking the Spanish stability page. The Spanish
+  README links it instead of the Portuguese guide, and the three READMEs link the stability page
+  from the Status section. No code, default dependency or golden changed.
+- The output grammar reference (#145, spec R1): `docs/reference/output-grammar.md`, in English like
+  the MCP surface, specifies every line kind of `search`, `context` and `trace`, the link notation
+  with its level and reason, the levels in order, the contract identifiers (`http::`, `http::ANY::`
+  for a provider of every method, `channel::`, `package::`, `resource::`), the `search` kinds, the
+  chain footer, the cut note and the token estimate, and tells readers to skip line kinds and
+  fields they do not know. Its tables are the grammar check's input: `tests/it/grammar.rs` matches
+  every line of every rendered-answer golden against the line kinds of its tool and fails naming
+  the golden and the line, fails on a documented line kind no golden shows, and holds the
+  document's levels, entry kinds, open item kinds and `search` kinds to the code's. The stability
+  document links it. No output changed; new goldens pin the answers only inline assertions covered (`no symbol
+  matches`, `no resource matches`, the server's `index behind the mirror`, and `trace` with no
+  start, several symbols, several call sites or a clean working tree).
+- The pt-BR user guide, second half (#147, spec #32), in `docs/user-guide.md` (sections 8 to 11):
+  each contract kind (HTTP routes, declared resources and gateway prefixes, OpenAPI and AsyncAPI
+  documents, channels with the limit that broker clusters are not modelled, packages), each 1.0
+  language pack (TypeScript and JavaScript, Python, Go, Rust) with its frameworks, clients,
+  environment reads, manifests, channel clients and known limits (including that Rust calls inside
+  macros are not indexed), shape drift, and communities and processes. Java, Kotlin, C# and Swift
+  are named only as planned Release 2 work. No code, default dependency or golden changed.
+- The pt-BR user guide, first half (#146, spec #32), in `docs/user-guide.md`: installation through
+  every channel (Cargo, prebuilt binary, shell installer, `npx @meada/meada`, container), MCP setup with
+  `npx @meada/meada mcp` and the three tools with their parameters, the `meada.toml` reference (every
+  table and key), decisions and deciders (protocols, environment variables, what is sent,
+  privacy), every CLI command and the export. The READMEs in all three languages gain the
+  installation channels, first steps, MCP setup and a 1.0 status section with the stability
+  promise. No code, default dependency or golden changed.
+- Surface goldens (#144, spec #32): `tests/golden/mcp.tools.json` holds the MCP tool list (names,
+  descriptions and parameter schemas of `search`, `context` and `trace`), checked beside the
+  1,000-token limit of the descriptions, and `tests/golden/cli.help-all.en.txt` the English help of
+  every command of the default build. A test pins the default token budget of 2,000. Both
+  goldens change only with `MEADA_BLESS=1`.
+- The stability document (#148, spec #32), `docs/site/{pt,en,es}/stability.md`: the surface 1.x
+  freezes (the MCP tools, the output grammar, CLI commands and flags, the `meada.toml`,
+  `meada.decisions.toml` and `meada.workspace.toml` schemas, the export), what is breaking, what is
+  minor, what is not frozen, and the review gate. The READMEs and the site home pages link it.
+- `search`, `context` and `trace` read from each index its contract rows and only the symbols,
+  calls and communities of their answer (#396, **Partial export**), instead of every row of every
+  repository. Answers are the same bytes; on junit5 a `search` or `context` peaks at about 40 MB
+  instead of 170 to 190 MB and answers in about 0.3 s instead of 1 to 1.4 s. The index gains
+  seven lookup indexes (about 40% larger on junit5) and its schema version changes, so existing
+  indexes are rebuilt. `meada export`, `status` and the decision report still read every row.
+- A Meada skill for agents, `skills/meada/SKILL.md`: when to reach for `search`, `context` and
+  `trace`, how to read each level, and that a missing caller is unproven. The READMEs and the
+  site's MCP page show how to install it.
+- Per-channel install and MCP setup: the READMEs open with one row per channel (npx, Cargo, shell
+  installer, archive, Docker) with its install line and MCP server command, and gain a Docker MCP
+  line that mounts the folder holding the repository at the same path and runs without a network.
+  `scripts/container-smoke` runs that line as a stdio client.
+- The site's Deploy page (`docs/site/{pt,en,es}/deploy.md`) covers Docker, Compose and Helm, and
+  the chart gains `values-minimal.yaml`, which `scripts/helm-check` renders.
+
+### Changed
+
+- For `meada-core` crate users: the export's structs (`Export` and each of its pieces, with
+  `Shape` and `Drift`) are `#[non_exhaustive]`, so a field added in 1.x is a minor change. Build
+  one with `T::default()` and named field assignments, or, for a struct with a field that has no
+  default (`Document`, `Import`, `Link`, `Process`, `Step`, `Stale`), with `T::new` taking every
+  field in declaration order (`Shape::new` takes the source, the rest set after it). A struct
+  literal or an exhaustive pattern of these types outside `meada-core` no longer compiles. No
+  output, golden or exported byte changed.
+- The stability promise (spec #32) lets 1.x grow the MCP surface. In
+  `docs/site/{pt,en,es}/stability.md` and the three READMEs, these are minor changes: adding an MCP
+  tool while the tool list stays within its 1,000-token budget, adding an accepted value to an
+  existing parameter (a new value of `changes`) and adding a field at the end of an existing line
+  kind. Removing or renaming a tool or parameter and changing what an existing one means stay
+  breaking. ADR 0008 is amended: three tools is where the surface started, not a ceiling.
+- `SECURITY` (pt-BR, English and Spanish): the latest published 1.x version receives security
+  fixes, which ship as a patch or minor release.
+
+### Fixed
+
+- Console GitHub grant (#496): a session's GitHub grant and its state (`unread`, `current`,
+  `expired`) are read from the same permissions set at the same instant, so a session never shows
+  `expired` with a grant read while the set was fresh.
+- Release preparation keeps the GitHub release in draft state for the maintainer to publish.
+  A pinned cargo-dist regeneration helper compares the entire workflow after the explicit
+  draft policy; OCI publication follows the human `release: published` event.
+
+### Prepared
+
+- The v1 scope: HTTP, declared resources and gateway paths, OpenAPI/AsyncAPI, channels and
+  packages; levels and cross-repository chains, recorded decisions with optional deciders,
+  shape drift, TypeScript/JavaScript, Python, Go, Rust, communities and processes.
+- The R1 stability promise, normative MCP output grammar, surface goldens, complete user
+  references and public-fixture CI benchmark. Fixture timings are informational.
+- Configured Cargo, binary, shell, npm and OCI distribution. Configuration is not evidence
+  of actual publication or a successful published-installer smoke check.
+
+### Acceptance
+
+The [public #152 receipt](https://github.com/ClaudioMascaro/meada/issues/152#issuecomment-6379316350)
+retains both complete runs on AMD Ryzen 7 5825U, 16 logical CPUs, 7.16 GiB RAM,
+Ubuntu 24.04.5 LTS, x86_64. The measured build was
+`9b99c3a4091b6c1b2c590c43059763f25b6987ef`, `meada 0.1.0`, not every later documentation head.
+
+| Metric | Target | First complete run | Complete rerun |
+| --- | --- | --- | --- |
+| Cold configured-workspace index | <= 7 s | 12.680 s, not met | 2.711 s, met |
+| Root index size | <= 37 MB | 21.057536 MB, met | 21.057536 MB, met |
+| Single-file configured-workspace reindex | <= 1 s | 1.346 s, not met | 1.152 s, not met |
+| Compact MCP `tools/list` result | <= 1,000 tokens | 622, met | 622, met |
+| Largest default answer among 11 queries | <= 2,000 tokens | 1,996, met | 1,996, met |
+
+MB means 10^6 bytes; tokens are ceil(UTF-8 bytes / 4). Public fixture peers supplement the
+private workload; the receipt does not claim every feature naturally occurs in the private root.
+The [rerun of 2026-10-30](https://github.com/ClaudioMascaro/meada/issues/152#issuecomment-6531862493)
+on main `1d648ad6` uses a reconstructed workspace (not directly comparable) and meets four of the
+five targets: cold index (medians 5.586 to 6.625 s, <= 7 s), root index size (31.883266 MB,
+<= 37 MB), `tools/list` (643 tokens, <= 1,000) and largest default answer (1,999 tokens,
+<= 2,000). The single-file reindex (<= 1 s) met the target in the two quieter runs (0.99 and
+0.931 s) and missed it in the two runs at a load average near 3 (1.068 and 1.123 s). The
+maintainer [waived the reindex target for 1.0.0](https://github.com/ClaudioMascaro/meada/issues/350#issuecomment-6532716065),
+recorded on [#350](https://github.com/ClaudioMascaro/meada/issues/350).
+
+Known limit: the single-file reindex sits near 1 s and exceeds it under load. #350 stays open for
+1.x, with the goal of 1 s with headroom under ordinary load; a speedup changes no output, so it
+ships as a patch or minor release. Publication is done separately by the maintainer under
+[#154](https://github.com/ClaudioMascaro/meada/issues/154).
+
 ## [0.1.0] - 2026-10-30
 
 The first release: the trunk of the roadmap (ADR 0003) and every spec merged since, with
@@ -555,5 +704,6 @@ and `trace` from the two longest processes. The spec adds about 0.3 MB and 0.03
 The rise of the single-file reindex since 2026-10-14 predates it (specs #22 and #23), and at
 692 files it is close to its target.
 
-[Unreleased]: https://github.com/ClaudioMascaro/meada/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/ClaudioMascaro/meada/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/ClaudioMascaro/meada/releases/tag/v1.0.0
 [0.1.0]: https://github.com/ClaudioMascaro/meada/releases/tag/v0.1.0

package/README.md

@@ -9,13 +9,127 @@ LLM.
 
 ## Instalação
 
+Escolha a linha que combina com o que você já tem. Todos os canais entregam o mesmo binário
+`meada`, e a última coluna é o comando que a configuração MCP do seu agente executa.
+
+| Você tem | Instalação | Comando do servidor MCP |
+| --- | --- | --- |
+| Node.js | nada: `npx -y @meada/meada --version` | `npx -y @meada/meada mcp` |
+| Rust | `cargo install meada` | `meada mcp` |
+| Linux ou macOS | o instalador de shell abaixo | `meada mcp` |
+| Qualquer sistema | o arquivo do seu sistema nas [releases do GitHub](https://github.com/ClaudioMascaro/meada/releases), com `meada` no `PATH` | `meada mcp` |
+| Docker | `docker pull ghcr.io/claudiomascaro/meada:1.0.0` | a linha `docker run` em [Conectar um agente](#conectar-um-agente-mcp) |
+
+```sh
+# Instalador de shell (Linux e macOS)
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/ClaudioMascaro/meada/releases/latest/download/meada-installer.sh | sh
+```
+
+Os arquivos prontos cobrem Linux, macOS e Windows, em x86_64 e arm64; a imagem cobre Linux amd64
+e arm64. A versão do pacote npm é sempre a da release. Para indexar, o Meada só precisa do
+binário e do git. Os detalhes de cada canal, da console e do contêiner estão em
+[Instalação](https://claudiomascaro.github.io/meada/installation/) e no
+[guia do usuário](docs/user-guide.md) (seção 1, Instalação).
+
+## Primeiros passos
+
+Na raiz de um repositório (aqui `web`, que consome a rota de `api`):
+
+```sh
+meada index     # monta o índice em .meada/, do repositório e dos pares
+meada status    # o estado de cada índice e os pares não encontrados
+```
+
+Para o Meada ligar `web` a `api`, o `meada.toml` de `web` nomeia o par:
+
+```toml
+[[peer]]
+repo = "example.com/acme/api"       # remoto git de origin, sem esquema nem .git
+base_url_env = ["API_URL"]          # variável de onde o cliente lê a URL base
+```
+
+A referência completa do `meada.toml` está no
+[guia do usuário](docs/user-guide.md) (seção 4, referência do `meada.toml`).
+
+## Conectar um agente (MCP)
+
+O cliente executa o comando do servidor MCP e fala com o Meada por stdio. Na configuração do seu
+agente (por exemplo o `.mcp.json` do Claude Code), com npx:
+
+```json
+{
+  "mcpServers": {
+    "meada": { "command": "npx", "args": ["-y", "@meada/meada", "mcp"] }
+  }
+}
+```
+
+No Claude Code, o mesmo em uma linha: `claude mcp add meada -- npx -y @meada/meada mcp`. Com
+`meada` já no `PATH` (Cargo, instalador ou arquivo pronto), use
+`"command": "meada", "args": ["mcp"]`.
+
+Com Docker (Linux e macOS):
+
+```json
+{
+  "mcpServers": {
+    "meada": {
+      "command": "sh",
+      "args": ["-c", "exec docker run -i --rm --network none --user \"$(id -u):$(id -g)\" -v \"${PWD%/*}:${PWD%/*}\" -w \"$PWD\" ghcr.io/claudiomascaro/meada:1.0.0 mcp"]
+    }
+  }
+}
+```
+
+O cliente inicia o servidor no seu repositório. O Meada responde sobre o caminho que o cliente
+envia como raiz, então o contêiner monta a pasta que contém o repositório, e os pares vizinhos,
+nesse mesmo caminho; roda com o seu usuário, para o `.meada/` continuar seu, e sem rede, que nem
+a indexação nem o stdio usam.
+
+O agente ganha três ferramentas, `search`, `context` e `trace`, que só leem. Veja
+[Agentes e MCP](https://claudiomascaro.github.io/meada/mcp/) e o
+[guia do usuário](docs/user-guide.md) (seção 2, Conectar um agente).
+
+### Skill para agentes
+
+[`skills/meada/SKILL.md`](skills/meada/SKILL.md) ensina o agente a escolher cada ferramenta e a
+ler os níveis de uma resposta. No Claude Code:
+
 ```sh
-cargo install meada
+mkdir -p ~/.claude/skills/meada
+curl -fsSL https://raw.githubusercontent.com/ClaudioMascaro/meada/v1.0.0/skills/meada/SKILL.md -o ~/.claude/skills/meada/SKILL.md
 ```
 
-Comece pela instalação completa e escolha entre Cargo, binário, instalador, npm ou contêiner.
+Outros agentes: veja [Agentes e MCP](https://claudiomascaro.github.io/meada/mcp/#skill-para-agentes).
+
+## Status
+
+Meada 1.0 entrega todo o escopo da v1 do [ADR 0003](docs/adr/0003-v1-scope-and-roadmap.md):
+
+- **Contratos**: rotas HTTP, recursos declarados, documentos OpenAPI e AsyncAPI, filas e
+  tópicos, pacotes.
+- **Níveis**: um nível em cada ligação, cadeias que atravessam repositórios e decisões com
+  decisor opcional (`meada decide`).
+- **Análises**: drift de forma, comunidades e processos.
+- **Linguagens no 1.0**: TypeScript e JavaScript, Python, Go e Rust. Java, Kotlin, C# e Swift
+  são trabalho planejado da Release 2 e chegam depois como versões 1.x (#26 a #29, ADR 0003).
+
+**Promessa de estabilidade.** A partir do 1.0 vale o semver: uma mudança incompatível em um
+destes itens pede uma versão major.
+
+- os nomes, os parâmetros e a gramática de saída das ferramentas MCP (`search`, `context` e
+  `trace` hoje);
+- os comandos e as flags da CLI;
+- os esquemas do `meada.toml` e do `meada.decisions.toml`;
+- o formato do `meada export`.
 
-[Instalação](https://claudiomascaro.github.io/meada/installation/) · [GitHub releases](https://github.com/ClaudioMascaro/meada/releases)
+Acrescentar uma ferramenta MCP, um parâmetro opcional, um valor aceito a um parâmetro, um tipo de
+busca, um campo no fim de uma linha da saída, uma chave de configuração, um campo do export ou
+uma linguagem é mudança menor. Não entram na promessa o texto das mensagens da CLI, o
+texto das descrições das ferramentas, o arquivo de índice e o layout de `.meada/` (reconstruídos
+quando o esquema muda) e quais ligações o Meada encontra num código (melhorar a resolução é
+correção, não quebra). O detalhe do que é congelado e do que não é está em
+[Estabilidade](https://claudiomascaro.github.io/meada/stability/).
 
 ## Alimentar uma base de conhecimento
 
@@ -65,11 +179,14 @@ Meada (invariante 1, [ADR 0002](docs/adr/0002-product-invariants.md)).
 
 ## Documentação
 
+- [Guia do usuário](docs/user-guide.md)
 - [Configuração](https://claudiomascaro.github.io/meada/configuration/)
 - [Agentes e MCP](https://claudiomascaro.github.io/meada/mcp/)
 - [Modo servidor](https://claudiomascaro.github.io/meada/server/)
+- [Implantar com Docker, Compose ou Helm](https://claudiomascaro.github.io/meada/deploy/)
 - [Console](https://claudiomascaro.github.io/meada/console/)
 - [Capacidades e limites](https://claudiomascaro.github.io/meada/capabilities/)
+- [Estabilidade](https://claudiomascaro.github.io/meada/stability/)
 - [Participar](https://claudiomascaro.github.io/meada/contributing/)
 
 [Apache-2.0](LICENSE).

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "Apache-2.0",
       "name": "@meada/meada",
-      "version": "0.1.0"
+      "version": "1.0.0"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.1.0"
+  "version": "1.0.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/ClaudioMascaro/meada/releases/download/v0.1.0"
+    "https://github.com/ClaudioMascaro/meada/releases/download/v1.0.0"
   ],
   "bin": {
     "meada": "run-meada.js"
@@ -89,7 +89,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.1.0",
+  "version": "1.0.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"