The naming was wrong
harness.os has had three layers since early on. Methodology — the universal theory. Configuration — one person’s specific setup. Mesh — the runtime connections between harness instances.
These names caused a problem I kept running into: what IS harness.os?
Is it the methodology? Is it my configuration? Is marco.ai the configuration? Or is marco.ai a mesh? And if harness.os is the methodology, why does the website URL say harness.os — is .os the methodology or the operating system?
The names were technically accurate but they didn’t carry enough meaning. “Configuration” sounds like a settings file. “Methodology” sounds like a PDF someone emails you. Neither conveys the relationship between the layers — that one is universal and the other is personal, that one defines the rules and the other applies them.
The confusion that triggered the rename
I was trying to explain to myself what marco.ai is. It’s an app — a personal assistant mesh. But it’s not my configuration. My configuration is bigger than any single app. My configuration declares all 13 subtypes, all products, all rules. marco.ai is just one mesh running inside that configuration.
But the word “configuration” kept pulling me toward thinking it was one thing — a single file, a single app. Something you cat and read. Not a complete system that multiple apps run inside of.
I tried other names: model (conflicts with LLM model), schema (sounds like a database), spec (overused), blueprint (too visual), manifest (too Kubernetes). Nothing stuck.
Then I noticed something. My configurations feel like operating systems. They’re opinionated. They’re complete. They’re shareable. You can fork one and make your own. And the apps running inside them are like processes running inside an OS.
That’s when the analogy clicked.
The Linux analogy
Linux has three layers that map cleanly to what harness.os does:
| Linux | harness.os | What it does |
|---|---|---|
| Kernel | harness.os | Universal primitives. Process management, memory, I/O, security. In harness.os: 4 types, 5 concerns, boundaries, inheritance, surfaces. Nobody runs the kernel directly. |
| Distribution | marco.os | Kernel + specific choices. Ubuntu picks apt, GNOME, systemd. marco.os picks subtypes, surfaces, rules, products. Opinionated. Shareable. Forkable. |
| Processes | Meshes | Running instances. Apache, Postgres, cron jobs. In harness.os: build.ai, cortex.ai, way2do. Without processes running, the distro is just a spec file. |
harness.os IS the kernel. It defines the universal system — four types, five concerns, inner/outer boundary, subtype inheritance. Nobody runs the kernel directly. You run a distribution. And inside the distribution, you run meshes.
This analogy solved every confusion I had:
- Is harness.os the methodology? It’s the kernel. The methodology is a way of describing what the kernel does.
- Is marco.ai my configuration? No.
marco.osis my distribution.marco.aiis one mesh (the personal assistant) running inside it. - Can someone else use this? Fork my distribution, change the subtypes and rules, create
acme.os. Same kernel, different distro. - What’s the .os suffix? It works at both levels.
harness.osis the kernel project.marco.osis a distribution built on that kernel.
Why “distribution” carries the right weight
“Configuration” was the wrong word because it implies something small and passive — a config file, a settings page. But what I’m actually building for myself is a complete operating environment. It declares 13 subtypes across four base types. It defines which surface each subtype uses. It sets the rules for governance, security, knowledge routing. It specifies all products and how they connect.
A Linux distribution does the same thing. Ubuntu isn’t “Linux configuration.” Ubuntu is a complete, opinionated system built on the Linux kernel. It makes choices that the kernel doesn’t make. It’s bigger than any one application running on it.
Distributions are portable and forkable. Someone can fork marco.os, swap out the subtypes, change the rules, rename it petcare.os, and run it on the same kernel. The universal primitives stay the same. The specific choices change.
The .ai suffix is for apps and products — marco.ai, build.ai, cortex.ai, way2fly. These are things that run. The .os suffix is for the operating system layer — the kernel and the distributions. This distinction turned out to be important: it prevents the confusion between “the system I built for organizing knowledge” and “the app that uses that knowledge.”
What this changes in practice
On the website
Every page now uses the new names. The methodology docs are now the kernel docs. The configuration docs are now marco.os. The showcase walks through kernel → distribution → mesh. The layer diagram in the hero section maps to Linux primitives that most engineers already understand.
In the documentation
The principle that was “Methodology is universal. Configuration is personal.” became “The kernel is universal. The distribution is personal.” Same idea, but the Linux framing makes the relationship immediately obvious. You don’t need to explain what a kernel vs. a distribution is to a software engineer — they already know.
In the refactor plan
The planned code restructure (renaming tables, splitting modules, reorganizing folders) now has clearer direction. The core/ directory maps to kernel primitives. The product/, build/, operations/, domain/ directories map to distribution-level specializations. The mesh/ directory maps to runtime connectivity. The mapping from theory to code was already planned — but the naming makes the mapping self-documenting.
Good names reduce the gap between theory and code. When your directories are named after concepts that engineers already understand, the architecture explains itself. You don’t need a diagram to understand that core/knowledge.py is a kernel primitive and product/sessions.py is a distribution concern.
The naming test
A good name passes three tests:
- Identity: Does it tell you what the thing IS? “Kernel” immediately says “foundational, universal, you build on top of it.” “Methodology” says “a document someone wrote.”
- Relationship: Does it tell you how layers relate? Everyone knows a distribution is built on a kernel and that processes run inside a distribution. You don’t need to explain the dependency chain.
- Portability: Does it suggest the right operations? Distributions are forked, shared, templated, versioned. Configurations are... edited. The word “distribution” carries the right verbs.
The old names passed test 1 weakly and failed tests 2 and 3. The new names pass all three. That’s the entire reason for the change — not aesthetics, but clarity.
What stays the same
The theory hasn’t changed. Four harness types. Five cross-cutting concerns. Inner/outer boundary. Subtype inheritance. Multiple surfaces. Everything that was true yesterday is still true today.
What changed is how you talk about it. And in a methodology — where the deliverable is a way of thinking, not a binary — how you talk about it is a bigger deal than it sounds.
I don’t know if kernel/distribution/mesh passes that bar for everyone. But for anyone who’s installed a Linux distro, configured a package manager, or run a process in a container — the mental model is already there. harness.os just maps to it.