Provisionar uma tecnologia

Provisionar admite uma tecnologia (technology) e uma das linhas principais (major lines) dela no Fito. Todo componente de conhecimento sobre essa tecnologia, e todo caso com escopo nela, se liga ao registro que este passo escreve.

Esta página é para quem cria casos e ainda não encontra a sua tecnologia no Fito, ou não encontra a linha principal dela. Ela cobre preparar um lugar de onde criar, declarar a tecnologia e confirmar o registro que o comando redige. Ela não cobre os componentes em si — eles vêm depois, a começar por Ingerir uma árvore de código-fonte.

Onde este passo fica

Criar conhecimento é uma cadeia, e ela roda antes de você criar um caso:

1. Provisionar a tecnologia e a linha principal dela — esta página.
2. Ingerir algo para ler: uma árvore de código-fonte ou documentação buscada.
3. Identificar componentes candidatos.
4. Gerar e publicar esses componentes.
5. Depois, criar um caso que os referencie.

Por que nada adiante funciona sem ele

Todo passo seguinte consulta a tecnologia primeiro, e para quando ela não está lá:

• Os comandos de identificação e de geração recusam com “The Fito vocabulary holds no <slug> technology”, porque não há contra o que comparar candidatos nem a que ligar componentes.
• O push para com No technology found for "<slug>"., e recusa um componente que nomeia uma linha principal que a tecnologia não tem.
• O /fito-case-design se recusa a definir um caso com escopo na tecnologia, apontando que ela não existe. Ele também recusa um caso cujos componentes ainda não foram publicados, e manda você de volta para esta cadeia.

Então, até alguém provisionar uma tecnologia, ninguém consegue escrever um componente sobre ela nem definir um caso nela. Cada linha principal conta por si: uma tecnologia provisionada na 6 não deixa você criar para a 7 até a 7 ser provisionada também.

Preparar um diretório de trabalho

Crie a partir de um diretório seu. O pipeline escreve cada etapa em ./output/, dentro do diretório em que a sua sessão do pi roda, então um diretório reservado para a criação mantém essas etapas num só lugar. O Fito carrega em toda sessão do pi, então esse diretório não precisa de uma instalação própria.

1. Instale o pacote do Fito primeiro, como em Instalação e pré-requisitos.

2. Crie um diretório de trabalho e entre nele:

   mkdir -p ~/fito-authoring
   cd ~/fito-authoring

3. Comece as suas sessões do pi de criação nesse diretório.

Quando você começa a criar, a cadeia preenche o ./output/ desse diretório, uma pasta por etapa, cada uma escrita pelo comando ao lado dela:

output/
├── 1-ingest/
│   ├── source_bundle/            --source, na identificação ou no provisionamento
│   │   ├── files/
│   │   └── bundle.json
│   └── extracted_links_content/  /fito-fetch-urls-content, ou --fetch
├── 2-technology/
│   └── technology.yaml           /fito-create-or-update-technology
├── 2-identify/
│   ├── domain_concepts/          /fito-identify-domain-concepts
│   ├── execution_facts/          /fito-identify-execution-facts
│   └── usage_scenarios/          /fito-identify-usage-scenarios
└── 3-generate/
    ├── concept_content/          /fito-generate-domain-concepts
    ├── execution_fact_content/   /fito-generate-execution-facts
    └── usage_scenario_content/   /fito-generate-usage-scenarios

Os padrões de cada comando leem e escrevem nessas pastas, então um passo seguinte encontra o resultado de um anterior sem que ninguém diga onde ele está. O /fito-push-knowledge lê as três pastas de 3-generate/. A única exceção é o source_bundle/: nada o lê por padrão — veja Montar de novo para o próximo comando.

Um checkout de caso que você está criando também serve como diretório de trabalho — veja Ingerir um caso que você está criando.

Antes de começar

• Uma sessão do pi no seu diretório de trabalho.
• Um login no Fito pelo terminal. As escritas são autenticadas — rode o /fito-login se ainda não rodou.
• Um provedor de LLM configurado no pi, e o pacote pi-subagents instalado. O rascunho é escrito por uma persona trabalhadora, no seu próprio modelo.
• Algo sobre a tecnologia para ler: uma árvore de código-fonte, uma lista de URLs de documentação, ou uma pasta que um passo anterior já ingeriu. O rascunho é escrito a partir dessa evidência, nunca da memória do modelo.

Escolher o slug e a linha principal

Você declara os dois, como <slug>@<version>. Nem o comando nem o trabalhador dele adivinham isso a partir das fontes.

• Para uma ferramenta, a versão é a linha principal publicada pelos mantenedores: javalin@7 diz que o Javalin publicou uma linha de versões 7.
• Para uma prática, não existe linha de versões, então a versão é a numeração do próprio Fito, e a convenção é começar em 1: hexagonal@1. Nada confere o rótulo. Quem chama a primeira linha de cockburn-2005 não quebra nada, e abre mão só da uniformidade.
• Uma formulação posterior e distinta de uma prática — uma reformulação, uma escola rival — é uma nova linha principal da mesma tecnologia, não um slug novo. O assunto não mudou.

Para o que os dois tipos significam, veja Tecnologias, ferramentas e práticas. Para como as linhas principais funcionam, veja Versões e definições alternativas.

Confira a grafia de um slug existente

Antes de provisionar, abra /knowledge no aplicativo web e procure a tecnologia. Um slug digitado errado não é detectado: ele admite uma segunda tecnologia, independente, ao lado da verdadeira, e os componentes publicados contra as duas caem em registros diferentes.

Provisionar a tecnologia

1. Rode o comando com a sua declaração e uma fonte para ler:

   /fito-create-or-update-technology --technology javalin@7 --source ~/code/my-javalin-app

   Troque javalin@7 pelo seu <slug>@<version>, e o caminho pelo do seu projeto. Para documentação em vez de código, passe --fetch --urls urls.txt.

2. Leia o que o comando relata sobre o estado atual do Fito. Ele consulta o slug e diz qual destas três execuções é esta, mostrando as descrições que já existirem:

   O Fito tem	A execução
   Nenhuma tecnologia com esse slug	Uma criação da tecnologia e da linha principal
   A tecnologia, mas não essa linha principal	Uma criação da linha principal; a visão geral da tecnologia já existe e é enriquecida
   A tecnologia e essa linha principal	Uma atualização das descrições existentes

3. Espere o rascunho. Um trabalhador redige o nome da tecnologia, o tipo (kind) dela, a visão geral — o que ela é em todas as linhas principais — e o texto da linha principal que você declarou. Numa tecnologia existente, ele enriquece as descrições que já estão lá, em vez de substituí-las. O rascunho fica em ./output/2-technology/technology.yaml.

4. Revise o rascunho e confirme. O comando mostra o nome e o tipo com a evidência por trás de cada um, e as duas descrições lado a lado. Nada é escrito até você confirmar.

   • Uma descrição null quer dizer que as fontes não fundamentaram nada. Ela é desconhecida, não vazia. Acrescente uma frase sua quando puder — as suas palavras voltam ao trabalhador, que reescreve o rascunho, e o arquivo que você confirma é o arquivo que é escrito.
   • O tipo é permanente. Veja o aviso abaixo.

5. Leia o resultado que a escrita relata, descrito em O que a escrita relata.

6. Leia o relatório com que o comando termina. Ele nomeia a tecnologia e a linha principal como estão agora, quais descrições foram escritas e quais ficaram como estavam, o que as fontes deixaram sem fundamento — o que uma execução futura ainda pode acrescentar — e qualquer quase duplicata que a execução encontrou, com a forma como você a resolveu. Ele fecha com os comandos que a tecnologia agora desbloqueia.

O tipo nunca pode ser mudado

Depois de escrito, o tipo tool ou practice de uma tecnologia fica fixo: todo caminho de atualização revisa só as descrições. O tipo decide quais trabalhadores e templates todo componente seguinte usa, então uma escolha errada é carregada por tudo o que for escrito depois. O comando pergunta sobre ele, pelo nome, antes da escrita.

Confirme que deu certo: abra /knowledge/<slug> no aplicativo web. A tecnologia mostra o nome e o tipo, e a linha principal que você declarou tem um cartão na seção Versions.

Flags

Flag	Obrigatória	Padrão	O que faz
--technology <slug>@<version>	Sim	—	A tecnologia e a linha principal a provisionar
--source <path>	Não	—	Monta o bundle de uma árvore de código-fonte e redige a partir dele
--fetch	Não	—	Roda o /fito-fetch-urls-content antes
--urls <file>	Não	urls.txt	A lista de URLs do --fetch
--docs <path>	Não	./output/1-ingest/extracted_links_content/	Uma pasta já ingerida para ler
--output <path>	Não	./output/2-technology/technology.yaml	Onde o rascunho vai parar

O comando pega a primeira fonte que se aplica: --source, depois --fetch quando nenhum bundle foi montado, depois --docs. Ele divide a etapa ./output/1-ingest/ com os comandos de identificação: um bundle que um passo anterior já produziu é reaproveitado em vez de remontado, então uma ingestão serve aos dois.

O que a escrita relata

A escrita nomeia o caminho que o Fito tomou, o slug e a linha principal, o nome, o tipo e o arquivo do rascunho:

✓ <outcome> <slug>@<version> — "<name>" (<kind>) ← <payload-file>

Resultado	O que aconteceu	O que vem depois
created	A tecnologia era nova. As duas descrições foram guardadas	Nada — terminou
version-added	A tecnologia existia e a linha principal não. A linha é acrescentada com o texto dela, mas a visão geral que você confirmou não é guardada — uma visão geral só é guardada quando a própria tecnologia é criada	O comando escreve a visão geral como atualização, quando você confirmou uma que melhora a que já existia
reused	A tecnologia e a linha principal já existiam. A criação não mudou nada	O comando escreve como atualização as descrições que você confirmou

Uma atualização escreve só as descrições que você confirmou mudar, e não consegue apagar uma: uma descrição null ou vazia é recusada antes de qualquer envio. A sessão a roda para você, como o update.js da skill de escrita com --overview, --version-prose ou os dois — uma flag por descrição.

Quando o resultado contradiz o que o comando leu no passo 2 — reused depois de não encontrar a tecnologia, por exemplo —, o Fito mudou nesse intervalo. O comando para antes de qualquer atualização, lê o Fito de novo e mostra o que ele tem agora. Ele nunca escreve por cima de um texto que você não viu.

Quando uma quase duplicata para a execução

Antes de criar uma tecnologia, o Fito a compara com as que já tem, em duas camadas:

• dedup-key — o slug colide com um existente depois que os dois são normalizados. Uma correspondência exata.
• trigram — o slug ou o nome está próximo do slug ou do nome de uma tecnologia existente. Uma candidata aproximada.

Uma correspondência para a execução sem criar nada, e lista cada correspondência com a camada que a encontrou:

Near-duplicate technologies found (409): <message>

  <slug> — "<name>" (<layer>)

A escolha é sua, e o comando nunca a faz por você:

Escolha	Quando	O que acontece
Reutilizar (reuse)	A correspondência é a sua tecnologia	Rode o comando de novo declarando o slug encontrado. A execução vira uma atualização dessa tecnologia. A resposta preferida
Declarar de novo (re-declare)	A correspondência só se parece com a sua	Rode o comando de novo com outro slug
Forçar (override)	A correspondência é um alarme falso	Uma tecnologia nova e independente é criada ao lado de cada correspondência. Componentes publicados contra qualquer um dos slugs caem em tecnologias diferentes. O comando repete isso antes de rodar

Para forçar, a sessão roda a criação de novo com --override. Você escolhe; ela digita.

Quando o comando para

Mensagem	O que significa	O que fazer
Declare the technology and its major line: …	Falta o --technology, ou falta o @ nele	Passe --technology <slug>@<version>
No sources found at <docs-path>. A technology's descriptions are drafted from evidence, never from recall — …	Nada para ler	Passe --source ou --fetch
You are not logged in to Fito. Run /fito-login first, then re-run this flow.	Não há sessão na hora da escrita	Rode /fito-login e depois o comando de novo
Uma recusa do Fito	O servidor recusou a escrita	O comando a mostra palavra por palavra. Leia, corrija a causa e rode de novo

O que vem a seguir

• Ingerir uma árvore de código-fonte — dê código para o pipeline ler.
• Identificar componentes de conhecimento — o passo que este desbloqueia.
• Tecnologias, ferramentas e práticas — o que o registro que você acabou de escrever significa para quem lê.