Seus bundles agora têm nome: okf 1.8.0

Até esta release, todo verbo da okf recebia um caminho. No dia 0 isso bastava, com o bundle morando ao lado do seu prompt. Mas conhecimento não fica num bundle só: existe o handbook, os docs do serviço, a wiki do time, o repositório em que você estava uma hora atrás. Caminho é relativo a onde você está, e você está sempre em outro lugar. Um caminho diz onde um bundle está. A okf 1.8.0 deixa você dizer o que ele é.

Registre uma vez, nomeie para sempre

$ okf registry set ./docs --as handbook
registered handbook → /Users/voce/work/billing/docs (37 concepts)

Esse nome agora funciona em todo lugar. O registry é um arquivo JSON simples em $OKF_HOME/registry.json (padrão ~/.okf): leia, grepe, edite na mão, versione nos seus dotfiles se quiser. Não há banco de dados nem daemon, e esse é o desenho inteiro. Ele guarda um caminho, um slug e um título por bundle, e nada mais, então nada pode apodrecer além do próprio caminho. Seus bundles continuam nos repositórios que são donos deles; o registry só sabe os nomes.

A gramática de nomes tem uma regra que vale conhecer: a gem pode inventar um nome, mas nunca pode substituir um que você escolheu. Um slug cunhado do nome do diretório ganha um sufixo em colisão (docs vira docs-2), porque você nunca pediu aquele nome. Um nome que você escolheu com --as ou rename é recusado em colisão, porque responder em silêncio por outro seria uma mentira.

@slug, onde quer que um diretório vá

Onde um verbo recebe um <dir>, agora vai um @slug:

okf lint @handbook            # de qualquer diretório da máquina
okf render @ -o graph.html    # @ sozinho é o default do registry
okf server @handbook @wiki    # um hub exatamente destes dois

O default não é uma configuração que você ajusta. O registry é ordenado, e a primeira entrada ainda em disco é o default: o bundle que um @ sozinho nomeia e que um okf server sem argumentos abre. okf registry default @slug move uma entrada para a frente, um rename mantém a posição, um del promove a próxima. Nada extra é guardado, então não existe coisa guardada para divergir, e o arquivo não consegue nomear um default que não está nele.

Um okf server sem argumentos agora significa algo

O okf server lê seu modo dos argumentos. Um bundle é a página clássica em /. Vários montam atrás de um hub, cada um em /b/<slug>/. E nenhum argumento serve o registry inteiro, com o default em /. Um comando agora abre tudo o que você conhece.

Atrás do hub, /b/ é um índice navegável dos bundles hospedados, um slug desconhecido responde com uma página que lista o caminho de volta em vez de texto seco, e Cmd/Ctrl-K abre um alternador, então ir do handbook para a wiki nunca sai da página. O hub lê seus bundles no boot; registrou um novo, reinicie, que é a troca honesta por um servidor que nunca re-escaneia seu disco a cada request.

A busca parou de se importar com qual bundle sabe

A pergunta que de fato manda você atravessar bundles é "onde isso está documentado?", e o okf search agora responde numa consulta só:

$ okf search @all rate limit
Search — @handbook @wiki · rate limit (2 of 40 concepts)

  @handbook  runbooks/rate-limits  Rate-limit runbook  ·  Runbook  ·  title
  @wiki      onboarding            Onboarding  ·  Note  ·  body

Os rankings se fundem entre bundles e cada linha é rotulada pelo bundle que respondeu, então "qual bundle sabe sobre X" custa um comando em vez de um comando por bundle. @all tolera um diretório registrado que sumiu, com um aviso; nomear um bundle explicitamente exige que ele exista. Pedir tudo é tolerante, pedir algo é estrito.

A página cresceu para o teclado, e para toda tela

A página do grafo deu o próprio passo nesta release. A paleta Cmd/Ctrl-K agora abre em todo modo, não só atrás de um hub: as views estão sempre na lista, e os bundles entram quando há bundles para alternar. / pula para a busca da view atual, e ? responde com uma folha de todos os atalhos, escrita contra o próprio handler de teclado que documenta, então ela não consegue divergir do que as teclas fazem. No inspetor, o type e as tags de um conceito viraram alças de filtro, e as listas de links leem como conceitos tipados, cada um com o ponto de cor que seu nó veste no grafo.

A mesma página agora viaja. Um único template serve um celular, um tablet e um desktop: em largura de celular o trilho de navegação vira uma gaveta, a barra de ferramentas se dobra numa folha de ajustes, os painéis ocupam a tela inteira e a lista de arquivos se recolhe para a barra de abas. O breakpoint acompanha a largura disponível para a página, não uma classe de dispositivo, então girar um tablet reavalia o layout e reajusta o grafo em vez de deixar você no layout errado.

A parte silenciosa: nomes são alicerce de ecossistema

Eis por que o registry importa além da conveniência. A direção que seguimos apontando é uma máquina onde qualquer agente consulta qualquer bundle, por uma interface padrão como o MCP, sem rastejar por arquivos. Toda versão desse futuro começa com o mesmo pré-requisito: a máquina precisa saber quais bundles tem e como eles se chamam. É exatamente isso que $OKF_HOME/registry.json é: um contrato que qualquer processo pode ler, num formato que você já inspeciona com cat.

okf search @all é esse futuro em miniatura, um processo por vez: recuperação federada sobre todo bundle que a máquina conhece. Nada a anunciar hoje, e nada que você precise esperar também, porque a coisa que torna o futuro possível é a mesma que faz a busca de hoje funcionar.

Sem Ruby na máquina? O hub está na imagem 1.8.0

Toda release publica uma imagem multi-arch correspondente no GitHub Container Registry, e a 1.8.0 não é exceção. A ghcr.io/serradura/okf:1.8.0 (também :1.8 e :latest), construída para linux/amd64 e linux/arm64, carrega o registry e o hub, então o grafo multi-bundle roda sem Ruby no host. Monte os bundles e sirva todos atrás de um hub:

docker run --rm -v "$PWD:/data" -p 8808:8808 \
  ghcr.io/serradura/okf:1.8.0 server handbook wiki --bind 0.0.0.0

Abra http://127.0.0.1:8808 e use Cmd/Ctrl-K para alternar entre eles. O guia de Docker também tem o instalador de um comando que dispensa o prefixo docker run, para você digitar okf server handbook wiki como a CLI nativa.

Também na 1.8.0

Uma pilha de coisas menores saiu junto: okf <comando> -h imprime o banner do próprio comando no stdout como qualquer outra saída, um arquivo que o leitor não consegue abrir não derruba mais o bundle inteiro (ele é pulado e reportado sob o §9.1 com seu errno), o lint e as views de leitura agora classificam um type em branco do mesmo jeito, e o endurecimento do registry que uma semana de revisão adversarial rendeu. O changelog tem a lista completa.