Provision a technology

Provisioning admits a technology and one of its major lines into Fito. Every knowledge component about that technology, and every case scoped on it, hangs off the record this step writes.

This page is for a case creator whose technology is not in Fito yet, or whose major line is not. It covers setting up a place to author from, declaring the technology, and confirming the record the command drafts. It does not cover the components themselves — those come after, starting at Ingest a source tree.

Where this step sits

Authoring knowledge is a chain, and it runs before you author a case:

1. Provision the technology and its major line — this page.
2. Ingest something to read: a source tree or fetched documentation.
3. Identify candidate components.
4. Generate and push them.
5. Then author a case that references them.

Why nothing downstream works without it

Every later step looks the technology up first, and stops when it is not there:

• The identify and generate commands refuse with “The Fito vocabulary holds no <slug> technology”, because there is nothing to check candidates against or to attach components to.
• The push stops with No technology found for "<slug>"., and refuses a component naming a major line the technology lacks.
• /fito-case-design refuses to scope a case on the technology, naming it as absent. It also refuses a case whose components have not been pushed yet, and sends you back to this chain.

So until someone provisions a technology, nobody can write a component about it or scope a case on it. Each major line counts on its own: a technology provisioned at 6 does not let you author for 7 until 7 is provisioned too.

Set up a working directory

Author from a directory of your own. The pipeline writes every stage under ./output/ in the directory your pi session runs in, so a directory set aside for authoring keeps those stages in one place. Fito loads in every pi session, so that directory needs no install of its own.

1. Install the Fito package first, as in Install and prerequisites.

2. Make a working directory, and change to it:

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

3. Start your authoring pi sessions in that directory.

Once you start authoring, the chain fills ./output/ in that directory, one folder per stage, each written by the command beside it:

output/
├── 1-ingest/
│   ├── source_bundle/            --source, on identify or provision
│   │   ├── files/
│   │   └── bundle.json
│   └── extracted_links_content/  /fito-fetch-urls-content, or --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

Each command’s defaults read and write these folders, so a later step finds an earlier one’s output without being told where it is. /fito-push-knowledge reads the three 3-generate/ folders. The one exception is source_bundle/: nothing reads it by default — see Bundle again for the next command.

A case checkout you are authoring works as a working directory too — see Ingest a case you are authoring.

Before you begin

• A pi session in your working directory.
• A Fito login from the terminal. The writes are authenticated — run /fito-login if you have not.
• An LLM provider configured in pi, and the pi-subagents package installed. The draft is written by a worker persona, on your own model.
• Something about the technology to read: a source tree, a list of documentation URLs, or a folder an earlier step already ingested. The draft is written from that evidence, never from the model’s memory.

Choose the slug and the major line

You declare both, as <slug>@<version>. Neither the command nor its worker ever guesses them from the sources.

• For a tool, the version is the upstream major line: javalin@7 says that Javalin published a 7 release line.
• For a practice, there is no release line, so the version is Fito’s own numbering, and the convention is to start at 1: hexagonal@1. Nothing checks the label. An author who calls the first line cockburn-2005 breaks nothing, and gives up only the uniformity.
• A later, distinct formulation of a practice — a restatement, a rival school — is a new major line of the same technology, not a new slug. The subject has not changed.

For what the two kinds mean, see Technologies, tools and practices. For how major lines work, see Versions and alternative definitions.

Check the spelling of an existing slug

Before provisioning, open /knowledge in the web app and look for the technology. A misspelt slug is not caught: it admits a second, independent technology beside the real one, and components pushed against the two land on different records.

Provision the technology

1. Run the command with your declaration and a source to read:

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

   Replace javalin@7 with your <slug>@<version>, and the path with your project. For documentation instead of code, pass --fetch --urls urls.txt.

2. Read what the command reports about Fito’s current state. It looks the slug up and tells you which of three runs this is, showing any descriptions already there:

   Fito holds	The run
   No such technology	A create of the technology and its major line
   The technology, but not this major line	A create of the major line; the technology’s overview already exists and is enriched
   The technology and this major line	An update of the existing descriptions

3. Wait for the draft. A worker drafts the technology’s name, its kind, its overview — what it is across every major line — and the prose for the major line you declared. On an existing technology it enriches the descriptions already there instead of replacing them. The draft lands at ./output/2-technology/technology.yaml.

4. Review the draft and confirm it. The command shows the name and the kind with the evidence behind each, and the two descriptions side by side. Nothing is written until you confirm.

   • A null description means the sources grounded nothing. It is unknown, not empty. Add a sentence of your own when you can — your words go back to the worker, which rewrites the draft, and the file you confirm is the file that gets written.
   • The kind is permanent. See the caution below.

5. Read the outcome the write reports, described in What the write reports.

6. Read the report the command ends on. It names the technology and major line as they now stand, which descriptions were written and which were left as they were, anything the sources left ungrounded — what a later run could still add — and any near-duplicate the run hit, with how you resolved it. It closes on the commands the technology now unblocks.

The kind can never be changed

Once written, a technology’s tool or practice kind is fixed: every update path revises descriptions only. The kind decides which workers and templates every later component uses, so a wrong call is carried by everything written after it. The command asks you about it by name before the write.

Confirm it worked: open /knowledge/<slug> in the web app. The technology shows its name and kind, and the major line you declared has a card in its Versions section.

Flags

Flag	Required	Default	What it does
--technology <slug>@<version>	Yes	—	The technology and the major line to provision
--source <path>	No	—	Bundle a source tree and draft from it
--fetch	No	—	Run /fito-fetch-urls-content first
--urls <file>	No	urls.txt	The URL list for --fetch
--docs <path>	No	./output/1-ingest/extracted_links_content/	An already-ingested folder to read
--output <path>	No	./output/2-technology/technology.yaml	Where the draft goes

The command takes the first source that applies: --source, then --fetch when no bundle was built, then --docs. It shares the ./output/1-ingest/ stage with the identify commands: a bundle an earlier step already produced is reused rather than rebuilt, so one ingestion can serve both.

What the write reports

The write names the branch Fito took, the slug and major line, the name, the kind and the draft file:

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

Outcome	What happened	What follows
created	The technology was new. Both descriptions are stored	Nothing — you are done
version-added	The technology existed and the major line did not. The line is added with its prose, but the overview you confirmed is not stored — an overview is stored only when the technology itself is created	The command writes the overview as an update, when you confirmed one that improves on what was there
reused	The technology and the major line both existed. The create changed nothing	The command writes the descriptions you confirmed as an update

An update writes only the descriptions you confirmed changing, and it cannot blank one out: a null or empty description is refused before anything is sent. The session runs it for you, as the write skill’s update.js with --overview, --version-prose or both — one flag per description.

When the outcome contradicts what the command read at step 2 — reused after it found no technology, say — Fito changed in between. The command stops before any update, reads Fito again, and shows you what it now holds. It never writes over prose you have not seen.

When a near-duplicate stops the run

Before creating a technology, Fito compares it with the ones it holds, in two layers:

• dedup-key — the slug collides with an existing one once both are normalized. A deterministic match.
• trigram — the slug or the name is close to an existing technology’s slug or name. A fuzzy candidate.

A match stops the run with nothing created, and lists every match with the layer that found it:

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

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

The choice is yours, and the command never makes it for you:

Choice	When	What happens
Reuse	The match is your technology	Run the command again declaring the matched slug. The run becomes an update of that technology. The preferred answer
Re-declare	The match only resembles yours	Run the command again with a different slug
Override	The match is a false alarm	A new, independent technology is created beside every match. Components pushed against either slug land on different technologies. The command restates this before it runs

For an override, the session runs the create again with --override. You pick; it types.

When the command stops

Message	What it means	What to do
Declare the technology and its major line: …	No --technology, or no @ in it	Pass --technology <slug>@<version>
No sources found at <docs-path>. A technology's descriptions are drafted from evidence, never from recall — …	Nothing to read	Pass --source or --fetch
You are not logged in to Fito. Run /fito-login first, then re-run this flow.	No session at write time	Run /fito-login, then run the command again
A rejection from Fito	The server refused the write	The command shows it word for word. Read it, correct the cause, and run again

What’s next

• Ingest a source tree — give the pipeline code to read.
• Identify knowledge components — the step this one unblocks.
• Technologies, tools and practices — what the record you just wrote means to a reader.