From 621d6ed630bb3f59a28895813d30521ae3d48d50 Mon Sep 17 00:00:00 2001
From: James Ross <james@flyingrobots.dev>
Date: Wed, 3 Jun 2026 07:21:44 -0700
Subject: [PATCH 1/2] Fix: update package module example

---
 index.ts                                      | 22 +++++++++++++++++++
 .../scripts/v18-package-surface-audit.test.ts | 11 ++++++++++
 2 files changed, 33 insertions(+)

diff --git a/index.ts b/index.ts
index 3e8d356f0..398ff9c34 100644
--- a/index.ts
+++ b/index.ts
@@ -10,6 +10,28 @@
  * First-use application code should open a named worldline with
  * `openWarpWorldline()`. `WarpApp`, `WarpCore`, and `openWarpGraph()` remain
  * supported compatibility and diagnostic surfaces for graph-first code.
+ *
+ * @example
+ * ```typescript
+ * import { GitGraphAdapter, openWarpWorldline } from '@git-stunts/git-warp';
+ * import GitPlumbing from '@git-stunts/plumbing';
+ *
+ * const persistence = new GitGraphAdapter({
+ *   plumbing: new GitPlumbing({ cwd: '.' }),
+ * });
+ *
+ * const events = await openWarpWorldline({
+ *   persistence,
+ *   worldlineName: 'events',
+ *   writerId: 'agent-1',
+ * });
+ *
+ * await events.commit((patch) => {
+ *   patch.addNode('user:alice');
+ * });
+ *
+ * const props = await events.live().getNodeProps('user:alice');
+ * ```
  */
 
 import GitGraphAdapter from './src/infrastructure/adapters/GitGraphAdapter.ts';
diff --git a/test/unit/scripts/v18-package-surface-audit.test.ts b/test/unit/scripts/v18-package-surface-audit.test.ts
index a2cde4d6a..06303ea31 100644
--- a/test/unit/scripts/v18-package-surface-audit.test.ts
+++ b/test/unit/scripts/v18-package-surface-audit.test.ts
@@ -12,6 +12,7 @@ function readText(relativePath: string): string {
 const packageJson = readText('package.json');
 const jsrJson = readText('jsr.json');
 const indexSource = readText('index.ts');
+const moduleDoc = indexSource.slice(0, indexSource.indexOf("import GitGraphAdapter"));
 
 describe('v18 package surface audit', () => {
   it('positions the registry package around the Worldline-first API', () => {
@@ -38,6 +39,16 @@ describe('v18 package surface audit', () => {
     expect(indexSource).toContain('WarpWorldlinePatchBuild,');
   });
 
+  it('keeps package hover docs on the Worldline-first example', () => {
+    expect(moduleDoc).toContain('@example');
+    expect(moduleDoc).toContain('openWarpWorldline');
+    expect(moduleDoc).toContain("events.commit((patch) =>");
+    expect(moduleDoc).toContain('events.live().getNodeProps');
+    expect(moduleDoc).not.toContain('WarpApp.open(');
+    expect(moduleDoc).not.toContain('app.createPatch(');
+    expect(moduleDoc).not.toContain('app.materialize(');
+  });
+
   it('keeps default export compatibility explicit', () => {
     expect(indexSource).toContain('export default WarpApp;');
     expect(indexSource).toContain('WarpApp remains the compatibility default export');

From 9a01f105516ae1c009dd372fe0c963544f7d2025 Mon Sep 17 00:00:00 2001
From: James Ross <james@flyingrobots.dev>
Date: Wed, 3 Jun 2026 14:42:41 -0700
Subject: [PATCH 2/2] Fix: bound package module doc guard

---
 test/unit/scripts/v18-package-surface-audit.test.ts | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/test/unit/scripts/v18-package-surface-audit.test.ts b/test/unit/scripts/v18-package-surface-audit.test.ts
index 06303ea31..d570868ec 100644
--- a/test/unit/scripts/v18-package-surface-audit.test.ts
+++ b/test/unit/scripts/v18-package-surface-audit.test.ts
@@ -12,7 +12,16 @@ function readText(relativePath: string): string {
 const packageJson = readText('package.json');
 const jsrJson = readText('jsr.json');
 const indexSource = readText('index.ts');
-const moduleDoc = indexSource.slice(0, indexSource.indexOf("import GitGraphAdapter"));
+
+function packageModuleDoc(): string {
+  const terminator = indexSource.indexOf('*/');
+  if (terminator === -1) {
+    throw new Error('index.ts is missing its package module JSDoc block');
+  }
+  return indexSource.slice(0, terminator + '*/'.length);
+}
+
+const moduleDoc = packageModuleDoc();
 
 describe('v18 package surface audit', () => {
   it('positions the registry package around the Worldline-first API', () => {