No. 001

Title

Your knowledge base, checked like code.

Aim

Specs, decisions and records live in a git knowledge base that people and agents both edit. The Cube checks every file, draws what depends on what, and its git hooks refuse a commit that adds an error, whoever wrote it.

Method

Install
curl -fsSL https://happonomyorg.github.io/cube-releases/install.sh | sh
irm https://happonomyorg.github.io/cube-releases/install.ps1 | iex
The installer checks the signature, GitHub's release record and the SHA-256 before it installs anything. See page 5.
Start from the starter kit
Extract it into a git repository, then run cube adopt and cube check. Quick start

~/my-kb $ cube check
ERROR REF_DANGLING shared/conventions/module_spec.yml:18: the design_system_ref names shared/design-system/, which does not exist
cube check: 1 error(s), 0 warning(s), 0 info(s)
...
~/my-kb $ git commit -am "Point conventions at the design system"
...
Ratchet: 0 -> 1 ERRORs: refused: a new ERROR
...
~/my-kb $ cube check
cube check: 0 error(s), 0 warning(s), 0 info(s)
...
~/my-kb $ git commit -am "Point conventions at the design system"
...
[main f1ad076] Point conventions at the design system

The full transcript (41 lines)

~/my-kb $ sed -i '18s|"shared/"|"shared/design-system/"|' shared/conventions/module_spec.yml
~/my-kb $ cube check
ERROR REF_DANGLING shared/conventions/module_spec.yml:18: the design_system_ref names shared/design-system/, which does not exist
cube check: 1 error(s), 0 warning(s), 0 info(s)
cube check: writable, cube_format 1; kit starter 0.1.0 (148 of 148 files, 100.00 %)
cube check: ran validator (_kit/tools/validator.py): exit 0, 0 finding(s), files seen 10, 152 ms
~/my-kb $ git commit -am "Point conventions at the design system"
warning: cube.path = /home/you/.local/bin/cube is owned by this account and listed in cube.allowUserOwned: not tamper-proof against same-account agents
# Fix brief (cube check)

Ratchet: 0 -> 1 ERRORs: refused: a new ERROR

Refused: a commit adds no new ERROR: fix or revert each key under "New against the base"; while ERRORs remain, a commit must also fix at least one of them

## New against the base

["REF_DANGLING","shared_conventions",["field=design_system_ref","target=shared/design-system/"]]

1 ERROR(s) to fix, 0 other finding(s) below. Fix each ERROR at its cause, run `cube check` again, and commit each step that lowers the ERROR count. A change that makes a check green without removing its cause is refused as a SHORTCUT_* ERROR itself.

## 1. REF_DANGLING -- shared/conventions/module_spec.yml:18

the design_system_ref names shared/design-system/, which does not exist

- Rule: every *_ref path and id reference resolves (source: kit edges)
- Real fix: point the reference at the file or node that exists, or write the missing target when it should exist
- Not a fix: emptying the field, pointing it at an unrelated file that exists, or deleting the file that holds the reference
- Act: none: an ordinary commit
cube: commit refused (0 -> 1 ERRORs: refused: a new ERROR); the fix brief is in /home/you/my-kb/.cube/cache/fix-brief.md
~/my-kb $ sed -i '18s|design-system/|design_system/|' shared/conventions/module_spec.yml
~/my-kb $ cube check
cube check: 0 error(s), 0 warning(s), 0 info(s)
cube check: writable, cube_format 1; kit starter 0.1.0 (148 of 148 files, 100.00 %)
cube check: ran validator (_kit/tools/validator.py): exit 0, 0 finding(s), files seen 10, 153 ms
~/my-kb $ git commit -am "Point conventions at the design system"
warning: cube.path = /home/you/.local/bin/cube is owned by this account and listed in cube.allowUserOwned: not tamper-proof against same-account agents
cube: 0 -> 0 ERRORs: commit allowed
warning: cube.path = /home/you/.local/bin/cube is owned by this account and listed in cube.allowUserOwned: not tamper-proof against same-account agents
cube: Cube-Checked: v=1 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 errors=0 warns=0 cube=0.1.0
[main f1ad076] Point conventions at the design system
 1 file changed, 1 insertion(+), 1 deletion(-)

Printout 1. cube 0.1.0 on the starter kit; the home folder shows as /home/you.

Witnessed

Release cube-v0.1.0commit b81fe87minisign key RWR3FugwULgFneOK2w98cIpSzUD9BAFixr5+IDM5NxR9n9bkguhZ0mI1GitHub release immutable

Continued on page 2

No. 002

Title

A commit that adds an error does not get in.

Record

shared/conventions/module_spec.yml, the Conventions module of the starter kit, continued from page 1.

Entry

17conventions_ref: ""
18design_system_ref: "shared/design-system/"
18design_system_ref: "shared/design_system/"
19architecture_ref: "shared/architecture/"

Refused: 0 to 1 ERROR (baseline 0). The folder is design_system.Witnessed: 0 ERROR (baseline 0). Commit allowed.

The hooks compare a commit with its parent. More errors than before: refused. The same or fewer: allowed. The errors an existing base already has do not block you; a new one does.

A commit cannot quietly weaken a kit's own rules. Switching a check off, deleting the evidence a check reads or editing its test is itself an error (SHORTCUT_*), and loosening a rule needs a rule-change act by a person.

These checks guard the knowledge base, not your machine. With the alpha's per-user install, an agent that runs as your account could still replace the cube program or change your git settings; the hooks warn you about that, and an install owned by root comes in a later release.

The fix brief an agent reads is on page 4.

Continued on page 3

No. 003

Title

Every reference is a checked link.

Note

Every file is indexed as a typed record (a module spec, a sub-spec, a decision record), and every *_ref field and link is checked: one that lands on nothing is an error. From what your specs declare, The Cube draws the graph: modules and utilities, their sub-specs and what each depends on, the events they publish and consume and the fields those events carry, their tables, the ports they need, and a utility's routes and components. So you can see what a change touches before you make it.

The graph shows what the specs declare: the more a spec names, the more it draws. References between files and decision records are checked, not drawn.

Graph

Photo 1. A made-up sample knowledge base on the starter kit (a "pantry" app, made for this page): 90 nodes and 177 edges, drawn by cube graph visualize, here opened on the pantry module and its neighbours. Drag it, zoom it, pick a node. Open the whole graph full size.

Photo

Photo 2. The same sample in the explorer's graph screen: the pantry module and its neighbours. Press play for the tour, with the keys it presses: the tree, a module spec, its preview, its graph.

Change

Before and after cube pack add ./pack-architecture-0.1.0

kit.yml
_kit/
.claude/
  skills/
    cube/

kit.yml       + packs: [architecture]
_kit/
  packs/architecture/          new
.claude/
  agents/architecture-reviewer.md  new
  skills/
    cube/                      re-rendered
    documenting-architecture/  new
    modeling-systems/          new
    reviewing-architecture/    new

The architecture pack adds a small model of the landscape, linked to the specs that realise it, and the skills and the reviewer agent that keep it. cube pack add never commits: you review the change and commit it.

See

Page 2 for the link that broke.

Continued on page 4

No. 004

Title

The state of the work, on one contents page.

Contents

Path	Kind	State
`shared/conventions/module_spec.yml`	module spec	SPECCED
`shared/design_system/module_spec.yml`	module spec	SPECCED
`shared/architecture/decisions_log.md`	decision log	–
`kit.yml`	kit contract	–

cube ls on the starter kit lists 10 files; the explorer shows the same tree with each spec's state.

An agent that starts here starts from facts: what each spec says, which state it is in, which links hold, which errors block. Without a checked base it starts from guesses, and someone repairs the context afterwards.

We have not measured that difference yet. This is the argument, not a benchmark.

~/my-kb $ cube check --format agent
# Fix brief (cube check)

1 ERROR(s) to fix, 0 other finding(s) below. Fix each ERROR at its cause, run `cube check` again, and commit each step that lowers the ERROR count. A change that makes a check green without removing its cause is refused as a SHORTCUT_* ERROR itself.

## 1. REF_DANGLING -- shared/conventions/module_spec.yml:18

the design_system_ref names shared/design-system/, which does not exist

- Rule: every *_ref path and id reference resolves (source: kit edges)
- Real fix: point the reference at the file or node that exists, or write the missing target when it should exist
- Not a fix: emptying the field, pointing it at an unrelated file that exists, or deleting the file that holds the reference
- Act: none: an ordinary commit
cube check: writable, cube_format 1; kit starter 0.1.0 (148 of 148 files, 100.00 %)
cube check: ran validator (_kit/tools/validator.py): exit 0, 0 finding(s), files seen 10, 152 ms

Printout 2. The fix brief an agent reads: cube check --format agent.

Install it, and check what you installed.

Continued on page 5

No. 005

Title

Install it, and check what you installed.

Method

curl -fsSL https://happonomyorg.github.io/cube-releases/install.sh | sh

irm https://happonomyorg.github.io/cube-releases/install.ps1 | iex

For your account only, no administrator rights: ~/.local/bin on Linux and macOS, %LOCALAPPDATA% on Windows. Read the scripts before you run them: install.sh, install.ps1.

The signed manifest
The list of releases is signed with minisign. The installer checks the signature when minisign is installed.
Check it by hand
```
minisign -Vm alpha.json -P RWR3FugwULgFneOK2w98cIpSzUD9BAFixr5+IDM5NxR9n9bkguhZ0mI1
```
GitHub's release record
The archive's digest on GitHub equals the manifest's, and the release is immutable: its files and its tag cannot change after publication.
The SHA-256 of the download
The file on your disk is the file the manifest names. On a mismatch nothing is installed.

Note

The checks stop a swapped archive or manifest. The script runs them, so read it first if you want to: how.

Continued on page 6

No. 006

Title

What this alpha does not do yet.

Limits

macOS and Windowscube check runs the engine's own checks and skips the kit's checks with a warning (KIT_CHECKS_SKIPPED): the check that a program is safe to run exists only for Linux so far. The git hooks (and cube setup) refuse there until a later release adds the macOS and Windows forms, and so does cube doctor. The other commands work.
Per-user installThe installer puts cube in your home folder. The git hooks run a program your account owns only after you opt it in (cube setup prints the git config --global --add cube.allowUserOwned command), and then every hook warns that it is not tamper-proof: an agent that runs as your account could replace the program or change your git settings. An install owned by root, which closes this gap, comes in a later release.
No self updateThere is no cube self update and no update check yet. To update, run the installer again.
Signaturescube itself does not check signatures yet. The installer checks the manifest's minisign signature only when the minisign program is installed. It always checks GitHub's record of the release (immutable, and the same SHA-256 digest as the manifest), which is a second, independent source, and the SHA-256 of the download. The release that brings cube self update checks signatures in cube itself.
Kits and packsThey are plain archives, not yet signed bundles with an index.
No code signingThe programs are not code-signed in the alpha and beta. Windows Smart App Control can block them. On macOS, a copy downloaded with a web browser is quarantined; the installer downloads with curl, which does not quarantine it, so use the install command.
Agentscube and its git hooks work with any agent that runs shell commands. The kits' agent guidance (skills, helper agents, slash commands) uses Claude Code's .claude/ layout for now; other agents get the checks and the hooks but may not load that guidance on their own.
PythonThe kit's checks need Python 3 with PyYAML.
Not yetcube setup mergiraf, the AGENTS.md target of cube skill render, and acknowledging agent acts in cube inbox.

Index

The Cube 0.1.0. Proprietary, free to use; the starter kit and the architecture pack are MIT-0. Every download carries its licence and notices. Licence and noticesNo cookies, no analytics, nothing loaded from third parties; The Cube collects no usage data. Privacy · Report a problem

Made by Happonomy

Your knowledge base, checked like code.

Install

Start from the starter kit

A commit that adds an error does not get in.

Every reference is a checked link.

The state of the work, on one contents page.

Install it, and check what you installed.

The signed manifest

GitHub's release record

The SHA-256 of the download

What this alpha does not do yet.