@xn-intenton-z2a/agentic-lib 7.2.11 → 7.2.13

package/.github/workflows/agentic-lib-init.yml

@@ -2,15 +2,12 @@
 # Copyright (C) 2025-2026 Polycode Limited
 # .github/workflows/agentic-lib-init.yml
 #
-# Self-contained init: update agentic-lib, purge, push to main [skip ci].
-# Does NOT create a PR. Does NOT trigger any other workflow.
-# Closes hanging init PRs before running.
-#
-# In agentic-lib: schedule trigger is commented out.
-# During init: #@dist restores the schedule.
+# Init: delegates to agentic-lib-update.yml for the update step, then
+# optionally reseeds or purges user content and configures schedule/model.
+# Commits and pushes to main [skip ci].
 
 name: agentic-lib-init
-run-name: "agentic-lib-init [${{ github.ref_name }}]"
+run-name: "agentic-lib-init ${{ inputs.mode || 'update' }} [${{ github.ref_name }}]"
 
 on:
   workflow_call:
@@ -120,49 +117,27 @@ on:
 permissions: write-all
 
 jobs:
-  params:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Normalise params
-        id: normalise
-        shell: bash
-        run: |
-          MODE='${{ inputs.mode }}'
-          echo "mode=${MODE:-update}" >> $GITHUB_OUTPUT
-          DRY_RUN='${{ inputs.dry-run }}'
-          echo "dry-run=${DRY_RUN:-false}" >> $GITHUB_OUTPUT
-          MISSION_SEED='${{ inputs.mission-seed }}'
-          echo "mission-seed=${MISSION_SEED:-hamming-distance}" >> $GITHUB_OUTPUT
-          MISSION_TEXT='${{ inputs.mission-text }}'
-          echo "mission-text=${MISSION_TEXT}" >> $GITHUB_OUTPUT
-          SCHEDULE='${{ inputs.schedule }}'
-          echo "schedule=${SCHEDULE}" >> $GITHUB_OUTPUT
-          MODEL='${{ inputs.model }}'
-          echo "model=${MODEL:-gpt-5-mini}" >> $GITHUB_OUTPUT
-          PROFILE='${{ inputs.profile }}'
-          echo "profile=${PROFILE}" >> $GITHUB_OUTPUT
-    outputs:
-      mode: ${{ steps.normalise.outputs.mode }}
-      dry-run: ${{ steps.normalise.outputs.dry-run }}
-      mission-seed: ${{ steps.normalise.outputs.mission-seed }}
-      mission-text: ${{ steps.normalise.outputs.mission-text }}
-      schedule: ${{ steps.normalise.outputs.schedule }}
-      model: ${{ steps.normalise.outputs.model }}
-      profile: ${{ steps.normalise.outputs.profile }}
+  # Step 1: Update agentic-lib and infrastructure (commits to main)
+  update:
+    uses: ./.github/workflows/agentic-lib-update.yml
+    with:
+      dry-run: ${{ inputs.dry-run || 'false' }}
+    secrets: inherit
 
+  # Step 2: Reseed/purge and configure (only if mode != update)
   init:
-    needs: params
+    needs: update
+    if: inputs.mode == 'reseed' || inputs.mode == 'purge'
     runs-on: ubuntu-latest
     env:
-      INIT_MODE: ${{ needs.params.outputs.mode }}
-      INIT_DRY_RUN: ${{ needs.params.outputs.dry-run }}
-      INIT_MISSION_SEED: ${{ needs.params.outputs.mission-seed }}
-      INIT_MISSION_TEXT: ${{ needs.params.outputs.mission-text }}
+      INIT_MODE: ${{ inputs.mode }}
+      INIT_MISSION_SEED: ${{ inputs.mission-seed || 'hamming-distance' }}
+      INIT_MISSION_TEXT: ${{ inputs.mission-text }}
     steps:
       - uses: actions/checkout@v6
-        if: needs.params.outputs.dry-run == 'true'
+        if: inputs.dry-run == 'true' || inputs.dry-run == true
       - uses: actions/checkout@v6
-        if: needs.params.outputs.dry-run != 'true'
+        if: inputs.dry-run != 'true' && inputs.dry-run != true
         with:
           ref: main
           token: ${{ secrets.WORKFLOW_TOKEN }}
@@ -172,11 +147,10 @@ jobs:
           node-version: "24"
 
       - name: Close hanging init PRs
-        if: github.repository != 'xn-intenton-z2a/agentic-lib' && env.INIT_MODE == 'purge' && needs.params.outputs.dry-run != 'true'
+        if: github.repository != 'xn-intenton-z2a/agentic-lib' && env.INIT_MODE == 'purge' && inputs.dry-run != 'true' && inputs.dry-run != true
         env:
           GH_TOKEN: ${{ secrets.WORKFLOW_TOKEN }}
         run: |
-          # Close any open PRs from previous init runs
           gh pr list --state open --json number,headRefName \
             --jq '.[] | select(.headRefName | startswith("agentic-lib-init-")) | .number' \
             | while read -r pr_num; do
@@ -184,18 +158,15 @@ jobs:
                 gh pr close "$pr_num" --delete-branch || true
               done
 
-      - name: Update agentic-lib to latest
-        run: npm update @xn-intenton-z2a/agentic-lib
-
-      - name: Run init
+      - name: Run init (reseed/purge)
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
           FLAGS="init"
           if [ "$INIT_MODE" = "reseed" ]; then FLAGS="$FLAGS --reseed"; fi
           if [ "$INIT_MODE" = "purge" ]; then FLAGS="$FLAGS --purge --mission $INIT_MISSION_SEED"; fi
-          if [ "$INIT_DRY_RUN" = "true" ]; then FLAGS="$FLAGS --dry-run"; fi
-          # Use local CLI if available (agentic-lib dev), otherwise npx
+          DRY_RUN='${{ inputs.dry-run }}'
+          if [ "$DRY_RUN" = "true" ]; then FLAGS="$FLAGS --dry-run"; fi
           if [ -f "bin/agentic-lib.js" ]; then
             node bin/agentic-lib.js $FLAGS
           else
@@ -203,7 +174,7 @@ jobs:
           fi
 
       - name: Write mission text (if provided, overrides seed)
-        if: env.INIT_MISSION_TEXT != '' && needs.params.outputs.dry-run != 'true'
+        if: env.INIT_MISSION_TEXT != '' && inputs.dry-run != 'true' && inputs.dry-run != true
         run: |
           printf '# Mission\n\n%s\n' "$INIT_MISSION_TEXT" > MISSION.md
           echo "Wrote custom mission text to MISSION.md"
@@ -221,18 +192,16 @@ jobs:
       - run: npm test
 
       - name: Update model and profile (if requested)
-        if: github.repository != 'xn-intenton-z2a/agentic-lib' && needs.params.outputs.dry-run != 'true' && (needs.params.outputs.model != '' || needs.params.outputs.profile != '')
+        if: github.repository != 'xn-intenton-z2a/agentic-lib' && inputs.dry-run != 'true' && inputs.dry-run != true && (inputs.model != '' || inputs.profile != '')
         uses: actions/github-script@v8
         with:
           script: |
             const fs = require('fs');
-            const model = '${{ needs.params.outputs.model }}';
-            const profile = '${{ needs.params.outputs.profile }}';
+            const model = '${{ inputs.model }}';
+            const profile = '${{ inputs.profile }}';
             const tomlPath = 'agentic-lib.toml';
             if (!fs.existsSync(tomlPath)) return;
             let toml = fs.readFileSync(tomlPath, 'utf8');
-            // Extract the [tuning] section, then replace within it.
-            // Previous regex [^\[]*? failed when comments contained '[' characters.
             const tuningSectionRegex = /(\[tuning\])([\s\S]*?)(?=\n\[|$)/;
             const tuningMatch = toml.match(tuningSectionRegex);
             if (tuningMatch) {
@@ -256,13 +225,13 @@ jobs:
             fs.writeFileSync(tomlPath, toml);
 
       - name: Update schedule (if requested)
-        if: github.repository != 'xn-intenton-z2a/agentic-lib' && needs.params.outputs.schedule != '' && needs.params.outputs.dry-run != 'true'
+        if: github.repository != 'xn-intenton-z2a/agentic-lib' && inputs.schedule != '' && inputs.dry-run != 'true' && inputs.dry-run != true
         uses: actions/github-script@v8
         with:
           script: |
             const fs = require('fs');
-            const frequency = '${{ needs.params.outputs.schedule }}';
-            const model = '${{ needs.params.outputs.model || 'gpt-5-mini' }}';
+            const frequency = '${{ inputs.schedule }}';
+            const model = '${{ inputs.model || 'gpt-5-mini' }}';
             const workflowPath = '.github/workflows/agentic-lib-workflow.yml';
             const tomlPath = 'agentic-lib.toml';
 
@@ -308,7 +277,7 @@ jobs:
             }
 
       - name: Commit and push to main [skip ci]
-        if: github.repository != 'xn-intenton-z2a/agentic-lib' && needs.params.outputs.dry-run != 'true'
+        if: github.repository != 'xn-intenton-z2a/agentic-lib' && inputs.dry-run != 'true' && inputs.dry-run != true
         env:
           GH_TOKEN: ${{ secrets.WORKFLOW_TOKEN }}
         run: |
@@ -334,9 +303,8 @@ jobs:
             fi
           done
 
-      # W8: Create initial seed issues after purge so the pipeline has work to do
       - name: Create initial seed issues
-        if: github.repository != 'xn-intenton-z2a/agentic-lib' && env.INIT_MODE == 'purge' && needs.params.outputs.dry-run != 'true'
+        if: github.repository != 'xn-intenton-z2a/agentic-lib' && env.INIT_MODE == 'purge' && inputs.dry-run != 'true' && inputs.dry-run != true
         uses: actions/github-script@v8
         with:
           script: |
@@ -345,7 +313,6 @@ jobs:
               ? fs.readFileSync('MISSION.md', 'utf8')
               : '(no MISSION.md found)';
 
-            // Ensure labels exist
             for (const label of ['automated', 'ready']) {
               try {
                 await github.rest.issues.createLabel({
@@ -356,7 +323,6 @@ jobs:
               } catch (e) { /* label already exists */ }
             }
 
-            // W8a: Initial unit tests issue
             const unitTestBody = [
               'Create a unit test file for each of the major features in the mission ',
               'and put a TODO in a trivial empty passing test in each.',
@@ -373,7 +339,6 @@ jobs:
             });
             core.info(`Created issue #${issue1.number}: Initial unit tests`);
 
-            // W8b: Initial web layout issue
             const webLayoutBody = [
               'Create the home page layout to showcase each of the major features in the mission ',
               'and put a TODO in a trivial empty passing test in each.',

package/.github/workflows/agentic-lib-update.yml

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2025-2026 Polycode Limited
+# .github/workflows/agentic-lib-update.yml
+#
+# Update agentic-lib to latest, extract workflows/actions/scripts, run tests,
+# commit and push to main [skip ci]. Does NOT reseed or purge user content.
+#
+# In agentic-lib: schedule trigger is commented out.
+# During init: #@dist restores the schedule.
+
+name: agentic-lib-update
+run-name: "agentic-lib-update [${{ github.ref_name }}]"
+
+on:
+  workflow_call:
+    inputs:
+      dry-run:
+        type: string
+        required: false
+        default: "false"
+  #@dist schedule:
+  #@dist   - cron: "15 6 * * *"
+  workflow_dispatch:
+    inputs:
+      dry-run:
+        description: "Preview changes without committing"
+        type: boolean
+        required: false
+        default: false
+
+permissions: write-all
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        if: inputs.dry-run == 'true' || inputs.dry-run == true
+      - uses: actions/checkout@v6
+        if: inputs.dry-run != 'true' && inputs.dry-run != true
+        with:
+          ref: main
+          token: ${{ secrets.WORKFLOW_TOKEN }}
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+
+      - name: Update agentic-lib to latest
+        run: npm update @xn-intenton-z2a/agentic-lib
+
+      - name: Run init (update mode)
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Use local CLI if available (agentic-lib dev), otherwise npx
+          if [ -f "bin/agentic-lib.js" ]; then
+            node bin/agentic-lib.js init
+          else
+            npx @xn-intenton-z2a/agentic-lib init
+          fi
+
+      - run: npm install
+
+      - name: Install agentic-step deps
+        if: hashFiles('.github/agentic-lib/actions/agentic-step/package.json') != ''
+        run: cd .github/agentic-lib/actions/agentic-step && npm ci
+
+      - name: Install sub-project dependencies (agentic-lib dev only)
+        if: hashFiles('src/actions/agentic-step/package.json') != ''
+        run: cd src/actions/agentic-step && npm ci
+
+      - run: npm test
+
+      - name: Commit and push to main [skip ci]
+        if: github.repository != 'xn-intenton-z2a/agentic-lib' && inputs.dry-run != 'true' && inputs.dry-run != true
+        env:
+          GH_TOKEN: ${{ secrets.WORKFLOW_TOKEN }}
+        run: |
+          TOKEN_USER=$(gh api /user --jq '.login')
+          TOKEN_ID=$(gh api /user --jq '.id')
+          git config user.name "${TOKEN_USER}"
+          git config user.email "${TOKEN_ID}+${TOKEN_USER}@users.noreply.github.com"
+          git add -A
+          git diff --cached --quiet && echo "No changes" && exit 0
+          VERSION=$(npx @xn-intenton-z2a/agentic-lib version 2>/dev/null || echo "latest")
+          git commit -m "update agentic-lib@${VERSION} [skip ci]"
+          for attempt in 1 2 3; do
+            git push origin main && break
+            echo "Push failed (attempt $attempt) — pulling and retrying"
+            git pull --rebase origin main || {
+              echo "Rebase conflict — aborting rebase and retrying"
+              git rebase --abort 2>/dev/null || true
+            }
+            sleep $((attempt * 2))
+            if [ "$attempt" -eq 3 ]; then
+              echo "::error::Failed to push after 3 attempts"
+              exit 1
+            fi
+          done

package/bin/agentic-lib.js

@@ -720,6 +720,7 @@ function initPurge(seedsDir, missionName, initTimestamp) {
     "zero-main.js": "src/lib/main.js",
     "zero-main.test.js": "tests/unit/main.test.js",
     "zero-index.html": "src/web/index.html",
+    "zero-lib.js": "src/web/lib.js",
     "zero-web.test.js": "tests/unit/web.test.js",
     "zero-behaviour.test.js": "tests/behaviour/homepage.test.js",
     "zero-playwright.config.js": "playwright.config.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xn-intenton-z2a/agentic-lib",
-  "version": "7.2.11",
+  "version": "7.2.13",
   "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
   "type": "module",
   "scripts": {

package/src/actions/agentic-step/tasks/transform.js

@@ -120,7 +120,7 @@ export async function transform(context) {
           `## Website Files (${webFiles.length})`,
           "The website in `src/web/` uses the JS library.",
           "When transforming source code, also update the website to use the library's new/changed features.",
-          "The `lib-meta.js` file (generated by `npm run build:web` from `package.json`) provides `name`, `version`, and `description` exports to the browser.",
+          "`src/web/lib.js` re-exports from `../lib/main.js` so the page imports the real library directly. Keep `main.js` browser-safe (guard Node APIs behind `typeof process` checks). NEVER duplicate library functions inline in the web page.",
           ...webFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
           "",
         ]

package/src/agents/agent-apply-fix.md

@@ -18,9 +18,9 @@ A fix is never just one file. These layers form a single unit — if you change
 
 - **Library source** (`src/lib/main.js`) — the core implementation
 - **Unit tests** (`tests/unit/`) — test every function at the API level with exact values and edge cases
-- **Website** (`src/web/index.html` and related files) — imports and calls the library to demonstrate features.
-  **NEVER duplicate library functions inline in the web page** — use the build pipeline (`lib-meta.js`, or
-  a generated browser module) to share code. Inline copies cause behaviour tests to test a simulation, not the real library.
+- **Website** (`src/web/index.html` and `src/web/lib.js`) — `lib.js` re-exports from `../lib/main.js`, so the
+  page imports the **real library** directly. **NEVER duplicate library functions inline in the web page** —
+  add exports to `main.js` and they are automatically available via `lib.js`.
 - **Website unit tests** (`tests/unit/web.test.js`) — verify HTML structure and library wiring
 - **Behaviour tests** (`tests/behaviour/`) — Playwright tests that load the website in a real browser
   and verify features work at a high navigational level (demo output visible, interactive elements work).

package/src/agents/agent-issue-resolution.md

@@ -79,23 +79,26 @@ automatically (from `docs/` via `npm run build:web`).
 
 ### How the library connects to the website
 
-- `src/lib/main.js` is the JS library — it exports functions, `name`, `version`, `description`, and `getIdentity()`
-- `npm run build:web` copies `src/web/*` to `docs/` and generates `docs/lib-meta.js` from `package.json`
-- `src/web/index.html` imports `lib-meta.js` via `<script type="module">` to display the library's identity
-- The website should import and call library functions — not just describe them
+- `src/lib/main.js` is browser-safe — in Node it reads `package.json` via `createRequire`, in the browser via `fetch`
+- `src/web/lib.js` re-exports from `../lib/main.js` — the page imports the **real library**
+- `src/web/index.html` imports `./lib.js` via `<script type="module">` to access the library directly
+- The website works at rest (no build step needed for development)
+- `npm run build:web` generates `docs/lib.js` as a self-contained module for production (GitHub Pages)
 
 ### What to do with the website
 
-- **Use the library**: Import the library (or its browser-compatible parts) and call its functions on the page
+- **Use the library**: Import from `./lib.js` which re-exports from `../lib/main.js` — call library functions directly
 - **Show real results**: Display actual output from library functions, not placeholder text
 - When you add or change library functions, update the website to reflect them
 - **Demonstrate features**: Each significant library feature should be visible and usable on the website.
   Behaviour tests will verify these demonstrations work, so make them testable (use IDs, structured output).
+- **Keep main.js browser-safe**: Do not add Node-only top-level code (e.g. bare `require`, `process.argv` checks)
+  without guarding them behind `typeof process !== "undefined"` checks
 
 ### CRITICAL: Never duplicate library code in the web page
 
-**Do NOT copy or recreate library functions inline in `src/web/index.html`.** The web page must consume
-the library through the build pipeline — not by reimplementing functions in a `<script>` block.
+**Do NOT copy or recreate library functions inline in `src/web/index.html`.** The web page imports the
+library directly via `src/web/lib.js` → `src/lib/main.js`. There is no reason to duplicate.
 
 Why this matters:
 - Unit tests test `src/lib/main.js` directly
@@ -104,11 +107,11 @@ Why this matters:
 - The two copies can diverge silently, and tests pass even when the real library is broken
 
 How to share code between library and web:
-- Identity (name, version, description) flows via `lib-meta.js` (generated by `build:web` from `package.json`)
-- If the web page needs to call mission-specific functions, make them available through the build pipeline
-  (e.g. generate a browser-compatible module in `docs/` or add a build step that packages the pure functions)
+- `src/web/lib.js` re-exports everything from `../lib/main.js` — add exports to `main.js` and they are
+  automatically available to the web page
+- If adding a new exported function to `main.js`, make sure it is browser-safe (no bare Node API calls)
 - The behaviour test imports `getIdentity()` from `src/lib/main.js` and asserts the page displays the same
-  version — this coupling test proves the pipeline is wired up correctly
+  version — this coupling test proves the import chain is wired up correctly
 
 ### Guidelines
 

package/src/scripts/build-web.cjs

@@ -6,8 +6,10 @@
 //
 // Builds the docs/ directory for web serving:
 // 1. Creates docs/ and copies src/web/* into it
-// 2. Generates docs/lib-meta.js with package metadata exports
-// 3. Generates docs/lib-browser.js from src/lib/main.js (if it has named exports)
+// 2. Generates docs/lib.js — a self-contained browser module with:
+//    - Package identity (name, version, description) from package.json
+//    - Browser-safe exported functions extracted from src/lib/main.js
+//    This overwrites the src/web/lib.js re-export (which only works in dev).
 //
 // This file is part of the Example Suite for `agentic-lib` see: https://github.com/xn-intenton-z2a/agentic-lib
 // This file is licensed under the MIT License. For details, see LICENSE-MIT
@@ -34,64 +36,63 @@ if (fs.existsSync(webDir)) {
   }
 }
 
-// Step 2: Generate docs/lib-meta.js with package metadata
+// Step 2: Generate docs/lib.js — self-contained browser module
+// This overwrites the re-export copied from src/web/lib.js above,
+// replacing it with a standalone module that works on GitHub Pages
+// (where src/lib/main.js and package.json are not available).
 const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
-const metaLines = ["name", "version", "description"].map(
-  (k) => `export const ${k} = ${JSON.stringify(pkg[k])};`
+const sections = [];
+
+// Identity exports from package.json
+sections.push(
+  `export const name = ${JSON.stringify(pkg.name)};`,
+  `export const version = ${JSON.stringify(pkg.version)};`,
+  `export const description = ${JSON.stringify(pkg.description)};`,
+  "",
+  "export function getIdentity() {",
+  "  return { name, version, description };",
+  "}"
 );
-fs.writeFileSync(path.join(docsDir, "lib-meta.js"), metaLines.join("\n") + "\n");
-console.log("Wrote docs/lib-meta.js");
 
-// Step 3: Generate docs/lib-browser.js from src/lib/main.js named exports
-// Parse the main module for `export function` and `export async function` declarations
-// and re-emit them as a standalone browser-compatible module.
+// Extract browser-safe exported functions from src/lib/main.js
 const mainPath = path.resolve("src", "lib", "main.js");
 if (fs.existsSync(mainPath)) {
   const mainSrc = fs.readFileSync(mainPath, "utf8");
-  // Match named export functions: export function foo(...) { ... } or export async function foo(...)
-  const exportRegex = /^export\s+(async\s+)?function\s+(\w+)/gm;
-  const exportNames = [];
-  let match;
-  while ((match = exportRegex.exec(mainSrc)) !== null) {
-    exportNames.push(match[2]);
-  }
+  const lines = mainSrc.split("\n");
 
-  if (exportNames.length > 0) {
-    // Extract the function bodies by finding each export function and copying it verbatim
-    const lines = mainSrc.split("\n");
-    const functionBodies = [];
-    for (let i = 0; i < lines.length; i++) {
-      if (/^export\s+(async\s+)?function\s+\w+/.test(lines[i])) {
-        // Collect lines until we find the closing brace at column 0
-        const fnLines = [lines[i]];
-        let braceDepth = 0;
-        for (let j = i; j < lines.length; j++) {
-          for (const ch of lines[j]) {
-            if (ch === "{") braceDepth++;
-            if (ch === "}") braceDepth--;
-          }
-          if (j > i) fnLines.push(lines[j]);
-          if (braceDepth === 0 && j >= i) {
-            break;
-          }
+  // Skip identity-related exports and the main/CLI function — only extract
+  // mission-specific exported functions (e.g. hammingDistance, etc.)
+  const SKIP_FUNCTIONS = new Set(["getIdentity", "main"]);
+
+  for (let i = 0; i < lines.length; i++) {
+    const fnMatch = lines[i].match(/^export\s+(async\s+)?function\s+(\w+)/);
+    if (fnMatch && !SKIP_FUNCTIONS.has(fnMatch[2])) {
+      // Collect the full function body by tracking brace depth
+      const fnLines = [lines[i]];
+      let braceDepth = 0;
+      for (let j = i; j < lines.length; j++) {
+        for (const ch of lines[j]) {
+          if (ch === "{") braceDepth++;
+          if (ch === "}") braceDepth--;
+        }
+        if (j > i) fnLines.push(lines[j]);
+        if (braceDepth === 0 && j >= i) {
+          break;
         }
-        functionBodies.push(fnLines.join("\n"));
       }
+      sections.push("");
+      sections.push(fnLines.join("\n"));
     }
-
-    const header = [
-      "// docs/lib-browser.js",
-      "// Generated browser-compatible module exposing named exports from src/lib/main.js.",
-      "// Auto-generated by build-web.cjs — do not edit manually.",
-      "",
-    ].join("\n");
-
-    fs.writeFileSync(
-      path.join(docsDir, "lib-browser.js"),
-      header + functionBodies.join("\n\n") + "\n"
-    );
-    console.log(
-      `Wrote docs/lib-browser.js (${exportNames.length} exports: ${exportNames.join(", ")})`
-    );
   }
 }
+
+const header = [
+  "// docs/lib.js",
+  "// Self-contained browser module generated by build-web.cjs.",
+  "// Identity from package.json; functions extracted from src/lib/main.js.",
+  "// Do not edit — regenerate with: npm run build:web",
+  "",
+].join("\n");
+
+fs.writeFileSync(path.join(docsDir, "lib.js"), header + sections.join("\n") + "\n");
+console.log("Wrote docs/lib.js");

package/src/seeds/zero-README.md

@@ -49,33 +49,35 @@ The pipeline runs as GitHub Actions workflows. An LLM supervisor gathers reposit
 ## File Layout
 
 ```
-src/lib/main.js              ← library (Node entry point: identity + mission functions)
-src/web/index.html            ← web page (browser: imports lib-meta.js, demonstrates library)
+src/lib/main.js              ← library (browser-safe: identity + mission functions)
+src/web/index.html            ← web page (imports ./lib.js)
+src/web/lib.js                ← browser entry point (re-exports from ../lib/main.js)
 tests/unit/main.test.js       ← unit tests (import main.js directly, test API-level detail)
 tests/unit/web.test.js        ← web structure tests (read index.html as text, verify wiring)
-tests/behaviour/              ← Playwright E2E (run page in browser, import main.js for coupling)
+tests/behaviour/              ← Playwright E2E (serve from project root, import main.js for coupling)
 docs/                         ← build output (generated by npm run build:web)
-docs/lib-meta.js              ← generated: exports name, version, description from package.json
+docs/lib.js                   ← generated: self-contained module for GitHub Pages
 ```
 
-These files form a **coupled unit**. Changes to the library must flow through to the web page, and tests verify this coupling:
+These files form a **coupled unit**. The library works in both Node and the browser:
 
-- `src/lib/main.js` exports `getIdentity()` → returns `{ name, version, description }` from `package.json`
-- `npm run build:web` copies `src/web/*` to `docs/` and generates `docs/lib-meta.js` from `package.json`
-- `src/web/index.html` imports `lib-meta.js` at runtime → displays library identity on the page
+- `src/lib/main.js` is browser-safe — in Node it reads `package.json` via `createRequire`, in the browser via `fetch`
+- `src/web/lib.js` re-exports from `../lib/main.js` — the page imports the **real library**, not a generated copy
+- `src/web/index.html` imports `./lib.js` → displays library identity on the page
 - The behaviour test imports `getIdentity()` from `main.js` AND reads `#lib-version` from the rendered page → asserts they match
+- `npm run build:web` generates `docs/lib.js` as a self-contained module for production (GitHub Pages)
 
-This coupling test proves the web page is consuming the real library via the build pipeline. Mission-specific functions should follow the same path — never duplicate library logic inline in the web page.
+This coupling proves the web page consumes the real library. Mission-specific functions should follow the same path — never duplicate library logic inline in the web page.
 
 ## Test Strategy
 
 | Test layer | What it tests | How it binds |
 |------------|--------------|--------------|
 | **Unit tests** (`tests/unit/main.test.js`) | Library API: return values, error types, edge cases | Imports directly from `src/lib/main.js` |
-| **Web structure tests** (`tests/unit/web.test.js`) | HTML structure: expected elements, `lib-meta.js` import | Reads `src/web/index.html` as text |
-| **Behaviour tests** (`tests/behaviour/`) | End-to-end: page renders, interactive elements work | Playwright loads the built site; coupling test imports `getIdentity()` from `main.js` and asserts the page displays the same version |
+| **Web structure tests** (`tests/unit/web.test.js`) | HTML structure: expected elements, `lib.js` re-export | Reads `src/web/index.html` and `src/web/lib.js` as text |
+| **Behaviour tests** (`tests/behaviour/`) | End-to-end: page renders, displays real library values | Playwright serves from project root; coupling test imports `getIdentity()` from `main.js` and asserts the page displays the same version |
 
-The **coupling test** in the behaviour test is the key invariant: it proves the web page displays values from the actual library, not hardcoded or duplicated values. If the build pipeline breaks, this test fails.
+The **coupling test** in the behaviour test is the key invariant: it proves the web page displays values from the actual library, not hardcoded or duplicated values. The page imports `lib.js` which re-exports from `main.js` which reads `package.json` — the same chain the unit tests exercise.
 
 ## Configuration
 

package/src/seeds/zero-index.html

@@ -33,16 +33,16 @@
   <p>This website uses the library. See <a href="https://github.com/xn-intenton-z2a/repository0">the repository</a> for source code and mission details.</p>
   <script type="module">
     try {
-      const { name, version, description } = await import('./lib-meta.js');
+      const { name, version, description } = await import('./lib.js');
       document.getElementById('lib-name').textContent = name;
       document.getElementById('lib-version').textContent = version;
       document.getElementById('lib-description').textContent = description || '(no description)';
       document.getElementById('demo-output').textContent = JSON.stringify({ name, version, description }, null, 2);
       document.title = name + ' v' + version;
     } catch (e) {
-      document.getElementById('lib-version').textContent = '(build required)';
-      document.getElementById('lib-description').textContent = 'Run npm run build:web to generate library metadata';
-      document.getElementById('demo-output').textContent = 'Library not yet built. Run: npm run build:web';
+      document.getElementById('lib-version').textContent = '(error)';
+      document.getElementById('lib-description').textContent = e.message;
+      document.getElementById('demo-output').textContent = 'Failed to load library: ' + e.message;
     }
   </script>
 </body>

package/src/seeds/zero-lib.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2025-2026 Polycode Limited
+// src/web/lib.js — Browser entry point, re-exports from the library.
+export { name, version, description, getIdentity } from "../lib/main.js";

package/src/seeds/zero-main.js

@@ -3,11 +3,21 @@
 // Copyright (C) 2025-2026 Polycode Limited
 // src/lib/main.js
 
-import { createRequire } from "module";
-import { fileURLToPath } from "url";
+const isNode = typeof process !== "undefined" && !!process.versions?.node;
 
-const require = createRequire(import.meta.url);
-const pkg = require("../../package.json");
+let pkg;
+if (isNode) {
+  const { createRequire } = await import("module");
+  const requireFn = createRequire(import.meta.url);
+  pkg = requireFn("../../package.json");
+} else {
+  try {
+    const resp = await fetch(new URL("../../package.json", import.meta.url));
+    pkg = await resp.json();
+  } catch {
+    pkg = { name: document.title, version: "0.0.0", description: "" };
+  }
+}
 
 export const name = pkg.name;
 export const version = pkg.version;
@@ -29,7 +39,10 @@ export function main(args) {
   console.log(`${name}@${version}`);
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  const args = process.argv.slice(2);
-  main(args);
+if (isNode) {
+  const { fileURLToPath } = await import("url");
+  if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const args = process.argv.slice(2);
+    main(args);
+  }
 }

package/src/seeds/zero-package.json

@@ -9,7 +9,7 @@
     "build:web": "node .github/agentic-lib/scripts/build-web.cjs",
     "test": "vitest --run tests/unit/*.test.js",
     "test:unit": "vitest --run --coverage tests/unit/*.test.js",
-    "test:behaviour": "npm run build:web && npx playwright test --config playwright.config.js",
+    "test:behaviour": "npx playwright test --config playwright.config.js",
     "start": "npm run build:web && npx serve docs",
     "start:cli": "node src/lib/main.js"
   },
@@ -17,7 +17,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xn-intenton-z2a/agentic-lib": "^7.2.11"
+    "@xn-intenton-z2a/agentic-lib": "^7.2.13"
   },
   "devDependencies": {
     "@playwright/test": "^1.58.0",

package/src/seeds/zero-playwright.config.js

@@ -7,10 +7,10 @@ export default defineConfig({
   timeout: 30000,
   retries: 2,
   use: {
-    baseURL: "http://localhost:3000",
+    baseURL: "http://localhost:3000/src/web/",
   },
   webServer: {
-    command: "npx serve docs -l 3000",
+    command: "npx serve . -l 3000",
     port: 3000,
     reuseExistingServer: true,
   },

package/src/seeds/zero-web.test.js

@@ -15,9 +15,15 @@ describe("Website", () => {
     expect(html).toContain("</html>");
   });
 
-  test("index.html imports the library via lib-meta.js", () => {
+  test("index.html imports the library via lib.js", () => {
     const html = readFileSync("src/web/index.html", "utf8");
-    expect(html).toContain("lib-meta.js");
+    expect(html).toContain("lib.js");
+  });
+
+  test("src/web/lib.js re-exports from the library", () => {
+    expect(existsSync("src/web/lib.js")).toBe(true);
+    const lib = readFileSync("src/web/lib.js", "utf8");
+    expect(lib).toContain("../lib/main.js");
   });
 
   test("index.html displays library identity elements", () => {