# Spec 036 — Backstage TechDocs + Spec Kit Companion (stack duplo)

**Criado:** 2026-06-22  
**Solicitado por:** Roger  
**Status:** 📋 **Backlog** — documentada 2026-06-22; implementação adiada (Roger)  
**Prioridade:** **P3** (futuro — após Watchman 035 e estabilização Spec Hub)  
**Hosts:** CT130 (Backstage web) · LAPTOP Roger (Spec Kit Companion)

---

## Resumo

Stack **duplo** e complementar — não competem:

| Camada | Onde | Para quê |
|--------|------|----------|
| **Spec Kit Companion** | Cursor / VS Code (LAPTOP) | Trabalho diário: Specify → Plan → Tasks → Done, timeline, Mermaid |
| **Backstage + TechDocs** | CT130 (web LAN/WAN) | Catálogo por VM/serviço, docs públicas à equipa, search central |
| **Forgejo** | CT130 | Fonte de verdade Git (já existe) |
| **spec.ligbox.com.br** | CT130 nginx | Hub de entrada → links Backstage + Forgejo + Companion doc |

**Substitui:** portal `/specs/` HTML caseiro (fase out após Backstage MVP).  
**Mantém:** Obsidian vault para notas; chat-bruto no repo.

---

## Arquitectura

```mermaid
flowchart TB
  subgraph LAPTOP["LAPTOP Roger"]
    Cursor[Cursor + Spec Kit Companion]
  end

  subgraph CT130["CT130"]
    Forgejo[Forgejo Git]
    BS[Backstage]
    PG[(PostgreSQL)]
    TD[TechDocs publisher]
    Hub[spec.ligbox.com.br hub]
  end

  Cursor -->|push specs| Forgejo
  Forgejo -->|clone / webhook| BS
  BS --> PG
  BS --> TD
  TD -->|mkdocs build| Forgejo
  Hub --> BS
  Hub --> Forgejo
```

---

## Backstage — modelagem Ligbox

### Entidades (Software Catalog)

| Kind | Exemplo | Anotação |
|------|---------|----------|
| **System** | `ligbox-platform` | Sistema global |
| **Component** | `vm122-ops-desk` | `backstage.io/techdocs-ref: dir:.` |
| **Component** | `vm112-onboard` | specs em `specs/001-*`, `017-*`, … |
| **API** | `desk-api` | OpenAPI futuro |
| **Resource** | `ct130-spec-hub` | Infra |

Ficheiro por VM: `catalog/vm122-catalog-info.yaml` (ou pasta `specs/` com annotation).

### TechDocs

- **Fonte:** `ligbox-ops-platform` — pastas `specs/NNN-*/` com `spec.md`, `mkdocs.yml` por spec ou monorepo plugin
- **Plugin:** [mkdocs-monorepo-plugin](https://github.com/backstage/mkdocs-monorepo-plugin) — nav por VM (Spotify pattern)
- **Build:** TechDocs backend no CT130 ou CI Forgejo → publicar em `techdocs-static/`

### URL alvo

| URL | Função |
|-----|--------|
| `backstage.ligbox.com.br` ou `spec.ligbox.com.br/catalog` | UI Backstage |
| Traefik CT114 | TLS + route |

---

## Spec Kit Companion — LAPTOP

### Instalação (Cursor = VS Code)

1. Extensions → pesquisar **SpecKit Companion** (`alfredoperez.speckit-companion`)
2. Abrir pasta `ligbox-ops-platform` (clone Forgejo)
3. Sidebar Companion → lista specs com fase actual
4. Workflow: Specify → Plan → Tasks → Done (alinhado com `/speckit.*`)

### Repo

- [github.com/alfredoperez/speckit-companion](https://github.com/alfredoperez/speckit-companion)
- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=alfredoperez.speckit-companion)

### Integração Ligbox

- `.specify/` e `specs/` já existem — Companion lê markdown local
- Push Forgejo após fase → Backstage reindexa TechDocs (web fica actualizado)
- Chat bruto: continua em `chat-bruto/`; link na spec.md

---

## CT130 — requisitos Backstage PoC

| Recurso | Actual | Mínimo Backstage PoC |
|---------|--------|----------------------|
| RAM | 4 GB (3.3 avail) | 4 GB apertado — **recomendado 6–8 GB** |
| Disco | 35 GB livre | ~5 GB (PG + node + cache) |
| Docker | forgejo + spec-portal | + backstage + postgres |

**Risco:** 4 GB pode funcionar em PoC leve; produção → aumentar RAM CT130 ou VM dedicada.

---

## Fases

### Fase 0 — Companion (hoje, LAPTOP)

- [ ] Roger instala extensão no Cursor
- [ ] Abre `ligbox-ops-platform` local
- [ ] Testa uma spec (ex. 035-watchman) no viewer

### Fase 1 — Backstage PoC CT130

- [ ] `deploy/backstage/docker-compose.yml` (app + postgres)
- [ ] `catalog-info.yaml` root + 5 VMs (112, 122, 123, 104, 130)
- [ ] TechDocs: 3 specs piloto (031, 035, 027)
- [ ] Traefik route `backstage.ligbox.com.br`

### Fase 2 — Catálogo completo

- [ ] Todas as specs 001–035 no catalog
- [ ] Search Backstage indexa chat-bruto (plugin custom ou path)
- [ ] Hub `spec.ligbox.com.br` aponta para Backstage como browser principal

### Fase 3 — Deprecar HTML `/specs/`

- [ ] Redirect `/specs/` → Backstage TechDocs
- [ ] `refresh-spec-driver.sh` só para fallback ou remove

---

## Critérios de aceitação (Fase 1)

1. Backstage abre no browser com 5 components (VMs) visíveis.
2. TechDocs renderiza spec 035 com sidebar e search.
3. Companion no Cursor mostra mesma spec com fases SDD.
4. Alteração em `spec.md` + push Forgejo → rebuild TechDocs em &lt; 10 min.

---

## Documentos relacionados

- Spec **031** — portal actual (a migrar)
- Spec **035** — Watchman
- [Backstage TechDocs](https://backstage.io/docs/features/techdocs/)
- [Spec Kit Companion](https://github.com/alfredoperez/speckit-companion)
