@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/pt/3-receitas/landing-page.md

@@ -0,0 +1,281 @@
+# Receita: Landing page do zero
+
+> **Para quem é:** desenvolvedor solo ou designer que precisa de uma landing page convincente sem gastar horas escrevendo copy e definindo componentes.
+> **Tempo de execução:** 45–90 min.
+> **O que você vai ter no fim:** landing page com copy de conversão, sistema visual aplicado, componentes especificados, código funcional e testes básicos — tudo rastreável em artefatos.
+
+---
+
+## Cenário
+
+Você tem um produto ou serviço novo e precisa de uma página de apresentação. O desafio clássico: ou você escreve copy genérico ("Bem-vindo ao nosso produto"), ou gasta horas tentando encontrar as palavras certas. E quando chega no código, o visual fica inconsistente — um botão com uma cor, o header com outra.
+
+Com AIOSON, quatro agentes resolvem isso em sequência: `@product` define o que comunicar, `@copywriter` escreve copy orientado a conversão, `@ux-ui` especifica o sistema visual, e `@dev` implementa. O resultado é uma página com narrativa e visual coerentes.
+
+Este é um projeto **SMALL** (1 tipo de usuário, 0 integrações externas, sem regras de negócio complexas — mas o design justifica o `@ux-ui`).
+
+> **Como o framework garante a ordem certa:** quando `project_type=site`, o `@product` recomenda `@copywriter` no handoff, e o `@ux-ui` tem um copy gate que **bloqueia** se `copy-{slug}.md` não existir. Você pode também iniciar pelo `@neo` — ele detecta `needs_copy` e roteia automaticamente. Em qualquer caminho, é impossível chegar no visual sem o copy pronto.
+
+---
+
+## Pré-requisitos
+
+- Node.js 18+ instalado
+- Claude Code (ou Codex/Gemini/OpenCode)
+- AIOSON instalado no projeto (`npx @jaimevalasek/aioson init minha-landing`)
+- Opcional: uma URL de referência para estilo visual (qualquer site público que você admire)
+
+---
+
+## Passo 1 — Criar o projeto e configurar
+
+```bash
+npx @jaimevalasek/aioson init minha-landing
+cd minha-landing
+```
+
+No wizard:
+```
+? Quais ferramentas AI? › Claude Code
+? Modo? › Development
+? Design system? › Clean SaaS UI
+? Idioma dos agentes? › pt-BR
+```
+
+> **Nota sobre design system:** se você prefere algo mais editorial, escolha Bold Editorial UI. Para apps dark e técnicos, Aurora Command UI. Pode trocar depois invocando `@ux-ui`. Veja a lista completa em [Decisões iniciais](../2-comecar/decisoes-iniciais.md).
+
+```bash
+claude .
+```
+
+```
+Você > @setup
+
+@setup > Detectando stack... Nenhuma instalada ainda.
+         Qual o tipo do projeto? [web_app · api · site · script · ...]
+Você > site
+
+@setup > Stack preferido? (ex: Next.js, Astro, HTML puro)
+Você > Next.js + Tailwind
+
+@setup > Quantos tipos de usuário? (visitantes da landing não contam como "tipo")
+Você > 1 (potencial cliente lendo a página)
+
+@setup > Integrações externas?
+Você > 0 por enquanto
+
+@setup > Score: 0+0+0 = 0 → MICRO, mas site com design system → recomendo SMALL para @ux-ui.
+Você > Sim, SMALL.
+
+@setup > Classificação: SMALL. Design skill registrado: clean-saas-ui.
+         project.context.md criado. Próximo: @product.
+```
+
+---
+
+## Passo 2 — `@product` define o que comunicar
+
+```
+Você > @product
+
+@product > Vamos definir o produto desta landing page.
+           Nome do produto?
+Você > ContaFácil — software de controle financeiro para pequenos negócios
+
+@product > Em uma frase, qual problema o ContaFácil resolve?
+Você > Pequenos empresários perdem dinheiro por não saber onde gastam. ContaFácil mostra.
+
+@product > Público-alvo principal?
+Você > Donos de restaurantes e pequenas lojas de 1–5 funcionários. Maioria sem formação financeira.
+
+@product > Qual a única ação que o visitante deve tomar nesta página?
+Você > Clicar em "Comece grátis" e criar uma conta
+
+@product > Quais objeções típicas o público tem?
+Você > "É complicado de usar", "Não tenho tempo pra aprender", "Funciona com meu tipo de negócio?"
+
+@product > Algum diferencial competitivo claro?
+Você > Dashboard em 5 minutos, importação automática do extrato bancário, sem planilhas.
+
+@product > Spec da landing gravada em .aioson/context/features/landing-principal/spec.md.
+           project_type=site detectado → próximo: @copywriter.
+           (Site converte por copy. O layout do @ux-ui só desbloqueia depois que copy-{slug}.md existir.)
+```
+
+> **Dica:** copy antes do layout é a ordem certa. O texto define o espaço que o visual vai preencher — não o contrário. O framework força isso: o `@ux-ui` tem um copy gate que para a sessão se nenhum `copy-*.md` existir em `.aioson/context/`.
+
+---
+
+## Passo 3 — `@copywriter` escreve o copy de conversão
+
+```
+Você > @copywriter
+
+@copywriter > Lendo spec da landing-principal...
+              Público: donos de restaurantes/lojas, sem formação financeira.
+              Objeções: complexidade, tempo, adequação.
+              CTA: "Comece grátis".
+
+@copywriter > Gerando copy com framework Problem → Agitate → Solution + prova social...
+
+@copywriter > Copy gerado e salvo em .aioson/context/copy-landing-principal.md.
+              Resumo das seções:
+
+              HERO:
+              Headline: "Saiba para onde vai cada real do seu negócio — em 5 minutos"
+              Subheadline: "ContaFácil conecta com seu banco e mostra o quadro real,
+                           sem planilhas, sem contador."
+              CTA: "Comece grátis — sem cartão"
+
+              PROBLEMA:
+              "Todo mês você fecha o caixa sem entender por que sobrou tão pouco..."
+
+              SOLUÇÃO + PROVA:
+              3 bullets com diferenciais + depoimento fictício de Maria, dona de restaurante.
+
+              FAQ: 3 perguntas cobrindo as objeções mapeadas.
+              CTA final repetido.
+
+@copywriter > Próximo: @ux-ui para especificar o layout onde este copy vai encaixar.
+```
+
+---
+
+## Passo 4 — `@ux-ui` especifica o sistema visual e layout
+
+```
+Você > @ux-ui
+
+@ux-ui > Lendo spec + copy da landing-principal. Design skill: clean-saas-ui.
+          Vou especificar seções, componentes e tokens.
+
+@ux-ui > Estrutura da página:
+          1. NavBar — logo + link âncoras + CTA ghost
+          2. Hero — headline H1 + sub + CTA primário + screenshot/mockup
+          3. Problema — 1 parágrafo + ícone ilustrativo
+          4. Funcionalidades — 3 cards feature com ícone, título e descrição
+          5. Prova social — 1 depoimento com foto avatar + estrelas
+          6. FAQ accordion — 3 perguntas
+          7. CTA final — fundo colorido + headline + botão grande
+          8. Footer — links legais
+
+@ux-ui > Tokens Clean SaaS UI aplicados:
+          Cor primária: #2563EB (azul)
+          Cor neutra: #F9FAFB (fundo), #111827 (texto)
+          Tipografia: Inter, 16px base, H1 48px/56px
+          Raio: 8px, Sombra: shadow-md
+
+@ux-ui > Especificação gravada em .aioson/context/design-doc-landing-principal.md.
+          Próximo: @dev para implementar.
+```
+
+---
+
+## Passo 5 — `@dev` implementa
+
+```
+Você > @dev
+
+@dev > [lê spec, copy, design-doc, project.context]
+       Stack: Next.js + Tailwind. Vou criar:
+
+       app/page.tsx             — página principal
+       components/NavBar.tsx
+       components/Hero.tsx
+       components/Features.tsx
+       components/Testimonial.tsx
+       components/FAQ.tsx
+       components/CTABand.tsx
+       components/Footer.tsx
+
+@dev > [implementa componentes com copy do arquivo]
+       Smoke test: next build → sem erros de TS/lint.
+       Servidor: next dev → abrindo localhost:3000 ✓
+
+@dev > dev-state.md atualizado. Próximo: @qa.
+```
+
+---
+
+## Passo 6 — `@qa` valida
+
+```
+Você > @qa
+
+@qa > ACs da spec:
+      AC-01: todas as 8 seções renderizam sem erro ✓
+      AC-02: CTA "Comece grátis" aparece em hero e CTA band ✓
+      AC-03: FAQ abre/fecha ao clicar (accordion) — verificando...
+      AC-04: responsivo em 375px, 768px, 1280px — verificando...
+
+@qa > AC-03 OK. AC-04: quebra no mobile (Hero — texto ultrapassa viewport).
+      Ciclo autônomo QA→Dev (iteração 1/2):
+      Repassando para @dev...
+@dev > Corrigindo Hero: max-w-full + text-3xl no mobile.
+@qa > Re-rodando... 4/4 ACs passando. Relatório salvo.
+```
+
+---
+
+## Passo 7 (opcional) — Commitar com `@committer`
+
+```
+Você > @committer
+
+@committer > Diff lido. Mensagem proposta:
+             feat(landing): implement ContaFácil landing page with Clean SaaS UI
+
+             - 8 sections: NavBar, Hero, Features, Testimonial, FAQ, CTABand, Footer
+             - Copy from @copywriter targeting restaurantes/lojas audience
+             - Mobile-responsive (375/768/1280px)
+
+             [✓] Aceitar
+Você > [Enter]
+@committer > Commitado.
+```
+
+---
+
+## O que ficou em disco (rastreio)
+
+```
+.aioson/context/
+├── project.context.md                    ← classificação SMALL, site, clean-saas-ui
+├── features/
+│   └── landing-principal/
+│       └── spec.md                       ← o que comunicar, ACs, fora-de-escopo
+├── copy-landing-principal.md             ← copy de conversão completo (@copywriter)
+├── design-doc-landing-principal.md       ← seções, tokens, componentes (@ux-ui)
+├── dev-state.md                          ← o que foi implementado, status
+└── qa-report-test-coverage.md            ← 4/4 ACs, 1 fix aplicado
+```
+
+---
+
+## Variações
+
+| Situação | Ajuste |
+|---|---|
+| Não quer usar Next.js | Diga no `@setup`. O `@dev` se adapta a Astro, HTML puro, Vue, etc. |
+| Quer clonar o estilo de um site que admira | Use `@site-forge` antes do `@ux-ui`. Veja a [receita de clone de design](./clonar-design-de-site.md). |
+| Quer combinar dois estilos visuais | `@design-hybrid-forge` cria um skill híbrido. |
+| Não precisa de copy elaborado | Pule o `@copywriter`. Passe o copy diretamente para `@ux-ui`. |
+| Precisa de formulário de captura de email | Declare no `@product` como AC. O `@dev` incluirá. |
+
+---
+
+## Solução de problemas
+
+| Problema | Solução |
+|---|---|
+| `@ux-ui` ignorou o design skill escolhido | Confira `design_skill: clean-saas-ui` em `project.context.md`. Se vazio, edite e reative `@ux-ui`. |
+| Copy gerado está genérico | Abra `copy-landing-principal.md` e adicione dados reais (preços, nome do fundador). Reative `@copywriter` com "refine a seção Hero com esses dados". |
+| `next build` com erros de tipo TS | Rode `@deyvin` — ele lê `dev-state.md` e resolve o erro em pair. |
+
+---
+
+## Próximo passo
+
+- Quer clonar o design de um concorrente? → [Clonar design de site](./clonar-design-de-site.md)
+- Quer publicar a landing no aioson.com? → [Publicar no aioson.com](./publicar-no-aioson-com.md)
+- Precisa de copy mais profundo? Consulte `copy-landing-principal.md` e peça ao `@copywriter` seções específicas.

package/docs/pt/3-receitas/plans-externos-para-product.md

@@ -0,0 +1,191 @@
+# Receita: Plans externos para `@product` e `@sheldon`
+
+> **Para quem é:** quem fez pesquisa ou planejamento em outro ambiente — ChatGPT, Claude.ai, Notion, Google Docs, papel — e quer que o AIOSON use esse material.
+> **Tempo de execução:** 5 min de setup + tempo da sessão normal.
+> **O que você vai ter no fim:** seus rascunhos sendo consumidos nativamente pelo `@product` e `@sheldon`, sem re-explicar nada.
+
+---
+
+## O problema
+
+Você pesquisou uma feature no ChatGPT. Escreveu uma análise no Claude.ai. Tem um doc no Notion. Começou a sessão no AIOSON e agora vai re-explicar tudo de novo — ou copiar e colar em partes.
+
+A pasta `plans/` resolve isso. É um canal direto entre "coisas que você escreveu antes" e os agentes que precisam saber.
+
+---
+
+## Como funciona
+
+```
+ChatGPT / Claude.ai / Notion / qualquer lugar
+            ↓  copiar texto
+       plans/{nome}.md     ← você escreve aqui
+            ↓  lido automaticamente por
+    @briefing / @product / @sheldon
+            ↓  artefato real criado em
+    .aioson/context/prd-{slug}.md
+```
+
+`plans/` é **gitignored por padrão**. Seu material de pesquisa nunca vai para o repositório — é somente seu, local.
+
+---
+
+## Passo a passo
+
+### 1. Crie o arquivo em `plans/`
+
+```bash
+# Na raiz do projeto (mesmo nível de src/, .aioson/, etc.)
+mkdir -p plans
+```
+
+Salve seu material lá. Pode ser qualquer formato de texto:
+
+```
+plans/
+├── analise-stripe-billing.md      ← conversa que você exportou do ChatGPT
+├── pesquisa-webhook-seguranca.md  ← pesquisa técnica sua
+├── briefing-reuniao-2026-05-01.md ← anotações de reunião
+└── benchmark-concorrentes.txt     ← texto simples também funciona
+```
+
+### 2. Escreva como quiser — sem formato obrigatório
+
+Os agentes lêem texto livre. Sem template. Suas anotações podem estar:
+
+- Desorganizadas (bullets soltos, títulos inconsistentes)
+- Em inglês ou português — ambos funcionam
+- Como exportação de conversa (Você: / ChatGPT:)
+- Como cópia de um Google Doc
+
+O `@briefing` e o `@product` sintetizam o que encontrarem.
+
+### 3. Ative o agente
+
+**Se a ideia ainda é vaga → use `@briefing` primeiro:**
+
+```
+Você > @briefing
+
+@briefing > Encontrei 2 arquivos em plans/:
+             - plans/analise-stripe-billing.md
+             - plans/pesquisa-webhook-seguranca.md
+             Quais devo usar?
+Você > Todos.
+```
+
+**Se a ideia já está clara → vá direto para `@product`:**
+
+```
+Você > @product
+
+@product > Encontrei fontes de pré-produção:
+            - plans/analise-stripe-billing.md
+            - plans/pesquisa-webhook-seguranca.md
+            Posso usar como base para o PRD?
+Você > Sim.
+
+@product > [lê, sintetiza, faz perguntas apenas sobre o que falta]
+            PRD criado: .aioson/context/prd-billing-assinatura.md
+```
+
+**`@sheldon` também lê `plans/` automaticamente:**
+
+```
+Você > @sheldon
+
+@sheldon > Lendo prd.md...
+            Cruzando com plans/:
+            - plans/pesquisa-webhook-seguranca.md:
+              risco identificado não está no PRD
+            Recomendo enriquecer o AC de idempotência.
+```
+
+### 4. O registro automático
+
+Toda vez que um agente consume um arquivo de `plans/`, ele registra em `plans/source-manifest.md`:
+
+```markdown
+| File | Consumed by | Date | Artifact produced |
+|------|-------------|------|-------------------|
+| plans/analise-stripe-billing.md | @product | 2026-05-07 | .aioson/context/prd-billing-assinatura.md |
+| plans/pesquisa-webhook-seguranca.md | @sheldon | 2026-05-07 | .aioson/context/sheldon-enrichment-billing-assinatura.md |
+```
+
+Isso permite rastrear: "qual artefato foi gerado a partir de qual pesquisa?".
+
+---
+
+## Exemplos de tipos de material que funcionam bem
+
+| Tipo de conteúdo | Onde colocar |
+|---|---|
+| Conversa exportada do ChatGPT sobre uma feature | `plans/conversa-{tema}.md` |
+| Análise técnica de API externa (Stripe, Twilio…) | `plans/pesquisa-{api}.md` |
+| Anotações de reunião de discovery | `plans/briefing-reuniao-{data}.md` |
+| Benchmark de concorrentes | `plans/benchmark-{produto}.md` |
+| Esboço de fluxo desenhado e transcrito | `plans/fluxo-{feature}.md` |
+| Cópia de documentação relevante | `plans/ref-{topico}.md` |
+| Lista de requisitos rascunhados | `plans/reqs-{feature}.md` |
+
+---
+
+## Regras do `plans/`
+
+| Regra | Detalhe |
+|---|---|
+| **Gitignored** | Por padrão em `.gitignore`. Nunca vai para o repositório. |
+| **Read-only para agentes** | Nenhum agente modifica ou deleta seus arquivos. |
+| **Permanecem até entrega** | Você decide quando remover. Mesmo depois do PRD pronto. |
+| **Qualquer formato de texto** | `.md`, `.txt`, `.log` — qualquer extensão funciona. |
+| **Não são PRDs reais** | São matéria-prima. O PRD real fica em `.aioson/context/`. |
+
+---
+
+## Diferença entre `plans/` e `.aioson/plans/`
+
+São duas coisas distintas:
+
+| | `plans/` (raiz) | `.aioson/plans/` |
+|---|---|---|
+| **Quem escreve** | Você (pesquisa externa) | `@sheldon` (plano faseado) |
+| **Quando existe** | Antes do ciclo de agentes | Durante/após `@sheldon` |
+| **O que contém** | Rascunhos, anotações, exportações | Fases de implementação geradas por IA |
+| **É gitignored?** | Sim (padrão) | Não (comprometido com o projeto) |
+| **Lido por** | `@briefing`, `@product`, `@sheldon` | `@analyst`, `@architect`, `@dev` |
+
+Veja [SDD: planos e estrutura](../5-referencia/sdd-planos-e-estrutura.md) para a referência completa.
+
+---
+
+## Casos especiais
+
+### Você tem muito material — como organizar?
+
+Sem padrão obrigatório. Mas nomenclatura descritiva ajuda:
+
+```
+plans/
+├── 01-contexto-mercado.md
+├── 02-analise-tecnica.md
+├── 03-requisitos-rascunhados.md
+└── 04-riscos-identificados.md
+```
+
+Quando o `@briefing` perguntar "quais usar?", você diz "todos" ou lista os relevantes.
+
+### O material está em inglês — tudo bem?
+
+Sim. Os agentes lêem em qualquer língua. O output deles vai seguir `interaction_language` do `project.context.md` (geralmente a mesma língua que você usa).
+
+### E se eu quiser compartilhar plans/ com o time?
+
+Remova a entrada do `.gitignore`. Não há nada no AIOSON que impeça isso — gitignored é o default, não uma obrigação técnica.
+
+---
+
+## Próximos passos
+
+- [Da ideia ao PRD via @briefing](./da-ideia-ao-prd-via-briefing.md) — fluxo completo quando a ideia é vaga
+- [Feature completa com @sheldon](./feature-completa-com-sheldon.md) — depois que o PRD está pronto
+- [SDD: planos e estrutura](../5-referencia/sdd-planos-e-estrutura.md) — entenda a diferença entre todos os tipos de plano

package/docs/pt/3-receitas/publicar-no-aioson-com.md

@@ -0,0 +1,219 @@
+# Receita: Publicar no aioson.com
+
+> **Para quem é:** desenvolvedor que criou um squad, skill ou genome e quer compartilhar com outros projetos ou com a comunidade.
+> **Tempo de execução:** 15–30 min.
+> **O que você vai ter no fim:** seu pacote publicado no aioson.com, disponível para instalação com um único comando — público ou privado (com lista de emails autorizados).
+
+---
+
+## Cenário
+
+Você criou um squad customizado para o domínio jurídico — com agentes `@regulator`, `@attorney` e `@auditor` — e quer usá-lo em outros projetos seus, ou disponibilizá-lo para clientes. Ou criou uma design skill personalizada e quer compartilhar com o time sem enviar arquivos manualmente.
+
+O fluxo é: empacote o que você criou (`system:package`), publique (`system:publish`), e qualquer projeto autorizado instala com `system:install`.
+
+---
+
+## O que pode ser publicado
+
+| Tipo | O que é | Onde fica |
+|---|---|---|
+| **Squad** | Grupo de agentes customizados | `.aioson/squads/<slug>/` |
+| **Skill** | Pacote plugável (design, processo, domínio) | `.aioson/skills/<tipo>/<slug>/` |
+| **Genome** | DNA cognitivo de persona | `.aioson/genomes/<slug>/` |
+
+---
+
+## Pré-requisitos
+
+- AIOSON instalado no projeto
+- Conta no aioson.com (crie em aioson.com/signup)
+- O que você quer publicar já criado localmente
+
+---
+
+## Passo 1 — Autenticar na CLI
+
+```bash
+npx @jaimevalasek/aioson auth:login
+```
+
+```
+? Email: voce@exemplo.com
+? Abrindo browser para autenticação...
+Autenticado com sucesso. Token salvo em ~/.aioson/auth.json.
+```
+
+---
+
+## Passo 2 — Verificar o que será empacotado
+
+Antes de empacotar, confirme que o pacote está válido:
+
+```bash
+npx @jaimevalasek/aioson system:list
+```
+
+```
+Pacotes locais disponíveis para publicação:
+  squads/
+    legal-compliance   ← 3 agentes: regulator, attorney, auditor
+  skills/
+    aurora-command-ui  ← design skill
+    aioson-spec-driven ← process skill
+  genomes/
+    persona-vc-advisor ← genome 4.0
+```
+
+---
+
+## Passo 3 — Empacotar
+
+```bash
+npx @jaimevalasek/aioson system:package --slug=legal-compliance --type=squad
+```
+
+```
+Empacotando squad: legal-compliance
+  Incluindo: agentes, config, README, manifest
+  Excluindo: dados sensíveis, tokens, runtime
+
+Pacote criado: .aioson/squads/legal-compliance/.aioson-pkg/package.json
+Versão: 1.0.0
+Checksum: sha256:a3f2b1...
+
+Pronto para publicar.
+```
+
+> **O que o `system:package` exclui automaticamente:** arquivos com padrão de secrets (`*.env`, `*token*`, `*credentials*`), runtime SQLite, logs. Se quiser revisar: `--dry-run` mostra o que seria incluído sem criar o pacote.
+
+---
+
+## Passo 4A — Publicar como público
+
+```bash
+npx @jaimevalasek/aioson system:publish --slug=legal-compliance --type=squad
+```
+
+```
+? Título: Squad Jurídico — Compliance Brasil
+? Descrição curta: Agentes especializados em conformidade com legislação brasileira.
+? Visibilidade: público
+
+Publicando...
+Publicado com sucesso.
+
+Slug público: legal-compliance
+Instalação: npx @jaimevalasek/aioson system:install --slug=legal-compliance
+URL: aioson.com/squads/legal-compliance
+```
+
+---
+
+## Passo 4B — Publicar como privado (com convites)
+
+Para apps ou squads pagos, ou para distribuição controlada para clientes:
+
+```bash
+npx @jaimevalasek/aioson system:publish \
+  --slug=legal-compliance \
+  --type=squad \
+  --private \
+  --invite=cliente1@empresa.com,cliente2@firma.com.br
+```
+
+```
+? Título: Squad Jurídico — Compliance Brasil (Privado)
+? Visibilidade: privado
+? Emails autorizados: cliente1@empresa.com, cliente2@firma.com.br
+
+Publicando...
+Publicado com sucesso.
+
+Acesso restrito a 2 emails.
+Para adicionar mais: system:publish --slug=legal-compliance --invite=novoemail@...
+```
+
+Os emails autorizados recebem o slug e podem instalar. Outros recebem erro de acesso negado.
+
+---
+
+## Passo 5 — Instalar em outro projeto
+
+Em qualquer outro projeto com AIOSON instalado:
+
+```bash
+npx @jaimevalasek/aioson system:install --slug=legal-compliance
+```
+
+```
+Buscando squad: legal-compliance...
+Verificando permissão...  ✓ (seu email está na lista)
+Instalando em .aioson/squads/legal-compliance/
+Checksum verificado: sha256:a3f2b1... ✓
+
+Squad instalado. Para usar:
+  @squad — ative o squad legal-compliance
+  ou: @regulator, @attorney, @auditor diretamente
+```
+
+---
+
+## Publicar uma design skill
+
+O fluxo é idêntico, mudando o `--type`:
+
+```bash
+npx @jaimevalasek/aioson system:package --slug=minha-design-skill --type=skill
+npx @jaimevalasek/aioson system:publish --slug=minha-design-skill --type=skill
+```
+
+Para instalar em outro projeto:
+```bash
+npx @jaimevalasek/aioson system:install --slug=minha-design-skill --type=skill
+```
+
+---
+
+## O que ficou em disco (rastreio)
+
+```
+.aioson/squads/legal-compliance/
+└── .aioson-pkg/
+    ├── package.json        ← versão, slug, tipo, checksum
+    ├── manifest.json       ← agentes incluídos, dependências
+    └── [arquivos do squad]
+```
+
+O `package.json` do pacote é diferente do seu `package.json` de Node.js. É o manifesto interno do AIOSON para versionamento e integridade.
+
+---
+
+## Variações
+
+| Situação | Ajuste |
+|---|---|
+| Quero versionar (v1.1, v2.0) | Edite `version` no `package.json` do pacote antes de `system:publish`. |
+| Quero atualizar um pacote publicado | `system:publish` com o mesmo slug atualiza. Projetos que instalaram precisam rodar `system:install --force`. |
+| Quero unpublish | Acesse aioson.com → seu perfil → gerenciar pacotes. Não há CLI para unpublish ainda. |
+| Quero inspecionar antes de instalar | `system:install --slug=X --inspect` mostra o manifesto sem instalar. |
+| Time usando o mesmo pacote em vários projetos | `system:install` em cada projeto. O pacote é independente do workspace. |
+
+---
+
+## Solução de problemas
+
+| Problema | Solução |
+|---|---|
+| `auth:login` não abre o browser | Copie a URL que aparece no terminal e abra manualmente. |
+| `system:publish` rejeita por secrets detectados | Rode `system:package --dry-run` para ver o que foi detectado. Remova o arquivo ou adicione ao `.aiosonignore`. |
+| Outro projeto não consegue instalar (privado) | Confirme que o email do usuário está na lista de convites. Adicione com `--invite=novo@email.com`. |
+| Versão instalada está desatualizada | `system:install --slug=X --force` reinstala a versão mais recente. |
+
+---
+
+## Próximo passo
+
+- Quer criar um squad antes de publicar? Veja [Mapa do ecossistema](../1-entender/mapa-do-ecossistema.md) (seção Squads).
+- Quer saber o que é um Genome antes de publicar um? Veja o [Glossário](../1-entender/glossario.md).
+- Criou uma landing page para o seu produto e quer publicar ela também? → [Landing page](./landing-page.md)