Padrão de README — Repositórios Koder

Formato do Arquivo

• Nome: README.kmd (Koder Markdown — extensão .kmd)
• Localização: raiz do repositório
• Idioma: inglês (en-US) — conforme regra geral de produtos Koder
• Encoding: UTF-8

Cabeçalho (Header)

O README sempre começa com um bloco HTML centralizado contendo:

<div align="center">
  <img src="icon.svg" alt="{Nome do Produto}" width="128" height="128">
  <h1>{Nome do Produto}</h1>
  <p><em>{Tagline — uma frase descritiva curta em itálico}</em></p>
</div>

Regras do cabeçalho:

• O ícone do produto (icon.svg) deve ser exibido centralizado horizontalmente no início do README, e abaixo dele o nome do produto também centralizado horizontalmente. Essa é a primeira coisa que o leitor vê ao abrir o repositório.
• O <img> referencia o icon.svg da raiz do repo por caminho relativo (src="icon.svg"). Isso garante que, ao alterar o icon.svg no repositório, o ícone exibido no README é atualizado automaticamente — sem necessidade de editar o README. A referência relativa é obrigatória; nunca usar URL absoluta ou data URI para o ícone no README.
• Tamanho fixo: width="128" height="128"
• O <h1> contém o nome do produto com formatação de título (ex: "Koder Kall", não "koder-kall")
• O <p><em> contém uma tagline descritiva, concisa, sem ponto final
• Nunca usar badges (stars, version, etc.) dentro do <div align="center">

Link do site (opcional, se o produto tiver landing page):

<p align="center"><a href="https://{subdominio}.koder.dev">https://{subdominio}.koder.dev</a></p>

Inserido logo após o </div> de fechamento do cabeçalho.

Badges (opcional):

Se o produto usar badges (license, linguagem, plataforma), colocá-las após o cabeçalho centralizado, em linha separada, antes do ---:

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Go](https://img.shields.io/badge/Go-1.22+-00ADD8.svg)](https://go.dev/)
[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20Windows%20%7C%20macOS-lightgrey.svg)]()

Usar shields.io estático (texto hardcoded, não dinâmico) para evitar dependência de serviços externos.

Separador:

Após o cabeçalho (e badges, se houver), sempre um --- horizontal rule.

Seções Obrigatórias (em ordem)

1. Features

Lista de funcionalidades organizadas em subcategorias com ###:

## Features

### {Subcategoria 1}
- Feature A
- Feature B

### {Subcategoria 2}
- Feature C

Regras:

• Bullet points (-), não numeração
• Frases curtas e objetivas, sem ponto final
• Agrupar features em subcategorias lógicas (ex: "Core", "Security", "Integrations", "AI")
• Mínimo 3 subcategorias, cada uma com 3-8 items

2. Quick Start

Instruções mínimas para instalar e rodar o produto:

## Quick Start

### Prerequisites
- {dependência 1}
- {dependência 2}

### Install
\```bash
git clone https://flow.koder.dev/{org}/{repo}.git
cd {repo}
{comando de instalação}
\```

### Configure
{instruções de configuração mínima}

### Run
\```bash
{comando para rodar}
\```

Regras:

• Clone URL sempre do Koder Flow (não GitHub)
• Usar kd install / kd run para projetos em Koder Koda
• Para Go: go build / go install
• Incluir exemplo de configuração mínima (apenas campos obrigatórios)
• Terminar com a URL padrão onde o serviço inicia (ex: http://localhost:7880)

3. Configuration Reference

Arquivo de configuração completo com todos os parâmetros documentados via comentários inline:

## Configuration Reference ({nome-arquivo}.toml)

\```toml
[section]
param = "default"    # Descrição do parâmetro
\```

Regras:

• Formato TOML preferido (ou YAML se o produto usar YAML)
• Cada parâmetro com comentário inline descritivo
• Mostrar valores default
• Agrupar em seções lógicas ([server], [auth], [database], etc.)

4. CLI Commands

Referência de todos os comandos disponíveis:

## CLI Commands

\```bash
{comando}    # Descrição
  --flag     # Descrição da flag
\```

5. API Reference

Se o produto expõe API REST, documentar os endpoints principais:

## REST API Reference

### {Recurso}

#### {Operação}

\```
{METHOD} {path}
\```

Request:
\```json
{...}
\```

Response `{status}`:
\```json
{...}
\```

Regras:

• Documentar autenticação no início da seção
• Incluir request e response bodies em JSON
• Mostrar status codes
• Agrupar por recurso (Rooms, Participants, Tokens, etc.)

6. Architecture Overview

Diagrama ASCII da arquitetura do sistema:

## Architecture Overview

\```
{diagrama ASCII}
\```

*Components:*
- *{Componente}*: {descrição}

Regras:

• Diagrama em ASCII art dentro de bloco de código (sem imagem externa)
• Lista de componentes em itálico abaixo do diagrama
• Mostrar fluxo de dados e dependências entre componentes

7. Development Guide

Informações para desenvolvedores que queiram contribuir:

## Development Guide

### Project Structure
\```
{árvore de diretórios}
\```

### Running Tests
\```bash
{comandos de teste}
\```

### Code Style
- {regra 1}
- {regra 2}

8. License

Última seção, sempre:

## License

MIT License. See [LICENSE](LICENSE) for details.

Seções Opcionais (inserir entre as obrigatórias conforme relevância)

Seção	Inserir após	Quando usar
WebSocket Protocol	API Reference	Se o produto usa WebSocket
Authentication Modes	API Reference	Se tem múltiplos modos de auth
Recording/Streaming	Features ou API	Se o produto grava/transmite mídia
Embed API	API Reference	Se o produto é embarcável via iframe/SDK
Webhooks	API Reference	Se o produto dispara webhooks
Prometheus Metrics	API Reference	Se expõe métricas Prometheus
TURN/STUN Config	Configuration	Se envolve WebRTC
AI Features	Features	Se tem recursos de IA
Data Models	Features	Se é um banco de dados ou similar
Migration Guide	Development	Se veio de outro nome/versão

Regras Gerais de Formatação

Separadores

• Usar --- (horizontal rule) entre todas as seções de nível ##
• Não usar --- entre subseções (###)

Blocos de código

• Sempre especificar a linguagem: ```bash, ```toml, ```json, ```html, etc.
• Para saídas genéricas ou diagramas ASCII: ``` sem linguagem
• Blocos de configuração devem mostrar o arquivo completo, não fragmentos

Tabelas

• Usar tabelas markdown para dados tabulares (data models, webhook events, comparativos)
• Alinhamento: coluna esquerda sem alinhamento especial, usar |---|---|

Links

• URLs internas: sempre Koder Flow (https://flow.koder.dev/{org}/{repo})
• Nunca referenciar GitHub para repos Koder
• Links para docs internos: usar caminhos relativos ([LICENSE](LICENSE), [docs](docs/))

Estilo de texto

• Termos técnicos em backtick: Redis, PostgreSQL, JWT
• Nomes de arquivos em backtick: kall.toml, icon.svg
• Comandos inline em backtick: kd run server
• Itálico para nomes de componentes na seção Architecture: SFU Router, HTTP API
• Negrito apenas para ênfase forte, usado com moderação
• Sem emojis

Comprimento

• README mínimo: ~200 linhas (produto simples/CLI)
• README típico: 400-800 linhas (produto com API)
• README máximo: ~1000 linhas (produto complexo como koder-kall, koder-kdb)
• Se ultrapassar 1000 linhas, mover seções detalhadas para docs/ e linkar

Referência de Implementação

O arquivo koder-kall/README.kmd é a implementação de referência canônica deste padrão. Em caso de dúvida sobre qualquer aspecto, consultar esse arquivo.