undefine-org/bl-org-dossier

Dossiês .bl.org que respondem

Um dossiê é um único arquivo .bl.org. Ele é a fonte, a página, o especificação executável e a folha de respostas. Um pequeno servidor Beam Lisp (o kit, ao lado deste arquivo) o renderiza com a partição bl.doc.spans real, publica-o na tailnet e escreve cada resposta que o leitor dá no bloco que ela responde. Sem banco de dados, sem segunda cópia: git diff mostra o que Othman disse.

Exemplar, leia antes de escrever um novo: ~/projects/tiny-tools/mobile-app/dossier/pocket-harness.bl.org (renomeado de baton.bl.org em 2026-10-31). Um exemplar pesado para desktop com mesas e um ciclo de vida executável: ~/projects/knowledger-interface-review/docs/reports/interface-review-20261031/knowledger-interface.bl.org. Casa de taste da qual descende: ~/code/undefine/omega/spikes/mobile/design-review/design-review.bl.org.

O ciclo

1. Pesquise primeiro. Fundamente cada afirmação em um caminho de arquivo, um comando que você executou ou uma fonte citada.
2. Escreva NOME.bl.org (estrutura abaixo). As células não recebem #+RESULTS escritas à mão — deixe bl doc run escrevê-las.
3. bl doc run ARQUIVO.bl.org e depois bl doc run ARQUIVO.bl.org --check (saída 0 = células verdes e resultados atuais).
4. Olhe para ele na largura de um celular antes de afirmar qualquer coisa (veja Vendo-o).
5. Publique:

   work serve NOME --http auto --cwd ~/.claude/skills/bl-org-dossier/kit \
     --env-file ~/.config/baton-dossier/service.env --ready-timeout 120 \
     -- /etc/profiles/per-user/othman/bin/bl serve serve.bl -- /abs/path/NOME.bl.org
   

   O arquivo env contém DOSSIER_OWNER= o login Tailscale do proprietário; somente essa identidade pode responder (Serve define Tailscale-User-Login; verificado em 2026-10-31). DOSSIER_HANDLE=timinou é o nome que as respostas carregam em :by; um login (um email) nunca é escrito no arquivo. O servidor relê o arquivo por requisição: editar o .bl.org não requer reinicialização. Editar o código .bl do kit requer: work restart NOME.
6. Leia as respostas:

   bl run ~/.claude/skills/bl-org-dossier/kit/answers.bl -- /abs/path/NOME.bl.org
   

   As respostas estão no cabeçalho do bloco: :answer B :at "2026-10-31 17:14" :note "…". Aja sobre elas, atualize o dossiê (altere o :status de uma decisão para decided, mova um cabeçalho do roteiro para DONE) e diga o que mudou.

Forma (o gosto de Othman)

Abra com a tese, termine com o que ele deve decidir. No meio, ganhe cada seção.

• #+title: nomeia a coisa e sua promessa. #+subtitle: uma frase. #+kicker: onde vive. #+status: honesto (Proposta · nada construído ainda).
• Em uma só respiração — lede + stats. Dois parágrafos curtos, quatro números.
• Defina as palavras — terms para cada substantivo que você usará. Se uma frase como "perfeito" carrega o pedido, divida-a nas promessas separadas que ela esconde e diga o que ela nunca significa (honest).
• Jobs — um job por momento de uso, cada um com o caminho do produto de referência e uma decisão.
• Screens — blocos screen, extraídos do texto. Nomes reais, repositórios reais, máquinas reais do ambiente real — nunca lorem ipsum.
• Como realmente funciona — sequence para qualquer coisa que cruze um fio; graph para topologia; rosetta para uma ideia em vários sistemas.
• O modelo, executável — Células Beam Lisp com asserts que fixam os invariantes do design. O resultado impresso sob cada célula é a prova.
• Trabalhos anteriores — matrix, fontes listadas, afirmações de terceiros rotuladas como de documentos.
• Decisões (decision, com as opções rejeitadas visíveis) → Perguntas (ask) → Roteiro (* TODO/DONE cabeçalhos com :PROPERTIES: :JOBS: :AREA: :PROTO:).
• O texto é curto. Posicionamento e peso carregam estado. Sem adjetivos de marketing. Diga o que não foi verificado.

Componentes

Atributos de cabeçalho: :chave valor ou :chave "valor entre aspas". Corpos são linguagens de linha; linhas a | b | c a menos que indicado.

Bloco	Corpo	Renderiza
lede	prosa	abertura em serifa grande
stats	valor | rótulo | nota	tiles de estatísticas
terms	termo | significado	lista de definições
principles	título | texto	cartões numerados
note / warning / honest (:title)	prosa	destaques (ardósia / argila / ocre)
rosetta	primeira linha = cabeçalhos	tabela alinhada; cartões no celular
matrix	primeira linha = cabeçalhos; células y, ~, n + palavras opcionais	matriz de pontos com legenda
job :id :title :codex :claude :decision :screen	a frase JTBD	cartão de job + resposta
decision :id :title :status proposed|decided	- [x] escolhido, - [ ] rejeitado, depois justificativa	cartão de decisão + Concordo/Retrabalho/Discordo
ask :id :title :options "A|B|C"	contexto	cartão de pergunta + opções
screen :id :title :job :caption [:theme dark]	linguagem de tela (abaixo)	mockup de celular + reação; telas consecutivas formam uma faixa deslizável
desk :id :title :job :caption [:url]	linguagem de mesa (abaixo)	moldura de aplicativo desktop + reação; mesmos botões de resposta que as telas
sequence :title	lanes a · sub | b · sub, a -> b : label (chamada), a --> b : label (resposta), a => b : label (o momento chave), note a, b : texto, == divisor	SVG em telas largas, passos numerados em celulares
graph :title	node id | label | sub | col,row | tom (you door station builder foreign), edge a -> b | label | estilo (baton solid dash none; <->, -- também)	topologia SVG
schema :id :title	sem indentação entidade @ícone | glossário; indentado atributo tipo | nota. Tipos: text date, -> kind (ref), ->> kind (muitos), a > b / c (fluxo de estado), a, b, c (enum)	cartões de entidade, refs linkam para #entity-NOME, uma contagem de entidades · atributos · estados; respondível
procedure :id :title :makes	step @ícone Título | quem | nome · tipo, … (produz; um terceiro · rascunho = o harness o rascunha quando a tarefa começa), check @ícone Título | quem | nome, … (conselho de um verificador, agente ou pessoa), gate @ícone Título | quem | nome, … (espera por transferência); quem nomeia um papel; outras linhas são prosa	uma trilha de passos, checks tracejados, gates como losangos; respondível

Um bloco schema ou procedure também é a fonte que uma célula pode compilar: bl doc run passa o arquivo em (BeamLisp/argv), então uma célula pode ler seu próprio bloco e transformá-lo em atributos datom ou tarefas (exemplar: team-machine/design/work/WORK.bl.org, células spine, procedure).

Linguagem de tela, um verbo por linha: bar Título | direita (< Título adiciona voltar), sub, chips a* | b (* = selecionado), section Rótulo | contagem, card tom | título | meta | corpo (tons turn approve run done fail idle), ask, actions Primário! | Simples? | Silencioso? | Perigo^, msg você|agente | texto, tool rótulo | detalhe, diff +12 −3 | caminho, code texto, strip tom | texto | botão, row rótulo | valor, banner warn|ok | texto, dest ícone | título | corpo, note, spacer, input placeholder | ↑, tabs A* | B, lock hora | data + notif app | título | corpo | Ação, Ação (com :theme dark), sheet Título — tudo após ele fica em uma folha inferior sobre a tela. card tom | título | meta | corpo | @check! @x @next? — uma quinta coluna coloca ações de apenas ícone no cartão (diga o que é necessário no cartão, mantenha as ações como ícones; Othman acha linhas de botão difíceis de analisar), machine tom | @servidor nome | função | detalhe | direita (tons up busy asleep you), search placeholder + pick @pasta nome* | detalhe | direita (um seletor de projeto, * = escolhido), listen dica (microfone + forma de onda), heard transcrição, intent @enviar Verbo | alvo | texto (voz), choices A | B* | C (uma pergunta de múltipla escolha, * = escolhido), reply placeholder (uma resposta de texto livre com microfone e enviar). Fatos laterais em pick e machine fluem para o texto; ações do cartão ficam sob as palavras.

Linguagem de mesa — todo verbo de tela, mais regiões de desktop e um documento: nav @home Início* | @matter Assuntos (barra lateral, * = aqui), crumb a › b, head Título | tom · Status | Ação! | Outro? (o slot de ação, canto superior direito), meta a | b, tabs, col doc|rail|main (colunas; doc desenha papel; repita col main para uma linha de cartões), page Título, para texto com {+inserido+} {-deletado-} {~proposto~} {!verificar!} ‹P-01› (chip de fonte) ^1 (âncora de comentário), point tom | @ícone tipo | título | corpo | Opção* | Opção, comment 1 | quem | texto (mesmo número que seu ^1), opts A* | B. Linhas antes do primeiro col abrangem toda a largura. Mesas usam a paleta Warm Signal do Knowledger (lâmpada no modo escuro).

Ícones: @nome em qualquer lugar de uma linha de tela ou mesa desenha um ícone de linha — home matter library playbook people audit settings search plus send file word check x alert clock user bot chat comment link seal eye edit version diff filter more back next down up bell wait calendar scale flag play undo lock attach grid list board split spark. Prefira um ícone a uma palavra para tipos de coisas.

Blocos respondíveis: ask decision screen desk job schema procedure. Cada um precisa de um :id único.

Org simples também funciona: cabeçalhos com palavras-chave TODO e tags, gavetas :PROPERTIES: (chips), tabelas, listas, caixas de seleção [ ]/[X], =code=, *bold*, /italic/, [[url][rótulo]], [[#tela-ID][rótulo]].

Células executáveis

#+begin_src beam-lisp :id ciclo-de-vida
(ns projeto.model)           ; primeira célula nomeia o namespace; todas as células o compartilham
(defn avançar [s e] …)
(assert (= … …))             ; um assert falho se torna o resultado e --check sai com 1
{:what "o último valor é a prova impressa"}
#+end_src

Apenas #+begin_src beam-lisp em minúsculas (maiúsculas nunca executam). Modele os invariantes do design (um escritor, ordenação de efeitos, cobertura de um mapeamento), não trivialidades.

Armadilhas do Beam Lisp encontradas ao escrever estas (instalado bl, 2026-10-31): não estão no núcleo — ffirst, reductions, spit, replace, format, parse-long, prn. Use File/read!, File/write!, File/rename!, String/replace, Regex/run|scan|split|replace, erlang/binary_to_integer, (println (pr-str x)). Argumentos avaliam da direita para a esquerda. Nunca nomeie uma fn pública após uma fn do núcleo. Filhos de Hiccup devem ser seqs (map/for), não vetores: (map identity v).

Vendo-o

chromium --headless=new --no-sandbox --hide-scrollbars --window-size=412,16000 \
  --virtual-time-budget=5000 --screenshot=/tmp/d.png http://127.0.0.1:PORTA/
nix shell nixpkgs#imagemagick --command magick /tmp/d.png -crop 412x1000+0+0 +repage /tmp/d0.png

Páginas mais altas que 16000 px: salve o HTML com section.part anteriores ocultos e capture isso. Verifique: largura de celular primeiro, cada diagrama legível, ambos os temas, nenhuma célula ✗ falhou.

Lendo-o como um aplicativo

Em uma tela larga, a página é um aplicativo de duas colunas sem alteração no arquivo: cada cabeçalho de nível 1 se torna uma página em uma barra lateral (com seus cabeçalhos de nível 2 sob ela quando aberta). Uma seção mostra quantas respostas ainda espera, um ✓ quando respondida, e um roteiro com seu DONE/total. Uma seção é mostrada por vez, com anterior/próximo no rodapé e ←/→ para mover. #all (« Documento inteiro ») mostra tudo; qualquer #âncora abre a seção que a contém. Em um celular, os chips alternam seções da mesma forma. Escreva cabeçalhos de nível 1 como as páginas do relatório e nível 2 como suas partes.

Linguagens de design

Mockups podem usar a linguagem de design real de um produto. #+design: forest no topo de um dossiê desenha cada screen e desk nele (um bloco pode substituir com :design NOME, ou optar por sair com :design none); as linhas do mockup não mudam. Prefira a linguagem do próprio produto à paleta padrão do kit sempre que uma existir.

Uma linguagem é um módulo literado, kit/dossier/design/NOME.bl.org, cujas células são o namespace dossier.design.NOME: tokens (claro e escuro), escala tipográfica, raios, sombras, tokens de movimento e o CSS que reassocia as variáveis de mockup do kit. Registre-o em kit/dossier/design.bl. O mesmo arquivo é sua página de espécime, através de quatro blocos que se desenham a partir do módulo: #+begin_palette, #+begin_type, #+begin_shape, #+begin_motion (cada um com :design NOME, corpo vazio). Mantenha uma célula parity que verifica os tokens contra o CSS enviado do produto; o teste do kit afirma que não há deriva.

Enviadas: forest — Nurturing Forest, a máquina de equipe da Ora (design/forest.bl.org, publicado como o serviço forest-language).

Kit

kit/serve.bl (rotas / /doc /rev /src /answers POST /answer), kit/answers.bl, kit/dossier/{org,attrs,ui,page,answer,design}.bl (puro), kit/dossier/design/*.bl.org, kit/style.css, kit/live.js. Testes: bl test -p ~/.claude/skills/bl-org-dossier/kit kit/test/kit_test.bl. Um novo componente = uma fn -h em ui.bl, um caso em block->h, CSS, uma agulha no teste. As respostas são escritas por patch-line: apenas :answer :note :at :by mudam; cada outro byte do arquivo permanece.

A skill vive em ~/projects/enchanted-skills/bl-org-dossier (o repositório público undefine-org/enchanted-skills); ~/.claude/skills/bl-org-dossier é um symlink para ele. É compartilhada por toda sessão que usa esta skill. Commit conforme avança, uma ideia por commit, e prepare apenas seus próprios arquivos (git status primeiro: outra sessão pode estar no meio de uma edição). Um work restart de um serviço de dossiê carrega o que está no disco, edições não commitadas incluídas. Mantenha as respostas de um leitor em seu próprio commit no repositório do dossiê, para que git diff mostre o que ele disse.