@pome-sh/checks 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @pome-sh/checks
 
+## 0.4.2 — 2026-09-15
+
+Version-only release: publish-relevant paths changed and no `## Unreleased`
+entry was supplied, so this heading is the whole record. `@pome-sh/checks`'s bytes
+moved under `packages/checks/`.
+
+- 0cc9708 Simplify user-facing documentation (#537)
+
 ## 0.4.1 — 2026-09-01
 
 Doc-only: a build-config comment no longer references the removed

package/README.md

@@ -1,88 +1,57 @@
 # `@pome-sh/checks`
 
-The grading vocabulary of Pome's five digital twins: the **check declarations**,
-the **seed schemas** and the **default seeds**, plus the **check DSL** they are
-written in.
+`@pome-sh/checks` contains the check declarations and seed contracts for Pome digital twins. It also exports the check DSL.
 
-Declarations only. No twin server, no database, no HTTP routes, no tool
-dispatch. If you want to *run* a twin, install
-[`@pome-sh/cli`](https://www.npmjs.com/package/@pome-sh/cli) (`npx @pome-sh/cli
-twin start github`) or pull the twin's container image — this package cannot
-start one and does not try to.
+This package does not contain a twin server, database, HTTP route, or MCP dispatcher. Use [`@pome-sh/cli`](https://www.npmjs.com/package/@pome-sh/cli) to run a twin.
+
+## Install
 
 ```bash
 npm install @pome-sh/checks zod
 ```
 
-`zod` is a **peer dependency**, and installing your own copy is the point: the
-seed schemas are zod values, and two copies of zod in one process means two
-schema identities — `instanceof` fails and parsed results stop being
-interchangeable. One zod, one identity.
-
-## What it is for
-
-A Pome task scores an agent with criteria. A `[code]` criterion is graded by a
-**check**: a declared, templated assertion over the twin's final state, its seed
-compared against its final state, or the recorded tape of tool calls. This
-package is where those declarations live, so the thing that grades a run and the
-twin that produced it agree on the vocabulary rather than each keeping its own
-copy of it.
+Node.js 24 or later is required. `zod` is a peer dependency and is not bundled.
 
 ## Use
 
-Everything under one specifier, with the seed helpers prefixed by twin:
+Import all twin declarations from the package root:
 
 ```ts
 import { GITHUB_CHECKS, TWIN_CHECKS, parseGitHubSeed, renderCheck } from "@pome-sh/checks";
 
-const check = GITHUB_CHECKS.find((c) => c.id === "github.issue-closed");
+const check = GITHUB_CHECKS.find((candidate) => candidate.id === "github.issue-state");
 ```
 
-Or one twin at a time, keeping that twin's own names:
+Import one twin through its subpath when you need its unprefixed seed exports:
 
 ```ts
 import { GITHUB_CHECKS, parseSeed, seedSchema } from "@pome-sh/checks/github";
 ```
 
-Subpaths: `./github`, `./slack`, `./stripe`, `./gmail`, `./linear`, and `./dsl`
-for the DSL alone.
+Available subpaths are `./github`, `./gmail`, `./linear`, `./slack`, `./stripe`, and `./dsl`.
 
-| Export | What |
+## Main exports
+
+| Export | Purpose |
 | --- | --- |
-| `GITHUB_CHECKS`, `SLACK_CHECKS`, `STRIPE_CHECKS`, `GMAIL_CHECKS`, `LINEAR_CHECKS` | Each twin's declarations, in authoring order |
-| `TWIN_CHECKS` | The five arrays keyed by twin id |
-| `CHECKS_TWIN_NAMES`, `ChecksTwinName` | The five twin ids, and the type derived from them |
-| `parse<Twin>Seed`, `<twin>SeedSchema`, `default<Twin>Seed` | Seed contract per twin |
-| `defineCheck`, `parseCheck`, `renderCheck`, `checkPattern`, `checksDigest`, `templateSlots`, `statePath`, `childStatePath` | The DSL |
-| `GitHubCheck`, `GmailCheck`, `LinearCheck`, `SlackCheck`, `StripeCheck` | Each twin's check element type. Every twin declares its own `Check<TArgs>` over its own state, so the barrel prefixes them; the per-twin subpaths keep the plain name `Check` |
-| `CheckDefinition`, `Check…State` types | The generic declaration type, and each twin's state shape — what you want when the twin is a parameter rather than known |
-| `VACUITY_SENTINEL`, `VACUITY_SENTINEL_NUMBER`, `VACUITY_SENTINEL_SNAKE` | The values that mark an assertion no state can satisfy |
-
-`applySeed` and `loadSeedFromEnv` are **not** exported. The first writes rows
-into a live SQLite database and the second reads `process.env`; both are twin
-runtime behaviour, not declarations.
-
-## Versioning
-
-Pre-1.0, so `^0.x` caret semantics apply and **minor plays the major role**:
-
-- **Minor (`0.N+1.0`)** — anything a consumer must act on: a check id renamed or
-  removed, a template changed, a polarity flipped, a seed schema tightened, an
-  `engines` floor bump.
-- **Patch (`0.N.x`)** — additive checks or exports, wording that does not change
-  a pattern, internal implementation swaps behind an unchanged surface.
-
-A grading vocabulary is a contract in a stricter sense than a normal library: a
-renamed check id does not break a build, it silently stops binding, and a
-criterion that stops binding scores nothing. Treat every id as public.
-
-## Where the source lives
-
-Nowhere in this package. Every declaration is re-exported from the twin that
-owns it (`packages/twin-*/src/check-*.ts`) and the DSL from
-`packages/sdk/src/checks.ts`, all in
-[pome-sh/digital-twins](https://github.com/pome-sh/digital-twins). Their
-compiled output is inlined here at build time, so this package declares no
-`@pome-sh/*` dependency and there is no second copy to drift.
-
-Licence: Apache-2.0.
+| `GITHUB_CHECKS`, `GMAIL_CHECKS`, `LINEAR_CHECKS`, `SLACK_CHECKS`, `STRIPE_CHECKS` | Check declarations for each twin |
+| `TWIN_CHECKS` | Check arrays keyed by twin ID |
+| `CHECKS_TWIN_NAMES`, `ChecksTwinName` | Supported twin IDs and their type |
+| `parse<Twin>Seed`, `<twin>SeedSchema`, `default<Twin>Seed` | Prefixed seed exports |
+| `defineCheck`, `parseCheck`, `renderCheck`, `checkPattern`, `checksDigest` | Core check DSL |
+| `statePath`, `childStatePath`, `templateSlots` | DSL helpers |
+| `GitHubCheck`, `GmailCheck`, `LinearCheck`, `SlackCheck`, `StripeCheck` | Twin-specific check types |
+| `CheckDefinition`, `Check...State` | Generic check and state types |
+| `VACUITY_SENTINEL`, `VACUITY_SENTINEL_NUMBER`, `VACUITY_SENTINEL_SNAKE` | Values that no state can satisfy |
+
+`applySeed` and `loadSeedFromEnv` are not exported. They modify runtime state or read process configuration.
+
+## Source and packaging
+
+The source declarations remain with their owning twins in `packages/twin-*/src/check*.ts`. The DSL source is in [`packages/sdk/src/checks.ts`](../sdk/src/checks.ts).
+
+The build bundles those declarations into this package. The published manifest has no runtime `@pome-sh/*` dependencies.
+
+Check IDs are public contract values. A renamed ID can stop a criterion from binding without a type error.
+
+License: Apache-2.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pome-sh/checks",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Pome's grading vocabulary — the check declarations, seed schemas and default seeds of all five digital twins, plus the check DSL they are written in. Declarations only: no twin server, no database, no routes, no tools.",
   "private": false,
   "type": "module",