docs: Add comprehensive onboarding documentation for new developers

[Copilot]

Overview

Created comprehensive documentation to help junior developers and new team members quickly understand and contribute to the Metacore Stack project. This addresses the need for a complete project inventory and onboarding guide in Portuguese.

What's New

📘 ONBOARDING.md (894 lines)

A complete onboarding guide covering all requested sections:

1. Visão Geral do Projeto e Propósito - Explains what Metacore Stack is, the problem it solves (transforming episodic AI interactions into continuous, governed workflows), and who uses it
2. Inventário de Componentes - Detailed breakdown of the repository structure, technologies (.NET 8, TypeScript, Node 20, SignalR, JSON-RPC 2.0), and ~1,217 lines of C# code across 7 main subsystems
3. Arquitetura do Sistema - Hybrid architecture explanation with SignalR for client communication and JSON-RPC 2.0 for MCP servers, including 3 detailed data flow examples
4. Funcionalidades Implementadas - Documents 7 major features: Room Management, Entities, Messaging, Artifacts, MCP Integration, Governance, and Telemetry
5. Como Iniciar/Rodar o Projeto - Step-by-step setup instructions with two options (local development and Docker Compose)
6. Testes e Qualidade - Coverage of 28 xUnit tests, schema validation, CI/CD pipelines, and quality tools

Plus extras: Advanced Concepts, FAQ, Next Steps, and Resources.

📐 ARCHITECTURE.md (285 lines)

Visual ASCII diagrams showing:

• Overall system architecture with all layers
• Message flow between entities in a room
• Artifact creation and versioning workflow
• MCP integration JSON-RPC flow
• Policy validation layers
• Room lifecycle states

📌 QUICKREF.md (343 lines)

Quick reference guide with:

• Essential Make commands
• SignalR Hub methods and HTTP endpoints
• JSON data models with examples (EntitySpec, MessageModel, ArtifactManifest)
• Common development workflows (connecting to rooms, calling MCP tools, creating artifacts)
• Troubleshooting tips
• Development shortcuts

📝 README.md (updated)

Enhanced with clear documentation hierarchy and prominent links to the new guides.

Documentation Statistics

• 1,522 lines of new documentation
• 3 new files created
• 10 major sections covered (6 required + 4 bonus)
• All content in Portuguese as requested
• Cross-referenced for easy navigation

Impact

New developers can now:

• ✅ Understand the project's purpose and architecture in minutes
• ✅ Set up their development environment with clear instructions
• ✅ Find examples of all major data models and workflows
• ✅ Quickly reference commands and concepts while coding
• ✅ Navigate between documentation levels (quick ref → onboarding → deep dive)

Example Usage

A junior developer can now:

1. Start with QUICKREF.md for immediate commands
2. Read ONBOARDING.md sections 1-3 to understand the system (30 min)
3. Follow section 5 to set up locally (make bootstrap && make run-server)
4. Reference ARCHITECTURE.md diagrams to understand data flows
5. Begin contributing with confidence

The documentation answers critical questions like "What is a Room?", "How do entities communicate?", "How does MCP integration work?", and "How do I create an artifact?" - all with practical examples.

Original prompt

Olá, sou um desenvolvedor júnior/novo membro da equipe e preciso me familiarizar rapidamente com um projeto existente. Você é um engenheiro de software experiente e um documentador técnico.

Sua tarefa é analisar o conteúdo do repositório que eu fornecerei e criar um inventário detalhado e uma explicação clara sobre o que está implementado, a arquitetura e como o projeto funciona. O objetivo é me dar uma visão geral completa para que eu possa começar a contribuir.

Por favor, organize sua resposta nas seguintes seções:

1. Visão Geral do Projeto e Propósito
   Nome do Projeto: [Se souber, pode preencher aqui, ou o Codex tentará inferir do README.md]
   Propósito Principal: Explique qual problema este projeto resolve e qual é seu objetivo final em termos de negócio ou funcionalidade.
   Público-alvo/Usuários: Quem utiliza este software?
2. Inventário de Componentes e Estrutura do Repositório
   Estrutura de Diretórios Principais:
   Liste os principais diretórios (ex: src/, tests/, docs/, config/, public/) e descreva brevemente a finalidade de cada um.
   Destaque arquivos importantes na raiz do projeto (ex: README.md, package.json, pom.xml, Dockerfile, Jenkinsfile, etc.).
   Tecnologias e Ferramentas Utilizadas:
   Liste as linguagens de programação, frameworks (frontend e backend), bibliotecas significativas, bancos de dados, ORMs, ferramentas de build (ex: Webpack, Maven, Gradle), sistemas de cache, filas de mensagens, etc.
   Identifique as principais dependências externas.
   Configurações Importantes:
   Mencione onde as configurações do ambiente são gerenciadas (ex: arquivos .env, application.properties, segredos de Kubernetes).
3. Arquitetura do Sistema e Fluxo de Dados
   Tipo de Arquitetura:
   Descreva se é uma aplicação monolítica, microsserviços, SPA (Single Page Application), cliente-servidor, etc.
   Explique as principais camadas ou serviços (ex: frontend, backend API, serviço de autenticação, serviço de dados).
   Comunicação entre Componentes:
   Como as diferentes partes do sistema se comunicam (ex: REST APIs, gRPC, filas de mensagens, RPC)?
   Fluxo de Dados Chave:
   Descreva um exemplo de fluxo de dados para uma funcionalidade crítica (ex: "Como um usuário se autentica?" ou "Como um novo item é adicionado ao sistema?").
   Explique como os dados são armazenados e recuperados do banco de dados.
4. Funcionalidades Implementadas
   Lista de Funcionalidades Principais:
   Enumere as principais funcionalidades que o sistema oferece ao usuário final ou a outros sistemas.
   Para cada funcionalidade, forneça uma breve descrição.
   Módulos/Arquivos Chave por Funcionalidade:
   Para 2-3 funcionalidades mais importantes, indique quais são os principais módulos ou arquivos de código responsáveis por sua implementação.
5. Como Iniciar/Rodar o Projeto (Visão Geral)
   Pontos de Entrada:
   Onde a execução da aplicação começa (ex: main em Java, app.js em Node.js, index.html para frontend)?
   Passos de Alto Nível para Execução Local:
   Resuma os passos essenciais para configurar e rodar o projeto em um ambiente de desenvolvimento (ex: "clonar repo, instalar dependências, configurar DB, rodar servidor").
   Mencione quaisquer ferramentas específicas necessárias (ex: Docker, Node.js, Java JDK).
6. Testes e Qualidade de Código (se aplicável)
   Estratégia de Testes:
   Mencione se existem testes unitários, de integração, end-to-end (E2E) e onde eles estão localizados.
   Ferramentas de Qualidade:
   Se houver, mencione linters, formatadores de código ou ferramentas de análise estática.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.