@jaimevalasek/aioson 1.3.0 → 1.4.0

package/README.md

@@ -67,6 +67,13 @@ The npm package is scoped as `@jaimevalasek/aioson`, but the installed CLI comma
 - [`aioson agent:prompt`](docs/en/cli-reference.md#agentprompt) `<agent> [--tool=codex|claude|gemini|opencode]`
 - [`aioson workflow:plan`](docs/en/cli-reference.md#workflowplan) `[path] [--classification=MICRO|SMALL|MEDIUM] [--json]`
 
+**Tracked live sessions for external AI clients**
+- `aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<agent> [--plan=<file>] [--no-launch]`
+- `aioson runtime:emit [path] --agent=<agent> --type=task_started|task_completed|milestone|correction|block|plan_checkpoint --summary="..."`
+- `aioson live:handoff [path] --agent=<agent> --to=<next-agent> --reason="..."`
+- `aioson live:status [path] [--agent=<agent>] [--watch=2] [--json]`
+- `aioson live:close [path] [--agent=<agent>] [--status=completed|failed] --summary="..."`
+
 **Locale**
 - [`aioson i18n:add`](docs/en/i18n.md#create-a-locale-scaffold) `<locale>`
 - [`aioson locale:apply`](docs/en/i18n.md#apply-localized-agent-prompts) `[path] [--lang=en|pt-BR|es|fr]`
@@ -101,6 +108,14 @@ If your AI CLI does not show a visual agent picker, these commands let you inter
 - [`aioson agent:prompt setup --tool=codex`](docs/en/cli-reference.md#agentprompt) — get activation prompt for any agent
 - [`aioson workflow:plan --classification=SMALL`](docs/en/cli-reference.md#workflowplan) — see the recommended agent sequence
 
+**Tracked live session flow**
+- `aioson live:start . --tool=codex --agent=deyvin --plan=plan.md --no-launch` — open a tracked session envelope before the AI client starts working
+- `aioson runtime:emit . --agent=deyvin --type=task_started --title="Fix stock modal"` — mark the start of a visible work slice
+- `aioson runtime:emit . --agent=deyvin --type=task_completed --summary="Stock modal fixed" --refs="src/app.js,src/styles.css"` — register a completed slice
+- `aioson live:handoff . --agent=deyvin --to=product --reason="Scope needs product decision"` — keep the same live session and switch active AIOSON agent
+- `aioson live:status . --agent=product --watch=2` — monitor status, active agent, plan progress, and process liveness
+- `aioson live:close . --agent=product --summary="Session closed"` — finish the session and generate `summary.md`
+
 **Setup and locale**
 - [`aioson init my-project --lang=pt-BR --tool=codex`](docs/en/cli-reference.md#init)
 - [`aioson install --lang=es --tool=claude`](docs/en/cli-reference.md#install)
@@ -135,7 +150,7 @@ If your AI CLI does not show a visual agent picker, these commands let you inter
 - [`aioson test:smoke --profile=parallel`](docs/en/cli-reference.md#testsmoke)
 - [`aioson test:package --dry-run`](docs/en/cli-reference.md#testpackage)
 
-Default planning includes `@product` → `@ux-ui` for SMALL/MEDIUM projects.
+Default planning includes `@product` → UI/UX (`@ux-ui`) for SMALL/MEDIUM projects.
 
 ## JSON output for CI
 Use `--json` on selected commands. See [JSON schemas](docs/en/json-schemas.md) for output contracts.
@@ -212,6 +227,8 @@ See the [Web3 guide](docs/en/web3.md) for the full reference.
 - [Browser QA guide](docs/en/qa-browser.md) — `qa:init`, `qa:doctor`, `qa:run`, `qa:scan`, `qa:report`
 - [Web3 guide](docs/en/web3.md) — `project_type=dapp`, framework detection, Web3 context fields
 - [JSON schemas](docs/en/json-schemas.md) — `--json` output contracts for all commands
+- [AI clients guide (PT-BR)](docs/pt/clientes-ai.md) — tracked usage with Codex, Claude, Gemini, and OpenCode
+- [Runtime observability (PT-BR)](docs/pt/runtime-observability.md) — `live:start`, `runtime:emit`, `live:handoff`, `live:status`, `live:close`, and dashboard projections
 
 **Release (internal)**
 - [Release guide](docs/en/release.md)
@@ -221,7 +238,7 @@ See the [Web3 guide](docs/en/web3.md) for the full reference.
 **Portuguese guides**
 - [Início rápido](docs/pt/inicio-rapido.md)
 - [Guia de agentes](docs/pt/agentes.md)
-- [Squad e Genoma](docs/pt/squad-genoma.md)
+- [Squad e Genome](docs/pt/squad-genome.md)
 - [Cenários de uso](docs/pt/cenarios.md)
 - [Clientes AI](docs/pt/clientes-ai.md)
 - [Guia do engenheiro](docs/pt/guia-engineer.md)

package/docs/pt/README.md

@@ -8,9 +8,15 @@ Bem-vindo à documentação em português do AIOSON — um framework leve de age
 |---|---|
 | [Início Rápido](./inicio-rapido.md) | Instale, configure e comece em menos de 10 minutos |
 | [Comandos CLI](./comandos-cli.md) | Referência em português dos comandos do `aioson`, com descrição, exemplos e usos práticos |
+| [Memória e Contexto](./memoria-contexto.md) | Guia prático dos arquivos de memória, descoberta, índices e pacotes mínimos de contexto |
+| [Deyvin](./deyvin.md) | Guia do agente de continuidade e pair programming do AIOSON |
 | [Cenários de Uso](./cenarios.md) | Exemplos completos e práticos para projetos MICRO, SMALL e MEDIUM |
 | [Guia de Agentes](./agentes.md) | Quando usar cada agente e o que ele entrega |
-| [Squad e Genoma](./squad-genoma.md) | Como criar squads modulares, diferenciar skill de genoma, aplicar genomas e publicar entregáveis HTML |
+| [Squad e Genome](./squad-genome.md) | Como criar squads modulares, diferenciar skill de genome, aplicar genomes e publicar entregáveis HTML |
+| [Agentes Customizados](./agentes-customizados.md) | Criar agentes personalizados com `squad:agent-create` — tipos, Voice DNA, infra operacional, maturity scoring |
+| [Skills](./skills.md) | Sistema de skills: tipos, instalação, mapeamento por framework e compatibilidade cross-tool |
+| [Automação de Squads](./automacao-squads.md) | Transformar processos de squad em scripts executáveis (Python/Node.js) que rodam sem LLM |
+| [Output Strategy e Delivery](./output-strategy-delivery.md) | Configurar webhooks, automatizar entrega de conteúdo, monitorar delivery e troubleshoot |
 | [Suporte Web3](./web3.md) | Guia para projetos dApp (Ethereum, Solana, Cardano) |
 
 ## Documentação em inglês
@@ -39,8 +45,62 @@ Depois, abra seu AI IDE e digite `/setup` para começar.
 
 Fluxo recomendado:
 - `@setup` primeiro
-- em projeto existente sem documentação, rode `scan:project --folder=src` ou `scan:project --folder=app` para gerar `scan-index.md`, `scan-folders.md`, `scan-<pasta>.md` e `scan-aioson.md`; adicione `--with-llm` se quiser `discovery.md` e `skeleton-system.md`
+- em projeto existente sem documentação, rode `scan:project --folder=src` ou `scan:project --folder=app` para gerar `scan-index.md`, `scan-folders.md`, `scan-<pasta>.md`, `scan-aioson.md`, `memory-index.md` e `module-<pasta>.md`
+- se existir `spec.md`, o scan local também deriva `spec-current.md` e `spec-history.md`
+- depois rode novamente com `--with-llm` para gerar ou atualizar `discovery.md` e `skeleton-system.md`
+- quando quiser mandar só o contexto mínimo para uma tarefa, use `context:pack`
+- quando quiser entender como o `@deyvin` trabalha, leia [Deyvin](./deyvin.md)
+- quando quiser continuar uma sessao, corrigir um recorte pequeno ou trabalhar em modo companheiro tecnico, use `@deyvin`
 - `@discovery-design-doc` quando o escopo ainda estiver vago ou a feature for grande
 - `@analyst` / `@architect` / `@dev` conforme a clareza e o tipo do trabalho
 
 Esse passo de `discovery-design-doc` e recomendado, nao obrigatorio.
+
+## Brownfield sem duvida
+
+Se voce instalou o AIOSON num projeto que ja existe, este e o fluxo inicial mais seguro:
+
+```bash
+# 1. Instale/atualize o AIOSON no repositorio
+npx @jaimevalasek/aioson install
+
+# 2. Gere o contexto principal
+npx @jaimevalasek/aioson setup:context --defaults
+
+# 3. Gere os mapas locais do codigo
+npx @jaimevalasek/aioson scan:project . --folder=src,app
+
+# 4. Gere ou atualize a memoria brownfield consolidada com LLM
+npx @jaimevalasek/aioson scan:project . --folder=src,app --with-llm --provider=openai
+
+# 5. Monte um pacote minimo de contexto para a tarefa atual
+npx @jaimevalasek/aioson context:pack . --agent=dev --goal="ajustar captions do editor" --module=src
+```
+
+O que cada etapa entrega:
+
+- `scan:project` sem `--with-llm`: gera `scan-index.md`, `scan-folders.md`, `scan-<pasta>.md`, `scan-aioson.md`, `memory-index.md`, `module-<pasta>.md` e, quando houver `spec.md`, também `spec-current.md` + `spec-history.md`
+- `scan:project` com `--with-llm`: gera ou atualiza `discovery.md` e `skeleton-system.md`
+- `scan:project` nunca gera `architecture.md`; esse arquivo vem depois com `@architect`
+- `context:pack`: gera `.aioson/context/context-pack.md` com o pacote mínimo recomendado para a tarefa atual
+
+Sem API LLM no `aioson`, ainda existe um caminho valido:
+
+- rode `scan:project . --folder=...` para gerar os mapas locais
+- rode `context:pack` se quiser entregar menos contexto e gastar menos tokens
+- abra Codex, Claude Code, Gemini CLI ou outro cliente de IA
+- ative `@analyst`
+- o `@analyst` pode usar `scan-index.md`, `scan-folders.md`, `scan-<pasta>.md` e `scan-aioson.md` para escrever `discovery.md`
+- se o cliente permitir escolher modelo, prefira um modelo rapido/barato nessa etapa
+
+Fluxo recomendado depois do scanner em projeto SMALL brownfield:
+
+- `@analyst` para consolidar ou revisar a descoberta do sistema e do escopo atual
+- `@architect` para transformar essa descoberta em `architecture.md`
+- `@dev` somente depois da memoria estar pronta
+
+Regra importante sobre atualizacao:
+
+- `scan:project --with-llm` usa `merge` por padrao quando `discovery.md` ou `skeleton-system.md` ja existem
+- antes de sobrescrever, ele cria backup automatico em `.aioson/backups/`
+- se voce quiser regenerar do zero, use `--context-mode=rewrite`

package/docs/pt/advisor-spec.md

@@ -9,7 +9,7 @@
 
 ## O que é um Advisor
 
-Um Advisor é um agente operacional completo baseado no perfil cognitivo inferido de uma pessoa real. Ele não é um genoma aplicado passivamente; ele opera diretamente em modo consultivo.
+Um Advisor é um agente operacional completo baseado no perfil cognitivo inferido de uma pessoa real. Ele não é um genome aplicado passivamente; ele opera diretamente em modo consultivo.
 
 Capacidades esperadas:
 
@@ -21,16 +21,16 @@ Capacidades esperadas:
 
 ---
 
-## Advisor versus Genoma
+## Advisor versus Genome
 
-| Aspecto | Genoma | Advisor |
+| Aspecto | Genome | Advisor |
 |---------|--------|---------|
 | Tipo | Artefato passivo de conhecimento | Agente ativo |
 | Execução direta | Não | Sim, em modo consultivo |
 | Web search | Não | Sim |
 | Memória | Não | Sim |
 | Uso principal | Enriquecer executores | Opinar, desafiar, aconselhar |
-| Localização | `.aioson/genomas/` | `.aioson/advisors/` |
+| Localização | `.aioson/genomes/` | `.aioson/advisors/` |
 
 ---
 
@@ -53,7 +53,7 @@ mbti: "[XXXX]"
 confidence: [low|medium|high]
 
 profiler_report: ".aioson/profiler-reports/[slug]/enriched-profile.md"
-genome: ".aioson/genomas/[slug].md"
+genome: ".aioson/genomes/[slug].md"
 
 web_search: true
 memory: true