@acropole/skills 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +4 -3
  2. package/package.json +4 -4
  3. package/skills/acropole/SKILL.md +2 -0
  4. package/skills/acropole/references/arquitetura.md +29 -5
  5. package/skills/acropole/references/fluxos/app-novo.md +4 -4
  6. package/skills/acropole/references/fluxos/tela-nova.md +1 -1
  7. package/skills/apollo/references/subscriptions.md +10 -4
  8. package/skills/apollo/references/testes-build.md +1 -0
  9. package/skills/auto-servico/SKILL.md +153 -0
  10. package/skills/auto-servico/references/diagnostico.md +42 -0
  11. package/skills/auto-servico/references/roteiros.md +63 -0
  12. package/skills/auto-servico/references/tools.md +108 -0
  13. package/skills/docker/SKILL.md +3 -0
  14. package/skills/docker/references/podman-local.md +73 -0
  15. package/skills/express/references/dados.md +3 -1
  16. package/skills/fastapi/SKILL.md +4 -4
  17. package/skills/fastapi/references/banco.md +53 -50
  18. package/skills/fastapi/references/estrutura.md +2 -2
  19. package/skills/fastapi/references/integracoes.md +8 -0
  20. package/skills/hefesto/SKILL.md +49 -14
  21. package/skills/hefesto/references/diagnostico.md +15 -5
  22. package/skills/hefesto/references/fluxo.md +64 -35
  23. package/skills/hefesto/references/mcp-diagnostico.md +44 -0
  24. package/skills/hefesto/references/mcp-roteiros.md +53 -0
  25. package/skills/hefesto/references/mcp-tools.md +94 -0
  26. package/skills/orfeu/SKILL.md +1 -1
  27. package/skills/orfeu/references/diferencas.md +1 -1
  28. package/skills/orfeu/references/node.md +1 -1
  29. package/skills/orquestracao/SKILL.md +1 -1
  30. package/skills/orquestracao/templates/spec.md +1 -1
  31. package/skills/trismegisto/SKILL.md +4 -4
  32. package/skills/trismegisto/references/angular-api.md +653 -507
  33. package/skills/trismegisto/references/angular-exports.md +541 -130
  34. package/skills/trismegisto/references/angular-types.md +1 -1
  35. package/skills/trismegisto/references/angular.md +28 -8
  36. package/skills/trismegisto/references/catalogo/icones.json +5 -0
  37. package/skills/trismegisto/references/catalogo/seletores.json +452 -31
  38. package/skills/trismegisto/references/catalogo/tokens.json +136 -16
  39. package/skills/trismegisto/references/spine-api.md +181 -44
  40. package/skills/trismegisto/references/spine-recipes.md +1 -1
  41. package/skills/trismegisto/references/spine.md +4 -3
@@ -1,6 +1,6 @@
1
1
  # Catálogo de API — @trismegisto/spine
2
2
 
3
- > **Gerado** por `scripts/gerar/trismegisto-spine.mjs` a partir do código-fonte da versão 1.0.0, a cada `npm run sync` do @acropole/skills.
3
+ > **Gerado** por `scripts/gerar/trismegisto-spine.mjs` a partir do código-fonte da versão 2.0.1, a cada `npm run sync` do @acropole/skills.
4
4
  > Gerado do código-fonte do `@trismegisto/spine`. Confira a versão instalada no `package.json` do pacote em `node_modules`.
5
5
 
6
6
  Uma seção por ponto de entrada (o `import` exato). Dentro dela: componentes (seletor, inputs/outputs),
@@ -55,18 +55,28 @@ Preferências do usuário que não são de tema (tema/família/densidade continu
55
55
 
56
56
  #### `SpineQuickAccessService` · `providedIn: root`
57
57
 
58
- Favoritos e páginas abertas por último. Um serviço só, e não cada componente com a sua cópia do `localStorage`: é o que faz o coração da trilha (`spine-page-bar`) e a tela inicial mostrarem a mesma coisa na hora, sem recarregar.
58
+ Favorites and recently visited pages, shared by every consumer in the app (page bar, home screen) and persisted per client and per user in `localStorage` (`SpineUserStorage`: `<clientId>_nav_favorites_<sub>`). Recents are cleared on logout; switching users reloads both lists.
59
59
 
60
60
  - `readonly favorites: Signal (somente leitura)`
61
61
  - `readonly recents: Signal (somente leitura)`
62
62
  - `isFavorite(id: string | null | undefined): boolean`
63
63
  - `toggleFavorite(item: QuickAccessItem): void`
64
- - `recordVisit(item: QuickAccessItem): void` — Registra a visita: o mais recente vai pro topo e a lista não repete página.
64
+ - `recordVisit(item: QuickAccessItem): void`
65
65
  - `forgetRecent(id: string): void`
66
66
 
67
+ #### `SpineUserStorage` · `providedIn: root`
68
+
69
+ Chaves de `localStorage` do shell por usuário: `<clientId>_<lista>_<sub>`, com o `sub` do token da sessão. Num computador compartilhado, uma pessoa não vê os recentes/buscas/favoritos de quem entrou antes.
70
+
71
+ - `userId(): string` — `sub` do token da sessão (só leitura do payload); vazio sem sessão.
72
+ - `key(list: SpineUserStorageKey): string` — Chave de `localStorage` da lista para o usuário atual.
73
+ - `clearHistory(): void` — Apaga buscas recentes e páginas recentes do usuário (o atual ou o último visto). Favoritos ficam.
74
+
67
75
  ### Funções
68
76
 
69
77
  - `function routerIdOf(route: Route | null | undefined): string | null` — `router_id` da tela (nó 'page'), aceitando o argos antigo (que só mandava `route_id`, mesmo valor).
78
+ - `function mergeRouteTree(routes: readonly Route[] | null | undefined): Route[]` — Funde nós IRMÃOS que apontam para o mesmo endereço (`route_redirect`), em toda a árvore.
79
+ - `function spineRoutesOf(view: { routes?: readonly Route[] | null } | null | undefined): Route[]` — A árvore fundida da view atual (`ViewService.currentView`) — ver `mergeRouteTree`.
70
80
  - `function provideUi(config?: SpineConfig): EnvironmentProviders` — Registra o catálogo de ícones inteiro — o spine (header/sidebar/navegação/modal/onboarding) usa ícones de várias origens (shield, pencil, trash, floppy, chevrons...) que não vêm embutidos de graça (os componentes do hermes só registram os ícones que eles próp…
71
81
  - `function resolveSpineLogo(logo: SpineLogoConfig | false | null | undefined): SpineLogoSources | null` — Normaliza `SpineConfig.logo`: omitido → convenção; `false`/vazio → sem imagem (`null`).
72
82
  - `function applySpineFavicon(doc: Document, href: string): HTMLLinkElement | null` — Aponta o favicon do documento para `href`: atualiza o primeiro `<link rel="icon">` (ou `shortcut icon`) e remove os outros (senão o navegador pode continuar escolhendo um deles); sem nenhum, cria um no `<head>`. O `type` acompanha a extensão (some quando ela…
@@ -82,6 +92,7 @@ Favoritos e páginas abertas por último. Um serviço só, e não cada component
82
92
  - `SPINE_DEFAULT_LOGO`: `'assets/images/logo.svg'` — Convenção quando o app não configura `logo`: `src/assets/images/logo.svg` servido em `assets/images/`.
83
93
  - `APP_PACKAGE_INFO`: `InjectionToken<PackageInfo>`
84
94
  - `SPINE_ADMIN_API`: `InjectionToken<string>` — Base da API do argos-admin-server (ex.: `https://exemplo.com.br/argos/admin/api`) — recursos do próprio usuário (`/me/*`, hoje os tokens de aplicação) que o painel de configurações usa. Quem chama `provideAutoService({ adminApi })` já fornece este token (é a…
95
+ - `SPINE_USER_STORAGE_KEYS` — Listas do shell guardadas no navegador, por usuário.
85
96
  - `SPINE_NEWS`: `InjectionToken<readonly (readonly SpineNewsItem[])[]>` — Multi: cada chamada de `provideSpineNews` contribui com uma lista.
86
97
  - `SPINE_MESSAGES_PT_BR`: `SpineMessages`
87
98
  - `SPINE_MESSAGES_EN`: `SpineMessages`
@@ -221,20 +232,25 @@ interface PackageInfo {
221
232
 
222
233
  #### `QuickAccessItem` (interface)
223
234
 
224
- Uma página guardada no navegador (favorito ou recente). Cópia, e não referência à árvore: a árvore pode mudar, e uma página que saiu do crachá atual continua listada até que se navegue pra ela -- melhor mostrar e receber "sem permissão" do que o favorito sumir sem explicação.
235
+ A page remembered by the shell, either as a favorite or as a recent visit.
225
236
 
226
237
  ```ts
227
238
  interface QuickAccessItem {
228
- /** Identidade do item: o endereço da página (`route_redirect`). */
229
239
  readonly id: string;
230
240
  readonly icon: string;
231
241
  readonly displayName: string;
232
242
  readonly redirect: string;
233
- /** Rótulos dos ancestrais, do topo pra baixo ("Rede › DNS"). Vazio = página de nível 1. */
243
+ /** Ancestor labels, top-down. `[]` = top-level page; absent = stored by an older version. */
234
244
  readonly trail?: readonly string[];
235
245
  }
236
246
  ```
237
247
 
248
+ #### `SpineUserStorageKey` (type)
249
+
250
+ ```ts
251
+ type SpineUserStorageKey = (typeof SPINE_USER_STORAGE_KEYS)[keyof typeof SPINE_USER_STORAGE_KEYS];
252
+ ```
253
+
238
254
  #### `RuntimeEnvironmentShape` (interface)
239
255
 
240
256
  O mínimo do `environment` de um app que dá pra derivar em tempo de execução. Estrutural de propósito (não importa o `Environment` de nenhum app): serve pra todos.
@@ -306,7 +322,7 @@ interface SpineNewsItem {
306
322
 
307
323
  #### `SpineMessages` (interface)
308
324
 
309
- Textos do próprio spine (cabeçalho, navegação, configurações, tour, telas do auto-serviço…), no mesmo formato do `HermesMessages` da lib: seção → chave, parâmetros nomeados (`{name}`) e plural por `PluralMessage`. Alguns textos levam marcação simples (`<b>`, `<strong>`, `<code>`) e são exibidos com `[innerHTML]` — estão indicados no comentário.
325
+ Textos do próprio spine (cabeçalho, navegação, configurações, tour, telas do auto-serviço…), no mesmo formato do `HermesMessages` da lib: seção → chave, parâmetros nomeados (`{name}`) e plural por `PluralMessage`. Alguns textos levam marcação simples (`<b>`, `<strong>`, `<code>`) e são exibidos com `[innerHTML]` — estão indicados no comentário. Os que têm parâmetro saem por `formatMessageHtml` (`…
310
326
 
311
327
  _Declaração longa — veja `@trismegisto/spine` em `node_modules` (arquivo de tipos do ponto de entrada)._
312
328
 
@@ -751,6 +767,8 @@ interface AuditTopRow {
751
767
  - `createRouter(clientId: string, body: any)`
752
768
  - `updateRouter(clientId: string, id: string, body: any)`
753
769
  - `deleteRouter(clientId: string, id: string)`
770
+ - `getRouterTree(clientId: string)` — Árvore do menu (header → … → página) com os router_ids de cada nó, já na ordem gravada.
771
+ - `reorderRouters(clientId: string, groups: RouterOrderGroup[])` — Grava a ordem de UM nível (irmãos): o índice do grupo é a ordem; cada grupo escreve `${type}_order` em todos os seus routers. Vale também para routers de template (ordem é do client).
754
772
  - `getGroups(clientId: string)`
755
773
  - `getGroupMembers(clientId: string, groupId: string)`
756
774
  - `addGroupMember(clientId: string, groupId: string, userId: string, role: string | null)`
@@ -788,6 +806,7 @@ interface AuditTopRow {
788
806
  - `AUTO_SERVICE_AUDIT_TEMPLATE_ROUTER_ID`: `'ad100004-0000-4000-8000-000000000001'`
789
807
  - `AUTO_SERVICE_HOME_TEMPLATE_ROUTER_ID`: `'6a9a13db-f31b-494e-b51c-79af0ac28b60'`
790
808
  - `AUTO_SERVICE_SCREENS`: `Readonly<Record<'home' | 'groups' | 'apps' | 'client' | 'audit', () => Promise<Type<unknown>>>>` — As 5 telas do auto-serviço, carregadas sob demanda. Cada `import()` relativo vira um chunk próprio no FESM publicado (`trismegisto-spine-auto-service-<tela>-<hash>.mjs`), que o bundler do app mantém fora do carregamento inicial. Não exporte as telas no `publi…
809
+ - `AUTO_SERVICE_DOCUMENTS`: `Readonly<Record<keyof typeof AUTO_SERVICE_SCREENS, RouteDocument>>` — Documentação das 5 telas (botão de documentação da barra da página e índice "Documentação do sistema"): o manual de uso (`load`) e a especificação técnica (`loadTechnical`, só com `SpineConfig.technicalDocs`). O Markdown fica em módulos `.ts` próprios em `./d…
791
810
 
792
811
  ### Tipos
793
812
 
@@ -802,6 +821,39 @@ interface AutoServiceConfig {
802
821
  }
803
822
  ```
804
823
 
824
+ #### `RouterOrderType` (type)
825
+
826
+ Nível de um nó na árvore do menu (`GET /routers/tree`).
827
+
828
+ ```ts
829
+ type RouterOrderType = 'header' | 'navigation' | 'menu' | 'item' | 'submenu' | 'page';
830
+ ```
831
+
832
+ #### `RouterOrderNode` (interface)
833
+
834
+ Nó da árvore do menu: uma rota num nível, com todos os routers que passam por ela.
835
+
836
+ ```ts
837
+ interface RouterOrderNode {
838
+ route_type: RouterOrderType;
839
+ routed_id: string;
840
+ route_name: string;
841
+ route_display_name: string | null;
842
+ route_icon: string | null;
843
+ order: number;
844
+ router_ids: string[];
845
+ children: RouterOrderNode[];
846
+ }
847
+ ```
848
+
849
+ #### `RouterOrderGroup` (interface)
850
+
851
+ Um item da ordem nova de um nível (`PATCH /routers/reorder`).
852
+
853
+ ```ts
854
+ interface RouterOrderGroup { type: RouterOrderType; router_ids: string[] }
855
+ ```
856
+
805
857
  #### `AutoServiceClient` (interface)
806
858
 
807
859
  ```ts
@@ -819,26 +871,26 @@ interface AutoServiceClient {
819
871
 
820
872
  #### `GraphqlEnvelopeError` · extends Error
821
873
 
822
- Falha de negócio devolvida pelo backend, com o status do envelope preservado — a tela decide pelo `status` (403 = sem acesso, 404 = vazio, 500 = tente de novo). `message` é texto do backend: exibir como texto, nunca por `innerHTML`.
874
+ Business failure carried by an envelope. `status` is kept exactly as the backend sent it.
823
875
 
824
876
  ### Funções
825
877
 
826
- - `function isEnvelopeOk(status: GraphqlEnvelope<unknown>['status']): boolean` — O status do envelope indica sucesso? Número: 2xx. Texto: qualquer coisa que não seja erro.
827
- - `function unwrap<T>(envelope: GraphqlEnvelope<T> | null | undefined): T` — Confere o envelope e devolve o `data`.
828
- - `function envelopesOf(data: unknown): { field: string; status: number | string; message: string; ok: boolean }[]` — Os envelopes `{ status, message }` de primeiro nível de uma resposta (um por operação raiz).
829
- - `function failedEnvelopes(data: unknown, fallbackMessage: string = currentSpineMessages().graphql.serviceFailure): { field: string; status: unknown; message: string }[]` — Os envelopes com falha dentro de uma resposta (`result.data` inteiro, um campo por operação raiz). Usado pelo link de aviso do `provideGraphql`; exportado pra quem quiser o mesmo diagnóstico.
878
+ - `function isEnvelopeOk(status: GraphqlEnvelope<unknown>['status']): boolean`
879
+ - `function unwrap<T>(envelope: GraphqlEnvelope<T> | null | undefined): T` — Returns `data` of an ok envelope; throws `GraphqlEnvelopeError` for a missing or failed one.
880
+ - `function envelopesOf(data: unknown): { field: string; status: number | string; message: string; ok: boolean }[]` — First-level envelopes found in an operation's `data` (fields that carry both `status` and `message`).
881
+ - `function failedEnvelopes(data: unknown, fallbackMessage: string = currentSpineMessages().graphql.serviceFailure): { field: string; status: unknown; message: string }[]` — First-level fields whose status is a failure; `message` is optional here.
830
882
  - `function injectGraphqlClient(namedClient: string): GraphqlClient` — O `GraphqlClient` do backend `namedClient` (`environment.graphql.<chave>.namedClient`). Chamar em contexto de injeção.
831
- - `function provideGraphql(options: GraphqlOptions): Provider` — Clientes Apollo dos apps — UM lugar pra configuração que antes vivia copiada (e divergindo) em cada app: - token do Orfeu em `x-access-token` (o `@orfeu/node` não lê `Authorization`), no HTT…
883
+ - `function provideGraphql(options: GraphqlOptions): Provider`
832
884
 
833
885
  ### Constantes e tokens
834
886
 
835
- - `wsReconnected$`: `Subject<string>` — Emite o `namedClient` toda vez que o WebSocket RECONECTA depois de uma queda (não na 1ª conexão). O graphql-ws reassina as subscriptions sozinho, mas não reenvia o que foi publicado durante a queda — a tela usa isto pra ressincronizar.
887
+ - `wsReconnected$`: `Subject<string>` — Emits the `namedClient` whose socket came back after a drop (never on the first connection).
836
888
 
837
889
  ### Tipos
838
890
 
839
891
  #### `GraphqlEnvelope` (interface)
840
892
 
841
- O envelope que os GraphQL dos apps devolvem: `{ status, message, data }`. **O status vem dentro do payload, não no transporte** — uma resposta HTTP 200 pode carregar `status: 403` ou `500`. Ler o `data` sem conferir o `status` é o que faz a tela mostrar "lista vazia" onde devia dizer que faltou permissão ou que o serviço falhou.
893
+ Shape every root query/mutation field returns on the platform: business status travels in the payload.
842
894
 
843
895
  ```ts
844
896
  interface GraphqlEnvelope<T> {
@@ -877,25 +929,19 @@ interface GraphqlClient {
877
929
 
878
930
  #### `GraphqlEndpoint` (interface)
879
931
 
880
- Um backend GraphQL do app — o tipo de `environment.graphql.<chave>` em TODO app (importar daqui, não redeclarar). Campos mutáveis de propósito: o `main.ts` pode derivar `http`/`ws` do domínio em tempo de execução antes do bootstrap.
881
-
882
932
  ```ts
883
933
  interface GraphqlEndpoint {
884
- /** Nome do cliente Apollo (`apollo.use(namedClient)`). */
934
+ // Mutable on purpose: the runtime environment rewrites `http`/`ws` before bootstrap.
885
935
  namedClient: string;
886
936
  http: string;
887
- /** Sem `ws`, o cliente não tem subscription (só HTTP). */
888
937
  ws?: string;
889
938
  }
890
939
  ```
891
940
 
892
941
  #### `GraphqlOptions` (interface)
893
942
 
894
- Sem opções de comportamento DE PROPÓSITO: o padrão é o mesmo em todo app (lote, toast do envelope, reconexão, no-cache). O que varia entre apps é só QUAIS backends existem (`endpoints`).
895
-
896
943
  ```ts
897
944
  interface GraphqlOptions {
898
- /** `environment.graphql` do app: um cliente Apollo nomeado por entrada. */
899
945
  readonly endpoints: Readonly<Record<string, GraphqlEndpoint>>;
900
946
  }
901
947
  ```
@@ -943,7 +989,7 @@ _Sem inputs/outputs._
943
989
 
944
990
  #### `spine-onboarding-overlay` — `OnboardingOverlayComponent`
945
991
 
946
- Onboarding próprio: escurece a tela (holofote via box-shadow gigante no recorte do alvo) e posiciona um balão explicativo perto do elemento — ou centralizado nos passos sem alvo (boas-vindas/encerramento). Sem dependência externa, sem sequestrar o scroll da página.
992
+ Desenho do tour guiado: escurece a tela, recorta um holofote sobre o alvo do passo e põe o balão (título, texto, progresso e navegação) onde couber. Segue o `OnboardingService`; recalcula a cada passo e quando a janela rola ou muda de tamanho.
947
993
 
948
994
  _Sem inputs/outputs._
949
995
 
@@ -955,7 +1001,7 @@ _Sem inputs/outputs._
955
1001
 
956
1002
  #### `spine-settings-panel` — `SettingsPanelComponent`
957
1003
 
958
- Painel de configurações do shell (substitui as telas do antigo módulo "Sistema"): Aparência, Região, Atalhos, Conta e Sobre, mais as seções que o app registrar com `provideSettingsSection`. Tudo vale na hora — cada controle chama o serviço que já persiste aquela preferência (tema, densidade, menu lateral, fuso).
1004
+ Painel de configurações do shell (substitui as telas do antigo módulo "Sistema"): Aparência, Região, Atalhos, Conta, Conta e segurança (MFA, códigos de recuperação e sessões do Argos) e Sobre, mais as seções que o app registrar com `provideSettingsSection`. Tudo vale na hora — cada controle chama o serviço que já persiste aquela preferência (tema, densidade, menu lateral, fuso).
959
1005
 
960
1006
  _Sem inputs/outputs._
961
1007
 
@@ -967,17 +1013,17 @@ _Sem inputs/outputs._
967
1013
 
968
1014
  #### `spine-docs` — `SpineDocsComponent`
969
1015
 
970
- Modal de documentação: índice com busca à esquerda — ele não some ao abrir um documento, é por ele que se pula de uma tela para outra — e a leitura à direita, com a aba técnica só quando `SpineDocsService.showTechnical`.
1016
+ Modal de documentação das telas: índice (com busca) à esquerda e leitura à direita. Montado uma vez pelo `spine-layout`; abrir, fechar e o que se lê vêm todos do `SpineDocsService`.
971
1017
 
972
1018
  _Sem inputs/outputs._
973
1019
 
974
1020
  #### `spine-markdown` — `SpineMarkdownComponent`
975
1021
 
976
- Markdown → HTML sanitizado. O HTML vem de `innerHTML`, que o encapsulamento de view não alcança: por isso `ViewEncapsulation.None` com tudo escopado em `.spine-markdown`.
1022
+ Renderiza Markdown (GFM) como HTML com a tipografia do design system. O texto é tratado como dado: o HTML gerado passa pelo DOMPurify, com o perfil restrito do spine (`SPINE_MARKDOWN_PURIFY_CONFIG`: sem `<style>`/`style`, formulários e `<iframe>`; link externo com `rel="noopener noreferrer"`), antes de chegar ao DOM.
977
1023
 
978
1024
  | Nome | Tipo | Tipo TS | Padrão | Descrição |
979
1025
  |---|---|---|---|---|
980
- | `content` | input | `string` | `''` | |
1026
+ | `content` | input | `string` | `''` | Markdown cru. Vazio não desenha nada. |
981
1027
 
982
1028
  ### Serviços e classes
983
1029
 
@@ -986,8 +1032,11 @@ Markdown → HTML sanitizado. O HTML vem de `innerHTML`, que o encapsulamento de
986
1032
  Onboarding interativo próprio (sem dependência externa). O overlay/holofote e o balão são renderizados pelo OnboardingOverlayComponent, que escuta este serviço. Aparece uma vez por máquina (flag em localStorage), namespaced por cliente.
987
1033
 
988
1034
  - `readonly current$: BehaviorSubject` — Passo atual (null = tour inativo). O overlay component reage a isto.
989
- - `maybeStart(): void` — Dispara o tour só se ainda não foi visto nesta máquina. Chamar após o login.
990
- - `restart(): void` — Reabre o tour manualmente (menu Ajuda), ignorando a flag.
1035
+ - `readonly state$: Observable<OnboardingState>` — Fase do tour (ver `OnboardingState`). Emite o valor atual ao assinar.
1036
+ - `get state: OnboardingState` — Fase atual, síncrona.
1037
+ - `maybeStart(): void` — Dispara o tour só se ainda não foi visto nesta máquina. Chamar após o login. Quando é devido, o estado vira `pending` NA HORA (síncrono), antes da espera pelo shell — é isso que segura as novidades; quando não é, contin…
1038
+ - `restart(): void` — Reabre o tour manualmente (menu Ajuda), ignorando a flag. Também passa por `pending` → `running`.
1039
+ - `stop(): void` — Interrompe o tour (pendente ou na tela) SEM marcar como visto: o automático volta na próxima entrada. Usado quando a pessoa abre outra coisa que disputaria a tela com ele (as novidades pelo menu).
991
1040
  - `next(): void`
992
1041
  - `prev(): void`
993
1042
  - `finish(): void` — Encerra o tour (concluído ou pulado) e marca como visto.
@@ -1024,21 +1073,33 @@ Tokens de aplicação pessoais (`x-app-token`) do usuário logado — `argos-adm
1024
1073
  - `create(body: { badge_id: string; name: string; validity_days: number }): Promise<CreatedAppToken>`
1025
1074
  - `revoke(id: string): Promise<void>`
1026
1075
 
1076
+ #### `SpineAccountSecurityService` · `providedIn: root`
1077
+
1078
+ Conta do usuário no Argos (verificação em duas etapas, códigos de recuperação, sessões) pela API da conta com Bearer: o access token da sessão do app (`@orfeu/angular`), no header `Authorization` — o mesmo jeito que o Orfeu fala com o Argos (ex.: `switchBadge`). O Argos reconhece a sessão SSO pelo `sid` do token; não há cookie envolvido. Token vencido (`401 invalid_token`): renova uma vez (`silentRenew`) e repete. `available` é falso sem `AUTH_CONFIG` utilizável.
1079
+
1080
+ - `readonly baseUrl`
1081
+ - `readonly available`
1082
+ - `overview(): Promise<AccountOverview>`
1083
+ - `register(methodId: string, code: string): Promise<AccountOverview>`
1084
+ - `remove(methodId: string): Promise<AccountOverview>`
1085
+ - `sessions(): Promise<{ sessions: AccountSession[] }>`
1086
+ - `endOtherSessions(): Promise<{ ended: number }>`
1087
+
1027
1088
  #### `SpineDocsService` · `providedIn: root`
1028
1089
 
1029
- Documentação das telas. A fonte é o próprio mapa de componentes (`COMPONENT_ROUTES`, campo `document`), e o índice só lista o que está na árvore de rotas da pessoa — documento de tela sem acesso nunca é oferecido nem baixado.
1090
+ Estado da documentação das telas: o que está registrado em `COMPONENT_ROUTES` com `document`, filtrado pelas telas que existem na árvore da pessoa (documento de tela sem acesso nunca é oferecido), e a leitura em andamento no modal `spine-docs`.
1030
1091
 
1031
- - `readonly technicalAvailable`
1092
+ - `readonly technicalAvailable: boolean` — Visão técnica liberada (`SpineConfig.technicalDocs`; sem configuração, só em desenvolvimento).
1032
1093
  - `readonly isOpen: Signal (somente leitura)`
1033
1094
  - `readonly current: Signal (somente leitura)`
1034
1095
  - `readonly view: Signal (somente leitura)`
1035
1096
  - `readonly content: Signal (somente leitura)`
1036
1097
  - `readonly loading: Signal (somente leitura)`
1037
- - `readonly error: computed(…)` — Texto do erro de carregamento (vazio = sem erro), no idioma ativo.
1098
+ - `readonly error: computed(…)`
1038
1099
  - `readonly showTechnical: computed(…)`
1039
1100
  - `readonly index: computed<DocsGroup[]>(…)`
1040
- - `documentFor(routerId: string | null | undefined, sourceTemplateRouterId?: string | null): DocsEntry | null` — Documento da tela (router_id do client e, como alternativa, o router do template de origem), ou `null` quando ela não tem (ou a pessoa não tem acesso).
1041
- - `openForRoute(routerId: string | null | undefined, sourceTemplateRouterId?: string | null): void` — Abre o modal no documento da tela; sem documento, no índice.
1101
+ - `documentFor(routerId: string | null | undefined, sourceTemplateRouterId?: string | null): DocsEntry | null`
1102
+ - `openForRoute(routerId: string | null | undefined, sourceTemplateRouterId?: string | null): void`
1042
1103
  - `openIndex(): void`
1043
1104
  - `close(): void`
1044
1105
  - `open(entry: DocsEntry, view: DocsView = 'usage'): Promise<void>`
@@ -1051,24 +1112,36 @@ Painel de novidades do app (ver `provideSpineNews`). Decide o que está devido
1051
1112
  - `readonly slides: signal<readonly SpineNewsSlide[]>(…)` — Slides em exibição (os devidos, ou todos os vigentes quando reaberto pelo menu).
1052
1113
  - `readonly isOpen: signal(…)`
1053
1114
  - `readonly hasAny: computed(…)` — Há alguma novidade vigente — o item "Novidades" do menu só aparece com isto.
1054
- - `scheduleOnEntry(): void` — Chamado uma vez pelo layout na entrada: abre as devidas, esperando o tour terminar.
1055
- - `showDue(): void` — Abre as devidas e as marca como vistas (vistas juntas, marcadas juntas).
1056
- - `showAll(): void` — Reabre todas as vigentes (menu do perfil), vistas ou não.
1115
+ - `scheduleOnEntry(): void` — Chamado uma vez pelo layout na entrada: abre as devidas quando o tour estiver `idle` (não devido, concluído, pulado ou sem passo), mais `AFTER_TOUR_MS` para não emendar. Se o tour começar nesse intervalo, volta a espera…
1116
+ - `showDue(): void` — Marca como vistas todas as novidades devidas e as abre num único painel.
1117
+ - `showAll(): void` — Reabre todas as vigentes (menu do perfil), vistas ou não; as devidas entre elas passam a vistas. Interrompe o tour se ele estiver pendente ou na tela (ação mais recente da pessoa).
1057
1118
  - `close(): void`
1058
1119
 
1059
1120
  ### Funções
1060
1121
 
1061
1122
  - `function findTourTarget(selector: string): HTMLElement | null` — Primeiro elemento do seletor que está de fato na tela (tem tamanho e conteúdo). Não usa `offsetParent`: ele é `null` pra `position: fixed` (a sidebar) e pra `display: contents`, e o passo sumia do tour mesmo com o alvo visível. Com as abas vivas do workspace…
1062
1123
  - `function provideSettingsSection(section: SpineSettingsSection): Provider` — Registra uma seção do app no painel de configurações (aparece depois das do spine, antes de "Sobre"). Pode ser chamado várias vezes, uma por seção.
1124
+ - `function argosAccountApi(authority: string | null | undefined, realm: string | null | undefined): string | null` — Base da API da conta no Argos: `{authority}/api/realms/{realm}/account` — o mesmo `{authority}/api` que o `@orfeu/angular` usa para o OIDC (a `authority` já traz o contexto do serviço, ex.: `https://host/argos`). Sem `authority`/`realm` (ou com o `CHANGE_ME`…
1125
+ - `function accountErrorCode(err: unknown): string` — Código de erro que o Argos devolveu (`{ error: 'invalid_code' }`), ou `''`.
1126
+ - `function sanitizeSpineMarkdownHtml(html: string): string | null` — HTML limpo pelo perfil do spine, ou `null` quando não há DOM (SSR: melhor não renderizar).
1063
1127
 
1064
1128
  ### Constantes e tokens
1065
1129
 
1066
1130
  - `SPINE_BRAND`: `InjectionToken<Type<unknown> | null>` — Componente de marca que o header do shell desenha no lugar da imagem de `SpineConfig.logo` (tem prioridade sobre ela). Injeção em vez de projeção de conteúdo porque o `LayoutComponent` é montado pelo `Router`, não pelo template do app — não existe `<ng-conten…
1067
1131
  - `SPINE_SETTINGS_KEYS` — Seções que o próprio spine já traz. `key` é também o valor de `?settings=` na URL.
1068
1132
  - `SPINE_SETTINGS_SECTIONS`: `InjectionToken<SpineSettingsSection[]>`
1133
+ - `SPINE_MARKDOWN_PURIFY_CONFIG`: `Config` — Perfil do DOMPurify para o Markdown do spine (documentação de tela, novidades). Mais restrito que o padrão: o HTML entra no DOM do shell (sem shadow DOM), então - `<style>` e o atributo `style` ficam de fora (CSS valeria para a página inteira: esconder/redese…
1069
1134
 
1070
1135
  ### Tipos
1071
1136
 
1137
+ #### `OnboardingState` (type)
1138
+
1139
+ Fase do tour: `idle` (inativo: não é devido, terminou, foi pulado/interrompido ou não sobrou passo), `pending` (vai aparecer: desde o `maybeStart()`/`restart()` até o primeiro passo, enquanto espera o shell e os alvos) e `running` (um passo na tela). Quem não pode disputar a tela com o tour (o painel de novidades) espera `idle` — não um tempo fixo.
1140
+
1141
+ ```ts
1142
+ type OnboardingState = 'idle' | 'pending' | 'running';
1143
+ ```
1144
+
1072
1145
  #### `OnboardingStep` (interface)
1073
1146
 
1074
1147
  ```ts
@@ -1199,12 +1272,74 @@ interface CreatedAppToken {
1199
1272
  }
1200
1273
  ```
1201
1274
 
1275
+ #### `AccountMethod` (interface)
1276
+
1277
+ Um método de verificação em duas etapas, como o Argos devolve (nunca o segredo do TOTP).
1278
+
1279
+ ```ts
1280
+ interface AccountMethod {
1281
+ method_id: string;
1282
+ /** `totp`, `email`, `sms`... (nome fixo do método no Argos). */
1283
+ method_name: string;
1284
+ active: boolean;
1285
+ /** E-mail/telefone mascarados. */
1286
+ secret?: string;
1287
+ }
1288
+ ```
1289
+
1290
+ #### `AccountOverview` (interface)
1291
+
1292
+ `GET {api}/security`: métodos, política do realm, códigos de recuperação e estado da reautenticação.
1293
+
1294
+ ```ts
1295
+ interface AccountOverview {
1296
+ user: { username: string; name: string | null; email: string };
1297
+ policy: { required: boolean };
1298
+ methods: AccountMethod[];
1299
+ recovery_codes: { remaining: number };
1300
+ /** Id do "método" código de recuperação (reautenticação com um código). */
1301
+ recovery_method_id: string;
1302
+ reauthenticated: boolean;
1303
+ reauth_expires_in: number;
1304
+ /** Só na resposta do cadastro do primeiro método: os códigos de recuperação, exibidos uma vez. */
1305
+ recovery_codes_issued?: string[];
1306
+ }
1307
+ ```
1308
+
1309
+ #### `AccountSession` (interface)
1310
+
1311
+ Uma sessão (um login num navegador) e os aplicativos que a usam.
1312
+
1313
+ ```ts
1314
+ interface AccountSession {
1315
+ id: string;
1316
+ /** A sessão deste login (a do token do app). */
1317
+ current: boolean;
1318
+ /** Outra sessão do mesmo navegador. */
1319
+ this_device: boolean;
1320
+ device: { browser?: string | null; os?: string | null; mobile: boolean; label: string };
1321
+ ip: string | null;
1322
+ created_at: string;
1323
+ last_seen_at: string;
1324
+ /** `false`: o login no Argos venceu, só o refresh de algum aplicativo segue vivo. */
1325
+ sso_active: boolean;
1326
+ clients: { client_id: string; name: string | null }[];
1327
+ }
1328
+ ```
1329
+
1330
+ #### `AccountReauth` (type)
1331
+
1332
+ ```ts
1333
+ type AccountReauth = { password: string } | { method_id: string; code: string };
1334
+ ```
1335
+
1202
1336
  #### `DocsEntry` (interface)
1203
1337
 
1204
- Documento de tela já resolvido contra a árvore de rotas: título e grupo sempre presentes.
1338
+ Documento de uma tela que a pessoa logada pode abrir.
1205
1339
 
1206
1340
  ```ts
1207
1341
  interface DocsEntry extends RouteDocument {
1342
+ /** Chave da tela (router_id ou, sem ele, o do template), sempre em minúsculas. */
1208
1343
  readonly id: string;
1209
1344
  readonly title: string;
1210
1345
  readonly group: string;
@@ -1377,18 +1512,20 @@ Gate de navegação REAL (deep link, F5, `router.navigateByUrl` do painel focado
1377
1512
 
1378
1513
  #### `RouteDocument` (interface)
1379
1514
 
1380
- Documentação de uma tela, carregada sob demanda. O texto é markdown cru — no app, `import('./README.md')` com o loader `.md: "text"` no `angular.json` —, então viaja no chunk lazy da própria tela e só é baixado quando alguém abre a documentação.
1515
+ Manual de uma tela, declarado no `document` da própria `ComponentRoute` (mesma chave, o router_id). Os textos são Markdown buscado só quando alguém abre a documentação: nos apps, um `import()` do `.md` com o loader `text`, de modo que o conteúdo vai no chunk lazy da tela e não no carregamento inicial.
1381
1516
 
1382
1517
  ```ts
1383
1518
  interface RouteDocument {
1384
- /** Nome no índice. Opcional: sem ele vale o `route_display_name` da rota na árvore. */
1519
+ /** Nome da tela no índice da documentação; se faltar, usa-se o rótulo da rota na árvore do usuário. */
1385
1520
  title?: string;
1386
- /** Agrupa o índice. Opcional: sem ele vale o módulo (nó raiz) da rota na árvore. */
1521
+ /** Seção do índice em que a tela aparece; se faltar, usa-se o módulo de topo que a contém. */
1387
1522
  group?: string;
1388
- /** Manual de uso, para quem opera a tela (o `README.md`). */
1523
+ /** Texto para quem usa a tela no dia a dia (normalmente o `README.md` dela). */
1389
1524
  load: () => Promise<string>;
1390
- /** Especificação técnica, para quem desenvolve (o `ESPECIFICACAO.md`). Só exibida quando
1391
- * `SpineConfig.technicalDocs` (padrão: fora de produção, `isDevMode()`). */
1525
+ /**
1526
+ * Especificação técnica, para desenvolvimento (normalmente o `ESPECIFICACAO.md`). Só aparece com
1527
+ * `SpineConfig.technicalDocs` ativo — por padrão, apenas em `isDevMode()`.
1528
+ */
1392
1529
  loadTechnical?: () => Promise<string>;
1393
1530
  }
1394
1531
  ```
@@ -1,4 +1,4 @@
1
- # Receitas — @trismegisto/spine 1.0.0
1
+ # Receitas — @trismegisto/spine 2.0.1
2
2
 
3
3
  Padrões prontos para um app que usa o spine. Todos os componentes são standalone (importe as classes no
4
4
  `imports`). Os componentes `hm-*` usados no conteúdo das telas são do `@trismegisto/angular` — a API deles está
@@ -1,6 +1,6 @@
1
1
  # @trismegisto/spine — guia do shell
2
2
 
3
- Escrito para a **API 1.0.0**. Nomes exatos de cada export: `spine-api.md` (gerado do código); receitas
3
+ Escrito para a **API 2.0.1**. Nomes exatos de cada export: `spine-api.md` (gerado do código); receitas
4
4
  prontas: `spine-recipes.md`. O conteúdo das telas (componentes `hm-*`, tokens, formulários) é do
5
5
  `@trismegisto/angular`: `angular.md`. Sessão, token, `PrivateGuard`, logout e troca de crachá são do
6
6
  `@orfeu/angular` — skill **orfeu**.
@@ -220,8 +220,9 @@ tipo daqui; não o redeclare. O comportamento é fixo de propósito (sem opçõe
220
220
  - token do Orfeu em `x-access-token` no HTTP e no `connection_init` do WebSocket (na raiz e em `headers`),
221
221
  junto de `routeId`/`clientId` para a auditoria das subscriptions;
222
222
  - HTTP em lote (`HttpBatchLink`), `fetchPolicy: 'no-cache'`, `errorPolicy` padrão (`none`);
223
- - subscription por `graphql-ws`, só no navegador, reconexão ilimitada (backoff até 30 s); 401/4401/4403
224
- recria os sockets; aba que volta de mais de 60 s em segundo plano também. `wsReconnected$` emite o
223
+ - subscription por `graphql-ws`, só no navegador, reconexão ilimitada (backoff até 30 s); qualquer fechamento
224
+ do socket (inclusive 4401/4403) leva a reconectar com o token atual, nunca a erro na subscription; 401 de
225
+ HTTP ou de resolver recria os sockets; aba que volta de mais de 60 s em segundo plano também. `wsReconnected$` emite o
225
226
  `namedClient` a cada **re**conexão — use para ressincronizar (receitas §6);
226
227
  - **toast automático do envelope** `{ status, message, data }` de cada campo raiz: mutation avisa sempre que
227
228
  falha (texto do catálogo se não vier `message`) e no sucesso quando o backend manda `message`; query só