@flashyos/mesh

One checklist for joining the mesh. What this repository has adopted, what is left, and the exact command for each.

npx @flashyos/mesh status

  your-repo on the mesh

    ✓ charter          Say what your organisation does, and who is accountable for each part
    ✓ charter-served   Serve the charter where a checker actually looks
    ✓ handshake        Publish the machine door — one URL an agent can find you at
    · capabilities     Tell the network what you can do, and what you want from it
    ✓ shipped          Seal a record of what you shipped, derived from your own history
    ✓ backlog          File what you intend to do, private until a named human publishes it
    · delivery         Track the rungs between a merged commit and a thing somebody has
    ✓ directory        Emit the record of what you are, and what surfaces you serve
    ✓ checkpoint       Publish a tree head over everything you have sealed
    ✓ frontdoor        Open the human door — the page a person clicks, not just the JSON

    8 of 10 done

  2 things left. In this order:
    ...

Exits non-zero while anything that applies is outstanding, so it works as a gate as well as a report.

Why this exists

Adopting these formats meant finding and sequencing eighteen commands across nine packages. Every one of them is documented and every one works; the order and the completeness lived in nobody's head but ours.

docs/onboarding.md specified this command in August and documented it as though it existed. It did not — which is the failure this estate keeps meeting, pointed at its own front door: a mechanism correct in every part and unusable as a whole.

What it does not do

It does not adopt anything. Every step names the command that does, and those live in their own packages where they are tested and vendored. A second implementation in here is how two copies of one rule start disagreeing, which this estate has paid for enough times to have a house rule about it.

What was missing was never the doing. It was knowing what to do, in what order, and when you are finished.

The three verdicts

✓ done · · missing · — does not apply

The third one matters most. A published library with no website cannot serve a front door, and grading it for lacking one is how this estate's own survey once measured an npm package as a property with a missing door. A step that does not apply is reported with its reason and kept out of the denominator, because a score that punishes a repository for its shape is a score people learn to ignore.

Two steps can never be settled from a checkout:

• capabilities lives on the network, not on disk.
• anything served is checked here as committed, which is not the same as served. This estate has learned that twice.

So the report never says you are finished. It says what it could see.

Route handlers count

src/app/.well-known/flashyos.json is a directory containing route.ts in every Next property here. Checking for a file at that path reported six properties as having no machine door while they had served one for weeks — the same mistake, twice written down, that first measured the handshake at 20%.

servedAt accepts a committed file or a route handler. flashy-network read 6 of 10 before that fix and 8 of 10 after, and the difference was entirely route handlers.

Four times wrong about where a surface lives

Every bug this package has had is one bug: an assumption about where a repository keeps a thing. Each passed the whole suite, because the fixtures were written by whoever wrote the rule. All four were found by a differential against the estate's own adoption gate, run over the same trees.

| | The assumption | What it missed | |---|---|---| | 1 | A surface is a file | A Next route handler is a directory containing route.ts. flashy-network read 6 of 10; it is 8 | | 2 | Surfaces sit at the repository root | flashyos serves three from apps/marketing — the repository that publishes the standard, graded by its own checklist as not holding it. 6 of 10; it is 9 | | 3 | Site directories are apps/ and sites/ | An allowlist is the shapes somebody thought of. flashyID serves from site/, flashy-labs from incubating/<project>/. Roots are derived from where a site framework actually sits | | 4 | .well-known has one spelling | Vercel does not reliably serve a dot-directory from a static deployment, so properties commit to public/well-known/ and rewrite. flashyID read 5 of 10; it is 8 |

A fifth, of a different kind: the not applicable verdict was computed before the evidence was read, so flashy-ledger — which serves a charter — was told it had nowhere to serve one. Evidence is read first now. A verdict that excuses a repository from something it has already done is worse than a wrong count; it tells somebody to stop looking.

tools/mesh-standards.test.mjs in flashyos is the differential, built like the two vendored-checker tests: both tools over one file list, failing on any disagreement about the verdict, never by comparing how a rule is spelled. The one direction that is always a defect is the gate seeing a surface the checklist cannot. Three record standards disagree deliberately — the gate reads the published fragment, the checklist reads the emitter config — and the test names each rather than reconciling them: a config with no fragment is a repository that has adopted and not yet emitted, and a fragment with no config is an orphan.

It reads a checkout, and a checkout is not a deploy

Everything here is measured from the working tree you run it in — not from the default branch, and not over the network. That is right for the job: an adopter standing in their own repository wants to know what they have. It is also the estate's most-repeated mistake when a number is quoted from it, so the report never claims a surface is served, only that it is committed.

npx @flashyos/conformance <domain> and node tools/estate-live.mjs are the other half, after a deploy.

Programmatic

import { scan, status, gaps, render, asJson } from '@flashyos/mesh';

const s = status(scan('/path/to/repo'));
console.log(render(s));
for (const gap of gaps(s)) console.log(gap.step.command);

status is pure — facts in, verdicts out — so it tests without a filesystem and runs against a checkout you do not trust. scan is the one part that touches disk, and it is separated precisely because both real bugs this package has had lived there: a route handler is a directory, and a monorepo keeps its site three levels down.

The steps, and why each is worth doing

Every step carries a why written for the adopter rather than for us, and a test asserts none is missing. A checklist that says only what produces compliance, and compliance produces the empty projections this estate has already measured: 63 backlog items filed with none published, 228 capabilities written down with one declared.

Apache-2.0. The spec and the clients are permissively licensed so anyone can embed them.