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..d570868ec 100644
--- a/test/unit/scripts/v18-package-surface-audit.test.ts
+++ b/test/unit/scripts/v18-package-surface-audit.test.ts
@@ -13,6 +13,16 @@ const packageJson = readText('package.json');
 const jsrJson = readText('jsr.json');
 const indexSource = readText('index.ts');
 
+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', () => {
     expect(packageJson).toContain(
@@ -38,6 +48,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');