Skip to content

Getting started

Before you start

kac is a dotnet tool, so it needs the .NET 10 SDK. Check what you have:

dotnet --list-sdks

You want a line opening 10.:

10.0.300 [/usr/local/share/dotnet/sdk]

If there is none, install it from dotnet.microsoft.com/download/dotnet/10.0. An older SDK beside it is fine, and nothing here removes one.

You also need git. kac lists a corpus with git ls-files, so a corpus outside version control is read a narrower way. Discovery says what changes.

Install the tool

kac is published as the dotnet tool KnowledgeAsCode.Tool. Installing it globally puts kac on your PATH:

dotnet tool install --global KnowledgeAsCode.Tool
kac --version

--version prints the release and the commit it was built from:

0.25.0+037426e8e60b7756f6883f307334a3368b80779d

If the shell cannot find kac after a global install, add ~/.dotnet/tools to your PATH and open a new shell. Troubleshooting covers that and the other first-run faults.

Start a corpus

kac new turns the folder you are standing in into a corpus: one repository of knowledge records kept in git. It takes the framework from the knowledge-as-code repository, writes the files that framework says a corpus receives, and writes the two no template can supply: .corpus.yaml, which names your corpus, and a README.md to rewrite.

mkdir my-corpus && cd my-corpus
kac new

It asks what the corpus is called, which types it adopts, where it publishes and what builds it, with a default for each. Name a publishing target and it asks one more: the URL a person opens to browse the corpus. Answer nothing at all and you still end with a corpus that validates, holding every type the framework declares. --yes takes every default and asks nothing, which is what a pipeline runs.

The folder does not have to be a repository yet. new offers to run git init where there is none. It finishes by running generate, then validate, then git add -A:

new: wrote 115 file(s) for my-corpus, taken from https://github.com/paul80nd/knowledge-as-code at 3b812bb.
updated 1 of 40 generated file(s).
validated 3 document(s) and 18 template(s), skipped 0 without frontmatter. 0 error(s), 0 warning(s)
new: staged. `git status` shows everything this wrote, and the first commit is yours.

The first commit is yours to make, once you have read what is staged.

git commit -m "Start a corpus"

Look at .corpus.yaml before you commit

new writes it from your answers. The corpus descriptor says what every key in it means, and which ones you move by hand afterwards.

You arrive with ignore rules, editor conventions and a wiki ordering. Name a CI system and its starter pipeline comes too. new writes that one system's and no other, so a corpus is never handed a workflow for a host it does not build on. new covers every flag, the order it asks in, and what stops it.

If you declined some types, the run ends by naming links the type pages make to types you did not take. Those pages are yours from here, so edit the links out.

Run the tool against your corpus

kac finds a corpus by walking up from the working directory looking for .corpus.yaml. Run it from inside your corpus.

cd path/to/your/corpus

kac validate            # frontmatter, links, structure, clauses and the graph
kac generate            # rewrite the indexes and the tables inside the markers

A clean validate prints the counts and exits 0:

validated 13 document(s) and 8 template(s), skipped 0 without frontmatter. 0 error(s), 0 warning(s)

A generate with nothing to do says so:

generated files already up to date; nothing written.

Anything else is a finding naming the file, the check and the line. Troubleshooting covers the ones you meet first.

Two more commands write your corpus out for an agent to read: kac export and kac bundle. Building the plugin is where those belong once a record of yours passes.

Every command takes the same few options, and each answers with one of three exit codes. The CLI reference covers both, and gives a page to every command.

Add your first record

Your corpus arrives with a few records in it. The ADR under adrs/ and the policy under policies/ are there to show the shape, and yours go beside them. The glossary under glossary/ is the framework's own vocabulary, inherited word for word. Write your own glossaries beside it and leave that one as it is.

  1. Pick the type. knowledge-as-code/taxonomy.md in your own corpus has a decision table saying where a record goes, covering the types that corpus adopted. The default types introduces every one of them.
  2. Copy that type's _template.md to a new file in the same folder. It marks what you supply as {{placeholder}} and fences its own guidance between DELETE FROM HERE and DELETE TO HERE comments. A finished record has neither left in it.
  3. Run kac validate, then kac generate. The first names what is still missing. The second writes your record into the folder's index.

Metadata says how an id is formed and how a citation reaches a part of a record. Running it in CI is what to read once a record of your own passes locally.