# AI-Bonded Systems: the Kinra Conventions

> The essay that names the map: how a portfolio of AI-bonded systems stays legible, bounded, and honestly checked across dozens of independent repositories.

**Type:** Essay

The first thing an AI peer reads in a new repository usually isn't the code. It's the file names — `README.md`, `package.json`, `src/`, `tests/` — the shape a project takes before anyone has explained what it does. Multiply that repository by dozens, spread across a working portfolio of AI-bonded systems — environments that get more particular, more reliable, and more useful through sustained use rather than staying fixed once built — and the shape of each one stops being a private style choice. It's the first thing every fresh peer has to re-learn, in every one of them, every session.

Kinra keeps a small set of conventions to make that re-learning cheap. Not a framework, not a validator, not a claim that this is the only way a portfolio could work — a short document of defaults, corrected in the open whenever use shows something better. What follows is what those defaults actually say, and why.

## The Prior You Get for Free

A model that has never seen your project has still seen a great many projects that put deployment notes in `README.md` and architectural reasoning in `docs/decisions/`. Call that fluency a prior: whatever your project's shape has in common with the shapes the model already knows, the model gets for free, without spending a token relearning it. Call your project's departures from that shape a tax — every private name, every invented catch-all file, every reinvented layout has to be explained fresh, by someone, before real work starts.

The conventions spend that tax deliberately. Use the ecosystem's own scaffolder where one exists — the tree its own toolchain generates — and reserve invented names for the handful of ideas that genuinely don't have one yet. This isn't an argument that convention beats invention in general. It's the narrower observation that a prior already paid for is cheaper than one paid for twice, in every one of dozens of repositories, every day.

## A Map, Not a Manual

An exhaustive manual and a trailhead sign solve different problems. The manual tries to tell you everything before you've asked a question; the sign tells you which trail, what to watch for near the ridge, and where the real guidebook lives if you need it. Most repository documentation gets written as a manual, because manuals feel thorough and thoroughness feels responsible. It's also the wrong artifact for a reader who reopens the work from zero every session and has to decide, in the first few hundred words, whether they're even looking at the right document.

So the map stays a map — commands and verification near the top, then the boundaries and landmines that aren't discoverable by reading the code, then a pointer to the README, the status file, or the policy document that actually owns the deeper truth, rather than a paraphrase of it. Copied prose moves back to whichever document owns it. Compact isn't a symptom of neglect here; it's the point. Two documents saying the same thing in different words is how one of them quietly starts being wrong.

## Say What You Own, Say What You Don't

A decision that only touches one project belongs entirely to that project. A decision to start something new, move ownership, or make a public commitment does not — and pretending otherwise is how authority quietly creeps past whoever was supposed to hold it. The proposal standard draws that line in writing rather than trusting everyone to feel where it is: a proposal decides whether something happens, where it lives, and under what authority — never how the accepted work gets designed or built, which stays with whoever ends up owning it. An accepted resolution authorizes exactly what it names and nothing implied around the edges. An AI peer working inside a repository's own guidance stays inside the boundary that guidance draws, and if a task seems to require stepping outside it, the honest move is to say so and stop, not to interpret generously on someone else's behalf.

## Truth Stays Where It's Made

Every fact worth knowing has exactly one place it's actually true, and a portfolio that scatters copies of that fact is really just scattering opportunities for the copies to disagree. A status file, a native ledger, a declared current state — these live in the repository whose work they describe, and every other document that needs the fact points at it instead of restating it. A root-level index can describe the shape of a portfolio; it cannot claim that a given repository's checks are passing today, because the only evidence for that claim lives where the checks actually ran. Ownership here isn't a courtesy. It's what keeps the number of places a stale claim could hide down at one.

## A Passing Check Is Not a Decision

A command that exits clean has proven something narrow and real: the thing it checked matched what it expected. It hasn't decided whether the outcome is good, whether the approach was right, or whether the work should land. Those are judgments, and folding them into an exit code is how a green result quietly starts standing in for review it never performed.

The conventions keep the two apart on purpose. Every active repository names the commands that prove its own outcomes, and those commands answer only for what they measure. What answers for whether the work is actually right is a separate act — a person reading the verification evidence, watching the thing behave, asking questions in conversation, checking the result against reality before calling anything decided. That's closer to how review runs here day to day: not by reading every changed line, but by treating a passing command as evidence, then holding the outcome against observed behavior before it counts as settled.

## Exceptions That Earn a Name

A repository that grew its own way of tracking truth before the wider standard existed faces an unflattering choice by default: conform, and lose whatever made the local method work — or keep the method and carry it forever as an apologetic footnote, re-explaining from scratch why this one place is different. Neither is honest about what actually happened, which is that someone solved a real problem before the standard caught up to it.

The better move is to name the pattern. A repository whose current truth is a typed projection read from an append-only trail — checked by a script that can only ever answer match, mismatch, or an honest unknown, never a silent pass — is running the same shape the Truth Machine's own kit already names in public: a typed current projection, checked by a governed read. Recognizing that shape as a portfolio pattern means a repository built on it isn't deviating from the standard; it's a governed instance of it. A repository that runs its own constitution, policy, and ratification lifecycle is recognized the same way, under its own name. Once a pattern is named, a repository's stated deviation cites it instead of re-describing a bespoke exception — the difference between an apology and a citation.

## A Fact About One Day

On 2026-08-16, every repository in this portfolio — twenty-seven of them — was brought under these conventions in a single day: declared on the axes above, generic catch-all documents folded into named owners, a handful of bootstrapped local conventions reconciled into recognized patterns instead of left standing as unexplained exceptions, every change landed behind that repository's own named verification. The operator directed and reviewed the work through conversation and observed behavior, largely without reading the changes line by line.

That's a fact about one day in one portfolio, not a proof about every project or every team that might try something like it. These are portfolio defaults, arrived at by using them and corrected wherever use showed a cheaper or more reliable practice — not a claim that this harness, this workflow, or working this way at all is the universally superior one. The conventions stay open to being wrong in exactly the way any one of the twenty-seven repositories is: checked, not assumed.

---

> **A convention earns its keep the same way a repository does — not by being invented well, but by being checked against real use and corrected the moment use shows something better.**