Backstage Documentation — local offline corpus
Documentação oficial do Backstage (489 markdown pages extraídas de https://backstage.io/docs em 2026-05-01) disponível 100% offline em /root/nxt/terminal.net.br/recursos/backstage/_docs/. Esta skill mapeia cada categoria pra caminhos exatos de arquivos pra você poder responder perguntas específicas sem fetch externo.
Como usar esta skill
- Identifique a categoria da pergunta usando o mapa em
references/MAP.md
- Leia o arquivo específico com a tool Read (não use Glob/Grep gigante — a estrutura já indica onde está o conteúdo)
- Cite o caminho no answer pro usuário (formato:
recursos/backstage/_docs/<categoria>/<file>.md) pra que ele possa abrir e verificar
- Se a pergunta cruzar categorias (ex: "auth + permissions"), leia ambos arquivos relevantes
Atalhos por intent
| Intent do usuário |
Onde olhar primeiro |
| "Como instalar / criar app novo" |
getting-started/ |
| "Como funciona o frontend system / extensions / blueprints" |
frontend-system/architecture__*.md |
| "Como criar plugin frontend" |
frontend-system/building-plugins__*.md + frontend-system/building-apps__*.md |
| "Como funciona backend system" |
backend-system/architecture__*.md |
| "Como criar plugin backend" |
backend-system/building-plugins-and-modules__*.md + backend-system/building-backends__*.md |
| "Software Catalog / entidades / kinds" |
features/software-catalog__*.md |
| "Software Templates / scaffolder / wizard" |
features/software-templates__*.md |
| "TechDocs / docs as code / MkDocs integration" |
features/techdocs__*.md |
| "Search" |
features/search__*.md |
| "Auth provider X" (github, okta, google, gitlab, ldap, oauth2-proxy) |
auth/<provider>.md |
| "Permissions / RBAC" |
permissions/, tutorial--using-permissions-in-your-plugin/ |
| "Integration X" (github, gitlab, bitbucket-cloud, bitbucket-server, gitea, gerrit, azure, aws-s3, google-gcs, azure-blob-storage) |
integrations/<provider>__*.md ou top-level <provider>/ |
| "Kubernetes plugin" |
features/kubernetes__*.md |
| "Deployment / docker / k8s deploy / heroku" |
deployment/, getting-started/deployment-*.md |
| "Notifications" |
notifications/ |
| "Configuration / app-config.yaml / env vars" |
conf/, configuration/, configuring-backstage/ |
"CLI / backstage-cli commands" |
tooling/, backstage-cli/ |
| "Architecture decisions / why X exists" |
architecture-decisions/, architecture-decision-records--adrs-/ |
| "Tutorial X" |
tutorials/ |
| "Golden Path / best practices" |
golden-path/ |
Mapa completo
Pra detalhamento de cada categoria + arquivos, leia: references/MAP.md
Contexto NXT-specific
O deploy Backstage NXT roda em backstage.plataforma.app com:
- Código:
/root/nxt/terminal.net.br/recursos/backstage/services/backstage/app/
- Catalog source:
recursos/<slug>/index.v2.json (1107 items) + 360 Systems + 360 Groups
- Seed script:
projetos/catalogo.plataforma.app/scripts/seed-backstage-catalog.ts
- Theme NXT: zinc + lime
#deff3f em app/packages/app/src/modules/theme/index.tsx
- Reverse proxy:
services/backstage/caddy.conf importado em /etc/caddy/Caddyfile
- Service:
/etc/systemd/system/backstage.service
- DB: Postgres container
backstage-db na porta 5440
- Doc operacional:
services/backstage/CLAUDE.md
Pra perguntas operacionais (restart, regen catalog, debug logs), leia esse CLAUDE.md antes — é mais relevante que a doc oficial pra esses casos.
Quando NÃO usar esta skill
- Pergunta sobre outra ferramenta (Datasette, MkDocs, Backrest) — use a skill correspondente ou
recursos/<slug>/CLAUDE.md
- Perguntas sobre Backstage roadmap futuro /
/next/ previews — não capturado (skipped no extract)
- Changelog detalhado por release —
_docs/releases/ foi pulado; use npx @backstage/cli versions:check ou github upstream
Atualização do corpus
Re-extrair se necessário (incremento mensal):
cd /root/nxt/terminal.net.br/recursos/backstage
bash _docs/_extract.sh
Lê _docs/_sitemap.txt (489 URLs) e re-baixa via curl + pandoc paralelo.
1---2name: backstage-docs3description: Consulta a documentação completa do Backstage (Spotify's developer portal, CNCF) em 489 markdown pages locais offline. Use SEMPRE que o usuário perguntar sobre Backstage — instalação, plugins, frontend system (alpha), backend system, software catalog, software templates, scaffolder, techdocs, search, permissions, auth providers (GitHub, Okta, GitLab, etc), kubernetes plugin, integrations (GitHub/GitLab/Bitbucket/Azure/AWS S3), deployment, configuration, ou qualquer tópico Backstage. Cobre também o deploy NXT específico em backstage.plataforma.app. Use também em dúvidas tipo "como faço X no Backstage", "qual a config Y do Backstage", "como criar plugin Backstage", "como customizar tema Backstage" — mesmo se a pergunta não usar a palavra "Backstage" mas o contexto deixar claro (ex: usuário trabalhando em /root/nxt/terminal.net.br/recursos/backstage/).4---5
6# Backstage Documentation — local offline corpus
7
8Documentação oficial do Backstage (489 markdown pages extraídas de https://backstage.io/docs em 2026-05-01) disponível 100% offline em `/root/nxt/terminal.net.br/recursos/backstage/_docs/`. Esta skill mapeia cada categoria pra caminhos exatos de arquivos pra você poder responder perguntas específicas sem fetch externo.
9
10## Como usar esta skill
11
121. **Identifique a categoria** da pergunta usando o mapa em `references/MAP.md`
132. **Leia o arquivo específico** com a tool Read (não use Glob/Grep gigante — a estrutura já indica onde está o conteúdo)
143. **Cite o caminho** no answer pro usuário (formato: `recursos/backstage/_docs/<categoria>/<file>.md`) pra que ele possa abrir e verificar
154. Se a pergunta cruzar categorias (ex: "auth + permissions"), leia ambos arquivos relevantes
16
17## Atalhos por intent
18
19| Intent do usuário | Onde olhar primeiro |
20|---|---|
21| "Como instalar / criar app novo" | `getting-started/` |
22| "Como funciona o frontend system / extensions / blueprints" | `frontend-system/architecture__*.md` |
23| "Como criar plugin frontend" | `frontend-system/building-plugins__*.md` + `frontend-system/building-apps__*.md` |
24| "Como funciona backend system" | `backend-system/architecture__*.md` |
25| "Como criar plugin backend" | `backend-system/building-plugins-and-modules__*.md` + `backend-system/building-backends__*.md` |
26| "Software Catalog / entidades / kinds" | `features/software-catalog__*.md` |
27| "Software Templates / scaffolder / wizard" | `features/software-templates__*.md` |
28| "TechDocs / docs as code / MkDocs integration" | `features/techdocs__*.md` |
29| "Search" | `features/search__*.md` |
30| "Auth provider X" (github, okta, google, gitlab, ldap, oauth2-proxy) | `auth/<provider>.md` |
31| "Permissions / RBAC" | `permissions/`, `tutorial--using-permissions-in-your-plugin/` |
32| "Integration X" (github, gitlab, bitbucket-cloud, bitbucket-server, gitea, gerrit, azure, aws-s3, google-gcs, azure-blob-storage) | `integrations/<provider>__*.md` ou top-level `<provider>/` |
33| "Kubernetes plugin" | `features/kubernetes__*.md` |
34| "Deployment / docker / k8s deploy / heroku" | `deployment/`, `getting-started/deployment-*.md` |
35| "Notifications" | `notifications/` |
36| "Configuration / app-config.yaml / env vars" | `conf/`, `configuration/`, `configuring-backstage/` |
37| "CLI / `backstage-cli` commands" | `tooling/`, `backstage-cli/` |
38| "Architecture decisions / why X exists" | `architecture-decisions/`, `architecture-decision-records--adrs-/` |
39| "Tutorial X" | `tutorials/` |
40| "Golden Path / best practices" | `golden-path/` |
41
42## Mapa completo
43
44Pra detalhamento de cada categoria + arquivos, leia: `references/MAP.md`
45
46## Contexto NXT-specific
47
48O deploy Backstage NXT roda em `backstage.plataforma.app` com:
49- Código: `/root/nxt/terminal.net.br/recursos/backstage/services/backstage/app/`
50- Catalog source: `recursos/<slug>/index.v2.json` (1107 items) + 360 Systems + 360 Groups
51- Seed script: `projetos/catalogo.plataforma.app/scripts/seed-backstage-catalog.ts`
52- Theme NXT: zinc + lime `#deff3f` em `app/packages/app/src/modules/theme/index.tsx`
53- Reverse proxy: `services/backstage/caddy.conf` importado em `/etc/caddy/Caddyfile`
54- Service: `/etc/systemd/system/backstage.service`
55- DB: Postgres container `backstage-db` na porta 5440
56- Doc operacional: `services/backstage/CLAUDE.md`
57
58Pra perguntas operacionais (restart, regen catalog, debug logs), leia esse `CLAUDE.md` antes — é mais relevante que a doc oficial pra esses casos.
59
60## Quando NÃO usar esta skill
61
62- Pergunta sobre outra ferramenta (Datasette, MkDocs, Backrest) — use a skill correspondente ou `recursos/<slug>/CLAUDE.md`
63- Perguntas sobre Backstage roadmap futuro / `/next/` previews — não capturado (skipped no extract)
64- Changelog detalhado por release — `_docs/releases/` foi pulado; use `npx @backstage/cli versions:check` ou github upstream
65
66## Atualização do corpus
67
68Re-extrair se necessário (incremento mensal):
69```bash
70cd /root/nxt/terminal.net.br/recursos/backstage
71bash _docs/_extract.sh
72```
73
74Lê `_docs/_sitemap.txt` (489 URLs) e re-baixa via `curl + pandoc` paralelo.
aibot88