feat: ship yool tuple hamt scaffold

.catalog/.gitkeep

@@ -0,0 +1 @@
+

.github/copilot-instructions.md

@@ -3,6 +3,10 @@
 > Instruction file lido automaticamente pelo **GitHub Copilot Chat** e **Copilot Workspace / Agent Mode**. Espelha [AGENTS.md](../AGENTS.md) com foco em **Agent Mode workflow**.
 >
 > Ao trabalhar em Agent Mode, o Copilot pode delegar pra custom agents em [`.agents/`](../.agents/) (canônico, padrão AGENTS.md ecosystem) e/ou em `.github/copilot/agents/` (mirror lido pelo Copilot Coding Agent). Lista atual: `tdd.agent.md`, `reviewer.agent.md`, `architect.agent.md`.
+>
+> Canonical pattern spec: [YOOL_TUPLE_HAMT.md](../YOOL_TUPLE_HAMT.md)
+>
+> Receipt schema reference: [YOOL_TUPLE_HAMT.md §1.8.4](../YOOL_TUPLE_HAMT.md#184-receipt-schema-reference)
 
 ---
 
@@ -173,6 +177,32 @@ Detalhes em `.skills/README.md`.
 
 ---
 
+## yool / tuple / HAMT
+
+Spec: [YOOL_TUPLE_HAMT.md](../YOOL_TUPLE_HAMT.md).
+
+Required agent fields:
+
+```markdown
+- yool_id: `agent.dev.python.v1`
+- authority: dev | ops | review | audit
+- lane: fast | slow | background
+- agent_terms:
+    cpu_quota_pct: 60
+    disk_quota_mb: 100
+    timeout_s: 300
+```
+
+Receipts live under `.receipts/` and should follow the canonical schema in [YOOL_TUPLE_HAMT.md §1.8.4](../YOOL_TUPLE_HAMT.md#184-receipt-schema-reference).
+
+Build the HAMT catalog with:
+
+```bash
+node bin/build-hamt-catalog --source AGENTS.md --output .catalog/agents.json
+```
+
+---
+
 ## Comandos especiais
 
 ### Criar nova ADR

.gitignore

@@ -63,6 +63,10 @@ Thumbs.db
 *.tar.gz
 .pnpm-store/
 
+# Runtime receipts
+.receipts/**
+!.receipts/.gitkeep
+
 # LLM Project Mapper tracked files
 .starter-meta.json
 .claude/settings.local.json
@@ -85,10 +89,13 @@ _BOOTSTRAP.md
 docs/**
 !docs/YOOL_TUPLE_HAMT.md
 scripts/**
+!scripts/build_hamt.py
 playwright-report/**
 tests/**
 !tests/unit/
 !tests/unit/*.test.js
+!tests/e2e/
+!tests/e2e/*.spec.ts
 test-results/**
 coverage/**
 bootstrap.ps1

AGENTS.md

@@ -1,5 +1,9 @@
 # AGENTS.md
 
+> Canonical pattern spec: [YOOL_TUPLE_HAMT.md](YOOL_TUPLE_HAMT.md)
+>
+> Receipt schema reference: [YOOL_TUPLE_HAMT.md §1.8.4](YOOL_TUPLE_HAMT.md#184-receipt-schema-reference)
+
 ## Operational Context
 
 Before changing code, agents should check the project-specific operational docs:
@@ -327,7 +331,7 @@ npm run lint && npm test -- --coverage && npx playwright test
 <!-- yool-tuple-hamt:start -->
 ## yool / tuple / HAMT (capability addressing)
 
-Spec: `docs/YOOL_TUPLE_HAMT.md` (vendored from https://github.com/wesleysimplicio/yool-tuple-hamt, version v0.2).
+Spec: [`YOOL_TUPLE_HAMT.md`](YOOL_TUPLE_HAMT.md) (vendored from https://github.com/wesleysimplicio/yool-tuple-hamt, version v0.2).
 
 Every agent registered in this repo MUST declare its capability with the following fields (header `### <Agent Name>` followed by frontmatter-style lines):
 
@@ -351,10 +355,33 @@ Why these fields exist:
 - `agent_terms.cpu_quota_pct` — soft throttle via `os.nice` or cgroups. Per Victor Genaro's guardrail: *"precisa de guardrail pra não fritar o processador."*
 - `agent_terms.disk_quota_mb` — local disk cap before GC kicks in. Per the same review: *"você precisa de garbage collector também pra não encher 100% do disco."*
 
+### Receipts schema
+
+Every repo using this pattern should keep execution receipts under `.receipts/` and treat them as append-only execution evidence, not ad-hoc logs.
+
+Minimum receipt contract:
+
+```json
+{
+  "id": "sha256:<content-hash>",
+  "tuple_id": "sha256:<tuple-hash>",
+  "yool_id": "agent.dev.python",
+  "status": "ok",
+  "created_at": "2026-05-19T17:30:00Z",
+  "artifacts": [],
+  "cost": {
+    "tokens": 0,
+    "usd": 0
+  }
+}
+```
+
+Canonical source for receipt semantics, retention, and catalog placement: [YOOL_TUPLE_HAMT.md §1.8.4](YOOL_TUPLE_HAMT.md#184-receipt-schema-reference).
+
 Build the HAMT catalog with:
 
 ```bash
-node bin/build-hamt-catalog --source AGENTS.md --output .catalog/hamt.json
+node bin/build-hamt-catalog --source AGENTS.md --output .catalog/agents.json
 ```
 
 Without all four fields, the catalog build skips the entry. CI gate enforces full population for any new agent declaration.

CHANGELOG.md

@@ -6,6 +6,16 @@ Format follows [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/) an
 
 ## [Unreleased]
 
+### Added
+- Root-level `YOOL_TUPLE_HAMT.md` vendored alongside the existing `docs/` copy so the canonical pattern spec is reachable directly from the repository root and ships with the npm package.
+- `build-hamt-catalog` wrapper plus stdlib-only `scripts/build_hamt.py`, enabling `npx @wesleysimplicio/llm-project-mapper build-hamt-catalog` to emit `.catalog/agents.json`.
+- Runtime scaffold defaults for `.catalog/.gitkeep`, `.catalog/agents.json`, `.receipts/.gitkeep`, and optional `mcp/server.{ts,py}` edge adapters via `--mcp-edge`.
+- Dedicated docs-site coverage for YOOL / tuple / HAMT, including the public `/yool-tuple-hamt` route and regression tests for the new page.
+
+### Changed
+- `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md` now point to the root spec, document the receipts schema, and align the generated catalog output on `.catalog/agents.json`.
+- The Node bootstrap path now mirrors the shell/PowerShell runtime scaffold so fresh `npx` installs create the catalog, receipts, and optional MCP edge templates consistently.
+
 ## [0.4.2] - 2026-05-19
 
 ### Added

CLAUDE.md

@@ -1,6 +1,10 @@
 # CLAUDE.md
 
 > Este arquivo espelha [AGENTS.md](./AGENTS.md). Edite ambos juntos OU mantenha apenas `AGENTS.md` e symlink `CLAUDE.md` -> `AGENTS.md` (`ln -sf AGENTS.md CLAUDE.md`). O Claude Code lê arquivo regular, não símbolo.
+>
+> Canonical pattern spec: [YOOL_TUPLE_HAMT.md](YOOL_TUPLE_HAMT.md)
+>
+> Receipt schema reference: [YOOL_TUPLE_HAMT.md §1.8.4](YOOL_TUPLE_HAMT.md#184-receipt-schema-reference)
 
 ---
 
@@ -333,7 +337,7 @@ npm run lint && npm test -- --coverage && npx playwright test
 <!-- codex-long-running-agent-overlay:start -->
 ## yool / tuple / HAMT (capability addressing)
 
-Spec: `docs/YOOL_TUPLE_HAMT.md` (vendored from https://github.com/wesleysimplicio/yool-tuple-hamt, version v0.2).
+Spec: [`YOOL_TUPLE_HAMT.md`](YOOL_TUPLE_HAMT.md) (vendored from https://github.com/wesleysimplicio/yool-tuple-hamt, version v0.2).
 
 Every agent registered in this repo MUST declare its capability with the following fields (header `### <Agent Name>` followed by frontmatter-style lines):
 
@@ -351,10 +355,33 @@ Every agent registered in this repo MUST declare its capability with the followi
 
 Guardrails are MANDATORY per Victor Genaro's review: *"precisa de guardrail pra não fritar o processador. Você precisa de garbage collector também pra não encher 100% do disco."* See spec §11.
 
+### Receipts schema
+
+Every repo using this pattern should keep execution receipts under `.receipts/` and treat them as append-only execution evidence, not ad-hoc logs.
+
+Minimum receipt contract:
+
+```json
+{
+  "id": "sha256:<content-hash>",
+  "tuple_id": "sha256:<tuple-hash>",
+  "yool_id": "agent.dev.python",
+  "status": "ok",
+  "created_at": "2026-05-19T17:30:00Z",
+  "artifacts": [],
+  "cost": {
+    "tokens": 0,
+    "usd": 0
+  }
+}
+```
+
+Canonical source for receipt semantics, retention, and catalog placement: [YOOL_TUPLE_HAMT.md §1.8.4](YOOL_TUPLE_HAMT.md#184-receipt-schema-reference).
+
 Build the HAMT catalog with:
 
 ```bash
-node bin/build-hamt-catalog --source AGENTS.md --output .catalog/hamt.json
+node bin/build-hamt-catalog --source AGENTS.md --output .catalog/agents.json
 ```
 
 ---

INIT.md

@@ -21,7 +21,8 @@ Antes de qualquer Write/Edit, leia `.starter-meta.json` na raiz do repo. Ele é
   "domain": "...",
   "stack": "...",
   "bootstrapped_at": "2026-05-08T19:45:00Z",
-  "starter_version": "0.2.0",
+  "starter_version": "0.4.0",
+  "mcp_edge_enabled": false,
   "existing_instruction_files": [".github/copilot-instructions.md"],
   "init_must_ask":   ["team", "domain", "vision_oneliner", "primary_personas"],
   "init_must_merge": [".github/copilot-instructions.md"],
@@ -56,6 +57,21 @@ playwright.config.ts (apenas se ainda não existe ou se é template nosso)
 
 Caminho fora dessa whitelist **e** que não é arquivo do template original → não escreve.
 
+## Artefatos criados pelo bootstrap
+
+Além da whitelist acima, o bootstrap pode preparar estes artefatos de scaffold/runtime:
+
+- `.catalog/.gitkeep`
+- `.catalog/agents.json` — stub inicial do catálogo HAMT/YOOL; a versão populada vem do builder.
+- `.receipts/.gitkeep` — diretório local para receipts; o default é ficar gitignored.
+- `mcp/server.ts` e `mcp/server.py` — **somente** quando `.starter-meta.json.mcp_edge_enabled == true`.
+
+Regras específicas:
+
+- Preserve o bloco de aviso dos arquivos em `mcp/`: **MCP é borda/edge, não o loop interno dos agentes**.
+- Se `AGENTS.md` já trouxer campos `yool_id`, `authority`, `lane` e `agent_terms`, trate isso como contrato do catálogo; não remova nem “simplifique”.
+- `mcp/` só existe para `snapshot` e `dispatch` de borda sobre `.catalog/agents.json`; não enfie orquestração interna ali.
+
 ---
 
 ## Fluxo (5 fases — paraleliza tudo que dá)

README.md

@@ -36,6 +36,15 @@ Fill these files after installing the starter in a real project. The goal is to
 
 ---
 
+## Patterns
+
+- Canonical spec: [YOOL_TUPLE_HAMT.md](YOOL_TUPLE_HAMT.md)
+- Receipts schema and storage conventions: [Receipt schema](YOOL_TUPLE_HAMT.md#184-receipt-schema-reference)
+
+The yool / tuple / HAMT pattern is the capability-addressing model this scaffold is standardizing for multi-agent repos. Keep the root spec vendored so agents can reach it from the repository root in one click.
+
+---
+
 ## TL;DR — get going in 60 seconds
 
 Pick **one** of the install paths below and run it inside your project folder. The bootstrap now starts an automatic local mapping pass immediately; `INIT.md` becomes an optional refinement step for a stronger agent.

README.pt-BR.md

@@ -35,6 +35,15 @@ Preencha esses arquivos depois de instalar o starter em um projeto real. O objet
 
 ---
 
+## Padroes
+
+- Especificacao canonica: [YOOL_TUPLE_HAMT.md](YOOL_TUPLE_HAMT.md)
+- Esquema de receipts e convencoes de armazenamento: [Esquema de receipts](YOOL_TUPLE_HAMT.md#184-receipt-schema-reference)
+
+O padrao yool / tuple / HAMT define o modelo de enderecamento de capacidades que este scaffold passa a assumir para repositorios multiagente. Mantenha a especificacao vendorizada na raiz para que qualquer agente chegue nela em um clique a partir do repo.
+
+---
+
 ## TL;DR — começa em 60 segundos
 
 Escolha **um** caminho de instalação abaixo e rode dentro da pasta do projeto. O bootstrap agora inicia automaticamente um mapeamento local e preenche a primeira versão dos arquivos; o `INIT.md` vira uma etapa opcional de refinamento com agente.