Este repositório é um laboratório de curadoria, runtime e distribuição para o ecossistema Pi. Contribuições devem manter a fronteira clara entre material distribuível, documentação pública e manutenção interna do laboratório.

1. Crie um arquivo .md em docs/research/.
2. Use o formato documentado no README de pesquisas.
3. Atualize o índice em docs/research/README.md.
4. Abra um PR com uma descrição clara do conteúdo adicionado.

1. Crie um arquivo .md em docs/guides/.
2. Inclua pré-requisitos, passo a passo e exemplos de código funcionais.
3. Atualize o índice em docs/guides/README.md.
4. Abra um PR com uma descrição clara do guia adicionado.

1. Crie um subdiretório em experiments/ com o formato YYYYMM-nome-descritivo.
2. Inclua um README.md seguindo o formato de experimento.
3. Nunca commite chaves de API ou segredos — use .env.example.
4. Abra um PR descrevendo o objetivo e os resultados iniciais.

Os pacotes first-party vivem em packages/ e são distribuídos como @aretw0/* no npm.

1. Crie um diretório em packages/meu-pacote/ com package.json e README.md.
2. Ative o modo desenvolvimento local:

   pnpm run pi:local     # aponta pi para os workspace paths

3. Faça /reload no pi para carregar o pacote.
4. Quando a mudança estiver pronta, crie um changeset (ver abaixo).
5. Quando o pacote estiver maduro, adicione-o à lista em packages/pi-stack/package-list.mjs.

O script pi-source-switch.mjs alterna os pacotes do pi entre local e npm:

pnpm run pi:local       # aponta pi para packages/ do monorepo
pnpm run pi:published   # volta para npm:@aretw0/*
pnpm run pi:status      # mostra configuração atual

Isso reescreve o ~/.pi/agent/settings.json. Use --pi-local para escrever no .pi/settings.json do projeto.

Use @marcfargas/pi-test-harness para testes automatizados:

# Testes smoke (vitest)
pnpm run test:smoke

# Testes unitários (node:test)
pnpm test

A skill test-pi-extension documenta como usar o test-harness. Veja exemplos em packages/pi-stack/test/.

1. O experimento de origem deve estar documentado e com resultados claros.
2. Crie um subdiretório em primitives/.
3. Siga os princípios de design de primitivas.
4. Atualize o catálogo em docs/primitives/README.md.
5. Abra um PR referenciando o experimento de origem.

Este monorepo usa Changesets com versionamento lockstep. Todos os pacotes @aretw0/* compartilham a mesma versão.

Sempre que alterar algo em packages/ que mereça release:

pnpm exec changeset
# Escolha: qual pacote, tipo (patch/minor/major), descrição da mudança
git add .changeset/
git commit -m "..."

Mudanças em docs/, experiments/ ou configurações internas não precisam de changeset.

Ver guia completo em docs/guides/publishing.md.

pnpm run release             # bumpa versões + atualiza CHANGELOG.md
pnpm run release:readiness:strict -- --target X.X.X
pnpm run release:readiness:strict:json -- --target X.X.X
git add .
git commit -m "chore(release): vX.X.X"
git tag vX.X.X
git push && git push --tags  # GitHub Actions publica no npm

• Idioma: Documentação principal em Português (BR); código e comentários técnicos podem ser em inglês.
• Markdown: Use Markdown padrão com tabelas e blocos de código quando apropriado.
• Nomenclatura de arquivos: Use kebab-case (ex.: pi-agent-core.md).
• Commits: Seguir Conventional Commits — o CI valida.
• Segredos: Nunca commite chaves de API, tokens ou credenciais.
• VS Code (escopo de configuracao): Nao versione chaves de escopo de aplicativo/perfil em .vscode/settings.json ou .devcontainer/devcontainer.json (ex.: extensions.autoUpdate, extensions.autoCheckUpdates). Essas opcoes devem ser definidas apenas nas configuracoes de usuario, no perfil Padrao.
• PRs pequenos: Prefira PRs focados em um único tópico.
• Contexto: Inclua sempre o contexto de por que a contribuição é relevante para o laboratório.

Abra uma Issue para:

• Propor novos temas de pesquisa
• Sugerir novas primitivas
• Discutir a estrutura do laboratório
• Trazer material para análise

Este laboratório é um espaço de aprendizado e colaboração. Seja respeitoso, construtivo e aberto a diferentes perspectivas.