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

name, description, allowed-tools

name	description	allowed-tools
docs	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.	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):

cd /root/Dev/acidaos-core
cargo doc --all-features --no-deps --open

Verificar cobertura de documentação:

cargo doc --all-features 2>&1 | grep "warning: missing documentation"

Template comentários 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):

cd /root/Dev/acidaos-dashboard
pnpm typedoc --out docs/api src/

Template JSDoc para componentes:

/**
 * 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:

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:

# 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.

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

Adicionar nova linha após cada erro corrigido.