new stand a corpus up in the folder you are in¶

kac new [--ci <SYSTEM>] [--from <URL|PATH>] [--name <NAME>] [--no-color] [--owner <OWNER>] [--path <PATH>] [--publishing <TARGET>] [--ref <REF>] [--types <TYPES>] [--yes]

What it does¶

new turns the folder you are standing in into a corpus (one repository of knowledge records kept in git). It fetches the framework from a template repository at a ref, and writes the files that template says a corpus receives. It also writes the files a template cannot supply:

• .corpus.yaml, which states your corpus's name.
• .config/dotnet-tools.json, which pins the version of kac running new.
• README.md, for you to rewrite, where the template sends none of its own.

It asks what the corpus is called, which types it adopts, where it publishes, what builds it and who owns the records it seeds. Each question has a default. Whichever types you adopt, the corpus it writes validates before the command finishes. Layers says which files it writes, and who owns each one afterwards.

If you adopt only some types, new removes the links to the types you skipped. A type page links the other type pages, and new drops each dead link and leaves the type's name standing in the sentence. The sentence may still send a reader to a type your corpus does not have, so new lists each line it left that way. A corpus adopting postmortems alone is told:

new: these lines name a type this corpus declined, and the link to it is gone. Read each one:
  frameworks.md:5  policies
  frameworks.md:25  standards
  postmortems.md:12  adrs
  postmortems.md:20  fixes, runbooks, nfrs
  postmortems.md:21  adrs
  postmortems.md:32  runbooks
  postmortems.md:34  fixes
  postmortems.md:86  nfrs

Rewrite each line it lists for your corpus.

A type's template links records of other types, one to a line, and new drops each line that links a type you skipped. A type's schema points ref: and versus: at the types beside it, and each of those points at a type, not at a folder, so a type you declined enforces nothing until update --add-type brings it in.

Use it once, on an empty or nearly empty folder. To take a newer framework into a corpus that already exists, run update.

Examples¶

A corpus, answering the questions¶

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

new asks five questions. Each has a default and each has a flag:

Name a publishing target and it asks a sixth: the URL the published corpus is browsed at. That one has no flag. A seeded record's owner says how the owner's default is worked out.

A corpus with no questions¶

kac new --yes --name my-corpus --ci github

--yes takes the default for every answer you did not give, which is what a pipeline runs. A run with no terminal and a missing answer exits rather than waiting, because a hung pipeline is worse than a failed one.

new prints each file as it writes it, then generates, validates and stages. The tail of a default run:

new: did not write azure-pipelines.yml: this corpus is built by github.
new: wrote 128 file(s) for my-corpus, taken from /path/to/template.
new: wrote human:alex.doe as the owner of adrs/0001-knowledge-as-code.md, policies/devi-deviations.md.
wrote README.md
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)
validate: skipped immutable-after-accepted, clause-id-kept, immutable-after-published, rule-id-kept and retire-not-delete, which compare each record with an earlier revision. Name one with `--since <ref>` to run them.
new: staged. `git status` shows everything this wrote, and the first commit is yours.
new: this corpus has no tracker to file on, so raise-finding and request-deviation will print each issue for you to file. Add a `tracker:` block to .corpus.yaml to set one.

The last line appears where the corpus has no tracker to file on. new writes no tracker block, so the tracker comes from publishing-target, and none gives none. The two skills that file an issue then print it for you to file.

Take the framework from a URL rather than a folder and the second line adds the commit it resolved, as …knowledge-as-code at c1c9621. The third line names the owner it wrote into the seeded records.

new stops short of committing. Read what is staged, then:

git commit -m "Start a corpus"

On a machine where git has never committed, this stops with Author identity unknown. Start a corpus gives the two git config lines that set your name and email.

A corpus with no network¶

kac new --from ../knowledge-as-code

--from takes a local path as well as a URL. This is the offline route, and it is what the tool's own tests use.

Known limits¶

It needs a network and a git client, unless you pass a local --from. new fetches the template at run time.

It is not idempotent and does not try to be. Run it twice in the same folder and it stops on the first check. A .corpus.yaml at or above the working directory means the corpus is already there.

It refuses a repository with uncommitted changes, and exits 1. Commit or stash them first, so that what new writes reads as a diff of its own. A folder that is not yet a repository gets git init, once you agree or pass --yes. A file the folder already holds stays where it is.

It refuses a publishing target it cannot build links for, and exits 1. --publishing takes the values the table above lists. mkdocs is not one, because export cannot address a page on an MkDocs site:

new: --publishing 'mkdocs' is not a target. It is one of azure-devops, azure-devops-wiki, github, none.

It does not decide what your repository looks like. Branch protection, reviewers and issue templates are questions about your repository, and new asks none of them.

It does not install the tool. A kac already on the machine runs new, and new fetches only the rest of the framework. It pins that kac in .config/dotnet-tools.json, which the CI starter restores with dotnet tool restore. The two halves are versioned apart from the moment a corpus is created.

update is what takes a newer framework into the corpus this created.