site: a first user hit a throwing stub, a source tree, and three wrong numbers

Four things, all found by walking the pages as a first-time reader.

**Getting started stalled at step 6.** The page went from `meta gen` straight to
"import the generated code and listen on 3000" — but `meta init` scaffolds
`src/db.ts` as a THROWING stub (it will not choose between better-sqlite3,
@libsql/client, pg and postgres.js on your behalf), so following the page start
to finish gives you a server that throws on the first request. There is now a
step 6, "Wire your database", between Generate and Use; the old 6 and 7 shift to
7 and 8. Its driver example is lifted from `DB_STUB_BODY` in the CLI's
`init.ts` rather than written from memory, as this repo's AGENTS.md requires.

**And it never said to install.** `meta init` DECLARES the packages the
scaffolded generators and the generated code import — into devDependencies and
dependencies — and then deliberately runs no package manager; its own warning
says "Run your package manager's install before `meta gen`", twice. The page
never repeated that, so the first `meta gen` reports TS2307 on files that are
perfectly correct. `npm install` is now the third line of step 1.

**The quickstart cards pointed at GitHub directory listings** — five languages,
five file trees to read past. Each now points at that port's guide under
`docs/ports/`, which opens Install → Configure → Generate → Use. The two client
cards land on `typescript-client.md` at their own anchors. All six verified 200.

**Three counts were wrong**, and the scaffold tree contradicted itself: it
announced "seven skills" directly above a list of six. Six is right —
`metaobjects-fit-assessment` carries `scaffold: false` because it is a
PRE-adoption tool. Corpus fixtures 253 → 313 and corpora 19 → 21 (both measured
upstream, see metaobjects 5f20e905d); base types 13 → 14, counted from
`expected-registry.json`.

Also: `requirements.html` opened with the sentence the homepage section linking
to it had just delivered, near-verbatim — "the columns are there, the types line
up, the tests pass — and no code path ever writes the value." Clicking "How
capability requirements work →" landed you on what you had just read. It now
opens a beat later, on why a test suite structurally cannot catch this: a test
exercises code that exists, so the absence has no address. (`story.html` was
checked for the same defect and does NOT have it — it shares the homepage's
heading, which is the link's promise, but its first paragraph is a different
beat. Left alone.)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NTcEKXTQMYt84fAjuw5A2M

Author: claude

www/getting-started.html

@@ -76,7 +76,13 @@ <h2 class="section-label">1 · Install &amp; scaffold</h2>
           <h3>Set up the project and the agent context</h3>
           <p>Add the TypeScript CLI and scaffold the workspace. <code>meta init</code> also teaches your coding agent how to use MetaObjects:</p>
           <pre class="gs-code">npm i <span class="s">@metaobjectsdev/cli</span>
-npx meta init</pre>
+npx meta init
+npm install   <span class="c"># init DECLARES what it scaffolds against; it does not install</span></pre>
+          <p class="gs-note">That third line is not optional. <code>meta init</code> adds the packages the
+            scaffolded generators and the generated code import — to <code>devDependencies</code> and
+            <code>dependencies</code> — but it deliberately never runs your package manager. Skip it and
+            <code>meta gen</code> and <code>npx tsc</code> both report <code>TS2307</code> on files that are
+            perfectly correct.</p>
           <p>That writes a small, legible tree — <strong>your models go in <code>metaobjects/</code></strong>,
             and the code generators land in your repo too:</p>
           <pre class="gs-code"><span class="c">your-project/</span>
@@ -92,7 +98,7 @@ <h3>Set up the project and the agent context</h3>
 ├── src/db.ts                    <span class="c"># throwing stub — swap in your DB connection</span>
 ├── CLAUDE.md                    <span class="c"># wired to auto-load the context below</span>
 ├── .metaobjects/                <span class="c"># tool state + agent docs (AGENTS.md, CLAUDE.md)</span>
-└── .claude/skills/              <span class="c"># seven skills your agent now has:</span>
+└── .claude/skills/              <span class="c"># six skills your agent now has:</span>
     ├── metaobjects-authoring/   <span class="c">#   write &amp; edit models</span>
     ├── metaobjects-codegen/     <span class="c">#   run codegen</span>
     ├── metaobjects-runtime-ui/  <span class="c">#   wire up runtime + UI</span>
@@ -239,7 +245,29 @@ <h2 class="section-label">5 · Generate</h2>
     </section>
 
     <section>
-      <h2 class="section-label">6 · Use it — and add your own logic</h2>
+      <h2 class="section-label">6 · Wire your database</h2>
+      <p class="gs-note"><code>meta init</code> scaffolded <code>src/db.ts</code> as a <strong>throwing
+        stub</strong>, on purpose: the generated routes have to import a <code>db</code> from somewhere for
+        <code>meta gen</code> and your first <code>tsc</code> to succeed, and MetaObjects will not pick a driver
+        for you — <code>better-sqlite3</code>, <code>@libsql/client</code>, <code>pg</code> and
+        <code>postgres.js</code> are your call, not a dependency it adds behind your back. It type-checks
+        everywhere and throws the first time anything actually touches it, with instructions. Replace it:</p>
+      <pre class="gs-code">$ npm i <span class="s">better-sqlite3</span>
+
+<span class="c">// src/db.ts — replace the scaffolded stub</span>
+import { drizzle } from <span class="s">"drizzle-orm/better-sqlite3"</span>;
+import Database from <span class="s">"better-sqlite3"</span>;
+
+export const db = drizzle(new Database(<span class="s">"dev.sqlite"</span>));</pre>
+      <p class="gs-note">Swap the driver import for your dialect. For libsql, Cloudflare D1, Postgres and
+        multi-tenant setups, see
+        <a href="https://github.com/metaobjectsdev/metaobjects/blob/main/docs/recipes/wiring-generated-queries.md">wiring
+        generated queries</a>. Create the tables themselves with
+        <code>meta migrate --from-db --db file:dev.sqlite --dialect sqlite --slug init --apply</code>.</p>
+    </section>
+
+    <section>
+      <h2 class="section-label">7 · Use it — and add your own logic</h2>
       <p class="gs-note">Import the generated code into your app. <strong>It runs with no MetaObjects dependency</strong> —
         Drizzle, Zod, and Fastify only:</p>
       <pre class="gs-code">import Fastify from <span class="s">"fastify"</span>;
@@ -255,7 +283,7 @@ <h2 class="section-label">6 · Use it — and add your own logic</h2>
     </section>
 
     <section>
-      <h2 class="section-label">7 · Keep it honest</h2>
+      <h2 class="section-label">8 · Keep it honest</h2>
       <p class="gs-note">As the model evolves, <code>meta verify</code> fails the build the moment generated code,
         schema, or prompt templates drift from it:</p>
       <pre class="gs-code">npx meta verify              <span class="c"># --templates (default): prompt-template drift</span>

www/index.html

@@ -294,7 +294,7 @@ <h2 class="section-label">Five ports. All installable today.</h2>
         </tbody>
       </table>
       <p class="impl-note">
-        Nineteen shared conformance corpora at <a href="https://github.com/metaobjectsdev/metaobjects/tree/main/fixtures"><code>fixtures/</code></a> — metamodel (253 fixtures), render, verify, extract, persistence (24 query scenarios against Testcontainers Postgres), API contract (cross-port, reference <em>and</em> generated lanes), YAML and more — validate every implementation against the same expectations. All ports implement <code>metamodelVersion</code> <code data-registry="metamodel">0.13</code> — the metadata contract, versioned separately from the package lines.
+        Twenty-one shared conformance corpora at <a href="https://github.com/metaobjectsdev/metaobjects/tree/main/fixtures"><code>fixtures/</code></a> — metamodel (313 fixtures), render, verify, extract, persistence (24 query scenarios against Testcontainers Postgres), API contract (cross-port, reference <em>and</em> generated lanes), YAML and more — validate every implementation against the same expectations. All ports implement <code>metamodelVersion</code> <code data-registry="metamodel">0.13</code> — the metadata contract, versioned separately from the package lines.
       </p>
     </section>
 
@@ -440,7 +440,7 @@ <h3 class="compare-subhead">Capability matrix — including AI-agent suitability
           <tr class="ai-row"><td>Machine-readable metadata (grep-friendly)</td> <td class="yes">YAML/JSON, named constants</td> <td class="partial">DSL or schema.prisma</td> <td class="no">annotations / decorators</td> <td class="yes">YAML/JSON</td></tr>
           <tr class="ai-row"><td>Generated code is plain (no proxy/decorator magic)</td> <td class="yes">idiomatic native</td> <td class="yes">idiomatic</td>         <td class="no">proxy/runtime magic</td><td class="yes">type stubs</td></tr>
           <tr class="ai-row"><td>Deterministic regen (same in → same out)</td> <td class="yes">conformance-gated</td><td class="yes">yes</td>                <td class="yes">yes</td>              <td class="yes">yes</td></tr>
-          <tr class="ai-row"><td>Small surface area for agent context window</td><td class="yes">13 base types + extensions</td> <td class="partial">single-lang ORM API</td> <td class="no">large framework surface</td><td class="yes">small spec</td></tr>
+          <tr class="ai-row"><td>Small surface area for agent context window</td><td class="yes">14 base types + extensions</td> <td class="partial">single-lang ORM API</td> <td class="no">large framework surface</td><td class="yes">small spec</td></tr>
         </tbody>
       </table>
 
@@ -474,23 +474,23 @@ <h2 class="section-label">Quickstart</h2>
       <div class="qs-group">
         <h3 class="qs-group-title">Server-side</h3>
         <div class="quickstart-grid">
-          <a href="https://github.com/metaobjectsdev/metaobjects/tree/main/server/typescript" class="quickstart-card">
+          <a href="https://github.com/metaobjectsdev/metaobjects/blob/main/docs/ports/typescript.md" class="quickstart-card">
             <span class="qs-lang">TypeScript</span>
             <span class="qs-arrow">→</span>
           </a>
-          <a href="https://github.com/metaobjectsdev/metaobjects/tree/main/server/java" class="quickstart-card">
+          <a href="https://github.com/metaobjectsdev/metaobjects/blob/main/docs/ports/java.md" class="quickstart-card">
             <span class="qs-lang">Java</span>
             <span class="qs-arrow">→</span>
           </a>
-          <a href="https://github.com/metaobjectsdev/metaobjects/tree/main/server/java/codegen-kotlin" class="quickstart-card">
+          <a href="https://github.com/metaobjectsdev/metaobjects/blob/main/docs/ports/kotlin.md" class="quickstart-card">
             <span class="qs-lang">Kotlin</span>
             <span class="qs-arrow">→</span>
           </a>
-          <a href="https://github.com/metaobjectsdev/metaobjects/tree/main/server/csharp" class="quickstart-card">
+          <a href="https://github.com/metaobjectsdev/metaobjects/blob/main/docs/ports/csharp.md" class="quickstart-card">
             <span class="qs-lang">C#.NET</span>
             <span class="qs-arrow">→</span>
           </a>
-          <a href="https://github.com/metaobjectsdev/metaobjects/tree/main/server/python" class="quickstart-card">
+          <a href="https://github.com/metaobjectsdev/metaobjects/blob/main/docs/ports/python.md" class="quickstart-card">
             <span class="qs-lang">Python</span>
             <span class="qs-arrow">→</span>
           </a>
@@ -500,11 +500,11 @@ <h3 class="qs-group-title">Server-side</h3>
       <div class="qs-group">
         <h3 class="qs-group-title">Client-side</h3>
         <div class="quickstart-grid quickstart-grid--client">
-          <a href="https://github.com/metaobjectsdev/metaobjects/tree/main/client/web/packages/runtime-web" class="quickstart-card">
+          <a href="https://github.com/metaobjectsdev/metaobjects/blob/main/docs/ports/typescript-client.md#browser-runtime-packages" class="quickstart-card">
             <span class="qs-lang">Runtime Web</span>
             <span class="qs-arrow">→</span>
           </a>
-          <a href="https://github.com/metaobjectsdev/metaobjects/tree/main/client/web/packages/react" class="quickstart-card">
+          <a href="https://github.com/metaobjectsdev/metaobjects/blob/main/docs/ports/typescript-client.md#generated-react-forms" class="quickstart-card">
             <span class="qs-lang">React</span>
             <span class="qs-arrow">→</span>
           </a>

www/requirements.html

@@ -100,10 +100,13 @@
       <p class="page-eyebrow">Capability requirements · ships in all five language ports</p>
       <h1>Check what your AI actually built.</h1>
       <p class="page-lede">
-        Your agent reports the feature done. The columns are there, the types line up, the tests
-        pass — and no code path ever writes the value. Nothing is broken, so nothing fails.
-        MetaObjects makes a capability a node in your model, so the distance between what your
-        software <em>claims</em> to do and what it does becomes something a build can check.
+        A test exercises code that exists. That is the whole reason a passing suite can sit on
+        top of a feature nobody finished: there is no test that fails because a column nobody
+        writes was never wired to anything, and no linter that flags the handler you meant to
+        add. The absence has no address — so give it one. A capability declared in MetaObjects
+        is a node in the same model as your entities, and its link to the code is
+        <strong>resolved, not trusted</strong>: name something that isn't there and the build
+        stops.
       </p>
 
       <h2>The failure that comes after drift</h2>