# Glossário

Termos de domínio usados no código, na API, nas tools MCP e na interface. A coluna
**Na interface** traz o rótulo pt-BR (fonte: `frontend/src/glossary.ts`).

## Núcleo

| Termo | Na interface | Definição |
| --- | --- | --- |
| Project | Projeto | Unidade de isolamento. Tudo (tasks, memórias, knowledge, telas, vínculos de skills e MCPs) pertence a um projeto; a chave de agente alcança só os projetos dela. |
| Task | Task / tarefa | Item do board, com status, prioridade, todos, decisões, anexos e vínculos. |
| Início | Início | Início previsto da task (roadmap): dia inteiro (`YYYY-MM-DD`) ou instante ISO 8601; nulo = sem data. |
| Fim | Fim | Fim previsto da task (roadmap); nunca antes do início (422). |
| Dia inteiro | Dia inteiro | Planejamento só com o dia (`00:00:00.000Z`, fim inclusivo), o mesmo dia em qualquer fuso. |
| Roadmap | Roadmap | Linha do tempo do projeto: Gantt e agenda sobre o início e o fim das tasks, com as dependências como setas. |
| Dias úteis | Dias úteis | Dias que o Gantt pinta como trabalho (`1,2,3,4,5` por padrão, 1 = segunda); preferência do projeto. |
| Gantt | Gantt | Visão do roadmap em barras no tempo, uma linha por task, com as dependências como setas; arrastar reprograma. |
| Agenda | Agenda | Visão do roadmap em calendário (mês, semana, dia): dia inteiro na faixa do topo, com hora na grade de horas. |
| Sem data | Sem data | Tasks sem início nem fim: a lista ao lado do roadmap, de onde se agenda. |
| Atrasada | atrasada | Task aberta com o fim já passado; calculada só na tela (não muda status nem o "Precisa de atenção"). |
| Demand | — | Sinônimo legado de **task** no Knowledge: `scope: "demand"` e `demandId` marcam uma página que é produto de uma task; `KnowledgeTicketLink` é o vínculo N:N página ↔ task. Código novo diz *task*. |
| Todo | Item / checklist | Passo verificável de uma task. Marcado só com evidência. |
| Decision (HITL) | Decisão | Pergunta estruturada para um humano (`TaskDecision`, opções, respostas com revisão). Com decisão obrigatória pendente a task fica em `awaiting_human_decision` e não executa. |
| More information | Mais informação | Pedido do humano para o agente enriquecer a decisão (`awaiting_more_information`); o agente devolve com `task_return_to_decision`. |
| Task event | Histórico | Linha append-only de cada mudança de status, descrição ou vínculo, com o ator real (`TaskEvent`). |
| Memory | Memória | Contexto persistente do projeto (decisão, regra, aprendizado, preferência). Não é documento: é o que o próximo agente precisa lembrar. |
| Knowledge | Knowledge / página | Documento do projeto em HTML ou Markdown, com hierarquia, versões e busca. |
| Skill | Skill | Pacote de instruções no formato Agent Skills (`SKILL.md` com frontmatter + anexos). Built-in = semeada pelo backend. |
| Skill folder | Pasta | Organização de skills no catálogo global. |
| Agent prompt | Prompt de agente | Instrução em markdown que o agente **lê antes de agir** no projeto: briefing, checklist ou handover. **Não é** MCP Prompt (`prompts/list`), que é outra coisa: capacity do protocolo MCP. O prompt é do projeto (a empresa vem do projeto), tem versões com ator e vai para a lixeira em vez de sumir. Os 3 modelos do sistema são só leitura: "usar no projeto" cria uma cópia editável. |
| Agent key | Chave de agente | Credencial `apk_*` com projetos, escopos (`read`, `write`, `render:write`, `github:write`) e toolsets permitidos. O segredo só aparece na criação. |
| Bootstrap token | — | `AGENTPACK_AGENT_TOKEN`: Bearer de agente usado antes de existirem chaves por projeto e para cadastrar o primeiro usuário. |
| Actor / principal | — | Quem fez a requisição (`request.actor`): usuário (JWT), chave de agente ou token de bootstrap. Vai para `TaskEvent` e para os logs. |

## MCP

| Termo | Definição |
| --- | --- |
| Gateway `/mcp` | Endpoint Streamable HTTP stateless do backend que publica tools, resources e prompts. |
| Built-in tool | Tool própria, com prefixo `agentpack_` ([lista](mcp/tools.md)). |
| Proxied tool | Tool de um MCP externo cadastrado (`McpServer`), republicada como `<toolPrefix>_<tool>`. |
| Toolset | Grupo de tools ligado ou desligado por requisição (`core`, `tasks`, `knowledge`, `skills`, `decisions`, `prompts`, `render`, `render-admin`, `github`, `proxied` e os `<domínio>-admin`). Não é permissão: o escopo da credencial continua valendo. |
| Tool prefix | Prefixo único de um MCP externo (`^[a-z0-9_]{1,24}$`), gerado do nome no cadastro. |
| Project MCP | Vínculo de um MCP externo a um projeto, com `isActive`, override de config e allow/denylist de tools. |

## Render

| Termo | Definição |
| --- | --- |
| Screen / design | Tela declarativa (`RenderDesign`, identificada por `baseKey`) com uma árvore JSON por tema (`RenderScreen` light/dark). |
| Node | Nó da árvore da tela, endereçado por `key` estável. |
| Library | Documento de catálogo: `ui` (componentes + estilos), `tokens` ou `manifest` (mapa de artboards). Pode ser global ou do projeto; o projeto herda o global até a primeira escrita. |
| Component / primitive | Componente de catálogo com props, template e stories; primitiva é um nó nativo do motor (Box, Text, Button...). |
| Style rule | Regra CSS do catálogo (`sel` + `sx`), com variante escura opcional (`sel@dark`). |
| Tokens | Cores, fontes, raios e sombras referenciados como `$color.primary.main`. |
| Design system (kit) | Conjunto versionado de `ui` + `tokens` (+ `manifest`) aplicável a um projeto. *Kit* é sinônimo usado nas descriptions de tools; "kit em branco" = design system semeado com os componentes do starter kit. |
| Starter kit | Os componentes base embutidos no backend (estilo shadcn) que um design system novo recebe. |
| Port (porte) | Cópia auditada de conteúdo de catálogo (library, seleção de componentes ou design) de um escopo para um projeto (`RenderPort`). Global com porte ativo só muda por decisão humana. |
| Bundle | Exportação autossuficiente (`render/1`) de bibliotecas, telas e assets de um escopo. |
| Asset | Binário do Render (imagem, fonte) guardado em `RENDER_ASSETS_DIR`. |
| Artboard / map | Posição de uma tela no mapa do projeto (`manifest`). |

## Rótulos legados

Aceitos só na leitura; escrita nova usa o formato atual.

| Rótulo | Significado |
| --- | --- |
| `fiscaliza.tokens/v1` | Schema dos tokens do Render herdado do projeto de origem (Fiscaliza). |
| `fiscaliza-renderer/1` | Nome antigo do formato de bundle; hoje `render/1`. |
| `demand` / `demandId` | Ver **Demand** acima. |
| `NEW-001`, `ADR-00N` nos comentários | Plano original do Knowledge; ver [ADRs](adr/README.md). |
| `MCP_HUMAN_CAPABILITY` | Capability humana antiga para responder decisões; ignorada desde a TSK-02 (só usuário autenticado responde). |