claude-plugins/acidaos/skills/docs/SKILL.md

---
name: docs
description: Gerar documentação técnica do AcidaOS a partir do código — Rust (rustdoc), TypeScript (TypeDoc), e publicar no Outline. Usar quando "documentação acidaos", "gerar docs", "rustdoc", "typedoc", "acidaos-docs", documentar código do projecto.
allowed-tools: Read, Write, Bash, mcp__gitea__get_file_content, mcp__gitea__get_dir_content, mcp__outline-api__create_document, mcp__outline-api__update_document, mcp__outline-api__search_documents, mcp__memory-supabase__search_memories
---

# AcidaOS Docs

Skill para gerar e publicar documentação técnica do AcidaOS.

## Estratégia de Documentação

| Camada | Ferramenta | Destino |
|--------|-----------|---------|
| API interna Rust | `rustdoc` + comentários `///` | `/docs` no repo |
| Componentes React | TypeDoc + Storybook | Storybook deployed |
| Arquitectura | Mermaid.js diagramas | Outline (Wiki) |
| Endpoints API | OpenAPI/Swagger | Outline (Wiki) |
| Decisões técnicas | ADRs em Markdown | Outline (Wiki) |

## Protocolo

```
mcp__memory-supabase__search_memories "acidaos documentação"
mcp__outline-api__search_documents "acidaos"  # ver docs existentes
```

---

## Operações

### 1. Gerar documentação Rust (`rustdoc`)

**Verificar comentários existentes:**
```
mcp__gitea__get_dir_content acidaos-core/src/
```

**Gerar localmente (no container dev):**
```bash
cd /root/Dev/acidaos-core
cargo doc --all-features --no-deps --open
```

**Verificar cobertura de documentação:**
```bash
cargo doc --all-features 2>&1 | grep "warning: missing documentation"
```

**Template comentários Rust:**
```rust
/// # ComponenteX
///
/// Breve descrição em uma linha.
///
/// ## Descrição detalhada
///
/// Explicação mais longa do comportamento e propósito.
///
/// ## Exemplos
///
/// ```rust
/// use acidaos_core::ComponenteX;
///
/// let c = ComponenteX::new("id");
/// assert!(c.is_valid());
/// ```
///
/// ## Erros
///
/// Retorna [`Error::Init`] se a inicialização falhar.
pub struct ComponenteX { ... }
```

---

### 2. Gerar documentação TypeScript (TypeDoc)

**Verificar configuração:**
```
mcp__gitea__get_file_content acidaos-dashboard/typedoc.json
```

**Gerar (no container dev):**
```bash
cd /root/Dev/acidaos-dashboard
pnpm typedoc --out docs/api src/
```

**Template JSDoc para componentes:**
```typescript
/**
 * AgentStatusCard — Mostra o estado de um agente AcidaOS
 *
 * @example
 * ```tsx
 * <AgentStatusCard
 *   agentId="agent-123"
 *   onRefresh={() => refetch()}
 * />
 * ```
 */
export interface AgentStatusCardProps {
  /** ID único do agente no Core */
  agentId: string;
  /** Callback chamado ao clicar em refrescar */
  onRefresh?: () => void;
}
```

---

### 3. Publicar arquitectura no Outline

**Criar/actualizar diagrama de arquitectura:**

```javascript
mcp__outline-api__create_document({
  title: "AcidaOS — Arquitectura Core",
  text: `
# Arquitectura AcidaOS Core

## Hub-and-Spoke

\`\`\`mermaid
graph TD
    A[acidaos-dashboard] -->|API REST| B[AcidaOS Core]
    B --> C[Agent Kernel]
    B --> D[Security & Sandboxing]
    B --> E[Memory Engine]
    B --> F[Observability]
\`\`\`

## Componentes

| Componente | Linguagem | Responsabilidade |
|-----------|-----------|-----------------|
| Core | Rust | Orquestração de agentes |
| Dashboard | Next.js | Interface de utilizador |
  `,
  collectionId: "<acidaos-collection-id>"
})
```

---

### 4. Criar ADR (Architecture Decision Record)

**Template ADR:**
```markdown
# ADR-<NNN>: <Título da Decisão>

**Data:** YYYY-MM-DD
**Estado:** [Proposto | Aceite | Depreciado | Substituído por ADR-NNN]

## Contexto

[Situação que levou à necessidade de tomar esta decisão]

## Opções Consideradas

1. **Opção A** — descrição breve
2. **Opção B** — descrição breve

## Decisão

[Opção escolhida e porquê]

## Consequências

**Positivas:**
- [Consequência positiva]

**Negativas / Trade-offs:**
- [Limitação ou custo]
```

---

## Quality Gate de Documentação

Antes de marcar tarefa como concluída:

- [ ] Rust: zero `missing documentation` warnings em `cargo doc`
- [ ] TypeScript: TypeDoc gera sem erros
- [ ] Novos módulos têm exemplos de uso nos comentários
- [ ] Diagramas Mermaid actualizado se arquitectura mudou
- [ ] ADR criado para decisões técnicas significativas

---
**Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos

---

## Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

```jsonl
{"date":"","issue":"","fix":"","source":"user|auto"}
```

*Adicionar nova linha após cada erro corrigido.*