docs: improve CLAUDE.md with accurate commands and architecture details

[ruibrunocunha]

Summary

• Remove nonexistent npm scripts (dev, build, dashboard section) that would mislead Claude Code
• Add monorepo workspace architecture (4 packages), single test execution commands, TypeScript path aliases, and Prettier/ESLint style details
• Add core module architecture table, git hooks behavior (lint-staged auto IDE sync, IDS registry), validation commands, and JSON schema references

Test plan

• Verify CLAUDE.md renders correctly on GitHub
• Confirm all listed npm scripts exist in package.json
• Validate no information was lost from the previous version

🤖 Generated with Claude Code

[vercel]

Someone is attempting to deploy a commit to the Pedro Valério Lopez's projects Team on Vercel.

A member of the Team first needs to authorize it.

[nikolasdehor]

Nice effort consolidating the CLAUDE.md, @ruibrunocunha! A few observations:

Positives:

• Expanded project structure tree with all 4 workspace packages is really helpful
• Adding concrete npm commands that actually exist (removing npm run dev/npm run build which don't) prevents confusion
• The core module architecture table (14 categories) is a great addition
• Git hooks section (lint-staged, IDS registry) documents behavior that trips up new contributors
• TypeScript path alias docs (@synkra/aios-core) — good to have

Concerns:

1. Removes <!-- FRAMEWORK-OWNED --> comment markers — The current CLAUDE.md uses these markers to distinguish sections the installer generates vs sections safe to customize. Removing them means npx aios-core install may overwrite these changes or fail to merge correctly. Consider preserving the markers.

2. Removes Language Configuration section — This section was framework-owned (generated by installer). Removing it could break the installer's ability to detect and update language config on npx aios-core install.

3. Removes the Error Handling pattern — The try/catch template with logger.error + error instanceof Error check is referenced by agent personas as the project standard. Worth keeping as a compact one-liner example at least.

4. Semantic-release mapping is incomplete — The commit section now shows feat → minor, fix → patch, perf → patch, breaking → major, but the original also documented docs:, test:, chore:, refactor: which are commonly used in this repo. Newer contributors won't know what types are valid.

5. Quality Gates section removed — The pre-push checklist (lint → typecheck → test) is gone. While the individual commands exist in the new "Comandos" section, the explicit "all these must pass before push" gate is useful context.

Overall a solid improvement — the expanded structure tree and real commands alone justify the PR. If you address items 1-2 (framework markers + language section), this would be ready to merge.

[nikolasdehor]

Tradução para pt-BR do review acima:

Bom trabalho consolidando o CLAUDE.md, @ruibrunocunha! Algumas observações:

Pontos positivos:

• Árvore expandida do projeto com os 4 workspace packages é muito útil
• Adicionar comandos npm que realmente existem (removendo npm run dev/npm run build que não existem) evita confusão
• A tabela de arquitetura dos módulos core (14 categorias) é uma ótima adição
• Seção de git hooks (lint-staged, IDS registry) documenta comportamento que confunde novos contribuidores
• Docs do TypeScript path alias (@synkra/aios-core) — bom ter

Preocupações:

1. Remove marcadores <!-- FRAMEWORK-OWNED --> — O CLAUDE.md atual usa esses marcadores para distinguir seções geradas pelo instalador vs seções seguras para customizar. Removê-los significa que npx aios-core install pode sobrescrever essas alterações ou falhar no merge.

2. Remove seção Language Configuration — Essa seção era framework-owned (gerada pelo instalador). Removê-la pode quebrar a capacidade do instalador de detectar e atualizar a config de idioma.

3. Remove o padrão de Error Handling — O template try/catch com logger.error é referenciado pelas personas dos agentes como padrão do projeto. Vale manter como exemplo compacto.

4. Mapeamento semantic-release incompleto — A seção de commits agora mostra feat → minor, fix → patch, mas o original também documentava docs:, test:, chore:, refactor: que são muito usados neste repo.

5. Seção Quality Gates removida — O checklist de pre-push (lint → typecheck → test) sumiu. O contexto "tudo isso deve passar antes do push" é útil.

No geral uma boa melhoria — se resolver os itens 1-2 (marcadores + seção de idioma), ficaria pronto pra merge.