@acropole/skills 1.3.0 → 1.4.1

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 (33) hide show
  1. package/README.md +5 -4
  2. package/package.json +2 -3
  3. package/skills/acropole/SKILL.md +1 -0
  4. package/skills/acropole/references/arquitetura.md +29 -5
  5. package/skills/acropole/references/fluxos/app-novo.md +4 -4
  6. package/skills/apollo/references/subscriptions.md +10 -4
  7. package/skills/apollo/references/testes-build.md +1 -0
  8. package/skills/docker/SKILL.md +3 -0
  9. package/skills/docker/references/podman-local.md +73 -0
  10. package/skills/express/references/dados.md +3 -1
  11. package/skills/fastapi/SKILL.md +4 -4
  12. package/skills/fastapi/references/banco.md +53 -50
  13. package/skills/fastapi/references/estrutura.md +2 -2
  14. package/skills/fastapi/references/integracoes.md +8 -0
  15. package/skills/hefesto/SKILL.md +49 -14
  16. package/skills/hefesto/references/diagnostico.md +15 -5
  17. package/skills/hefesto/references/fluxo.md +64 -35
  18. package/skills/hefesto/references/mcp-diagnostico.md +44 -0
  19. package/skills/hefesto/references/mcp-roteiros.md +53 -0
  20. package/skills/hefesto/references/mcp-tools.md +94 -0
  21. package/skills/orfeu/SKILL.md +1 -1
  22. package/skills/orfeu/references/diferencas.md +1 -1
  23. package/skills/orfeu/references/node.md +1 -1
  24. package/skills/orquestracao/SKILL.md +1 -1
  25. package/skills/orquestracao/templates/spec.md +1 -1
  26. package/skills/trismegisto/SKILL.md +2 -2
  27. package/skills/trismegisto/references/angular-api.md +7 -5
  28. package/skills/trismegisto/references/angular-exports.md +12 -1
  29. package/skills/trismegisto/references/angular.md +10 -0
  30. package/skills/trismegisto/references/catalogo/seletores.json +8 -0
  31. package/skills/trismegisto/references/spine-api.md +148 -9
  32. package/skills/trismegisto/references/spine-recipes.md +1 -1
  33. package/skills/trismegisto/references/spine.md +1 -1
@@ -1,7 +1,7 @@
1
1
  # Catálogo de API — @trismegisto/angular
2
2
 
3
- > **Gerado** a partir do código-fonte da versão 1.0.2, a cada `npm run sync` do @acropole/skills.
4
- > Gerado do código-fonte do `@trismegisto/angular` 1.0.2. Confira a versão instalada no `package.json` do pacote em `node_modules`.
3
+ > **Gerado** a partir do código-fonte da versão 2.0.1, a cada `npm run sync` do @acropole/skills.
4
+ > Gerado do código-fonte do `@trismegisto/angular` 2.0.1. Confira a versão instalada no `package.json` do pacote em `node_modules`.
5
5
 
6
6
  Legenda: `input` = `[prop]`; `model` = two-way `[(prop)]`; `output` = `(evento)`.
7
7
  Slots são os seletores de `<ng-content>`: projete com o atributo (ex.: `<div footer>`).
@@ -2132,10 +2132,11 @@ Botão "voltar para o aplicativo" para quando a sessão/solicitação morreu de
2132
2132
 
2133
2133
  | Nome | Tipo | Tipo TS | Padrão | Descrição |
2134
2134
  |---|---|---|---|---|
2135
- | `origin` | input | `string \| null \| undefined` | `null` | URL de retorno (ex.: referrer do fluxo). Vazio esconde o botão. |
2135
+ | `origin` | input | `string \| null \| undefined` | `null` | URL de retorno (ex.: referrer do fluxo). Vazia, inválida ou fora de `http:`/`https:` esconde o botão. |
2136
+ | `allowedOrigins` | input | `readonly string[] \| null` | `null` | Origens aceitas além da própria página (`https://app.exemplo.com`; só esquema + host + porta contam). `null`/vazio = qualquer origem `http(s)`. |
2136
2137
  | `label` | input | `string` | `''` | Vazio = texto do catálogo no idioma ativo (`HERMES_MESSAGES.sessionRecovery.back`). |
2137
2138
  | `navigate` | input | `boolean` | `true` | |
2138
- | `returned` | output | `string` | | |
2139
+ | `returned` | output | `string` | | Emite o endereço já normalizado (absoluto) antes de navegar. |
2139
2140
 
2140
2141
  ## `hm-settings-dialog`
2141
2142
 
@@ -2249,12 +2250,13 @@ Item de rota da navegação lateral: um `<a routerLink>` de verdade (Ctrl/clique
2249
2250
  | `route` | input (obrigatório) | `string \| readonly unknown[]` | | |
2250
2251
  | `label` | input (obrigatório) | `string` | | |
2251
2252
  | `icon` | input (obrigatório) | `string` | | Nome de ícone do catálogo; quem usa registra. |
2253
+ | `opensMenu` | input | `boolean` | `false` | O item leva ao menu de um módulo, não direto a uma página: mostra a seta de "abre um menu". |
2252
2254
 
2253
2255
  ## `hm-sidebar-node`
2254
2256
 
2255
2257
  `SidebarNodeComponent` — import de `@trismegisto/angular/sidebar` (também na raiz)
2256
2258
 
2257
- Desenha uma árvore de `SidebarNode` com `hm-sidebar-group`/`hm-sidebar-link`. `depth` é quantos níveis ainda podem virar grupo: `0` desenha só links (lista de módulos), `Infinity` aninha até as folhas.
2259
+ Desenha uma árvore de `SidebarNode` com `hm-sidebar-group`/`hm-sidebar-link`. `depth` é quantos níveis ainda podem virar grupo: `0` desenha só links (lista de módulos), `Infinity` aninha até as folhas. Nó com filhos visíveis desenhado como link (profundidade esgotada) é a entrada de um módulo: o link ganha `opensMenu` (seta de "abre um menu"); folha de verdade leva direto à página, sem seta.
2258
2260
 
2259
2261
  | Nome | Tipo | Tipo TS | Padrão | Descrição |
2260
2262
  |---|---|---|---|---|
@@ -1,6 +1,6 @@
1
1
  # Exports por ponto de import — @trismegisto/angular
2
2
 
3
- > **Gerado** a partir do código-fonte da versão 1.0.2, a cada `npm run sync` do @acropole/skills (junto com o `angular-api.md`).
3
+ > **Gerado** a partir do código-fonte da versão 2.0.1, a cada `npm run sync` do @acropole/skills (junto com o `angular-api.md`).
4
4
 
5
5
  Tudo que cada `@trismegisto/angular/<ponto>` exporta: serviços (com os membros públicos), funções, constantes,
6
6
  tokens de injeção e tipos (com a declaração). Componentes, diretivas e pipes aparecem só pelo nome — inputs,
@@ -550,6 +550,15 @@ type CopyButtonVariant = 'icon' | 'text';
550
550
  - `DataGridColumnFilterComponent` — `hm-data-grid-column-filter` (ver angular-api.md)
551
551
  - `DataGridHeaderDirective` — `ng-template[hmColumnHeader]` (ver angular-api.md)
552
552
  - `DataGridComponent` — `hm-data-grid` (ver angular-api.md)
553
+ - `DataGridActionConfirm` — Confirmação de uma ação por linha (`HermesDialogService.confirm`). `confirmLabel` padrão: o rótulo da ação; `danger` padrão: o `danger` da ação.
554
+
555
+ ```ts
556
+ type DataGridActionConfirm = Omit<HermesConfirmOptions, 'danger' | 'confirmLabel'> & {
557
+ readonly danger?: boolean;
558
+ readonly confirmLabel?: string;
559
+ };
560
+ ```
561
+
553
562
  - `DataGridRowAction` — Ação por linha, desenhada como item do menu da última coluna.
554
563
 
555
564
  ```ts
@@ -560,6 +569,7 @@ interface DataGridRowAction<T = unknown> {
560
569
  readonly danger?: boolean;
561
570
  readonly separatorAbove?: boolean;
562
571
  readonly available?: (row: T) => boolean;
572
+ readonly confirm?: DataGridActionConfirm | ((row: T) => DataGridActionConfirm);
563
573
  }
564
574
  ```
565
575
 
@@ -2147,6 +2157,7 @@ type SegmentedControlEmphasis = 'subtle' | 'action';
2147
2157
  ## `@trismegisto/angular/session-recovery`
2148
2158
 
2149
2159
  - `SessionRecoveryComponent` — `hm-session-recovery` (ver angular-api.md)
2160
+ - `function safeReturnUrl(origin: string | null | undefined, document: Document, allowed?: readonly string[] | null): string | null` — `origin` resolvido contra a página e validado: só `http:`/`https:` e, com `allowed`, só a mesma origem da página ou uma das listadas. Devolve o `href` normalizado ou `null`.
2150
2161
 
2151
2162
  ## `@trismegisto/angular/settings`
2152
2163
 
@@ -392,6 +392,16 @@ expect(await name.getErrorText()).toBe('');
392
392
  - **`label=""` para satisfazer o tipo é bug de acessibilidade**: dê um rótulo real e use `labelHidden` se não
393
393
  quiser mostrá-lo.
394
394
  - **`Validators.required` não serve no `hm-date-range-picker`**: use `DateRangeValidators.required`/`.order`.
395
+ - **Largura de campo em barra de filtros**: não fixe largura menor que o tamanho natural do componente (ex.:
396
+ `flex: 0 0 16rem` num `hm-date-range-picker`). Até a 2.0.1 o campo não encolhia e o quadro vazava por cima do
397
+ vizinho; mesmo depois da correção, espremer duas datas corta o texto. Prefira `flex: 0 0 auto` (tamanho natural) ou
398
+ uma largura mínima que caiba o conteúdo, e confira a barra na largura de tela mais estreita que o app suporta.
399
+ - **`initialWidth` numa coluna de ações do `hm-data-grid`**: até a 2.0.1 ela é o tamanho FIXO da coluna no encaixe
400
+ automático (o conteúdo não é medido); um grupo de botões mais largo vaza da célula e o "…" do `hm-button-group` some.
401
+ Dimensione pelo conteúdo real (botões + "…" + respiro da célula) ou deixe sem `initialWidth`. Nas versões
402
+ seguintes ela vale como mínimo e a coluna cresce até caber.
403
+ - **Token que não existe não quebra o build**: `var(--hm-nome-errado)` deixa a propriedade inválida e o navegador usa o
404
+ valor inicial (ex.: ícone do tamanho do contêiner). Em estilo do app, use só tokens do `tokens.css` publicado.
395
405
  - **Ícone com nome errado não quebra o build**: vira ícone genérico com aviso `[hermes-icons]` no console. Confira
396
406
  o nome no catálogo.
397
407
  - **Não sobrescreva o DOM interno** (`.hm-btn__…`, `.hm-field__…`) nem teste por ele: muda entre versões. Ajuste
@@ -5523,6 +5523,10 @@
5523
5523
  "classe": "SessionRecoveryComponent",
5524
5524
  "import": "@trismegisto/angular/session-recovery",
5525
5525
  "inputs": [
5526
+ {
5527
+ "nome": "allowedOrigins",
5528
+ "tipo": "readonly string[] | null"
5529
+ },
5526
5530
  {
5527
5531
  "nome": "label",
5528
5532
  "tipo": "string"
@@ -5742,6 +5746,10 @@
5742
5746
  "nome": "label",
5743
5747
  "tipo": "string"
5744
5748
  },
5749
+ {
5750
+ "nome": "opensMenu",
5751
+ "tipo": "boolean"
5752
+ },
5745
5753
  {
5746
5754
  "nome": "route",
5747
5755
  "tipo": "string | readonly unknown[]"
@@ -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.2, 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,7 +55,7 @@ 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
- Favorites and recently visited pages, shared by every consumer in the app (page bar, home screen) and persisted per client in `localStorage`.
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)`
@@ -64,6 +64,14 @@ Favorites and recently visited pages, shared by every consumer in the app (page
64
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).
@@ -84,6 +92,7 @@ Favorites and recently visited pages, shared by every consumer in the app (page
84
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/`.
85
93
  - `APP_PACKAGE_INFO`: `InjectionToken<PackageInfo>`
86
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.
87
96
  - `SPINE_NEWS`: `InjectionToken<readonly (readonly SpineNewsItem[])[]>` — Multi: cada chamada de `provideSpineNews` contribui com uma lista.
88
97
  - `SPINE_MESSAGES_PT_BR`: `SpineMessages`
89
98
  - `SPINE_MESSAGES_EN`: `SpineMessages`
@@ -236,6 +245,12 @@ interface QuickAccessItem {
236
245
  }
237
246
  ```
238
247
 
248
+ #### `SpineUserStorageKey` (type)
249
+
250
+ ```ts
251
+ type SpineUserStorageKey = (typeof SPINE_USER_STORAGE_KEYS)[keyof typeof SPINE_USER_STORAGE_KEYS];
252
+ ```
253
+
239
254
  #### `RuntimeEnvironmentShape` (interface)
240
255
 
241
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.
@@ -307,7 +322,7 @@ interface SpineNewsItem {
307
322
 
308
323
  #### `SpineMessages` (interface)
309
324
 
310
- 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` (`…
311
326
 
312
327
  _Declaração longa — veja `@trismegisto/spine` em `node_modules` (arquivo de tipos do ponto de entrada)._
313
328
 
@@ -752,6 +767,8 @@ interface AuditTopRow {
752
767
  - `createRouter(clientId: string, body: any)`
753
768
  - `updateRouter(clientId: string, id: string, body: any)`
754
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).
755
772
  - `getGroups(clientId: string)`
756
773
  - `getGroupMembers(clientId: string, groupId: string)`
757
774
  - `addGroupMember(clientId: string, groupId: string, userId: string, role: string | null)`
@@ -789,6 +806,7 @@ interface AuditTopRow {
789
806
  - `AUTO_SERVICE_AUDIT_TEMPLATE_ROUTER_ID`: `'ad100004-0000-4000-8000-000000000001'`
790
807
  - `AUTO_SERVICE_HOME_TEMPLATE_ROUTER_ID`: `'6a9a13db-f31b-494e-b51c-79af0ac28b60'`
791
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…
792
810
 
793
811
  ### Tipos
794
812
 
@@ -803,6 +821,39 @@ interface AutoServiceConfig {
803
821
  }
804
822
  ```
805
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
+
806
857
  #### `AutoServiceClient` (interface)
807
858
 
808
859
  ```ts
@@ -950,7 +1001,7 @@ _Sem inputs/outputs._
950
1001
 
951
1002
  #### `spine-settings-panel` — `SettingsPanelComponent`
952
1003
 
953
- 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).
954
1005
 
955
1006
  _Sem inputs/outputs._
956
1007
 
@@ -968,7 +1019,7 @@ _Sem inputs/outputs._
968
1019
 
969
1020
  #### `spine-markdown` — `SpineMarkdownComponent`
970
1021
 
971
- Renderiza Markdown (GFM) como HTML com a tipografia do design system. O texto é tratado como dado: o HTML gerado passa pelo DOMPurify antes de chegar ao DOM.
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.
972
1023
 
973
1024
  | Nome | Tipo | Tipo TS | Padrão | Descrição |
974
1025
  |---|---|---|---|---|
@@ -981,8 +1032,11 @@ Renderiza Markdown (GFM) como HTML com a tipografia do design system. O texto é
981
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.
982
1033
 
983
1034
  - `readonly current$: BehaviorSubject` — Passo atual (null = tour inativo). O overlay component reage a isto.
984
- - `maybeStart(): void` — Dispara o tour só se ainda não foi visto nesta máquina. Chamar após o login.
985
- - `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).
986
1040
  - `next(): void`
987
1041
  - `prev(): void`
988
1042
  - `finish(): void` — Encerra o tour (concluído ou pulado) e marca como visto.
@@ -1019,6 +1073,18 @@ Tokens de aplicação pessoais (`x-app-token`) do usuário logado — `argos-adm
1019
1073
  - `create(body: { badge_id: string; name: string; validity_days: number }): Promise<CreatedAppToken>`
1020
1074
  - `revoke(id: string): Promise<void>`
1021
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
+
1022
1088
  #### `SpineDocsService` · `providedIn: root`
1023
1089
 
1024
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`.
@@ -1046,24 +1112,36 @@ Painel de novidades do app (ver `provideSpineNews`). Decide o que está devido
1046
1112
  - `readonly slides: signal<readonly SpineNewsSlide[]>(…)` — Slides em exibição (os devidos, ou todos os vigentes quando reaberto pelo menu).
1047
1113
  - `readonly isOpen: signal(…)`
1048
1114
  - `readonly hasAny: computed(…)` — Há alguma novidade vigente — o item "Novidades" do menu só aparece com isto.
1049
- - `scheduleOnEntry(): void` — Chamado uma vez pelo layout na entrada: abre as devidas, esperando o tour terminar.
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…
1050
1116
  - `showDue(): void` — Marca como vistas todas as novidades devidas e as abre num único painel.
1051
- - `showAll(): void` — Reabre todas as vigentes (menu do perfil), vistas ou não.
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).
1052
1118
  - `close(): void`
1053
1119
 
1054
1120
  ### Funções
1055
1121
 
1056
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…
1057
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).
1058
1127
 
1059
1128
  ### Constantes e tokens
1060
1129
 
1061
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…
1062
1131
  - `SPINE_SETTINGS_KEYS` — Seções que o próprio spine já traz. `key` é também o valor de `?settings=` na URL.
1063
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…
1064
1134
 
1065
1135
  ### Tipos
1066
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
+
1067
1145
  #### `OnboardingStep` (interface)
1068
1146
 
1069
1147
  ```ts
@@ -1194,6 +1272,67 @@ interface CreatedAppToken {
1194
1272
  }
1195
1273
  ```
1196
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
+
1197
1336
  #### `DocsEntry` (interface)
1198
1337
 
1199
1338
  Documento de uma tela que a pessoa logada pode abrir.
@@ -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**.