Author a competence

A competence names a standing capability a technology demands, and each of its elements is a knowledge component Fito already holds. This page shows how to record one from the terminal, how to edit its name and description, and how to delete it.

This page is for a case creator who has pushed knowledge components and wants to group them into the capabilities a learner builds. It does not explain what a competence is, or how a learner’s proficiency under one is computed — for that, see Competences and learning objectives.

Where this step sits

A competence comes after the knowledge chain, because every element must point at a component that is already live:

1. Provision the technology and its major line.
2. Identify, generate and push the components.
3. Author the competences those components form — this page.

A case does not need a competence. A case points at knowledge components, as its learning objectives and prerequisites, so you can author a case without this step.

Before you begin

• A pi session in your authoring directory — see Set up a working directory.
• A Fito login from the terminal. Every write is authenticated — run /fito-login if you have not.
• To create a competence, you are a curator or an admin. There is no curator role to request: once you own a case, in any status, you are a curator. See Work the curation catalogue.
• The technology, provisioned at the major line you author for, and every component the competence needs, already pushed.

Create a competence

1. Run the command with the technology and its major line:

   /fito-create-or-update-competence --technology javalin@7

   Replace javalin@7 with your <slug>@<version>. The command checks that Fito holds both the technology and that major line, and stops when either is missing.

2. Read what the technology already demands. The command lists each competence by name, id, description and elements, with its sub-competences nested under it. When none of them is the competence you have in mind, tell the command: this run is a create. When one of them is, pick it and follow Edit the name or the description instead.

3. Choose the elements. The command lists the components live on the declared major line, each by name and summary, and reads back every component you pick before it becomes an element. The elements keep the order you set, and a component appears once.

4. Review the record and confirm it. The command shows the name, the description and the elements in order, each by its component’s name. Nothing is written until you confirm.

   • A null description is unknown, not empty. Add one when you can: another author reads it to decide whether this competence is the one they meant.
   • Read Three rules a create never warns you about first. None of them can be undone after the write.

   The confirmed record lands at ./output/4-competence/competence.yaml.

5. Read the id the write prints:

   ✓ Created competence "<name>" (<id>) ← <payload-file>

   Keep the id. An edit and a delete both address the competence by it.

The technology’s competence listing now carries the competence, for every author drafting against the same technology and every learner browsing it.

Three rules a create never warns you about

Fito accepts each of these without a word, so they are easy to discover only after they have cost you:

• The elements are frozen. After a create, no command adds an element, removes one or reorders them. When the element list is wrong, create a new competence with the right elements, then delete the wrong one.
• A create is always top-level. Nothing here nests one competence under another. A competence you meant as a sub-competence is stored at the top level instead, as a peer of its intended parent.
• A create is not idempotent. Nothing makes a competence name unique, so a second run under the same name stores a second competence. After a lost connection, a timeout or a server error, read the technology’s listing first, and create again only when your competence is absent from it.

When a component is missing

When a component the competence needs is not in Fito, the command refuses to draft the competence. It writes no record, and it never drops the element to make the record fit: a competence without a component it needs is a weaker competence, and it is the vocabulary that must grow. A component that is live only on a different major line counts as missing.

The command names the missing references and sends you to the knowledge pipeline. To continue:

1. Push the missing components — see Identify knowledge components and Generate and push components.
2. Run /fito-create-or-update-competence again, with the same elements.

When every component comes back missing, suspect the major line before the vocabulary. The components may be live on another line, and the command asks you before it lists them without the version.

Fito applies the same rule at the write. When a component goes missing between your confirmation and the create, or a reference was mistyped, the write is refused, and the refusal lists every reference that names nothing:

✗ Create failed (422): competence element references resolve to no knowledge component: <references>

Keep every element you confirmed, push the missing components, and create again.

Edit the name or the description

An edit changes the name, the description or both, in place. The competence keeps its id, its elements and every learner’s recorded proficiency under it.

1. Run the command with the technology, and the competence’s id when you hold it:

   /fito-create-or-update-competence --technology javalin@7 --competence COMPETENCE_ID

   Replace COMPETENCE_ID with the id the create printed, or leave out --competence and pick from the listing.

2. Pick the competence from the listing. An id the listing does not report is refused, and the command asks you to pick one it does. A sub-competence is a target like any other, by the id nested under its parent.

3. Confirm the new name, the new description, or both. The command skips the element steps, because an edit writes no elements. The record lands at ./output/4-competence/edit.yaml.

4. Read the result the write prints. It names only what you confirmed changing:

   ✓ Updated the name and the description of competence "<name>" (<id>) ← <payload-file>

An edit can set a description or replace one, but never clear one. A null or blank description is refused before anything is sent.

Who may edit or delete a competence

The author who creates a competence owns it. Its owner and any admin may edit or delete it, and nobody else may, curator or not. The refusal names both ways in, so you can tell which one you lack:

✗ Update failed (403): user <user-id> is neither the owner nor an admin, so may not edit competence <competence-id>

A refused delete reads the same, with Delete failed and delete.

A competence that came from seeding has no owner, so only an admin can edit or delete it. When you cannot edit Request handling fundamentals on javalin, that is why: ask an admin.

Delete a competence

A delete removes the competence and every sub-competence beneath it, in one write. Fito has no in-use check and no undo, so the preview and your yes are the only safeguard.

A delete cannot be undone

Re-creating a deleted competence mints a new id, and every sub-competence under it has to be created again, under new ids of its own. Anything that held the old id holds nothing.

1. Run the command with the competence’s id:

   /fito-delete-competence COMPETENCE_ID

   Replace COMPETENCE_ID with the id. When you no longer hold it, pass --technology javalin instead and pick from the listing. That slug is bare, with no @<version>. When you pass both, the id wins, and the listing only confirms it.

2. Read the preview. The command first runs the delete without confirming it, which deletes nothing and shows what would go:

   This will delete competence "<name>" (<id>) and everything beneath it:
     - "<sub-competence-name>" (<sub-competence-id>)
   1 sub-competence goes with it. No learner's recorded proficiency is touched.
   
   Nothing has been deleted. A delete needs the author's explicit confirmation:
     node delete.js <id> --confirm

   This run exits non-zero and prints to standard error, by design. It is not a crash.

3. Say yes, naming the competence. The command never takes silence, or your having run it, as a yes. When the review took a while, or someone else may be writing, ask for a fresh preview first: a sub-competence added after the preview goes with the rest.

4. Read the result:

   ✓ Deleted competence "<name>" (<id>) and its 1 sub-competence

No learner’s recorded proficiency changes. Fito records proficiency per knowledge component, so a delete removes a competence from the learner’s view and destroys no score.

Arguments and flags

The two commands take the following arguments and flags:

Command	Argument or flag	Required	What it does
/fito-create-or-update-competence	--technology <slug>@<version>	Yes	The technology, and the major line the elements are chosen on
/fito-create-or-update-competence	--competence <id>	No	The competence to edit, when you hold its id
/fito-create-or-update-competence	--output <path>	No	Where the confirmed record goes. Defaults to ./output/4-competence/competence.yaml on a create and ./output/4-competence/edit.yaml on an edit
/fito-delete-competence	<competence-id>	One of the two	The competence to delete
/fito-delete-competence	--technology <slug>	One of the two	A bare slug, to pick the competence from a listing

When the command stops

Each refusal writes nothing. The command shows Fito’s message word for word:

Message	What it means	What to do
Declare the technology and its major line: …	No --technology, or no @ in it	Pass --technology <slug>@<version>
Name the competence to delete — …	Neither an id nor --technology	Pass the id, or --technology <slug>
You are not logged in to Fito. Run /fito-login first, then re-run this flow.	No session	Run /fito-login, then run the command again
✗ Create failed (403): user <user-id> is neither a curator nor an admin, so may not create a competence	You own no case and are not an admin	Author a case first, or ask an admin
✗ Create failed (404): technology "<slug>" does not exist	No technology has that slug	Check the slug, or provision the technology
✗ Update failed (404): competence "<id>" does not exist	No competence has that id. A delete reads Delete failed	Pick the competence from the technology’s listing
✗ Create failed (400): <message>	A record breaking a rule: no elements, a duplicate element, a blank name, a name over 255 characters or a description over 4,000. An edit or a delete reads Update failed or Delete failed, and also refuses an id that is not a UUID	Fix the record, confirm it again, and run the command again

What’s next

• Competences and learning objectives — how a learner’s proficiency under a competence is computed from its elements.
• Author your first case — put the components you pushed to work.
• Generate and push components — grow the vocabulary when a competence needs a component Fito lacks.