Landing Pages — Meta Portal (meta.koder.dev)

1. Visão Geral

meta.koder.dev é o portal público de documentação da Koder Stack. Renderiza o conteúdo de meta/docs/ do monorepo como site estático navegável.

Não é uma landing de produto, marca, área ou spec individual — é um indexador de documentos. Tem nav hierárquico por tipo (RFC, spec, policy, registry, module, runbook, compendium), uma página por arquivo fonte, search client-side e cross-links resolvidos.

Distinto de:

• specs/landing-pages/products.kmd — landings de um produto
• specs/landing-pages/specs.kmd — landing de uma spec/formato (KVG, KPKG)
• specs/landing-pages/areas.kmd — landing de Área L2 (foundation, ai, …)
• specs/landing-pages/institutional.kmd — landings sobre a Koder (www, company)
• specs/landing-pages/catalog.kmd — Hub catalog (hub.koder.dev)
• specs/landing-pages/packages.kmd — página individual de pacote no Hub

Histórico canônico (2026-05-24):

1. ~10 landings de Área (meta/sites/areas), meta/sites/brand/

   e meta/sites/_ecosystem_gen.py referenciaram docs.koder.dev desde 2026-Q2 como "Public documentation" (sempre dead link).

2. Sessão de 2026-05-24 turn 3: owner pediu site pro conteúdo de

   meta/. Pragmaticamente decidido construir docs.koder.dev reusando o nome já referenciado. Implementação concluída em 5 turns (spec, renderer, vhost, audit, deploy paralelo) — portal shipped com 652 docs.

3. Mesma sessão turn 12: owner observou que o nome docs. está

   semanticamente errado pro conteúdo (RFCsspecspolicies/registries = "meta", não "docs do usuário"). Decisão revertida: canonical é meta.koder.dev, mirror direto do L1 domain meta/ do monorepo.

4. Cutover atomic agendado (Phase B) quando infra/net/jet liberar

   o lock atual (jet#160 Phase 1) — ver jet#NNN follow-up ticket no umbrella META-DOCS-131. docs.koder.dev → 301 → meta.koder.dev, landings editorialmente atualizadas, per-product docs ficam em <product>.koder.dev/docs/ quando os produtos shipam.

2. Escopo de Conteúdo

2.1 Em escopo (público, vai pro portal)

2.2 Fora de escopo (NUNCA publicar)

• meta/context/ — runbooks internos, hooks de IA, credenciais,

  notices, recaps. Privado por contrato.

• meta/brand/ — assets de marca (vivem em brand.koder.dev)
• meta/sites/ — landings (cada uma tem seu próprio domínio)
• Qualquer arquivo com frontmatter visibility: internal ou

  audit: private (ver §6.3)

• meta/docs/stack/backlog/ — tickets de trabalho interno

2.3 Avaliação per-diretório (decidir caso a caso)

• meta/docs/platform/ — possivelmente público; auditar conteúdo
• meta/docs/trust/ — possivelmente público; auditar conteúdo
• meta/docs/flow-releases/ — público se substituir

  flow.koder.dev/releases; senão, manter privado

• meta/docs/company/ — documentação de empresa/negócio pt-BR (marca/INPI,

  datacenter, cloud, projetos, processos, sessões). Mantida no monorepo (decisão de owner: tudo num repo); renomeada de meta/docs/docs/ + .kd→.kmd (stack-docs#157).

• meta/docs/stack/diagrams/, presentation/, build/ — públicos

  como assets/anexos, não páginas próprias

3. URL Canônica

Padrão: https://meta.koder.dev/<category>/<path>/

• <category> ∈ { rfcs, specs, policies, registries, modules,

  runbooks, releases, compendiums }

• <path> espelha 1:1 a estrutura de subdir na fonte, com .kmd/.md

  removidos e nomes preservados

• Trailing slash sempre presente (URLs com slash final → index.html

  do diretório virtual)

• Casos especiais:
  • Homepage: https://meta.koder.dev/ (não /index.html)
  • Search: https://meta.koder.dev/search/?q=<query> (client-side)
  • Sitemap: https://meta.koder.dev/sitemap.xml
  • 404: https://meta.koder.dev/404.html

Exemplos:

Regra de imutabilidade: URLs uma vez publicadas não mudam. Renomes em meta/docs/ precisam de redirect 301 em /redirects.toml consumido pelo Jet (#131.5 audit).

4. Estrutura do Arquivo de Site

meta/sites/meta/
├── _assets/
│   ├── meta.css            ← Estilos do portal (tokens, nav, sidebar, TOC, footer)
│   ├── meta-search.js      ← Busca da rota /search/ (padrão KDS, vanilla)
│   ├── graph.css / graph.js / graph3d.js  ← Graph explorer (home, §5.5)
│   ├── kvg.wasm / wasm_exec.js            ← gerados (META-DOCS-150.8, gitignored)
│   ├── fonts/              ← Inter + JetBrains Mono woff2 self-hosted
│   ├── search-index.json   ← Gerado pelo renderer (gitignored)
│   ├── icon.svg
│   └── og-image-default.png
├── _data/stack-graph.json  ← Gerado por koder-stack-graph
├── index.html              ← Gerado: homepage
├── <category>/             ← Gerado per category
│   ├── index.html
│   └── <doc-slug>/
│       └── index.html
├── search/index.html       ← Gerado
├── sitemap.xml             ← Gerado
├── robots.txt              ← Gerado (env-aware, §14)
└── 404.html                ← Gerado

Todos os HTMLs servidos são gerados pelo renderer (#131.2); os templates vivem embedded no renderer (products/dev/koder-tools/internal/docsrender/templates index.html, meta/sites/brand/index.html, meta/sites/_ecosystem_gen.py) e marque cada uma como:

• ✅ resolves — path canônico existe
• 🔁 redirects-to: <new-path> — entrada em redirects.toml necessária
• ❌ broken — bloqueia release até #131.5 decidir destino

CI gate: build do portal falha se houver broken sem resolução.

12. i18n

• Conteúdo (doc body) NÃO é traduzido — é EN por

  policies/language.kmd

• Chrome (nav, footer, breadcrumbs, status badges, "Recently

  updated") É traduzido EN ↔ PT-BR

• Toggle EN/PT no nav (mesmo padrão das outras landings)
• Default por geo / browser language; persiste em localStorage
• T1-T6 da spec specs/i18n/contract.kmd aplicam

13. Acessibilidade

• WCAG 2.1 AA
• Skip-to-content link no topo
• Sidebar tree navegável por teclado (arrow keys)
• Theme toggle com aria-label + aria-pressed
• TOC com aria-current="location" no item ativo
• Code blocks com role="region" e aria-label="Code sample"
• Tabela de conformance per page em audit periódico (#131 followup)

14. SEO

• sitemap.xml gerado no build, submetido ao Google Search Console
• Per-page meta tags (§7)
• robots.txt na raiz (/robots.txt — crawlers só leem a raiz) —

  Allow: / + Sitemap: em prd, Disallow: / em stg/dev (per policies/environments.kmd); gerado pelo renderer via --env

• IndexNow ping no deploy de produção (lista de URLs alteradas)
• Schema.org TechArticle JSON-LD em doc pages

15. Deploy

Per policies/web-server.kmd (Jet only) + policies/environments.kmd:

DNS A record provisionado via ClouDNS (meta/context/infrastructure/dns.md). TLS via Jet autocert (LE/ACME).

Pipeline de deploy:

1. CI roda koder-docs-render --env <env> no monorepo
2. Output em meta/sites/docs/ (sub-paths gitignored)
3. rsync pro /var/www/meta.koder.dev/ no s.forge
4. Jet reload (zero-downtime)
5. Smoke: curl -I https://meta.koder.dev/ → 200 + TTFB <500ms
6. Lighthouse: a11y ≥ 95, perf ≥ 90, SEO = 100

16. Performance Targets

17. Governança

• Owner: Koder Stack (Rodrigo)
• Spec maturity gate: v1.0 normative quando #131.2.3.4.5.6/.7

  do umbrella META-DOCS-131 estiverem done + lighthouse scores atingidos + dead-link audit limpa em 2 builds consecutivos

• Versioning: a spec do portal segue semver per

  specs/landing-pages/specs.kmd §6

• Audit: koder-spec-audit landing-pages --slug docs (a ser

  implementado pelo audit harness em dev/koder-tools/)

18. Decisões Em Aberto

1. Search backend long-term: lunr.js (v0) → kdb-search quando

   rfcs/stack-RFC-001-kdb-as-unified-data-plane.kmd entregar layer de busca. Decisão revisitada no kickoff de #131.2.

2. Versionamento de docs: always-latest (HEAD) vs por tag

   (v1.0, v1.1). Default v0: always-latest; versões anteriores acessíveis via Flow se requestado. Revisitar quando portal tiver ≥1 ano de tráfego.

3. OG image generation per page: usar kicon generate --targets og

   per doc, ou template estático compartilhado por categoria? Default v0: estático por categoria (8 imagens curadas).

4. Comments / feedback: deixar fora do v0. Avaliar Giscus

   (GitHub-backed) vs solução self-hosted em v2.

5. Versioned dark mode: usar Verge default ou expor preset

   switcher como no KDS? Default v0: Verge default, sem switcher.

6. Base CSS compartilhada — RESOLVIDO 2026-06-10 (c3, owner-aprovado

   via k-arch→k-go): a paleta web virou o preset Verge Web (verge.kmd §R9, export kds.koder.dev/tokens/verge-web.css) e o portal consome o export vendored com zero mudança visual (META-DOCS-171 done). Migração das demais landings: follow-up.

19. Referência Cruzada

• specs/landing-pages/institutional.kmd — padrão de footer dark + nav
• specs/landing-pages/specs.kmd — padrão de doc-as-page
• specs/kmd/ — parser canônico
• policies/hyperscale-first.kmd — gate de build incremental
• policies/reuse-first.kmd — reuso de ecosystem.css
• meta/sites/_ecosystem_gen.py — gerador atual de landings de Área

  (referencia o dead link meta.koder.dev/ecosystem)

• META-DOCS-131 — umbrella ticket do programa
• JET-161 — vhost ticket

20. Estado Atual (2026-05-24)