create-geonosis

A repo that passes its own gates on day one.

npm create geonosis@latest pinecone -- \
  --runtime pnpm --backend medusa --ui atoms-only --brand Pinecone

There is no default for --runtime, --backend or --ui. Each decides the shape of the tree, and a default borrowed from another repo would be that repo's stack hardcoded into this one.

| Flag | Choices | |---|---| | --runtime | pnpm · bun | | --backend | medusa · sagaflow-cf · none | | --ui | tiered-shadcn · atoms-only · none | | --domains <a,b> | the domains the app composes, written into its src/platform.ts | | --medusa <range> | the Medusa a --backend medusa tree declares | | --brand <name> | turns on no-brand-names for that word | | --themekit <name> | consumes a themekit by version, never by copying it | | --marketplace <path> | install the plugin from a local marketplace instead of GitHub | | --kit <path> | read the kit from a workspace instead of the registry — a proof aid | | --no-install | write the files and stop | | --check | say what an existing repo lacks of what the scaffold writes today; write nothing | | --plan | what adopting an existing repo would take, computed off its tree; write nothing |

What it writes

• One catalog of shared versions — pnpm-workspace.yaml on pnpm, workspaces.catalog on bun. A repo whose workspaces each pin their own typescript is a repo where one of them typechecks against a compiler the others do not run.
• An exports map and no barrel in every workspace.
• typecheck + lint + test in EVERY workspace — Midday has several without, and turbo silently skips those. Each test asks vitest for its own JSON report, because a runner's exit code is not a verdict.
• docs/architecture.md, and the edges table is the one place the graph is written. geonosis-ledger sync generates turbo's boundaries.tags AND the linter's layer-walls layers from it, so a tag added there reaches both gates and neither can drift from the other. The scaffold runs both splices for you.
• LAW.md under 60 lines, with CLAUDE.md the one line that imports it, plus a docs/pipelines/ page template.
• The five config files: geonosis.json (verify tiers, ledger, walk, testbed, doctor), .oxlintrc.json with the presets the answers imply, geonosis.ratchet.json, gate-baseline.json, .oxfmtrc.json.
• lefthook.yml (staged oxfmt + oxlint), .github/workflows/ci.yml with nothing switched off in it, skills-lock.json empty, .claude/settings.json installing the kit's plugin.
• lint-corpus/ — see below.

The baseline, and the one number that is not zero

Every counter starts at 0: a new repo has earned no debt. lawLineCount starts at the measured length of the LAW.md that was just written, because it counts something that already exists and a 0 there would fail the first ratchet run over a clean tree.

lint-corpus/ — the reach corpus a shipped one cannot be

geonosis-doctor asks whether every enabled rule can fire at all, against the corpus the plugin ships. That cannot answer for a rule whose reach is the repo's own vocabulary — its layer names, its brand, its plugin package root, the within its sagas live in — and the plugin's corpus says acme and layers/core. So the scaffold writes a small corpus in this repo's vocabulary, with a manifest.json naming exactly the rules it is evidence about.

It is deliberately broken code, so it is excluded from the repo's own lint, format and typecheck — the same treatment the plugin gives its own fixtures. The corpus run copies it to a temp root and lints with --no-ignore, so nothing is hidden from the check it exists for.

--kit <path>

A proof aid. It symlinks the kit's packages into node_modules after the install and rewrites the manifest to declare them as link: — which is a declaration geonosis-doctor accepts and can verify. It is done by hand because neither package manager can do it: pnpm resolves link: happily, and bun refuses both link: and file: here, because it follows into the target and tries to resolve the workspace:* specifiers the kit's own packages use.

--check — what an existing repo never received

npx create-geonosis . --check --runtime pnpm --backend medusa --ui tiered-shadcn

A repo is scaffolded once and the scaffold keeps learning, so the divergence is permanent and one-way. --check closes the loop in the only direction that is safe: it says what is missing and writes nothing — no file created, no file opened for writing, no writeScaffold on the path at all. Exit 0 when nothing drifted, 1 with a line per drift.

Two things are compared and two are deliberately not:

• a file the scaffold writes that the repo has never had — drift;
• a key inside a JSON file the repo does have — drift, named as file → a.b.c;
• a file's contents — never. A repo that has been worked in has rewritten them and was entitled to;
• a value — never. doctor.corpus pointing somewhere else is that repo's answer, not a drift.

The workspaces are out of the question. packages/core/src/money.ts is a sample that makes a new repo compile, not a shape a repo must hold. Measured over a consumer: including them turned 24 real findings into 52, thirty of them about a sample workspace that repo does not have.

Over a repo scaffolded before D-054 moved the law it reads LAW.md, geonosis.json → law.file and the rest of what the scaffold has learned since; proofs/024-W31a-create-check/ has a whole run and the before/after hash.

A JSON file the repo has that is not plain JSON — a tsconfig.json with // comments, legal JSONC — is reported rather than skipped. A check that could not read a file has not passed over it.

Proven, not claimed

A repo scaffolded on both runtimes passes its own geonosis-verify full in a temp directory — see proofs/022-W10-scaffold/.