Muninn

Muninn gives every contributor one checked route to your repository’s current documentation. It creates a small documentation scaffold and catches broken routes, links, anchors, and authority mappings before they drift.

Pre-release: @rasmushjulskov/muninn is not published to npm yet. The install and run commands below are the intended path for the public 0.1.0 release. Requires Node.js 20.19 or newer; Bun works too.

Quick start

Install Muninn as a development dependency:

npm install --save-dev @rasmushjulskov/muninn
# or: bun add --dev @rasmushjulskov/muninn

New repository

npx muninn init .
npx muninn check .

init creates the missing files for a minimal passing contract:

README.md
docs/README.md
docs/knowledge.yaml

It preserves any of these files that already exist.

Existing repository

Initialize the scaffold, then adapt it before expecting a passing check:

npx muninn init .

Link the existing README.md to docs/README.md, then review docs/knowledge.yaml and map the docs that are current authority. Run npx muninn check . when those routes are ready.

For a larger documentation set, use the one-time setup prompt to inventory entrypoints and authority. Muninn reports routes that still need attention; it does not rewrite existing documentation.

What Muninn checks

By default, check runs offline and validates:

• the manifest, required files, repository-relative paths, casing, and symlink containment;
• visible routes from human and agent entrypoints to the documentation index;
• links from the index to every active authority;
• replacement routes for superseded documents;
• Markdown links and exact GitHub-style heading anchors;
• declared scope globs (patterns that match no files, same-kind overlaps between active authorities);
• reviewed attestations (scoped files changed since the attested commit require re-review).

A passing check exits with 0. Contract failures exit with 1; invalid CLI usage exits with 2. Verification commands declared in the manifest are validated but not executed.

Run it in CI

Add a package script:

{
  "scripts": {
    "knowledge:check": "muninn check ."
  }
}

Then run it with the rest of your checks:

- uses: oven-sh/setup-bun@v2
  with:
    bun-version: 1.3.14
- run: bun install --frozen-lockfile
- run: bun run knowledge:check

CLI

| Command | Purpose | | ------------------------------ | ------------------------------------------------- | | muninn init [root] | Create missing files for a minimal contract. | | muninn check [root] | Validate a repository offline. | | muninn default --path | Print the installed path to the default contract. | | muninn setup-prompt [--path] | Print the setup prompt or its installed path. |

Run npx muninn --help for external-check and custom-manifest options. The TypeScript API is available through the package’s main export.

Reference

• Default contract, manifest, and authority lifecycle
• One-time setup prompt for existing repositories

Contributing

git clone [email protected]:the-magrathean-custom-builders/muninn.git
cd muninn
bun install --frozen-lockfile
bun run check

License

MIT