Naming, locations and refusals

ki is not where the work happens. Most of a Knowledge Islands day is spent talking to an agent, and ki is what made the agent capable of the conversation — it installed the harness, it activated the skills, and it runs the checks when the work is done.

So the command line shows up at three moments, and almost nowhere else:

Setting up — once per machine, and once per repository. ki bootstrap, then ki repo skill add.
Checking — ki repo audit before you commit, ki repo conform to fix what it found.
When something is wrong — ki manage doctor, ki repo diag, ki manage outdated.

How the command groups divide covers the command surface itself, and every command there is is the inventory. This page covers the parts that are about living with the tool rather than about its grammar: what a capability is called, where your files end up, and what a refusal means.

How capabilities are named

A skill is named by its bare name — ki-work-roadmap, ki-authoring, ki-mcp:

ki skill add ki-recap
ki repo skill add ki-work-roadmap

Harness-qualified keys are invalid. Writing knowledgeislands/ki-agentic-harness:ki-work-roadmap will be rejected, and a declaration in .ki.toml written that way is not a valid declaration. The reason is that a repository declares what governs it, not where that came from: the provider is declared separately, under [repo], and is a property of the installation rather than of the governance.

[repo]
harnesses = ["knowledgeislands/ki-agentic-harness"]

[skills.ki-work-roadmap]
# this skill's own configuration goes here

A provider must appear in that harness list before any of its skills can be added. Each installed harness declares which capability prefixes it owns, through [skills.ki-repo-harness] in its own root configuration, so two harnesses cannot both claim to supply the same skill name.

If exactly one installed harness provides the name you ask for, the bare name resolves. If two do, the command stops rather than choosing — which is the same refusal ki repo upgrade makes, for the same reason.

Where `ki` keeps things

Four locations, each resolved from the first non-empty value in its row:

Contents	Resolution order
Data — installed harness payloads	`$KI_DATA_HOME`, then `$XDG_DATA_HOME/ki`, then `~/.local/share/ki`
Configuration — your user-scope declarations	`$KI_CONFIG_HOME`, then `$XDG_CONFIG_HOME/ki`, then `~/.config/ki`
Cache — recoverable working material	`$KI_CACHE_HOME`, then `$XDG_CACHE_HOME/ki`, then `~/.cache/ki`
State — the repository registry, among other things	`$KI_STATE_HOME`, then `$XDG_STATE_HOME/ki`, then `~/.local/state/ki`

ki manage diag prints the values actually in force, which is faster than reasoning about the table.

The one file that does not live in any of them is .ki.toml, at each KI repository's root. That is deliberate: it travels with the repository, so a colleague who clones it inherits the same governance without configuring anything on their own machine.

What the host will and will not run

ki repo audit and ki repo conform do not implement any checks. They resolve the operations a repository's declared skills register, verify them against the installed harness's integrity evidence, and run those.

It will not run anything else. Not a repository-local wrapper script, not a copied rubric runner sitting in the tree, not a package alias, not a checkout that happens to be nearby. If you want a repository to have rules of its own, the supported route is a declared ki-self provider — see operator guides — and it is still resolved rather than discovered.

This is why "the audit passed" is a precise claim: it means the operations registered by the skills this repository declared, from harnesses whose payloads verified, all succeeded. It does not mean the code is good, and it does not mean anything about rules nobody declared.

When a command refuses

ki refuses unknown options, ambiguous capabilities, unsafe paths, and managed state it does not recognise. Each refusal names a recovery route, and following it is meaningfully safer than fixing the symptom by hand.

The reason is that most of what ki manages is a link between two records — a declaration and a payload, a registry entry and a checkout. Deleting a file that looks stale usually breaks the other half of a pair, and the tool then cannot tell a deliberate removal from damage. ki repo repair and ki manage repair exist to reconcile exactly those projections; ki manage doctor tells you which are broken.

Legacy repository-vendored .ki/ directories are the case worth stating explicitly. They are migration evidence, not an execution fallback — the host never runs anything from them. Leave unfamiliar legacy state in place until its native replacement is proven, rather than recreating it or removing it piecemeal.

Getting the exact grammar

ki --help
ki <command> --help

Your installed binary is the authority for your version. Every ki command is the same inventory taken from the manual at the release this site advertises, which is the right reference when you are reading rather than typing.

Install and get started is the end-to-end setup path if you have not run any of this yet.

Written from