Generate and push components

Generating writes each new candidate up as a full knowledge component, as a file on your disk. Pushing publishes those files to Fito, one at a time. The two share a page because a generated component is only a file until you push it — and once pushed, it is published and cannot be edited.

This page assumes identify has run and left a candidate list. If it has not, start at Identify knowledge components. It does not cover authoring a case — that starts at Author your first case, once the components the case needs are pushed.

Before you begin

• A pi session in a working directory of your own, with Fito installed there. See Set up a working directory.
• An LLM provider configured in pi, and the pi-subagents package installed. Generation runs on a worker persona, on your own model.
• A candidate list from identify, in the same working directory.
• For the push, a Fito login from the terminal — run /fito-login if you have not. Generating needs no login.

Generate the components

One command per component type. Each reads the list its identify command wrote, and writes one file per component:

Command	Reads by default	Writes by default
/fito-generate-domain-concepts	./output/2-identify/domain_concepts/domain_concepts.json	./output/3-generate/concept_content/
/fito-generate-execution-facts	./output/2-identify/execution_facts/execution_facts.json	./output/3-generate/execution_fact_content/
/fito-generate-usage-scenarios	./output/2-identify/usage_scenarios/usage_scenarios.json	./output/3-generate/usage_scenario_content/

1. Run the command with the same name, technology and major line you gave identify:

   /fito-generate-domain-concepts Javalin --technology javalin --technology-version 7

   By default it writes up every new candidate in the list. To write up only some, add --mode batch --select with the ones you want — see Generate flags.

2. Read the summary it relays. It names every component it wrote, and every candidate it skipped because that component already exists in Fito.

3. Repeat for the other two types, if you identified them.

Confirm it worked: the output folder holds one .json file per new candidate.

Generate flags

Flag	Required	Default	What it does
<tool-name>	Yes	—	The subject’s name, as the first argument
--technology <slug>	No	The name, lower-cased, spaces turned to dashes	The technology the components belong to
--technology-version <slug>[,<slug>...]	Yes	—	The major lines the components apply to. Comma-separate them — 6,7 — for components that hold on more than one
--version <ver>	No	None	The tool’s release to target, so examples, API names and terminology match it
--concepts, --facts or --scenarios <path>	No	The list in the table above	The candidate list to read — the flag’s name follows the command
--output <path>	No	The folder in the table above	Where the component files go
--mode one|batch|all	No	all	How many candidates to write up
--select <items>	With one or batch	—	Which candidates, comma-separated
--audience beginner|intermediate|advanced	No	intermediate	The reader the prose is pitched at
--language <lang>	No	English	The language of every generated sentence
--identify	No	—	Run the matching identify command first. The four flags below reach identify only through it
--source <path>	No	—	Bundle this source tree and read it. Wins over --fetch
--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

--version is neither a major line nor a revision

--technology-version names the major lines a component applies to, and it is what Fito records. --version only tells the writer which release to be accurate about — 7.1.4, say — and Fito never stores it. A component’s own revision is something else again, set at push time. When you leave --version off, the execution-fact and usage-scenario commands infer a release from the candidate list; the concept command writes without one.

--select takes candidate ids, ranges and names, mixed freely:

--select "1-3, 10, Bean"

A range is two integers, both ends included. The names differ by command: a concept’s name, a fragment of an execution fact’s statement, or a fragment of a usage scenario’s title. Execution facts carry ids such as EF-010.

Which generator runs

The technology’s kind picks the writer again, as it picked the identifier. It also picks the template the component is written against, which the command reads from Fito, so a concept about a tool and a concept about a practice ask for different fields. Usage scenarios are the exception: both kinds share one template.

Every field value is a markdown fragment. The component’s content is a set of fields, and each field holds its own small piece of markdown.

What a component file is

Each file is named <id>-<slug>.json — 1-dependency-injection.json, say — where the number is the candidate’s id in the list. That name is for your disk only. Fito mints the component’s reference id when you push, from the component’s name.

Using --identify

--identify runs the matching identify command before generating. Every ingestion flag you pass travels with it, so the input rules are identify’s own — see Where the input comes from.

/fito-generate-domain-concepts Javalin --technology javalin --technology-version 7 --identify --source ~/code/my-javalin-app

Pass no ingestion flag, and identify reads the fetched-documentation folder. Inside a case checkout that is yours to author, it offers to read the checkout itself instead.

--concepts and --identify write and read different folders

--identify always writes the candidate list to the folder in the table above. --concepts — and --facts, and --scenarios — sends generate somewhere else to read. Combine the two and generate ignores the list it just made: it either stops with No domain concepts found, or, if an older list sits at that path, writes components from the stale one and says nothing. Use one or the other.

When generation stops

Message	What it means	What to do
Please provide the Fito technology version(s) the components apply to with --technology-version <slug> …	No major line	Add --technology-version. The push refuses a component with no major line
The Fito vocabulary holds no <slug> technology, so there is nothing to attach these components to. …	The slug does not exist in Fito	Provision it, or correct a misspelt --technology
No domain concepts found at <concepts-path>. …	No candidate list at that path — the other two commands name their own type	Run identify first, or pass --identify
Please specify which concepts to process with --select. …	--mode one or batch without --select	Add --select
Content template not found. The Fito package installation may be incomplete.	The Fito package on your machine is missing a file	Reinstall the package

As with identify, a server failure other than not-found is reported as it came, and the command stops without telling you to provision anything.

Push the components

1. Run the push, with no argument to push everything generate wrote:

   /fito-push-knowledge

   Or name what to push — a component file, or a folder of them:

   /fito-push-knowledge ./output/3-generate/concept_content/

   With no argument, it collects every .json file directly inside ./output/3-generate/concept_content/, execution_fact_content/ and usage_scenario_content/. It does not look into subfolders.

2. Check the list it shows you. The push names every file and the count before it stores anything.

3. Answer each stop. The push handles one file at a time, and a file that resembles something already in Fito stops for your choice — see Settle a similar or duplicate component.

4. Read the report at the end. It has three lists, and each item names the component and its file: Stored, with each reference id and the total count; Skipped by you; and Not stored because of an error, each with its reason.

Each stored component prints one line, naming the component, its new reference id, its revision and the file it came from:

✓ Stored "<name>" as <reference-id> (revision <revision>), from <component-file>

Confirm it worked: open the component in the web app at /knowledge/<type>/<technology-slug>.<component-slug>. For concept:javalin.handler, that is /knowledge/concept/javalin.handler.

Settle a similar or duplicate component

Two checks run on every plain push, and either can stop a file before anything is stored. Both compare your component only with components of the same technology that share a major line with it.

Similar components come first. Fito looks for existing components close to the new one — including ones reworded enough to slip under the duplicate bar. The push names your component and its file, lists each match by how similar it is, its name and its reference id, and asks what to do:

"Observer Pattern" (./3-observer-pattern.json) was not stored.
Fito already has components that are similar to it:

   99% similar  "Observer"              concept:design-patterns.observer
   90% similar  "Observer Participant"  concept:design-patterns.observer-participant

What do you want to do?
  Link                  Store it as an alternative definition of "Observer".
  Supersede             Store it as the next revision of "Observer" (now revision 1.0.0).
  Skip                  Store nothing for this file.
  Create new component  Store it as a separate component, next to the similar ones.
                        If it is almost the same as one of them, Fito asks you again.

A duplicate comes second. A component almost the same as one already in Fito is refused, and the push names the duplicate and asks the same question.

Either way, the choice is yours, and the push never makes it for you:

Choice	What is stored
Link	A new component, with its own reference id, linked as an alternative definition of the closest match
Supersede	A new component that is the closest match’s next revision
Skip	Nothing. The file is recorded as skipped
Create new component	An independent component that coexists with the matches

Link and supersede are the preferred answers. Both target the closest match.

Create new component leaves two components describing nearly the same thing. Its description says so, so choosing it is your confirmation. After the similar-components stop, Fito can still refuse it as a duplicate, and the push then asks you again.

Three things about supersede are easy to miss:

• The revision needs a newer label. The push asks for one, shows the current revision and suggests the next one — 2.0.0 after 1.0.0. It refuses a label that is not in the X.Y.Z form, or that is not newer than the current revision. When the current revision is not in that form, any X.Y.Z label is accepted.
• The reference id can change. The new revision’s id is minted from its own name, so a renamed revision gets a new id. The version history links the two.
• The major lines are inherited. A new revision applies to exactly the lines its predecessor did, whatever the file says.

Supersede only works on the newest revision in a chain. Aim it at an older one and the push names the newest instead, and asks whether to supersede that one.

Pushing the same file twice

If a push was interrupted and you run it again, a file already pushed stops on the component it created, 100% similar. The session adds a line under the message that says so. Skip is the right answer: it is already in Fito.

For each choice, the session runs the push script again with one flag — --link '<reference-id>'; --supersede '<reference-id>', then --version <label> once you give the label; or, for Create new component, --proceed after the similar-components stop and --override '<reference-id>' after the duplicate one. You pick; it types.

When a push fails

A failed file is recorded and the push moves on to the next one. One bad file never stops the run.

Never edit a component file to make it pass. The files are read-only inputs to the push. When one is wrong, regenerate it with the generate command and push the new file.

Message	What it means	What to do
You are not logged in to Fito. Run /fito-login first, then re-run this flow.	No session	Run /fito-login, then push again
No generated component files found in <path>. …	Nothing to push	Generate first, or name the folder
No technology found for "<slug>".	The file names a technology Fito does not hold	Provision it, then push again
"<name>" (<file>) was not stored: technology "<slug>" has no version "<v>"	The file names a major line the technology does not have	Regenerate with the right --technology-version
"<name>" (<file>) was not stored: Invalid component content: …	The content breaks the template; each offending field is named	Regenerate the component
<file> is not valid JSON. or <file> is not a generated component file. Generate it again.	The file is damaged, or is not a component file	Regenerate it
No registered template for component type …	The Fito server has no templates loaded	A server problem — tell whoever runs your Fito server

What’s next

• Author your first case — put the components you pushed to work.
• Browse the knowledge area — read what you published, the way a learner will.
• Author a competence — group the components you pushed into a capability a technology demands.