@jaimevalasek/aioson 1.5.1 → 1.6.0

package/docs/pt/recuperacao-de-sessao.md

@@ -0,0 +1,125 @@
+# Recuperação de Sessão
+
+> Gera e restaura contexto entre sessões do Claude Code sem perder estado após compactação.
+
+Quando o LLM compacta o contexto durante uma sessão longa, o histórico de tarefas, objetivo e arquivos modificados se perde. O `recovery:generate` cria um arquivo markdown estruturado em `.aioson/context/recovery-context.md` que pode ser re-injetado no início da próxima sessão para restaurar exatamente onde você parou.
+
+---
+
+## Comandos
+
+### `recovery:generate`
+
+Gera o arquivo de recuperação para a sessão atual.
+
+```bash
+aioson recovery:generate [path] [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--goal="..."` | Objetivo atual da sessão |
+| `--agent="..."` | Agente ativo |
+| `--json` | Retorna resultado em JSON |
+
+**Exemplos:**
+
+```bash
+# Gerar recovery simples
+aioson recovery:generate .
+
+# Gerar com contexto da sessão
+aioson recovery:generate . --goal="implementar busca FTS5" --agent="deyvin"
+
+# Retornar JSON para scripts
+aioson recovery:generate . --json
+```
+
+---
+
+### `recovery:show`
+
+Exibe o conteúdo do arquivo de recuperação existente.
+
+```bash
+aioson recovery:show [path]
+```
+
+**Exemplos:**
+
+```bash
+# Ver o recovery atual
+aioson recovery:show .
+
+# Saída em JSON
+aioson recovery:show . --json
+```
+
+---
+
+## O que o arquivo contém
+
+O `recovery-context.md` é gerado automaticamente com:
+
+- **Objetivo da sessão** — o que foi passado via `--goal`
+- **Agente ativo** — o que foi passado via `--agent`
+- **Tarefas recentes** — lista de tasks com status
+- **Notas** — observações da sessão
+- **Arquivos modificados** — `git diff --name-only HEAD`
+- **Commits recentes** — últimos 10 commits do repositório
+
+O arquivo é salvo em `.aioson/context/recovery-context.md`.
+
+**Exemplo de arquivo gerado:**
+
+```markdown
+# Recovery Context — Direct Session
+> Generated: 2026-03-30T06:00:00.000Z
+
+## Current Goal
+implementar busca FTS5 e cache de contexto
+
+## Active Agent
+deyvin
+
+## Modified Files
+- src/context-search.js
+- src/context-cache.js
+- tests/context-search.test.js
+
+## Recent Commits
+- a1b2c3d Adicionar IndexManager com FTS5
+- d4e5f6g Implementar context cache RAM
+```
+
+---
+
+## Orçamento de tokens
+
+O arquivo é mantido abaixo de **2000 tokens** automaticamente. Se o conteúdo ultrapassar esse limite, os commits e eventos mais antigos são removidos — o objetivo, agente, arquivos modificados e tarefas são sempre preservados.
+
+---
+
+## Como usar após uma compactação
+
+Quando o Claude compactar o contexto da sessão, basta re-injetar o arquivo:
+
+```
+Read .aioson/context/recovery-context.md and continue from where we left off.
+```
+
+Ou usar o `recovery:show` para copiar o conteúdo direto:
+
+```bash
+aioson recovery:show .
+```
+
+---
+
+## Relação com squads
+
+O `recovery:generate` é específico para **sessões diretas** (sem squad). Para squads, o AIOSON já gera recovery automaticamente via `squad:recovery` quando detecta queda de 30% no uso de contexto.
+
+Para saber mais sobre recovery em squads, veja a documentação do [Squad Dashboard](./squad-dashboard.md).

package/docs/pt/sandbox.md

@@ -0,0 +1,125 @@
+# Sandbox de Execução
+
+> Executa comandos shell com timeout automático, redação de secrets e summarização de output longo.
+
+O `sandbox:exec` roda comandos em subprocesso isolado com três garantias: o comando é interrompido se passar do tempo máximo, qualquer secret reconhecido no output é redatado antes de ser exibido, e outputs maiores que 5KB são automaticamente resumidos mantendo início e fim.
+
+---
+
+## Comando
+
+### `sandbox:exec`
+
+```bash
+aioson sandbox:exec "<comando>" [opções]
+```
+
+**Opções:**
+
+| Opção | Descrição |
+|---|---|
+| `--timeout=<ms>` | Interromper após N milissegundos (padrão: 30000) |
+| `--cwd=<path>` | Diretório de trabalho do comando |
+| `--intent="..."` | Rótulo para output truncado (aparece na marcação de omissão) |
+| `--json` | Retorna stdout, stderr, exitCode e timedOut em JSON |
+
+**Exemplos:**
+
+```bash
+# Rodar testes com timeout de 60 segundos
+aioson sandbox:exec "npm test" --timeout=60000
+
+# Comando que pode exibir secrets (redatado automaticamente)
+aioson sandbox:exec "env | grep TOKEN"
+
+# Executar em outro diretório
+aioson sandbox:exec "npm run build" --cwd=./frontend
+
+# Capturar resultado estruturado
+aioson sandbox:exec "node -e 'console.log(JSON.stringify({ok:true}))'" --json
+```
+
+---
+
+## Redação automática de secrets
+
+O output é varrido automaticamente antes de ser exibido. Qualquer padrão reconhecido é substituído por `[REDACTED]`:
+
+| Padrão | Exemplo |
+|---|---|
+| GitHub token (`ghp_*`) | `ghp_abc123...` → `ghp_[REDACTED]` |
+| GitHub fine-grained (`github_pat_*`) | `github_pat_abc...` → `github_pat_[REDACTED]` |
+| AWS access key (`AKIA*`) | `AKIAIOSFODNN7EXAMPLE` → `AKIA[REDACTED]` |
+| Google OAuth (`ya29.*`) | `ya29.A0ARrd...` → `ya29.[REDACTED]` |
+| Bearer token | `Bearer eyJhb...` → `Bearer [REDACTED]` |
+| Senha em URL | `:minhasenha@host` → `:[REDACTED]@host` |
+| `password=...` | `password=abc123` → `password=[REDACTED]` |
+| `passwd=...` | `passwd=abc123` → `passwd=[REDACTED]` |
+| `secret=...` | `secret=xyz` → `secret=[REDACTED]` |
+| `api_key=...` | `api_key=sk-abc` → `api_key=[REDACTED]` |
+| Bloco de chave privada | `-----BEGIN PRIVATE KEY-----...` → `[REDACTED]` |
+
+A redação é aplicada tanto ao stdout quanto ao stderr.
+
+---
+
+## Timeout e interrupção
+
+O comando é encerrado com `AbortController` quando o timeout é atingido. O resultado retorna `timedOut: true` e `ok: false`.
+
+```bash
+# Vai ser interrompido após 500ms
+aioson sandbox:exec "sleep 10" --timeout=500
+```
+
+---
+
+## Summarização de output longo
+
+Se o output ultrapassar 5KB, a resposta mantém o início e o fim e indica quantos bytes foram omitidos:
+
+```
+[início do output...]
+
+[... 12.450 bytes omitted (npm test) ...]
+
+[...fim do output]
+```
+
+Use `--intent="..."` para que o rótulo apareça na marcação de omissão.
+
+---
+
+## JSON output
+
+```json
+{
+  "ok": true,
+  "stdout": "Tests: 42 passed\n",
+  "stderr": "",
+  "exitCode": 0,
+  "timedOut": false,
+  "signal": null
+}
+```
+
+Quando há timeout:
+
+```json
+{
+  "ok": false,
+  "stdout": "",
+  "stderr": "Command timed out after 500ms",
+  "exitCode": null,
+  "timedOut": true
+}
+```
+
+---
+
+## Quando usar
+
+- Rodar scripts ou testes dentro de uma sessão de agente sem expor secrets do ambiente
+- Capturar output de comandos que podem conter variáveis de ambiente sensíveis
+- Executar builds ou verificações com tempo máximo controlado
+- Testar comandos cujo output vai ser lido de volta pelo agente (redação evita envenenamento de contexto com secrets)

package/docs/pt/skills.md

@@ -36,19 +36,27 @@ Estrutura:
 │   ├── ethereum-docs.md
 │   ├── solana-docs.md
 │   └── cardano-docs.md
-└── design/          ← design systems visuais
-    ├── cognitive-core-ui/
-    ├── interface-design/
-    └── premium-command-center-ui/
+├── design/          ← design systems visuais
+│   ├── cognitive-core-ui/
+│   ├── interface-design/
+│   └── premium-command-center-ui/
+└── process/         ← metodologia de fluxo e contratos entre agentes
+    └── aioson-spec-driven/
 ```
 
 **Carregamento condicional:** O agente `@dev` carrega apenas as skills que correspondem ao valor de `framework` em `project.context.md`. Exemplo: se `framework=Laravel`, carrega `laravel-conventions.md` e opcionalmente `tall-stack-patterns.md` se o stack for TALL.
 
+**Process skills** são carregadas pelos agentes de spec (`@product`, `@analyst`, `@architect`, `@sheldon`, `@dev`, `@deyvin`) no início de sessões de especificação, requirements e design — nunca todas de uma vez. Cada agente carrega o `SKILL.md` central e depois apenas o arquivo de `references/` relevante para sua fase atual.
+
 ### Skills instaladas (`.aioson/installed-skills/`)
 
-Skills de terceiros instaladas pelo usuário. São **versionadas com o projeto** (não gitignored), permitindo que toda a equipe use as mesmas skills.
+Skills versionadas com o projeto. Entram aqui em dois casos:
+
+- skills de terceiros instaladas pelo usuário via CLI
+- skills locais geradas dentro do próprio projeto por agentes/process skills
 
 Cada skill instalada contém um `SKILL.md` com frontmatter YAML descrevendo quando usá-la.
+Quando existir, o arquivo `.skill-meta.json` registra origem, autor e metadados do gerador/modelo.
 
 ## Instalando skills
 
@@ -61,7 +69,7 @@ aioson skill:install @tech-leads-club/agent-skills --skill coupling-analysis
 Isso:
 1. Baixa o pacote npm temporariamente
 2. Copia a skill para `.aioson/installed-skills/{nome}/`
-3. Distribui para ferramentas nativas (`.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`)
+3. Distribui recursivamente para ferramentas nativas (`.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`)
 4. Registra a skill na seção "Installed skills" do `AGENTS.md`
 
 ### Via aioson.com (registry cloud)
@@ -89,6 +97,7 @@ aioson skill:list
 ```
 
 Mostra todas as skills em `.aioson/installed-skills/` com nome, descrição e fonte.
+Quando a metadata existir, também pode mostrar autor e modelo gerador.
 
 ### Remover uma skill
 
@@ -150,6 +159,89 @@ Skills de design disponíveis:
 - `interface-design` — Design de interfaces (dashboards, apps, ferramentas)
 - `premium-command-center-ui` — UI premium para command centers
 
+## Skills de processo
+
+Skills de processo ensinam os agentes **como as fases do AIOSON se conectam** — não o que implementar, mas como sequenciar, quando aprofundar e como fazer handoff limpo entre agentes.
+
+Diferente das skills de framework (que são por stack) e das skills de design (que são por sistema visual), process skills são transversais: carregadas por qualquer agente de spec conforme a fase em que ele se encontra.
+
+### `aioson-spec-driven`
+
+Localização: `.aioson/skills/process/aioson-spec-driven/`
+
+A skill central de metodologia do AIOSON. Cobre:
+
+- **Sequência de fases** — quais fases existem, quais artefatos cada uma produz e quem é o agente responsável
+- **Profundidade por classificação** — MICRO usa fluxo mínimo, SMALL usa fluxo padrão, MEDIUM usa pacote completo
+- **Gates de aprovação** — Gate A (requirements), Gate B (design), Gate C (plan) — critérios do que deve estar pronto antes de avançar para a próxima fase
+- **Hardening lane** — como identificar quando um input ainda está em modo "exploratório/vibe" e o que fazer para convertê-lo em spec executável
+- **Manutenção e estado** — como escrever checkpoints úteis em `spec-{slug}.md` para que qualquer agente ou sessão futura possa retomar sem redescobrir o que já foi decidido
+
+**Estrutura:**
+
+```
+.aioson/skills/process/aioson-spec-driven/
+├── SKILL.md                          ← entry point curto — carregue sempre primeiro
+└── references/
+    ├── artifact-map.md               ← qual artefato fica onde e quem é o dono
+    ├── classification-map.md         ← profundidade de fase por MICRO/SMALL/MEDIUM
+    ├── approval-gates.md             ← critérios dos Gates A, B e C
+    ├── hardening-lane.md             ← quando endurecer vs quando explorar
+    └── maintenance-and-state.md      ← como escrever spec e checkpoints úteis
+```
+
+**Carregamento:** Os agentes `@product`, `@analyst`, `@architect`, `@sheldon`, `@dev` e `@deyvin` verificam automaticamente se esta skill está disponível e carregam `SKILL.md` + apenas o arquivo de `references/` relevante para a fase atual. Nunca carregam a pasta inteira de uma vez.
+
+### `design-hybrid-forge`
+
+Localização: `.aioson/skills/process/design-hybrid-forge/`
+
+Skill first-party para criar uma nova skill de design híbrida a partir de **2 skills primárias obrigatórias** e, opcionalmente, até 2 modificadores de escopo limitado. Em modo avançado, pode liberar um 3º modificador, ainda preso a lanes secundárias.
+
+Se você quer o fluxo completo em um só lugar, leia a página dedicada: [design-hybrid-forge](./design-hybrid-forge.md).
+
+Fluxo padrão:
+
+1. O usuário ativa `@design-hybrid-forge` no Codex ou `/design-hybrid-forge` no Claude
+2. Se quiser um overlay visual mais ousado, o usuário pode rodar `aioson design-hybrid:options` para gerar `.aioson/context/design-variation-preset.md`
+3. O comando usa `conversation_language` do projeto quando existir; `--locale` funciona como override manual
+4. O agente pede as 2 skills primárias, até 2 modificadores opcionais e lê o preset visual quando ele existir
+5. Se o usuário tiver criado o preset com `--advanced`, o agente pode aceitar um 3º modificador de escopo estreito
+6. O híbrido é gerado em `.aioson/installed-skills/{slug}/`
+7. O `AGENTS.md` é atualizado para que o Codex possa usar `@{slug}`
+8. O pacote também pode ser espelhado para `.claude/skills/`, `.cursor/skills/` e `.windsurf/skills/`
+
+Saída padrão:
+
+```
+.aioson/installed-skills/{slug}/
+  SKILL.md
+  .skill-meta.json
+  references/
+  previews/
+```
+
+Esse fluxo cria uma **skill local do projeto**. Se depois você quiser promover a skill para o core do AIOSON ou para um marketplace, trate isso como uma segunda etapa de curadoria, separada da geração local.
+
+O preset criado em `.aioson/context/design-variation-preset.md` é **temporário**:
+- ele serve como input para a próxima geração híbrida
+- depois da geração, deve ser removido ou movido do contexto ativo
+- uma cópia histórica fica em `.aioson/context/history/design-variation-presets/`
+- ele não redefine o layout padrão do projeto; quem continua mandando no projeto é a `design_skill` ativa
+
+O preset gerado por `design-hybrid:options` cobre direções como:
+- clássico / editorial
+- extravagante / maximalista
+- cinematográfico / imersivo
+- retrofuturista
+- motion-driven
+- CSS avançado (scroll-driven animations, View Transition API, masks, SVG filters, 3D)
+
+Recomendação de uso:
+- fluxo normal: até 2 modificadores
+- fluxo avançado: `aioson design-hybrid:options --advanced` para permitir até 3 modificadores
+- mesmo no modo avançado, modificadores não podem dominar substrato nem estrutura
+
 ## Skills de squad
 
 Squads podem ter suas próprias skills em `.aioson/squads/{squad-slug}/skills/`. Essas são carregadas automaticamente quando a tarefa pertence ao escopo do squad.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",

package/src/agent-loader.js

@@ -0,0 +1,280 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { IndexManager } = require('./context-search');
+
+const SHARD_SEARCH_DIR = path.join(os.homedir(), '.aioson', 'shards');
+const MAX_SHARD_TOKENS = 2000;
+const DEFAULT_SHARDS = 3;
+
+function estimateTokens(str) {
+  return Math.ceil(str.length / 4);
+}
+
+/**
+ * Split a markdown document into semantic shards by H2/H3 headings.
+ * Each shard = heading + its content until the next heading.
+ *
+ * @param {string} content — raw markdown
+ * @param {string} agentId — used to label shards
+ * @returns {Array<{id, heading, level, content, tokens}>}
+ */
+function shardMarkdown(content, agentId) {
+  const lines = content.split('\n');
+  const shards = [];
+  let currentHeading = '(preamble)';
+  let currentLevel = 1;
+  let currentLines = [];
+  let shardIndex = 0;
+
+  function flushShard() {
+    const text = currentLines.join('\n').trim();
+    if (!text) return;
+    const tokens = estimateTokens(text);
+    shards.push({
+      id: `${agentId}:shard:${shardIndex}`,
+      heading: currentHeading,
+      level: currentLevel,
+      content: text,
+      tokens
+    });
+    shardIndex++;
+  }
+
+  for (const line of lines) {
+    const h2 = line.match(/^##\s+(.+)/);
+    const h3 = line.match(/^###\s+(.+)/);
+
+    if (h2 || h3) {
+      flushShard();
+      currentHeading = (h2 || h3)[1].trim();
+      currentLevel = h2 ? 2 : 3;
+      currentLines = [line];
+    } else {
+      currentLines.push(line);
+    }
+  }
+
+  flushShard();
+  return shards;
+}
+
+/**
+ * Agent shard loader — indexes agent instruction files as shards
+ * and loads only the relevant ones based on a goal query.
+ */
+class AgentLoader {
+  constructor(opts = {}) {
+    this._searchDir = opts.searchDir || SHARD_SEARCH_DIR;
+    this._idx = null;
+    this._shardMap = new Map(); // id → shard content
+  }
+
+  async open() {
+    this._idx = new IndexManager(this._searchDir);
+    await this._idx.open();
+    return this;
+  }
+
+  close() {
+    if (this._idx) {
+      this._idx.close();
+      this._idx = null;
+    }
+  }
+
+  /**
+   * Index a single agent instruction file as shards.
+   * @param {string} filePath — absolute path to agent .md file
+   * @param {string} agentId
+   * @param {object} opts — { force? }
+   */
+  async indexAgentFile(filePath, agentId, opts = {}) {
+    const content = await fs.readFile(filePath, 'utf8');
+    const shards = shardMarkdown(content, agentId);
+
+    // Write individual shard files to a temp dir for FTS5 indexing
+    const shardDir = path.join(this._searchDir, 'agent-shards', agentId);
+    await fs.mkdir(shardDir, { recursive: true });
+
+    for (const shard of shards) {
+      const shardFile = path.join(shardDir, `${shard.id.replace(/:/g, '_')}.md`);
+      const shardContent = `# ${shard.heading}\n\n${shard.content}`;
+      await fs.writeFile(shardFile, shardContent, 'utf8');
+      // Keep content in memory for fast retrieval
+      this._shardMap.set(shard.id, shard);
+    }
+
+    // Index the shard dir
+    await this._idx.indexDirectory(shardDir, { force: opts.force !== false });
+
+    return { agentId, shards: shards.length };
+  }
+
+  /**
+   * Index an entire agents directory.
+   * @param {string} agentsDir — directory containing agent .md files
+   * @param {object} opts — { force? }
+   * @returns {{ agents: number, totalShards: number }}
+   */
+  async indexAgentsDir(agentsDir, opts = {}) {
+    let entries;
+    try {
+      entries = await fs.readdir(agentsDir, { withFileTypes: true });
+    } catch {
+      return { agents: 0, totalShards: 0 };
+    }
+
+    let agents = 0;
+    let totalShards = 0;
+
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (!entry.name.endsWith('.md')) continue;
+
+      const agentId = entry.name.replace(/\.md$/, '');
+      const filePath = path.join(agentsDir, entry.name);
+
+      try {
+        const result = await this.indexAgentFile(filePath, agentId, opts);
+        agents++;
+        totalShards += result.shards;
+      } catch {
+        // best-effort: skip unreadable files
+      }
+    }
+
+    return { agents, totalShards };
+  }
+
+  /**
+   * Load the most relevant shards for an agent given a goal query.
+   *
+   * Strategy:
+   * 1. Search FTS5 index for the goal query, filtered to agent shards
+   * 2. Always include H1/H2 "Role" and "preamble" shards
+   * 3. Fill remaining budget with ranked results
+   *
+   * @param {string} agentId
+   * @param {string} goal
+   * @param {object} opts — { maxShards?, maxTokens? }
+   * @returns {{ shards: Array, tokens: number, agentId: string }}
+   */
+  async loadRelevantShards(agentId, goal, opts = {}) {
+    const maxShards = opts.maxShards || DEFAULT_SHARDS;
+    const maxTokens = opts.maxTokens || MAX_SHARD_TOKENS;
+
+    // If shards aren't in memory (e.g., loaded from a previous session), load from disk
+    if (this._shardMap.size === 0) {
+      await this._loadShardsFromDisk(agentId);
+    }
+
+    const agentShards = [...this._shardMap.values()].filter(s => s.id.startsWith(`${agentId}:`));
+
+    if (agentShards.length === 0) {
+      return { shards: [], tokens: 0, agentId };
+    }
+
+    // Always include preamble/role shards
+    const priority = agentShards.filter(s =>
+      s.heading === '(preamble)' ||
+      /^role$/i.test(s.heading) ||
+      /^your role$/i.test(s.heading)
+    );
+
+    let selected = [...priority];
+    let usedTokens = selected.reduce((sum, s) => sum + s.tokens, 0);
+
+    // Search for relevant shards
+    if (goal && goal.trim()) {
+      const searchResults = this._idx.search(`${agentId} ${goal}`, { limit: maxShards + 2 });
+
+      for (const result of searchResults) {
+        if (selected.length >= maxShards) break;
+
+        // Match result back to shard via heading
+        const matchedShard = agentShards.find(s =>
+          result.relPath.includes(s.id.replace(/:/g, '_')) ||
+          s.heading.toLowerCase().includes(result.title.toLowerCase())
+        );
+
+        if (!matchedShard) continue;
+        if (selected.some(s => s.id === matchedShard.id)) continue;
+
+        if (usedTokens + matchedShard.tokens <= maxTokens) {
+          selected.push(matchedShard);
+          usedTokens += matchedShard.tokens;
+        }
+      }
+    }
+
+    // Fill with remaining shards if budget allows
+    if (selected.length < maxShards) {
+      for (const shard of agentShards) {
+        if (selected.length >= maxShards) break;
+        if (selected.some(s => s.id === shard.id)) continue;
+        if (usedTokens + shard.tokens <= maxTokens) {
+          selected.push(shard);
+          usedTokens += shard.tokens;
+        }
+      }
+    }
+
+    return {
+      agentId,
+      shards: selected,
+      tokens: usedTokens,
+      totalShards: agentShards.length
+    };
+  }
+
+  /**
+   * Load shards from disk (for cross-session use).
+   * @private
+   */
+  async _loadShardsFromDisk(agentId) {
+    const shardDir = path.join(this._searchDir, 'agent-shards', agentId);
+    let files;
+    try {
+      files = await fs.readdir(shardDir);
+    } catch {
+      return;
+    }
+
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue;
+      const filePath = path.join(shardDir, file);
+      try {
+        const content = await fs.readFile(filePath, 'utf8');
+        // Reconstruct shard id from filename
+        const id = file.replace(/\.md$/, '').replace(/_/g, ':');
+        const headingMatch = content.match(/^#\s+(.+)$/m);
+        const heading = headingMatch ? headingMatch[1] : '(unknown)';
+        const tokens = estimateTokens(content);
+        this._shardMap.set(id, { id, heading, level: 2, content, tokens });
+      } catch {
+        // skip
+      }
+    }
+  }
+
+  /**
+   * Build a merged context string from selected shards.
+   * @param {Array} shards
+   * @returns {string}
+   */
+  static buildContext(shards) {
+    return shards.map(s => s.content).join('\n\n---\n\n');
+  }
+
+  /**
+   * Return index statistics for all agent shards.
+   */
+  stats() {
+    return this._idx.stats();
+  }
+}
+
+module.exports = { AgentLoader, shardMarkdown };