@softize/opus 25.6.0 → 25.7.0

package/src/ui/docs/registry.tsx

@@ -27,6 +27,9 @@ export type { DocEntry, DocGroup, DocSection } from "./types.ts";
 
 // — Conceituais (Começar/Framework/Design/Introdução) —
 import gettingStartedMd from "./content/getting-started.md?raw";
+import overviewMd from "./content/overview.md?raw";
+import installationMd from "./content/installation.md?raw";
+import documentationPortalMd from "./content/documentation-portal.md?raw";
 import upgradingMd from "./content/upgrading.md?raw";
 import cycleMd from "./content/cycle.md?raw";
 import authMd from "./content/auth.md?raw";
@@ -149,8 +152,8 @@ export const iconScope: Record<string, unknown> = Object.fromEntries(
 );
 
 /** Página conceitual (Começar/Framework/Design/Intro): markdown direto (o H1/lead moram no md). */
-const doc = (content: string) => (): React.ReactElement => (
-  <DocMarkdown content={content} scope={iconScope} />
+const doc = (content: string, codeCollapsible = true) => (): React.ReactElement => (
+  <DocMarkdown content={content} scope={iconScope} codeCollapsible={codeCollapsible} />
 );
 
 /**
@@ -217,127 +220,206 @@ function UiRedirect(): React.ReactElement {
   );
 }
 
-/** As seções da doc do SDK (surface `/docs` do site). "Começar" fica na RAIZ (seção sem
- *  label); depois o Protocolo (núcleo invariante) e os Recursos (peças opt-in). */
+/** O percurso documental do SDK agrupa páginas pelo trabalho de quem consulta. */
 export const PROTOCOL_SECTIONS: DocSection[] = [
   {
-    // Sem label → páginas soltas no topo do menu (sem cabeçalho de seção).
-    label: "",
+    label: "Introdução",
     groups: [
       {
         pages: [
           {
-            slug: "getting-started",
-            title: "Primeiros passos",
-            render: doc(gettingStartedMd),
+            slug: "overview",
+            title: "Visão geral",
+            searchText: overviewMd,
+            render: doc(overviewMd, false),
           },
-          { slug: "cycle", title: "Evolução contínua", render: doc(cycleMd) },
           {
-            slug: "upgrading",
-            title: "Atualizar o Opus",
-            render: doc(upgradingMd),
+            slug: "installation",
+            title: "Instalação",
+            searchText: installationMd,
+            render: doc(installationMd, false),
+          },
+          {
+            slug: "getting-started",
+            title: "Primeiros passos",
+            searchText: gettingStartedMd,
+            render: doc(gettingStartedMd, false),
           },
         ],
       },
     ],
   },
   {
-    // O núcleo invariante do protocolo — uma página por recurso. Opus é protocolo + peças
-    // opcionais entregues como SDK (não Framework: a inversão de controle é do app).
-    label: "Protocolo",
+    label: "Conceitos fundamentais",
     groups: [
       {
         pages: [
           {
             slug: "actions",
-            title: "Actions & contratos",
+            title: "Actions e contratos",
+            searchText: actionsMd,
             render: doc(actionsMd),
           },
           {
             slug: "runtime",
-            title: "Runtime & adapters",
+            title: "Runtime e adapters",
+            searchText: runtimeMd,
             render: doc(runtimeMd),
           },
-          { slug: "data", title: "Camada de dados", render: doc(dataMd) },
+          {
+            slug: "data",
+            title: "Camada de dados",
+            searchText: dataMd,
+            render: doc(dataMd),
+          },
           {
             slug: "data-products",
             title: "Produtos de Dados",
+            searchText: dataProductsMd,
             render: doc(dataProductsMd),
           },
-          {
-            slug: "testing",
-            title: "Testes de action",
-            render: doc(testingMd),
-          },
-          { slug: "cli", title: "CLI opus", render: doc(cliMd) },
         ],
       },
     ],
   },
   {
-    // As peças OPT-IN que você liga (adapter + driver). A UI também é recurso do SDK, mas
-    // com catálogo próprio — a entrada 'ui' redireciona pra superfície /ui.
-    label: "Recursos",
+    label: "Integrações",
     groups: [
       {
         pages: [
           {
             slug: "auth",
             title: "Autenticação",
-            badge: "auth",
+            searchText: authMd,
             render: doc(authMd),
           },
           {
-            slug: "audit",
-            title: "Auditoria",
-            badge: "audit",
-            render: doc(auditMd),
+            slug: "ai",
+            title: "IA generativa",
+            searchText: aiMd,
+            render: doc(aiMd),
+          },
+          {
+            slug: "mcp",
+            title: "MCP",
+            searchText: mcpMd,
+            render: doc(mcpMd),
           },
+          { slug: "ui", title: "Interface com Opus ↗", render: () => <UiRedirect /> },
+          {
+            slug: "documentation-portal",
+            title: "Publicação de documentação",
+            searchText: documentationPortalMd,
+            render: doc(documentationPortalMd, false),
+          },
+        ],
+      },
+    ],
+  },
+  {
+    label: "Automação",
+    groups: [
+      {
+        pages: [
           {
             slug: "events",
             title: "Eventos",
-            badge: "events",
+            searchText: eventsMd,
             render: doc(eventsMd),
           },
-          { slug: "log", title: "Log", badge: "log", render: doc(logMd) },
-          {
-            slug: "observability",
-            title: "Observabilidade",
-            badge: "observability",
-            render: doc(observabilityMd),
-          },
           {
             slug: "queue",
             title: "Filas",
-            badge: "queue",
+            searchText: queueMd,
             render: doc(queueMd),
           },
           {
             slug: "executions",
-            title: "Acompanhamento de execuções",
-            badge: "executions",
+            title: "Execuções",
+            searchText: executionsMd,
             render: doc(executionsMd),
           },
           {
             slug: "scheduler",
             title: "Agendador",
-            badge: "scheduler",
+            searchText: schedulerMd,
             render: doc(schedulerMd),
           },
+        ],
+      },
+    ],
+  },
+  {
+    label: "Operação",
+    groups: [
+      {
+        pages: [
+          {
+            slug: "audit",
+            title: "Auditoria",
+            searchText: auditMd,
+            render: doc(auditMd),
+          },
+          {
+            slug: "observability",
+            title: "Observabilidade",
+            searchText: observabilityMd,
+            render: doc(observabilityMd),
+          },
+          {
+            slug: "log",
+            title: "Log",
+            searchText: logMd,
+            render: doc(logMd),
+          },
           {
             slug: "storage",
             title: "Armazenamento",
-            badge: "storage",
+            searchText: storageMd,
             render: doc(storageMd),
           },
+        ],
+      },
+    ],
+  },
+  {
+    label: "Testes e evolução",
+    groups: [
+      {
+        pages: [
           {
-            slug: "ai",
-            title: "IA generativa",
-            badge: "ai",
-            render: doc(aiMd),
+            slug: "testing",
+            title: "Testes de actions",
+            searchText: testingMd,
+            render: doc(testingMd),
+          },
+          {
+            slug: "upgrading",
+            title: "Atualização do Opus",
+            searchText: upgradingMd,
+            render: doc(upgradingMd),
+          },
+          {
+            slug: "cycle",
+            title: "Evolução contínua",
+            searchText: cycleMd,
+            render: doc(cycleMd),
+          },
+        ],
+      },
+    ],
+  },
+  {
+    label: "Referência",
+    groups: [
+      {
+        pages: [
+          {
+            slug: "cli",
+            title: "CLI",
+            searchText: cliMd,
+            render: doc(cliMd),
           },
-          { slug: "mcp", title: "MCP", badge: "mcp", render: doc(mcpMd) },
-          { slug: "ui", title: "UI ↗", render: () => <UiRedirect /> },
         ],
       },
     ],
@@ -348,8 +430,7 @@ export const PROTOCOL_SECTIONS: DocSection[] = [
  *  patterns. Mesma família das seções de protocolo — superfície própria só pelo volume. */
 export const UI_SECTIONS: DocSection[] = [
   {
-    // Raiz (sem label): o "getting started" da UI.
-    label: "",
+    label: "Introdução",
     groups: [
       {
         pages: [
@@ -798,16 +879,20 @@ export const UI_SECTIONS: DocSection[] = [
 ];
 
 /** O catálogo INTEIRO (compat): Maestro (lente) e `/__docs` mostram tudo numa nav só —
- *  inclusive o changelog, que no SITE é página do menu superior (fora destas seções);
+ *  inclusive o changelog, que no site é um destino global fora dos capítulos;
  *  o site divide em duas superfícies de navegação do mesmo SDK (PROTOCOL_SECTIONS em /docs,
- *  UI_SECTIONS em /ui). */
+ *  UI_SECTIONS em /ui). Mantém Primeiros passos como a página inicial histórica. */
 export const DOC_SECTIONS: DocSection[] = [
   {
     ...PROTOCOL_SECTIONS[0]!,
+    label: "",
     groups: [
       {
         pages: [
-          ...PROTOCOL_SECTIONS[0]!.groups[0]!.pages,
+          ...["getting-started", "cycle", "upgrading"].map((slug) =>
+            PROTOCOL_SECTIONS.flatMap((section) => section.groups.flatMap((group) => group.pages))
+              .find((page) => page.slug === slug)!,
+          ),
           {
             slug: "changelog",
             title: "Changelog",
@@ -815,16 +900,21 @@ export const DOC_SECTIONS: DocSection[] = [
           },
         ],
       },
+      {
+        label: "Introdução ao SDK",
+        pages: PROTOCOL_SECTIONS[0]!.groups[0]!.pages.filter((page) => page.slug !== "getting-started"),
+      },
     ],
   },
   // A união (/__docs, lente do Maestro) mostra tudo numa nav só e NÃO tem a superfície /ui
   // à parte — então tira a entrada-redirect 'ui' (o catálogo já entra via UI_SECTIONS).
   ...PROTOCOL_SECTIONS.slice(1).map((s) => ({
     ...s,
+    label: s.label === "Testes e evolução" ? "Testes" : s.label,
     groups: s.groups.map((g) => ({
       ...g,
-      pages: g.pages.filter((p) => p.slug !== "ui"),
+      pages: g.pages.filter((p) => !["ui", "cycle", "upgrading"].includes(p.slug)),
     })),
   })),
-  ...UI_SECTIONS,
+  ...UI_SECTIONS.map((section, index) => index === 0 ? { ...section, label: "Introdução à UI" } : section),
 ];

package/src/ui/docs/types.ts

@@ -3,6 +3,8 @@ import type * as React from 'react'
 export interface DocEntry {
   slug: string
   title: string
+  /** Rótulo curto para o menu; preserva o título completo na leitura e na busca. */
+  navigationTitle?: string
   /** Tag técnica opcional exibida na navegação ao lado do título. */
   badge?: string
   /** Texto adicional consultado pela busca. Não é apresentado na navegação. */