@ref0/sdk 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,376 @@
-# Temporary Holding Version
+# @ref0/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What a repo's `.ref0/` code imports to run on ref0, the Git platform for agents, and ref0's HTTP client.
+
+## Install
+
+```sh
+cd .ref0
+pnpm add @ref0/sdk zod@^4
+```
+
+Its types are built on Effect's, which need `"lib": ["ESNext"]` in `tsconfig.json`, or `skipLibCheck`. Checks' params and called workflows' inputs use zod 4.
+
+Each TypeScript block below is a whole file. The path on its first line is relative to the repo's root. Pip writes the files, and Mo is the person accountable for the thread in these examples.
+
+## 1. A gate reads what changed
+
+`.ref0/gate.ts` says what a change needs before it merges. Pip's gate reads the root `package.json` on both sides of the change and asks for `dependencies` only when a dependency changed.
+
+```ts
+// .ref0/gate.ts
+import { approval, gate, local, passkey, review } from '@ref0/sdk';
+import { z } from 'zod';
+import e2e from './checks/e2e';
+import unit from './checks/unit';
+
+const manifest = z.object({
+  dependencies: z.record(z.string(), z.string()).default({}),
+  devDependencies: z.record(z.string(), z.string()).default({}),
+  optionalDependencies: z.record(z.string(), z.string()).default({}),
+  peerDependencies: z.record(z.string(), z.string()).default({}),
+});
+
+export default gate(async ({ change }) => {
+  const [before, after] = await Promise.all([
+    change.before.readJSON({ path: 'package.json' }),
+    change.after.readJSON({ path: 'package.json' }),
+  ]);
+  const was = manifest.parse(before ?? {});
+  const next = manifest.parse(after ?? {});
+  const moved = Object.entries(was).some(([field, dependencies]) => {
+    const current = next[field as keyof typeof next];
+
+    return Object.keys({ ...dependencies, ...current }).some(
+      (name) => dependencies[name] !== current[name],
+    );
+  });
+
+  return [
+    review(),
+    moved && approval('dependencies'),
+    change.touches('src/billing/**') && approval('billing'),
+    !change.only('**/*.md') && [local(unit()), passkey.check(local(e2e()))],
+  ];
+});
+```
+
+The comparison catches added, removed and changed versions in the four dependency fields. A change to scripts alone asks no dependency approval. A repo with other manifests or install configuration needs to cover those files too.
+
+A gate returns needs. `review()` needs a review with no blocking finding, `approval('billing')` needs a holder of that permission, and `unit()` needs a successful run of that check. Story 5 explains the `local` and `passkey.check` wrappers. ref0 skips false, null and undefined items and flattens nested lists. Its floor adds needs the gate can't lower.
+
+ref0 runs the gate in an isolate with no network, a fixed clock and seeded randomness. `change.before` is the base's tree, and `change.after` is the expected tree. Their reads are recorded with the version. A decision reads at most 200 objects, at most 1 MiB each and 8 MiB in all. A read past a bound fails the decision.
+
+## 2. A check decides who may start it
+
+A check is a file in `.ref0/checks/`, named by its file. It judges a tree and returns a conclusion. Pip's e2e check limits each agent to ten new runs a day and three an hour, across both browsers.
+
+```ts
+// .ref0/checks/e2e.ts
+import { allow, check, oneOf, refuse, text } from '@ref0/sdk';
+import { z } from 'zod';
+import node from '../sandboxes/node';
+
+export default check({
+  description: 'End-to-end tests for one browser',
+  params: z.object({ browser: oneOf(['chromium', 'webkit']) }),
+  on: ['change', 'tip'],
+  start: ({ actor, params, runs, now }) => {
+    const own = runs.filter((run) => run.actor.kind === actor.kind && run.actor.id === actor.id);
+    const recent = own.filter((run) => run.startedAt > now - 60 * 60 * 1000);
+
+    return [
+      actor.kind === 'agent' && own.length >= 10
+        ? refuse(
+            text`Ten e2e runs a day each. Reuse a result instead of starting ${params.browser}`,
+          )
+        : allow(),
+      actor.kind === 'agent' && recent.length >= 3
+        ? refuse(
+            text`Three e2e runs an hour each. Reuse a result instead of starting ${params.browser}`,
+          )
+        : allow(),
+    ];
+  },
+  run: async ({ params, step }) => {
+    const { exitCode } = await node.run(step, 'e2e', {}, (sb) =>
+      sb.exec(['pnpm', 'exec', 'playwright', 'test', '--project', params.browser]),
+    );
+
+    return { conclusion: exitCode === 0 ? 'success' : 'failure' };
+  },
+});
+```
+
+`oneOf` makes one check run for each value unless the start supplies that param. `now` and each run's `startedAt` are milliseconds since the epoch. `runs` covers the check's last day, including new runs admitted earlier in the same start. A run the starter can't read hides its details, but still counts.
+
+A start rule returns a list. Any `refuse(text)` refuses with its words. Otherwise, `allow()` or an empty list allows. ref0's own starts for the gate and the queue's tip bypass the rule, as do starts answered by reuse or a run already going. `on` says when ref0 starts the check itself, here on a change and on the queue's tip. `on: []` leaves starts to people and code.
+
+The sandbox is another whole file. Its setup installs the repo's dependencies before a session opens. The example assumes the repo has Playwright browser projects named `chromium` and `webkit`.
+
+```ts
+// .ref0/sandboxes/node.ts
+import { sandbox } from '@ref0/sdk';
+
+export default sandbox({
+  image: 'node-24',
+  cache: { inputs: ['package.json', 'pnpm-lock.yaml'] },
+  setup: ['pnpm install --frozen-lockfile'],
+  egress: { setup: ['registry.npmjs.org'] },
+});
+```
+
+Here is the unit check that the gate needs. The repo supplies its `test:unit` script.
+
+```ts
+// .ref0/checks/unit.ts
+import { check } from '@ref0/sdk';
+import node from '../sandboxes/node';
+
+export default check({
+  description: 'Unit tests',
+  run: async ({ step }) => {
+    const { exitCode } = await node.run(step, 'unit tests', {}, (sb) =>
+      sb.exec(['pnpm', 'run', 'test:unit']),
+    );
+
+    return { conclusion: exitCode === 0 ? 'success' : 'failure' };
+  },
+});
+```
+
+A check reads the tree it judges through `repo.readFile`, `readText`, `readJSON` and `readTree`. It opens a sandbox through `run(step, name, options, work)`. ref0 reads `description`, `timeout`, `on` and `reuse` from their literals. `params`, `output`, `start` and `run` are code.
+
+## 3. A workflow waits for Mo
+
+A called workflow has `input` and a `title`. This one asks Mo whether to spend on e2e, then asks for Mo's passkey yes to one statement. Mo is the run's accountable person, so both requests use `'accountable'`.
+
+```ts
+// .ref0/workflows/approve-e2e.ts
+import { allow, ask, passkey, refuse, text, workflow } from '@ref0/sdk';
+import { z } from 'zod';
+
+export default workflow({
+  input: z.object({ browser: z.string() }),
+  title: ({ input }) => text`Approve e2e on ${input.browser}`,
+  permissions: { ask: ['accountable'], budgets: { asks: 2 } },
+  run: async ({ input, step }) => {
+    const answer = await ask.run(step, {
+      to: 'accountable',
+      key: 'e2e-cost',
+      question: text`Run e2e on ${input.browser}?`,
+      answers: [
+        { key: 'run', title: text`Run it`, detail: text`About $4 and 12 minutes` },
+        { key: 'skip', title: text`Skip`, detail: text`Keep the current result` },
+      ],
+      lean: 'skip',
+      deadline: '30 minutes',
+    });
+    if (answer.key !== 'run') return refuse(text`Mo skipped this e2e run`);
+
+    const signed = await passkey.run(step, {
+      from: 'accountable',
+      statement: text`Spend about $4 on e2e (${input.browser})`,
+      deadline: '30 minutes',
+    });
+
+    return signed.approved ? allow() : refuse(text`No passkey approval for e2e`);
+  },
+});
+```
+
+`ask.run` is a step of its own. It waits for `{ key, by, via, at }`. At its deadline it returns the lean with `via: 'deadline'` and no `by`. It offers two to five answers, and a run uses each ask key once. A refused or withdrawn ask throws `AskRefused`.
+
+`passkey.run` is also a step of its own. Only the person in their approving browser can answer yes with their passkey. The result has `approved`, `at` and, when someone answered, `by`. A deadline answers no. `from` can also name `{ person: 'mo' }` or `{ permission: 'deploy' }`, with `person` or `permission` in `permissions.ask`. Agents have no passkey.
+
+Call both leaves outside `step.do` callbacks. Each request spends from the workflow's `asks` budget. Deadlines range from a minute to a day, bounded by the run's remaining day. A called workflow parses its input with one `z.object` and returns JSON to its caller.
+
+## 4. A start waits for that workflow
+
+A second check can use the same sandbox command while its start waits for `approve-e2e`. An agent's start calls the workflow's handle with `{ browser }`.
+
+```ts
+// .ref0/checks/approved-e2e.ts
+import { allow, check, oneOf } from '@ref0/sdk';
+import { z } from 'zod';
+import node from '../sandboxes/node';
+import approveE2e from '../workflows/approve-e2e';
+
+export default check({
+  description: 'End-to-end tests with a person approving an agent start',
+  params: z.object({ browser: oneOf(['chromium', 'webkit']) }),
+  on: [],
+  start: ({ actor, params: { browser } }) => [
+    actor.kind === 'agent' ? approveE2e({ browser }) : allow(),
+  ],
+  run: async ({ params, step }) => {
+    const { exitCode } = await node.run(step, 'e2e', {}, (sb) =>
+      sb.exec(['pnpm', 'exec', 'playwright', 'test', '--project', params.browser]),
+    );
+
+    return { conclusion: exitCode === 0 ? 'success' : 'failure' };
+  },
+});
+```
+
+The start holds no check run while it waits. Every called workflow must return `allow()` before ref0 starts the check. A refusal, a failed run or any other output refuses the start. Another start of the same check, params and tree joins that wait.
+
+From an agent session on Mo's thread, start one browser:
+
+```sh
+ref0 run approved-e2e --thread pip/shop#3 --param browser=webkit
+```
+
+After Mo answers the ask, while the passkey request is still open, the command shows a tree like this:
+
+```text
+approved-e2e (webkit) · waiting, until 2026-10-23 10:00 UTC · startwait_01k6zt7m0yf8q2v3w4x5y6z7ab
+└─ Approve e2e on `webkit` · going · approve-e2e.ts
+   ├─ ask · mo answered "Run it" · 2m ago
+   └─ passkey · waiting on mo · "Spend about $4 on e2e (`webkit`)" · 1m ago
+```
+
+The command waits by default and prints the tree again when it changes. After nine minutes it exits with instructions to wait again or cancel. `--no-wait` returns while the start is waiting. Cancelling the start cancels its called runs.
+
+## 5. Run a check on Pip's machine
+
+On an attached machine, in a clean checkout of a thread's expected tree:
+
+```sh
+ref0 run unit --local --thread pip/shop#3
+```
+
+The CLI runs the parts requested by the open version's gate, with their params and code from ref0. It runs the sandbox's setup in the checkout, then executes commands on the machine. It reports a local result with its signer and attachment. Outside an agent session, add `--agent pip/claude` to select the attachment and approve the read and reports. `exec` and `serve` work locally. A local check that calls `browse` or `push` refuses by name.
+
+Local results appear beside ref0's runs. A plain check need still takes only ref0's own runs.
+
+The gate in story 1 takes local results with `local(unit())` and `passkey.check(local(e2e()))`. A local run from the version's thread can meet a need that takes `local` when it has the same check-run identity. ref0 leaves those parts for the local run unless another need requires ref0's own run.
+
+The newest finished local run counts unless a ref0 failure stands. A newer local run replaces an earlier one, and a newer ref0 pass counts instead. A ref0 failure stands until an admin overrides it, even if a later run passes.
+
+`passkey.check` waits for the person behind the counted run to say yes over its result with their passkey. For a local run, that's the signer's person. For ref0's run, it's the version's accountable person. `{ from }` asks someone else, as in `passkey.check(local(e2e()), { from: { person: 'mo' } })`. The statement names the check-run identity, conclusion and outputs' hash. A newer counted run needs a new yes.
+
+When ref0 runs the same check-run identity as a signed success and it fails twice, the signer stops answering that check. For `local`, ref0 revokes the attachment. For `passkey.check`, it revokes the person whose yes stood over the result. An admin restores the signer with `ref0 checks signers restore`, using `--person` for a person. The floor's needs and the queue's tip take only ref0's runs.
+
+## Event workflows and actions
+
+An event workflow has `on` instead of `input`. ref0 runs it from `main` and checks each action against its declared `permissions`. This workflow comments when a change to contracts merges.
+
+```ts
+// .ref0/workflows/docs.ts
+import { text, workflow } from '@ref0/sdk';
+
+export default workflow({
+  on: ['pull_request.merged'],
+  where: { 'pull_request.merged': { paths: ['packages/contracts/**'] } },
+  permissions: { comment: ['accountable'] },
+  run: async ({ event, step, ref0 }) => {
+    await step.do('tell the accountable person', () =>
+      ref0.comments.create({ to: 'accountable', text: text`Merged ${event.pullRequest}` }),
+    );
+  },
+});
+```
+
+ref0 reads `on`, `where` and `permissions` from their literals. Each piece of text is a `text` template ref0 has read in the source. A run fills in its values, never its words. Actions run inside `step.do`, and ref0 keeps their answers so replay doesn't act twice. Check an action's answer for a refusal before continuing.
+
+A workflow calls a called workflow with `.run(step, input)`. That call runs outside `step.do`, starts a run of its own and waits for its output. `where` on a check run selects `main` or a thread's head, separately from a check's `on`. Here, `where: 'thread'` selects the head of the thread that became active.
+
+```ts
+// .ref0/workflows/test-thread.ts
+import { text, workflow } from '@ref0/sdk';
+import e2e from '../checks/e2e';
+import approveE2e from './approve-e2e';
+
+export default workflow({
+  on: ['thread.stage.moved'],
+  where: { 'thread.stage.moved': { to: ['active'] } },
+  permissions: { checks: 'run', comment: ['accountable'] },
+  run: async ({ step, ref0 }) => {
+    const decision = await approveE2e.run(step, { browser: 'webkit' });
+    if (decision.kind !== 'allow') return;
+
+    const results = await e2e.run(step, { where: 'thread', params: { browser: 'webkit' } });
+    await step.do('report', () =>
+      ref0.comments.create({ to: 'accountable', text: text`E2e finished ${results.length} runs` }),
+    );
+  },
+});
+```
+
+A called workflow's permissions are its own. It ships in the caller's version and is approved with it. `.run` throws `CalledRunFailed` if ref0 refuses the call or the run fails. A replay finds the same child for the same call and input. A call with different input makes another child.
+
+`ref0.pr.needs.add` adds a need to an open pull request. This called workflow takes its number as input and declares `needs: 'add'`.
+
+```ts
+// .ref0/workflows/billing-review.ts
+import { approval, text, workflow } from '@ref0/sdk';
+import { z } from 'zod';
+
+export default workflow({
+  input: z.object({ pullRequest: z.number().int().positive() }),
+  title: ({ input }) => text`Billing approval for pull request ${input.pullRequest}`,
+  permissions: { needs: 'add' },
+  run: async ({ input, step, ref0 }) => {
+    await step.do('ask for billing approval', () =>
+      ref0.pr.needs.add(input.pullRequest, approval('billing')),
+    );
+  },
+});
+```
+
+`ref0.pr.open` opens a pull request from a fork the workflow has pushed. This repo supplies an `update-docs` script. The workflow gets its own fork, changes it in a sandbox, pushes, then opens the pull request.
+
+```ts
+// .ref0/workflows/update-docs.ts
+import { text, workflow } from '@ref0/sdk';
+import node from '../sandboxes/node';
+
+export default workflow({
+  on: ['pull_request.merged'],
+  where: { 'pull_request.merged': { paths: ['packages/contracts/**'] } },
+  permissions: { code: 'write', budgets: { forks: 1, pushes: 1, threads: 1 } },
+  run: async ({ step, ref0 }) => {
+    const fork = await step.do('fork', () => ref0.forks.create());
+    if (fork.kind !== 'fork') return;
+
+    const pushed = await node.run(step, 'update docs', { tree: fork }, async (sb) => {
+      const result = await sb.exec(['pnpm', 'run', 'update-docs']);
+      if (result.exitCode !== 0) throw new Error(result.stderr);
+
+      return await sb.push({ message: 'Update the contracts docs' });
+    });
+    if (pushed.kind !== 'pushed') return;
+
+    await step.do('open pull request', () =>
+      ref0.pr.open({ fork, title: text`Update the contracts docs` }),
+    );
+  },
+});
+```
+
+## Versions
+
+The package a repo installs gives its editor the types. ref0 runs its own build of the same major version in its place.
+
+## A check that browses
+
+A check that imports `@ref0/sdk/browser` borrows a browser with `sb.browse`. The published module holds only its types and an `expect` that throws. ref0 loads its own browser module in its place.
+
+Its types are Playwright's, from the version ref0 pins, an optional peer. Install it beside the SDK, and resolve modules as a bundler does, which Playwright's types need:
+
+```sh
+pnpm add -D @cloudflare/playwright@1.3.6
+```
+
+```json
+{ "compilerOptions": { "module": "preserve", "moduleResolution": "bundler" } }
+```
+
+## The client
+
+`@ref0/sdk/client` is ref0's HTTP client, which ref0's web app and CLI use.
+
+## License
+
+Apache 2.0