Inkan: decisions

Context#

Most static site generators expect you to own the site: a src/ folder, layouts, a framework config and a dependency list that you keep up to date. A decision log is maintained by many people who are not front-end developers. They should only touch Markdown and one config file, and an upgrade should be npm update. Zudoku solved this for API docs by shipping the whole app inside the package and running it from a CLI; Inkan needed the same shape for decisions.

Decision#

Inkan is one npm package, @tilaven/inkan, with an inkan binary. The package contains the complete site (an Astro application in app/), the built-in templates and the starter files. Your repository holds content and inkan.config.* and nothing else. The CLI runs Astro programmatically with the app folder inside the package as the Astro root and your folder as the source of content and config.

Your config reaches the app through virtual modules, the same model Zudoku uses with Vite. There is no generated code in your repository, no src/ and no framework config to maintain.

How to use it#

Install#

1
npm install -D @tilaven/inkan

The package requires Node.js 22.22 or newer. Astro, Pagefind, Mermaid, KaTeX and Expressive Code are dependencies of the package; you do not install them yourself.

Commands#

init adds dev, build, preview, new, status, supersede and check as npm scripts, so npm run dev, npm run check and npm run new -- adr sre "Title" do the same thing.

dev, build, preview and init live in bin/cli.mjs; every other command is a module in lib/commands/<name>.mjs that exports run({ args, flags, root }) and returns the exit code. An error thrown by a command is printed on stderr and exits with code 1.

Options#

Flags take their value from --port 3000 or --port=3000; --root, --out, --project, --url and --author must have one. --date takes the next argument as its value when there is one, so write it after the positionals (inkan status sre/adr/1 accepted --date), and an argument the command does not expect is refused. Example:

1
npx inkan dev --root docs --port 3000 --host

This is how the Inkan repository builds this site: the config is docs/inkan.config.ts, so the root is docs.

What happens on dev and build#

flowchart LR
  cfg["inkan.config.ts<br/>decisions/"] --> load["loadConfig()<br/>validate, resolve paths,<br/>run plugin hooks"]
  load --> vm["virtual modules<br/>config, assets, user-css,<br/>mdx-components, components/*"]
  vm --> astro["Astro app in<br/>node_modules/@tilaven/inkan/app"]
  astro --> dist["dist/<br/>HTML, CSS, pagefind/, feeds"]

1. The CLI sets INKAN_ROOT to the resolved root. When sources lists repo entries, build fetches every one of them first (unless --offline) and dev fetches the missing ones. Then it calls Astro’s dev, build or preview with root pointing at the app inside the package.
2. app/astro.config.mjs loads and validates your config, then registers a Vite plugin that serves it as virtual modules:
   • virtual:inkan/config: the resolved config as JSON (plugins stripped).
   • virtual:inkan/assets: your logo and favicon as asset URLs.
   • virtual:inkan/user-css: imports of every file in customCss.
   • virtual:inkan/mdx-components: your mdxComponents module, or an empty map.
   • virtual:inkan/components/<Name>: your override of a component, the built-in one, or an empty slot.
3. Content collections read from your contentDir and pagesDir. Vite is allowed to read files from your repository root, so images and CSS next to your records work.
4. Output goes to <root>/dist; caches go to <root>/node_modules/.inkan (including sources/<project> clones) and .vite-inkan. Astro’s telemetry and dev toolbar are off.

The dev server watches the config file and restarts when it changes. Files the config points at (components, CSS, the MDX components module) hot-reload on their own.

Upgrading#

1
npm update inkan

Because the site is inside the package, a new version brings new pages, styles and fixes without any change to your repository. Options that were removed or renamed are reported by the config validation, with a hint, the next time you run dev or build.

Consequences#

• Zero site code in your repository. Content authors see only Markdown and one config file.
• Upgrades are a version bump. Breaking config changes surface as validation errors, not silent misbehaviour.
• Customisation goes through defined seams: config, customCss, component overrides, MDX components and plugins. You cannot edit the app’s own files; if a seam is missing, that is a feature request.
• The CLI wraps Astro’s programmatic API, so Astro’s own CLI flags beyond --port and --host are not exposed.
• --root must point at the folder with the config. Running inkan dev from a different folder without it finds no config and builds a site with the defaults and an empty decisions/ folder.
• The install is heavier than a Markdown linter because the full toolchain (Astro, Mermaid, KaTeX, Pagefind) is a dependency, even if you never use diagrams or math.

Context#

A tool that needs “only Markdown and one config file” still has a first five minutes: a config with the right import, a project folder with a _project.yml, one record that shows the format, npm scripts, a .gitignore, and a CI workflow so the site is published from day one. Writing these by hand from the README is slow and error-prone, and a decision log often starts inside an existing repository that already has a package.json.

Decision#

inkan init [dir] copies a starter repository from the package and wires up package.json. It never overwrites a file that already exists, so it is safe to run inside an existing repository. npm create @tilaven/inkan is a thin wrapper, published as create-inkan, that runs the same init in a new folder.

The starter is complete: it builds and deploys without edits. Everything in it is a plain file you can change or delete afterwards.

How to use it#

A new repository#

1
npm create @tilaven/inkan@latest my-decisions
2
cd my-decisions
3
npm install
4
npm run dev

npm create @tilaven/inkan [dir] resolves the @tilaven/inkan package it depends on and runs inkan init <dir>. When you give no folder name it uses decisions-site. After init you still run npm install yourself; the output ends with the exact next commands.

An existing repository#

1
npm install -D @tilaven/inkan
2
npx inkan init

Without an argument init targets the current folder (or --root). With npx inkan init docs the files land in docs/, which is how this site is laid out. Run the CLI from that folder afterwards, or pass --root docs.

What init creates#

The dotfiles are stored in the package as _gitignore and _dockerignore and renamed on copy, because npm drops .gitignore from published packages. init prints every file it added with a + and marks package.json with ~.

How package.json is handled#

If there is no package.json, init creates one:

1
{
2
  "name": "my-decisions",
3
  "private": true,
4
  "type": "module",
5
  "scripts": {
6
    "dev": "inkan dev",
7
    "build": "inkan build",
8
    "preview": "inkan preview",
9
    "new": "inkan new"
10
  },
11
  "devDependencies": {
12
    "@tilaven/inkan": "^0.1.0"
13
  }
14
}

If one exists, init only adds to it:

• The four scripts are added. Scripts you already have, including ones with the same names, are kept as they are.
• "type": "module" is set only when type is missing. The config file is an ES module, so a repository that uses CommonJS keeps .ts for the config and is otherwise unaffected.
• @tilaven/inkan is added to devDependencies at the installed version, unless it is already in dependencies.

Nothing else in the file is touched, and key order of your existing fields is preserved.

Existing files are never replaced#

init skips any file that already exists at the destination and keeps going. Running it twice is harmless. This also means a second init does not refresh an old workflow file: delete it first if you want the current one.

After init#

1. Set title, url and repo in inkan.config.ts. repo enables the edit and “New ADR” buttons; url is used in feeds and llms.txt.
2. Rename the platform folder or add your own projects. A folder with records is enough; _project.yml adds the display name.
3. Push. The GitHub workflow needs Pages set to “GitHub Actions” as the source; the GitLab pipeline publishes to Pages on the default branch. Both set BASE_PATH=/<repository name> for project pages; remove that line for a custom domain. See GitHub and GitLab Pages.
4. Optional: docker build -t decisions . for a self-hosted image. See Docker and nginx.

Consequences#

• One command gives a repository that builds and deploys. New users see a working site before reading any documentation.
• Safe in existing repositories: nothing is overwritten and package.json is extended, not replaced.
• The starter is a snapshot. Files it created are yours from then on; updates to the package’s starter do not propagate to them, which is intended for CI files you will edit anyway.
• npm create @tilaven/inkan pins the @tilaven/inkan version it was published with. Use @latest to get the current one.
• The starter ships files for every target (GitHub, GitLab, Docker). Delete the ones you do not use.

Context#

Records are numbered files, 0007-use-kafka.md, and the number is part of how people refer to them (PLATFORM-ADR-0007). Finding the next free number by hand means listing a folder and counting; two people doing that on the same day get a conflict. Each record also starts from the same skeleton, with today’s date and the author’s handle, which nobody wants to type again. log4brains and adr-tools both solved this with a new command, and users expect one.

Decision#

inkan new <type> <project> "<title>" creates the next numbered record of a type inside a project from a template. The number is one more than the highest number already in that folder. The file name is the number padded to four digits plus a slug of the title. The template comes from your templatesDir when it has a file for that type, otherwise from the package. If the project folder has no _project.yml yet, the command creates a minimal one so the project appears on the site with a name. An existing folder can be named by its slug: inkan new adr ops-plans "…" writes into Ops Plans/.

How to use it#

The command#

1
npx inkan new adr platform "Move the event bus to Kafka"
2
# Created decisions/platform/adr/0010-move-the-event-bus-to-kafka.md
3

4
npx inkan new rfc payments "Settle in async batches" --author jules

With the npm script that init adds: npm run new -- adr platform "Move the event bus to Kafka".

Numbering#

The command reads the folder <contentDir>/<project>/<type>/, takes the leading digits of every file name and adds one to the largest. An empty or new folder starts at 0001. Numbers are per project and per type, so sre/adr/0003 and sre/rfc/0003 are different records, and gaps are allowed: deleting 0005 does not renumber anything, and the next record after 0004 and 0009 is 0010. Numbers are padded to four digits.

The site derives the number from the file name the same way, so a record you create by hand with a correct name is indistinguishable from one created by the command. See Record type comes from the folder.

The slug#

The title is lowercased, accents are stripped (é to e, ł to l), every run of characters that is not a-z or 0-9 becomes one -, and leading or trailing hyphens are removed:

Templates and placeholders#

Templates are Markdown files named after the type: adr.md, rfc.md, postmortem.md. The package ships adr.md and rfc.md. Your own templates live in templatesDir (default templates/, relative to the config file); a file there with the same name replaces the built-in one, and types without a file fall back to the package’s. A type with no template at all gets a three-line front matter with title, date and authors.

Three placeholders are replaced everywhere in the template:

The built-in ADR template:

1
---
2
title: {{title}}
3
description: One sentence that says what was decided.
4
status: proposed
5
date: {{date}}
6
authors: [{{author}}]
7
deciders: []
8
tags: []
9
---
10

11
## Context
12

13
What is the problem and why does it need a decision now?
14

15
## Options considered
16

17
1. **Option A**: …
18
2. **Option B**: …
19

20
## Decision
21

22
What we will do.
23

24
## Consequences
25

26
What becomes easier or harder because of this decision.

The built-in RFC template starts with status: draft and has the sections Summary, Motivation, Proposal, Alternatives and Open questions. To use your own, copy a built-in file into templates/ and edit it:

1
templates/
2
  adr.md          replaces the built-in ADR template
3
  postmortem.md   template for a custom type from docTypes

Automatic _project.yml#

When <contentDir>/<project>/_project.yml does not exist, the command writes one before creating the record:

1
name: payments
2
description:
3
owners: []

It prints a reminder to fill in the details. The folder name is the id used in URLs; name is only the display name, so set it to Payments. See One folder per project and the fields in the front matter reference.

Author handles#

Without --author, the command looks the Git user up in _authors.yml: an entry whose email matches git config user.email, or whose handle, name, github or gitlab matches git config user.name, gives its handle, so Jane Doe <jane@example.com> becomes authors: [jane.doe]. Without a match the Git user name is written as it is, for example Jane Doe, and inkan check reports it as an unknown author; pass --author jane.doe or edit the line after creation. The RFC on filling date and authors from git discusses the same matching for date and authors at build time.

Custom fields that have a default are written into the new record’s front matter. See Custom metadata fields.

Consequences#

• The next number is always right for the folder you have checked out. Two branches that both add 0010 still conflict at merge time; the build does not notice, but inkan check reports the clash as a duplicate-number error, so the CI check from init catches it on the merged branch. See Check records in CI.
• Templates are plain Markdown with three placeholders. There is no templating language, no conditionals and no per-project template.
• The command needs the config to know contentDir, templatesDir and docTypes, so it must run in the folder with inkan.config.* or with --root.
• The slug only keeps ASCII letters and digits. Titles in scripts without a Latin transliteration produce very short slugs; rename the file if you need to, the number is what matters.
• Nothing is renumbered or renamed afterwards. Changing a title later leaves the file name as it was, which keeps links stable.

Context#

A decision log is edited by many people in pull requests, often without running the site locally. Metadata mistakes are quiet: status: acepted renders fine but the record never shows up as current, a misspelled config key is ignored and the feature “does not work”. With a static site there is exactly one moment where every file is read, the build, so that is where mistakes must be caught, with messages that name the file and the field.

Decision#

Inkan validates two things and stops on the first problem:

• The config file, with a zod schema in which every key is optional and unknown keys are rejected. Each unknown key gets a “did you mean” hint. Plugins are the exception: unknown keys on a plugin are kept, because a newer plugin may carry more, but each one is reported as a warning.
• Content metadata: the front matter of every record and page, every _project.yml and _authors.yml, through Astro content collections with zod schemas. status is an enum built from the keys of statuses in your config, so the allowed values are exactly the ones you defined. A failure stops inkan build with a non-zero exit code, which fails the pull request check.

How to use it#

Config errors#

Run inkan dev or inkan build. The config is validated before anything else. A broken config looks like this:

1
Invalid inkan config:
2
  inkan.config.ts: titel: unknown option, did you mean "title"?
3
  inkan.config.ts: repo.provder: unknown option, did you mean "provider"?
4
  inkan.config.ts: theme.default: expected one of "system"|"light"|"dark"
5
  inkan.config.ts: contentDir: must not be empty

What is checked:

The hint is the closest known key at that position, measured by edit distance; a key that is nowhere near anything known gets no hint. $schema is accepted at the top level of any config and dropped, so a JSON config can point an editor at a schema.

Unknown keys on a plugin do not fail the build. They are printed once at load time:

1
inkan: plugin "acme": unknown key "remarkPlugin"

The known plugin keys are name, config, remarkPlugins, rehypePlugins, vitePlugins, integrations, pages, motifs, head and navigation. See Plugins with definePlugin.

Front matter errors#

Every .md and .mdx file in contentDir is parsed against the record schema. The schema is in app/src/content.config.ts and documented field by field in the front matter reference. The rules in short:

• title is required and a string.
• status, when present, must be one of your configured statuses. With the defaults: draft, proposed, in-review, accepted, implemented, rejected, withdrawn, deprecated, superseded.
• date, reviewBy and reviewed must be dates; reviewEvery must be an interval (1 year, 6 months, 90 days) or never, on records and in _project.yml alike.
• authors, deciders, tags, supersedes, supersededBy and related are lists of strings; a single string is accepted and wrapped.
• order is a number, draft a boolean.

A bad record stops the build. Astro prints the collection, the file and the field, for example a status: acepted is reported as an invalid enum value for status in decisions/sre/adr/0002-error-budget.md, together with the allowed values. Fields that the schema does not know are dropped silently, so a Status: with a capital letter is not an error; it is simply not a status. Watch the sticker on the record to confirm.

_project.yml and _authors.yml are validated the same way: name is required in both, ink must be one of the six ink letters, and a links[].url must start with http://, https:// or /. motif is checked once all projects are read: a name that is neither built in nor registered by a plugin fails the build with project "sre": unknown motif "ring", did you mean "rings"? (available: ...). A plugin motif whose module does not exist fails at config load with plugin "acme" motif "stamp": module not found: ....

Page and route conflicts#

The build also fails when two things would be served at the same URL: a project folder named like a built-in page (decisions, tags), two project folders with the same slug (Ops Plans/ and ops-plans/), a root-level about.md next to a project folder about/, or a page in pagesDir or from a plugin that shadows a record, a redirect or a built-in page. Dynamic pages such as guides/[slug].astro only warn. A plugin page whose entrypoint file does not exist fails as well.

Running it in CI#

The workflow and pipeline that inkan init creates run npm run build on every pull or merge request, so a bad record cannot be merged. Without them, a minimal check is:

1
- run: npm install
2
- run: npm run build

The build exits with code 1 on the first error. Fix it and run again; errors are reported one file at a time.

Checking without building the site#

inkan check validates what the build cannot see: references in supersedes, supersededBy and related that point nowhere, duplicate numbers, one-sided supersede links, unknown authors, overdue reviews and projects without _project.yml or owners. It reads the files directly, takes seconds and reports path:line level message. It also catches front matter that does not parse, a missing title, an unknown status and a malformed date, with the same config the build uses. The CI files from init run it before the build. See Check records in CI.

The config alone can be checked programmatically with validateConfig from inkan/lib/config.mjs, which throws an error with one line per problem; this is what the test suite of the package uses.

Consequences#

• Typos in the config and in status are found at build time, with the file and the key named. Nothing silently does nothing, except unknown front matter fields.
• The status list is a closed enum per site. That is what makes the backlog, the “current” flag and the stickers reliable, at the cost of a build failure when the list changes.
• Plugins can carry keys the core does not know, so a plugin written for a newer version loads on an older one with a warning instead of an error.
• Build-time validation covers shape, not meaning. A supersedes path that points at a record that does not exist, a duplicate number or a missing owners entry passes the build; inkan check is the second step that catches them.
• Front matter fields outside the schema are dropped without a warning. A misspelled field name such as author: instead of authors: is the one class of typo the build does not catch.

Context#

A record changes status a few times in its life: proposed, accepted, implemented, one day superseded. Each change is a small edit to front matter, and each one is easy to get wrong by hand: a misspelled status, a supersededBy on the old record without the matching supersedes on the new one, or a status left at accepted after the replacement landed. The build only catches the first of these. People also edit records from scripts and from pull request bots, where opening a file in an editor is not an option.

Decision#

Two commands edit front matter for you:

• inkan status <record> <status> sets status on one record.
• inkan supersede <old> <new> sets status: superseded and appends <new> to supersededBy on the old record, and appends <old> to supersedes on the new one.

Both validate the status against your configured statuses, resolve records by several spellings, rewrite only the keys they change and leave the rest of the file as written: comments, key order, quoting and line endings survive. --dry-run prints a diff instead of writing. Records fetched from a repo source are refused, because their clone is overwritten on the next sync.

How to use it#

Change a status#

1
npx inkan status sre/adr/0003 accepted

1
sre/adr/0003-define-slos: proposed -> accepted

The status must be a key of statuses in your config (the nine defaults, or your own map). A wrong one exits with code 1 and a hint:

1
Unknown status "acepted". Did you mean "accepted"? Known: draft, proposed, in-review, accepted, implemented, rejected, withdrawn, deprecated, superseded.

Running the command again with the same status writes nothing and prints sre/adr/0003-define-slos: already accepted.

Supersede a record#

1
npx inkan supersede platform/adr/0004 platform/adr/0009

1
platform/adr/0004-use-sqs-as-the-event-bus: accepted -> superseded, supersededBy += platform/adr/0009-move-the-event-bus-to-kafka
2
platform/adr/0009-move-the-event-bus-to-kafka: supersedes += platform/adr/0004-use-sqs-as-the-event-bus

What changes on each file:

Ids are written in full (platform/adr/0009-move-the-event-bus-to-kafka), as a flow list (supersedes: [platform/adr/0004-use-sqs-as-the-event-bus]). Existing entries stay; if a list already names that record under any spelling, nothing is added, so the command is safe to run twice. The two records may live in different projects. A record cannot supersede itself. --dry-run works here too and shows the diff of both files. --date [YYYY-MM-DD] sets date on <old>, the record whose status changes, exactly as it does for inkan status.

Which spellings of a record are accepted#

<record>, <old> and <new> can be written as:

A query that matches more than one record (duplicate numbers in one folder, or a trailing part shared by two projects) is refused with the list of candidates, and a query that matches nothing gets a “did you mean” hint built from ids and references.

What —dry-run prints#

A unified-style diff per file, changed lines only, followed by the summary line with [dry run]:

1
--- decisions/platform/adr/0004-use-sqs-as-the-event-bus.md
2
- status: accepted
3
+ status: superseded
4
+ supersededBy: [platform/adr/0009-move-the-event-bus-to-kafka]
5
platform/adr/0004-use-sqs-as-the-event-bus: accepted -> superseded, supersededBy += platform/adr/0009-move-the-event-bus-to-kafka [dry run]

How the file is edited#

The front matter is parsed as a YAML document and the changed keys are set on that document; everything else is serialised back as it was. A # comment above tags, a quoted title, "status" written with quotes and CRLF line endings all survive. A file without front matter gets one. Front matter that does not parse stops the command with the file name and the first YAML error; run inkan check to find such files first.

In scripts and npm#

init adds status and supersede to the scripts of package.json, so these do the same thing:

1
npm run status -- sre/adr/0003 accepted
2
npm run supersede -- platform/adr/0004 platform/adr/0009

The exit code is 0 on success (including “already …”), 1 on a usage error, an unknown status, an unresolved record or a read-only source record. Pair the commands with inkan check in CI to catch supersede links that were edited by hand on one side only; see Check records in CI.

Consequences#

• Status changes are validated at the moment they are made, not at the next build, and the two sides of a supersede link are always written together.
• The commands only know front matter. The body of the old record is not touched, so add a sentence pointing at the replacement yourself when you want one.
• supersede sets status: superseded only if that status exists in your statuses. A lifecycle without it gets the links but no status change.
• Formatting is preserved key by key, not byte by byte: a list written one item per line is kept, but a key the command writes is always in flow style.
• The lookup by trailing id part is convenient and ambiguous by design; scripts should pass full ids or references.

Context#

Most teams that try Inkan already have decisions: a docs/adr/ folder made with adr-tools, a log4brains site, or MADR files written by hand. Those formats keep metadata in the body, as a ## Status section, a Date: line or a list of * Status: accepted items under the title. Inkan keeps metadata in front matter and takes the type and number from the path. Converting a few dozen files by hand is boring and error-prone, and it is the first thing a new user has to do.

Decision#

inkan import <dir|file...> --project <name> reads files in the three common dialects and writes them as <contentDir>/<project>/<type>/NNNN-slug.md with front matter:

• the first # heading becomes title; a leading 1. becomes the record number,
• status, date, deciders and tags move into front matter, with status spellings mapped to your configured statuses,
• a Superseded by [..](..) status and adr-tools Supersedes [..](..) lines become supersededBy and supersedes when they point at files of the same import,
• links between imported files are rewritten to the new file names,
• original numbers are kept when they are free; existing files are never overwritten.

The command converts the metadata and leaves the body as it was, so the imported text reads exactly like the original.

How to use it#

Run it#

1
npx inkan import ../old-repo/docs/adr --project platform --dry-run
2
npx inkan import ../old-repo/docs/adr --project platform

1
Wrote decisions/platform/adr/0001-record-architecture-decisions.md  <- ../old-repo/docs/adr/0001-record-architecture-decisions.md (adr-tools, accepted)
2
Wrote decisions/platform/adr/0002-use-postgres.md  <- ../old-repo/docs/adr/0002-use-postgres.md (adr-tools, superseded)
3
Wrote decisions/platform/adr/0003-use-cockroachdb.md  <- ../old-repo/docs/adr/20200927-use-cockroachdb.md (madr, accepted)
4
Imported 3 records into decisions/platform/adr.

Inputs are folders (walked recursively, _-prefixed files and folders skipped) or single .md and .mdx files, in any mix. Files named README, index or template (any case) are skipped. When the project folder has no _project.yml, one is created with name: <project> for you to fill in.

Dialect detection#

With --format auto, a file is adr-tools when its body has a ## Status heading and a Date: ... line before the first ## heading. Everything else is parsed as MADR, which covers log4brains and MADR 2.x header lists as well as MADR 3 and 4 front matter.

In every dialect the first # heading is the title (falling back to a front matter title) and is removed from the body; a file with neither is skipped with no heading. A status that reads Superseded by [title](file.md) sets supersededBy from the link and the status superseded.

Status mapping#

The status is reduced to its first word, lowercased, and matched against your statuses:

1. an exact key (accepted),
2. a synonym, when the target is configured: approved to accepted, pending to proposed, wip to draft, declined to rejected, obsolete to deprecated, done to implemented,
3. the closest key by edit distance (acepted to accepted).

A status that maps to nothing is left out, and a warning names the file: status "Parked" is not configured; left out. Add the status to statuses first if you want to keep it; see Configurable status lifecycle.

Numbers, names and dates#

Original numbers are kept when no record in the target folder uses them. Two sources claiming the same number, or a number already taken, fall back to the next free number in input order. The slug comes from the file name, or from the title when the name has none. A slug that already exists in the target folder means the file was imported before and is skipped with already imported as <file>; a target file that exists is never overwritten.

Links#

Relative Markdown links from one imported file to another are rewritten to the new name, keeping any #anchor: [2. Use Postgres](0002-use-postgres.md) becomes [2. Use Postgres](./0002-use-postgres.md) under its new number. supersedes, supersededBy and related get the full id of the target record (platform/adr/0002-use-postgres). A link whose target is not part of the same import is left as text and, for the three link fields, dropped with a warning: supersedes link "0003-x.md" points outside this import; left out. Import a whole folder at once so the links resolve.

Check the result#

1
npx inkan check
2
npx inkan dev

check reports one-sided supersede links, unknown authors and missing owners in the new _project.yml; see Check records in CI. Deciders are imported as written (Ann, Bob), so either add them to _authors.yml under those handles or edit them to existing handles.

Consequences#

• A folder of adr-tools, log4brains or MADR files becomes a working Inkan project in one command, with the body text unchanged.
• Only metadata the three formats agree on is mapped. consulted and informed are written to front matter but the site does not display them; MADR “Decision Outcome” or “Considered Options” sections stay as ordinary body text.
• Numbers are preserved per type folder. Importing two sources into the same project renumbers the second one wherever numbers collide, and links are rewritten accordingly only within one run.
• Links to records outside the import are not resolved. Import related folders together, or fix the supersedes fields afterwards with inkan supersede.
• The command never overwrites or deletes, so re-running it is safe but does not update records that changed in the source.

Context#

The build validates the shape of every record: a status outside the configured list or a date that is not a date fails it. It does not validate meaning. A supersedes entry can point at a record that does not exist, two files in one folder can share a number, a record can carry supersededBy while its status still says accepted, and an RFC can sit past its reviewBy date for months. None of this breaks the HTML, so none of it failed a pull request, and the build itself takes long enough that nobody runs it just to check a link.

Decision#

inkan check reads every record directly, without Astro, and runs a fixed set of rules over them. Problems that make the site wrong are errors and set the exit code to 1; problems that make it worse are warnings and only fail with --strict. The output names the file and the front matter line, so it reads like a linter. On GitHub Actions each problem is also emitted as an annotation, so it appears inline in the pull request. The CI files that inkan init creates run check before the build.

How to use it#

Run it#

1
npx inkan check

1
decisions/payments/adr/0003-use-stripe.md:9 error supersedes points to "payments/adr/0001-build-our-own-gateway", which does not exist, did you mean "payments/adr/0001-build-our-own-card-gateway"?
2
decisions/payments/adr/0003-use-stripe.md:6 warning author "jule" is not in _authors.yml, did you mean "jules"?
3

4
decisions/sre/_project.yml warning project "sre" has no owners
5

6
1 error, 2 warnings (41 records in 7 projects).

Each line is path:line level message. The path is relative to the folder you run in (or to the site root when the file is outside it), and the line points at the offending front matter key when there is one. Problems are grouped by file. With nothing to report the output is one line: No problems found (40 records in 7 projects).

init adds check to package.json, so npm run check does the same.

The rules#

Errors (the site would be wrong):

Warnings (the site is incomplete or misleading):

Both project rules skip projects that come from sources. Reference values are matched the way the site matches them: full id, short id (sre/adr/3), reference (SRE-ADR-0003) or file path; see Link records by path.

Exit codes#

JSON output#

1
npx inkan check --format json

1
{
2
  "ok": false,
3
  "errors": 1,
4
  "warnings": 1,
5
  "records": 41,
6
  "projects": 7,
7
  "problems": [
8
    {
9
      "level": "error",
10
      "rule": "missing-record",
11
      "message": "supersedes points to \"payments/adr/0001-build-our-own-gateway\", which does not exist, did you mean \"payments/adr/0001-build-our-own-card-gateway\"?",
12
      "file": "decisions/payments/adr/0003-use-stripe.md",
13
      "line": 9,
14
      "record": "payments/adr/0003-use-stripe"
15
    }
16
  ]
17
}

ok is true when there are no errors, regardless of warnings. line and record are absent when they do not apply (a project-owners problem has no record). The exit code follows the same rules as the text output, so a script can read the JSON and still rely on the status.

GitHub Actions annotations#

When GITHUB_ACTIONS=true, check prints one workflow command per problem after the report:

1
::error file=decisions/payments/adr/0003-use-stripe.md,line=9,title=inkan check (missing-record)::supersedes points to ...

GitHub turns these into annotations on the changed files in the pull request. Paths are relative to GITHUB_WORKSPACE (or the repository root); files outside the workspace and under node_modules, such as fetched sources, get no annotation. GitLab has no equivalent; the job log and the exit code carry the result there.

In the starter CI files#

inkan init writes a GitHub workflow and a GitLab pipeline that run check before the build on every pull or merge request and on the default branch:

1
- uses: actions/checkout@v4
2
  with:
3
    fetch-depth: 0 # full history for "Last updated"
4
- uses: actions/setup-node@v4
5
  with:
6
    node-version: 22
7
- run: npm install
8
- run: npx inkan check # broken links, duplicate numbers, unknown statuses … as PR annotations
9
- run: npm run build

1
variables:
2
  GIT_DEPTH: 0 # full history for "Last updated"
3

4
build:
5
  script:
6
    - npm install
7
    - npx inkan check
8
    - npm run build

A failing check stops the job before the build runs. Add --strict to the step when you want warnings to block merges too. The full history (fetch-depth: 0, GIT_DEPTH: 0) is for the dates and authors inferred from git, not for check. See GitHub and GitLab Pages.

What it does not check#

check reads the front matter and the folder layout. It does not render Markdown, so broken relative links in the body, missing images and Mermaid syntax errors are left to the build, and it does not validate inkan.config.* beyond loading it (the schema runs on load, so a bad config still fails). Content from repo sources is included: missing clones are fetched first, with progress on stderr. See Validate config and content at build time for what the build covers.

Consequences#

• Reference and numbering mistakes fail a pull request within seconds, with the file and line, and show up inline on GitHub.
• Errors and warnings are separate by design: a project without owners should not block a hotfix to a record, but --strict is there for repositories that want a clean log.
• The rule set is fixed. There is no configuration to disable one rule; keep the warning level in mind when a rule does not fit your process.
• check is a second validator next to the build, with its own messages. The two agree on what a valid status and date are, because both read the same config, but check is stricter about dates (the build accepts anything Date can parse).
• Records in repo sources are checked but cannot be fixed here; the fix goes to the source repository.

Context#

A decision matters when the people it affects know about it. A pull request that sets a record to accepted is reviewed by a few people, and everyone else finds out when they open the site, if they do. The site is passive: it is always up to date and nobody is told that something changed. Teams already work in a chat tool, and a short message with the title and a link there is what gets a decision read.

Decision#

inkan notify compares the records with an earlier commit and posts a message for every record whose status changed into a notified status. The default is accepted; notify.statuses changes it. It runs in CI after the site is deployed, so the link in the message already works. Slack, Microsoft Teams and any generic webhook are supported. Webhook URLs come from environment variables or from the config through process.env, never from literals, and they are not part of the built site.

How to use it#

What counts as a change#

A record is reported when all of these hold:

• its file changed between the compared commit and the working tree;
• its status is in the notified list;
• its status at the compared commit was different, or the record did not exist there. A record added in the range counts as changed from no status.

Renames are followed: a record that moved to another folder and went from proposed to accepted is reported once, with proposed as its previous status. A record that is edited but keeps its status is not reported, and neither is a record that left the notified status. Records from repo sources are skipped, because their history lives in their own repository.

Protected records are never posted: a record of a project with protected: true or on a path in protectedRoutes (see Sign-in and protected projects) is left out of every channel, whatever its filters, because a chat room is not a place only members can see. The message would carry the title, description and link of something the public site hides.

Which commit it compares with#

The first push of a new branch has no previous commit (the sha is all zeros). The command then prints No previous commit to compare with (first push of a branch); nothing to notify. and exits with 0. A compared commit that is not in the clone is an error that names the cause. The job needs the full history: fetch-depth: 0 on GitHub, GIT_DEPTH: 0 on GitLab.

Locally the working tree is included in the comparison (tracked files only: git add a new record first), so npx inkan notify --since main --dry-run shows what a pull request would send.

Channels#

A channel is a webhook that receives messages. The simplest setup is an environment variable, usually a CI secret:

For more than one channel of a type, or for filters, list them in notify.channels:

1
export default defineConfig({
2
  url: 'https://decisions.acme.dev',
3
  notify: {
4
    statuses: ['accepted'],
5
    channels: [
6
      { type: 'slack', name: 'platform-slack', url: process.env.SLACK_PLATFORM },
7
    ],
8
  },
9
});

Channels from the environment and from the config add up. A status that is not in statuses of the config is an error (notify: unknown status "acepted". Did you mean "accepted"? Known: ...), checked before anything is sent, so a typo fails the job instead of silencing it.

Route decisions to the team that cares#

Each channel has its own filters, so one pipeline can serve several rooms:

1
export default defineConfig({
2
  notify: {
3
    channels: [
4
      { type: 'slack', name: 'platform', url: process.env.SLACK_PLATFORM, projects: ['platform', 'sre'] },
5
      { type: 'slack', name: 'payments', url: process.env.SLACK_PAYMENTS, projects: ['payments'] },
6
      { type: 'teams', name: 'architects', url: process.env.TEAMS_ARCHITECTS, types: ['adr', 'rfc'], statuses: ['accepted', 'rejected'] },
7
    ],
8
  },
9
});

A record reaches a channel when its project and type match (an empty or missing list matches everything) and its status is in the channel’s statuses, or in notify.statuses when the channel has none. The command works out the union of all these statuses first, so a channel that wants rejected sees rejected records even though the global list says accepted.

Slack#

Create an incoming webhook for a channel (Slack app, Incoming Webhooks) and store the URL as INKAN_SLACK_WEBHOOK. Each record becomes a Block Kit message: the heading as a link, the description, and a line with the project, type, status change and authors. Link unfurling is off. Mattermost and Rocket.Chat accept the same payload on their incoming webhooks, so use type: 'slack' for them.

Microsoft Teams#

In a Teams channel add a workflow from the template “Post to a channel when a webhook request is received” and store its URL as INKAN_TEAMS_WEBHOOK. The message is an Adaptive Card with the project and type, the heading, the description, a fact set (status change, authors) and an “Open record” button. Classic incoming webhooks accept the same card.

Any other webhook#

type: 'webhook' posts one JSON document per run with all events that match the channel:

1
{
2
  "site": { "title": "Acme decisions", "url": "https://decisions.acme.dev" },
3
  "events": [
4
    {
5
      "id": "sre/adr/0003-define-slos",
6
      "ref": "SRE-ADR-0003",
7
      "title": "Define SLOs",
8
      "description": "Availability and latency targets per service.",
9
      "project": "sre",
10
      "projectName": "Site reliability",
11
      "type": "adr",
12
      "typeLabel": "ADR",
13
      "status": "accepted",
14
      "statusLabel": "Accepted",
15
      "previousStatus": "proposed",
16
      "previousStatusLabel": "Proposed",
17
      "authors": ["Alex Chen"],
18
      "tags": ["slo"],
19
      "url": "https://decisions.acme.dev/sre/adr/0003-define-slos/",
20
      "file": "docs/decisions/sre/adr/0003-define-slos.md"
21
    }
22
  ]
23
}

headers are added to the request. For services that expect their own format, body receives { site, events } and returns what to send:

1
channels: [
2
  {
3
    type: 'webhook',
4
    name: 'discord',
5
    url: process.env.DISCORD_WEBHOOK,
6
    body: ({ events }) => ({ content: events.map((e) => `**${e.title}** is now ${e.statusLabel}: ${e.url ?? e.file}`).join('\n') }),
7
  },
8
  {
9
    type: 'webhook',
10
    name: 'google-chat',
11
    url: process.env.GOOGLE_CHAT_WEBHOOK,
12
    body: ({ events }) => ({ text: events.map((e) => `${e.title} is now ${e.statusLabel}`).join('\n') }),
13
  },
14
],

Digest and links#

Slack and Teams get one message per record. Above 5 records in one run they get a single digest that lists up to 20 of them, with a “…and N more” line after that. The generic webhook always gets one request.

A record links to the site (<url>/<base>/<id>/) when url is set in the config (set the same BASE_PATH as for the build), and to the file in the repository (from repo) otherwise. Without either there is no link, and the message still names the record.

Dry run and exit codes#

1
npx inkan notify --dry-run

--dry-run resolves everything and prints the JSON bodies instead of sending them. Output of a real run:

1
sre/adr/0003-define-slos: proposed -> accepted
2
platform/adr/0009-move-the-event-bus-to-kafka: (new) -> accepted
3
slack: sent 2 messages (2 records)
4
architects: skipped, no URL (is its secret set in this pipeline?)
5
discord: failed, 404 Not Found: Unknown Webhook

In the starter CI files#

inkan init writes a notify job that runs after the site is deployed, on the default branch only. A channel whose secret is not set is skipped, so the job does nothing until you add a webhook.

1
notify:
2
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
3
  needs: deploy
4
  runs-on: ubuntu-latest
5
  steps:
6
    - uses: actions/checkout@v4
7
      with:
8
        fetch-depth: 0 # compares with the commit before the push
9
    - uses: actions/setup-node@v4
10
      with:
11
        node-version: 22
12
    - run: npm install
13
    - run: npx inkan notify
14
      env:
15
        BASE_PATH: /${{ github.event.repository.name }} # same as the build, so links point at the right pages
16
        INKAN_SLACK_WEBHOOK: ${{ secrets.INKAN_SLACK_WEBHOOK }}
17
        INKAN_TEAMS_WEBHOOK: ${{ secrets.INKAN_TEAMS_WEBHOOK }}

1
notify:
2
  needs: [pages]
3
  script:
4
    - npm install
5
    - BASE_PATH="/$CI_PROJECT_NAME" npx inkan notify
6
  rules:
7
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PIPELINE_SOURCE == "push"

On GitLab add INKAN_SLACK_WEBHOOK and INKAN_TEAMS_WEBHOOK as masked variables in Settings, CI/CD, Variables. On GitHub add them as repository secrets. See GitHub and GitLab Pages.

Consequences#

• People hear about accepted decisions on the day they land, with a link, without anyone writing the announcement.
• The comparison is by status in git history, so the command is stateless: nothing is stored between runs. A run that is repeated on the same push sends the same messages again.
• Squash merges and pushes of many commits work, because only the first and the last state are compared. A record that went proposed to accepted to proposed inside one push is not reported.
• A failed delivery fails the job but not the deploy, because notify runs after it. Re-run the job to retry.
• Secrets live in the CI system. A webhook URL that someone hard-codes in the config ends up in the repository, which is why the docs and the examples always use process.env.
• Records from repo sources are not announced here; run notify in their own repository. See Records from other repositories.
• Pairs with Change status and supersede from the CLI and Check records in CI: check guards the merge, notify announces the result.

Context#

Review decisions on a schedule gives decided records a review date. Closing a review is a front matter edit: set reviewed to today, drop a reviewBy that has just been honoured, perhaps change the interval. Done by hand, the edit is easy to get wrong in the same ways a status change is, and a review that leaves reviewBy in the past is reported as overdue again on the next check. The other half of the loop, finding out what is due, needs the site or a jq query over decisions.json; a weekly job and a quick look before a team meeting want it from the terminal.

Decision#

Two commands, built like status and supersede:

• inkan reviewed <record> records a review: it sets reviewed (today unless --date says otherwise), sets reviewBy from --next, sets reviewEvery from --every, and, without --next, removes reviewBy once an interval takes over. It refuses records whose status is not a review status.
• inkan reviews lists the records whose review is overdue or due within a window, soonest first, with --all for every scheduled record and --json for scripts.

Both resolve records by the spellings every command accepts, rewrite only the keys they change, and refuse records from a repo source. --dry-run prints the diff.

How to use it#

Record a review#

1
npx inkan reviewed dbre/adr/0001

1
dbre/adr/0001-standardize-on-postgresql-16: reviewed 2026-10-17, next review 2027-10-17

What the command writes depends on what the record already has:

The record must be in a review status (reviews.statuses, by default accepted and implemented). A proposed RFC is not reviewed this way: its reviewBy is a decision deadline, and the command exits with code 1 and the list of review statuses. Decide on the record with inkan status first; see Change status and supersede from the CLI.

The front matter is edited key by key, the way status does it: comments, key order, quoting and line endings survive.

List what is due#

1
npx inkan reviews

1
2026-09-30  17 days late  DBRE-ADR-0001  Standardize on PostgreSQL 16
2
2026-11-15  in 29 days    PAYMENTS-ADR-0003  Use Stripe as the primary payment provider
3

4
1 overdue, 1 due within 30 days.

The list comes from the same rule as the site and check: reviewBy, or the interval after reviewed or date, for records in a review status. Records from sources are included. With nothing due the output is one line saying so. A job that should fail on overdue reviews runs inkan check --strict, where an overdue review is the review-due warning; see Check records in CI.

In scripts and agents#

1
npx inkan reviews --json > due-reviews.json

The same list is one MCP tool away for agents, due_reviews, see MCP server for agents. A weekly workflow that runs inkan reviews and posts the output is in Review decisions on a schedule.

Consequences#

• Closing a review is one command that leaves the record in a state check accepts: no reviewBy in the past, an interval or a next date in place.
• The command does not change status. A review that finds the decision no longer holds continues with status, supersede or a new record, which is a deliberate second step.
• Refusing a record without an interval and without --next or --every is stricter than status; it stops a review from silently taking the record off the schedule.
• reviews reads the files, so it sees uncommitted edits, and it reads the config, so a custom reviews.statuses is honoured. A published site offers the same through decisions.json and the MCP server’s --url mode.

Context#

Review RFCs with reviewers puts each reviewer’s answer in front matter. Editing a map by hand is easy once and error-prone the tenth time: the date is forgotten, a list has to become a map, a note needs quoting. Reviewers also want the opposite question answered from a terminal or a script: what is waiting on me?

Decision#

inkan rfc-review does both. Like status and supersede, it edits the file in place and keeps the rest of the front matter as written (comments, key order, quoting); the reviewers block itself is rewritten in map form, so comments inside it are dropped, and --dry-run shows the change without writing it.

How to use it#

Answer#

1
npx inkan rfc-review sre/rfc/2 marek approve
2
npx inkan rfc-review sre/rfc/2 jules request-changes --note "Needs a rollback plan"
3
npx inkan rfc-review sre/rfc/2 jules reset

--note "…" stores a short note next to the state. <record> is anything inkan status accepts: id, short id, reference or file path. A list of handles is rewritten as a map; other reviewers keep their state, date and note. A reviewer who is not listed yet is added. The command refuses a record whose reviewers it cannot read, and a record from a repo source, which is read-only here.

What is waiting on someone#

1
npx inkan rfc-review --for marek
2
npx inkan rfc-review --for marek --format json

The text form is one line per open record whose review waits on that handle: reference, title, review status and reviewBy. The JSON form prints the same records as an array, for scripts and chat bots. A handle is waited on as the review status says: pending reviewers, the authors when changes were requested, the deciders (or authors) once approved. Nothing waiting is not an error: the exit code is 0.

Consequences#

• Answering a review is one command and one commit, and the date is not forgotten.
• The state is written for the reviewer you name. The CLI does not check who is running it; git blame and the pull request show who changed the line.
• A list of reviewers becomes a map on the first answer, which touches every line of the field in the diff.
• --for reads the files, not the site, so it sees uncommitted answers and works without a build.