@xn-intenton-z2a/agentic-lib 7.1.62 → 7.1.63

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

@@ -654,7 +654,8 @@ jobs:
           SOURCES=$(yq -r '.paths.librarySourcesFilepath.path // "SOURCES.md"' "$CONFIG")
           README=$(yq -r '.paths.readmeFilepath.path // "README.md"' "$CONFIG")
           DEPS=$(yq -r '.paths.dependenciesFilepath.path // "package.json"' "$CONFIG")
-          echo "writablePaths=${SOURCE};${TESTS};${FEATURES};${DOCS};${LIBRARY};${SOURCES};${README};${DEPS}" >> $GITHUB_OUTPUT
+          WEB=$(yq -r '.paths.web // "src/web/"' "$CONFIG" 2>/dev/null || echo "src/web/")
+          echo "writablePaths=${SOURCE};${TESTS};${FEATURES};${DOCS};${LIBRARY};${SOURCES};${README};${DEPS};${WEB}" >> $GITHUB_OUTPUT
 
       - name: Check mission-complete signal
         id: dev-mission-check
@@ -715,6 +716,11 @@ jobs:
           issue-number: ${{ steps.issue.outputs.issue-number }}
           writable-paths: ${{ steps.config.outputs.writablePaths }}
 
+      - name: Build website
+        if: steps.issue.outputs.issue-number != ''
+        run: |
+          npm run build:web 2>/dev/null || echo "No build:web script"
+
       - name: Commit and push
         if: github.repository != 'xn-intenton-z2a/agentic-lib' && steps.issue.outputs.issue-number != '' && needs.params.outputs.dry-run != 'true'
         uses: ./.github/agentic-lib/actions/commit-if-changed
@@ -822,10 +828,15 @@ jobs:
 
       - name: Summary
         run: |
+          REPO="${{ github.repository }}"
+          OWNER="${REPO%%/*}"
+          REPO_NAME="${REPO##*/}"
+          SITE_URL="https://${OWNER}.github.io/${REPO_NAME}/"
           echo "## agentic-lib-workflow run summary" >> $GITHUB_STEP_SUMMARY
           echo "- Mode: ${{ needs.params.outputs.mode }}" >> $GITHUB_STEP_SUMMARY
           echo "- Model: ${{ needs.params.outputs.model }}" >> $GITHUB_STEP_SUMMARY
           echo "- Dry-run: ${{ needs.params.outputs.dry-run }}" >> $GITHUB_STEP_SUMMARY
+          echo "- Website: [${SITE_URL}](${SITE_URL})" >> $GITHUB_STEP_SUMMARY
 
   # ─── Schedule change (if requested) ────────────────────────────────
   update-schedule:

package/agentic-lib.toml

@@ -14,6 +14,7 @@ source = "test/src/lib/"                        #@dist "src/lib/"
 tests = "test/tests/unit/"                      #@dist "tests/unit/"
 features = "test/features/"                     #@dist "features/"
 library = "test/library/"                       #@dist "library/"
+web = "test/src/web/"                            #@dist "src/web/"
 docs = "test/docs/"                             #@dist "docs/"
 examples = "test/examples/"                     #@dist "examples/"
 readme = "test/README.md"                       #@dist "README.md"

package/bin/agentic-lib.js

@@ -886,6 +886,7 @@ function readTomlPaths() {
   let sourcePath = "src/lib/";
   let testsPath = "tests/unit/";
   let examplesPath = "examples/";
+  let webPath = "src/web/";
   const tomlTarget = resolve(target, "agentic-lib.toml");
   if (existsSync(tomlTarget)) {
     try {
@@ -893,14 +894,16 @@ function readTomlPaths() {
       const sourceMatch = tomlContent.match(/^source\s*=\s*"([^"]+)"/m);
       const testsMatch = tomlContent.match(/^tests\s*=\s*"([^"]+)"/m);
       const examplesMatch = tomlContent.match(/^examples\s*=\s*"([^"]+)"/m);
+      const webMatch = tomlContent.match(/^web\s*=\s*"([^"]+)"/m);
       if (sourceMatch) sourcePath = sourceMatch[1];
       if (testsMatch) testsPath = testsMatch[1];
       if (examplesMatch) examplesPath = examplesMatch[1];
+      if (webMatch) webPath = webMatch[1];
     } catch (err) {
       console.log(`  WARN: Could not read TOML for paths, using defaults: ${err.message}`);
     }
   }
-  return { sourcePath, testsPath, examplesPath };
+  return { sourcePath, testsPath, examplesPath, webPath };
 }
 
 function clearAndRecreateDir(dirPath, label) {
@@ -916,16 +919,19 @@ function clearAndRecreateDir(dirPath, label) {
 function initPurge(seedsDir, missionName) {
   console.log("\n--- Purge: Reset Source Files to Seed State ---");
 
-  const { sourcePath, testsPath, examplesPath } = readTomlPaths();
+  const { sourcePath, testsPath, examplesPath, webPath } = readTomlPaths();
   clearAndRecreateDir(sourcePath, sourcePath);
   clearAndRecreateDir(testsPath, testsPath);
   clearAndRecreateDir(examplesPath, examplesPath);
+  clearAndRecreateDir(webPath, webPath);
   clearAndRecreateDir("docs", "docs");
 
   // Copy seed files (including config TOML) — MISSION.md handled separately via mission seed
   const SEED_MAP = {
     "zero-main.js": "src/lib/main.js",
     "zero-main.test.js": "tests/unit/main.test.js",
+    "zero-index.html": "src/web/index.html",
+    "zero-web.test.js": "tests/unit/web.test.js",
     "zero-SOURCES.md": "SOURCES.md",
     "zero-package.json": "package.json",
     "zero-README.md": "README.md",
@@ -938,6 +944,18 @@ function initPurge(seedsDir, missionName) {
     }
   }
 
+  // Bootstrap docs/ for GitHub Pages — copy web seed so the site is available immediately
+  const webSeed = resolve(seedsDir, "zero-index.html");
+  if (existsSync(webSeed)) {
+    const docsDir = resolve(target, "docs");
+    if (!dryRun) {
+      mkdirSync(docsDir, { recursive: true });
+      writeFileSync(resolve(docsDir, ".nojekyll"), "");
+    }
+    initCopyFile(webSeed, resolve(docsDir, "index.html"), "SEED: zero-index.html → docs/index.html");
+    console.log("  CREATE: docs/.nojekyll");
+  }
+
   // Force-overwrite agentic-lib.toml during purge (transformed from root)
   const tomlSource = resolve(pkgRoot, "agentic-lib.toml");
   if (existsSync(tomlSource)) {
@@ -1118,6 +1136,31 @@ function initPurgeGitHub() {
   } catch (err) {
     console.log(`  SKIP: Could not create discussion (${err.message})`);
   }
+
+  // Enable GitHub Pages (serve from docs/ on main branch)
+  console.log("\n--- Enable GitHub Pages ---");
+  try {
+    if (!dryRun) {
+      execSync(
+        `gh api repos/${repoSlug}/pages -X POST -f build_type=legacy -f "source[branch]=main" -f "source[path]=/docs"`,
+        { cwd: target, encoding: "utf8", timeout: 15000, stdio: ["pipe", "pipe", "pipe"] },
+      );
+      console.log(`  ENABLED: GitHub Pages from docs/ on main`);
+      console.log(`  URL: https://${owner}.github.io/${repo}/`);
+      initChanges++;
+    } else {
+      console.log(`  ENABLE: GitHub Pages from docs/ on main (dry run)`);
+      console.log(`  URL: https://${owner}.github.io/${repo}/`);
+      initChanges++;
+    }
+  } catch (err) {
+    if (err.message?.includes("409") || err.stderr?.includes("409")) {
+      console.log("  SKIP: GitHub Pages already enabled");
+    } else {
+      console.log(`  SKIP: Could not enable GitHub Pages (${err.message})`);
+      console.log(`  Manual: Settings → Pages → Source: Deploy from branch, Branch: main, Folder: /docs`);
+    }
+  }
 }
 
 function runInit() {

package/package.json

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

package/src/agents/agent-discussion-bot.md

@@ -47,9 +47,22 @@ You can request the supervisor to:
 - Review and close issues
 - Fix failing PRs
 - Create new issues from feature ideas
+- Re-seed the repository with a new mission (via `init --purge --mission <name>`)
 
 When relaying supervisor responses back to the user, present them naturally as your own awareness of what's happening in the repository.
 
+## Feature Requests and Re-Seeds
+
+Users can ask for new features or mission changes through this discussion thread:
+
+- **Feature requests** — When a user says "add feature X" or "I want Y", acknowledge the request and pass it to the supervisor to create a GitHub issue. The pipeline will pick it up and implement it.
+- **Re-seed requests** — When a user says "change the mission to Z" or "re-seed with plot-code-lib", explain that this requires running `npx @xn-intenton-z2a/agentic-lib init --purge --mission <name>`. List the available missions if asked: hamming-distance, fizz-buzz, roman-numerals, string-utils, dense-encoding, cron-engine, owl-ontology, plot-code-lib, time-series-lab, lunar-lander, empty. Note that re-seeding resets all source code, issues, and discussions.
+- **Website feedback** — The project has a website published via GitHub Pages. If a user comments on the website, pass feedback to the supervisor to create an issue for the pipeline to address.
+
+## Website Awareness
+
+The repository publishes a website via GitHub Pages that showcases the library. The URL follows the pattern `https://<owner>.github.io/<repo>/`. When discussing the project, mention the website as a way for users to see the library in action.
+
 ## Conversation Style
 
 - Use previous interactions to build rapport — reference things the user mentioned before

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

@@ -21,3 +21,17 @@ When implementing features, also produce evidence artifacts under `docs/`:
 
 Design the library API with hooks that make evidence capture easy: return structured result objects,
 support `outputFile` options where appropriate, and emit results that observers can record.
+
+## Website Showcase
+
+Maintain a website in `src/web/` that visually demonstrates the library's capabilities. The website is
+published to GitHub Pages automatically (from `docs/` via `npm run build:web`).
+
+- `src/web/index.html` is the main page — evolve it to showcase the library interactively
+- You may add CSS, JS, images, or additional HTML pages in `src/web/`
+- The website should demonstrate what the library does in a way a visitor can see and interact with
+- Keep it self-contained (no external CDN dependencies unless essential)
+- Link back to the repository for source code and mission details
+- When the library produces visual output (plots, graphs, data), embed or render it on the website
+- When the library is computational (algorithms, utilities), create an interactive demo or show example results
+- The website tests in `tests/unit/web.test.js` verify the HTML exists and is structurally valid — you may extend them

package/src/agents/agent-supervisor.md

@@ -38,6 +38,7 @@ When open issues with the `automated` label lack the `ready` label and are more
 ### Mission Initialised (init completed)
 When recent workflow runs show an init completion, the repository has a fresh or updated mission.
 Dispatch the discussions bot to announce the new mission to the community.
+Include the website URL in the announcement — the site is at `https://<owner>.github.io/<repo>/`.
 
 ### Mission Accomplished (bounded missions)
 When ALL of the following conditions are met, the mission is accomplished:
@@ -47,7 +48,7 @@ When ALL of the following conditions are met, the mission is accomplished:
 4. Evidence artifacts exist under `docs/` (example outputs, test results, or walkthroughs)
 
 When all conditions are met:
-1. `dispatch:agentic-lib-bot` — announce mission accomplished in the discussions thread
+1. `dispatch:agentic-lib-bot` — announce mission accomplished in the discussions thread. Include the website URL (`https://<owner>.github.io/<repo>/`) so users can see the finished product.
 2. `set-schedule:off` — stop the workflow. The mission is done.
 3. Log `mission-accomplished` in the activity log.
 
@@ -81,6 +82,7 @@ Also check for notable progress worth reporting:
 - Mission milestones achieved (all core functions implemented, all tests passing)
 - Schedule changes (mission accomplished, throttling down)
 - Significant code changes (large PRs merged, new features completed)
+- Website first deployed or significantly updated (include the URL: `https://<owner>.github.io/<repo>/`)
 
 When notable progress exists or there are unresponded referrals, use `respond:discussions | message: <status update> | discussion-url: <url>` to post an update. Keep it concise — 2-3 sentences summarising what happened and what's next.
 

package/src/seeds/missions/c64-emulator.md

@@ -0,0 +1,110 @@
+# Mission
+
+A JavaScript Commodore 64 emulator capable of running the classic game "The Lords of Midnight" (1984, Mike Singleton).
+
+## Architecture
+
+The emulator is structured as layered components, each independently testable:
+
+1. **MOS 6510 CPU** — the core processor (6502 variant with I/O port at $00/$01)
+2. **Memory subsystem** — 64KB RAM, ROM banking (BASIC, KERNAL, character ROM), I/O area ($D000–$DFFF)
+3. **VIC-II video** — text mode (40x25), bitmap mode, sprites, raster interrupt timing
+4. **SID sound** — 3-voice synthesiser with ADSR envelopes (basic waveform generation)
+5. **CIA timers** — two CIA chips for keyboard scanning, timer interrupts, and joystick input
+6. **Input** — keyboard matrix and joystick mapped to browser events
+7. **PRG/TAP loader** — load `.prg` files (and optionally `.tap` tape images) into memory
+
+## Core Functions
+
+Export all from `src/lib/main.js`:
+
+- `createC64(opts?)` — create an emulator instance with default ROMs and 64KB RAM. Returns an object with `cpu`, `memory`, `vic`, `sid`, `cia1`, `cia2` subsystems.
+- `loadPRG(c64, data)` — load a `.prg` file (Uint8Array) into memory at the address specified in its two-byte header.
+- `step(c64)` — execute one CPU instruction, advance cycle count, and update timers. Returns the new state.
+- `runFrame(c64)` — execute instructions for one video frame (~19656 cycles PAL). Trigger raster interrupts at the appropriate scanlines. Returns the framebuffer.
+- `getFramebuffer(c64)` — return the current screen as a Uint8Array RGBA pixel buffer (320x200 or 384x272 with borders).
+- `pressKey(c64, key)` / `releaseKey(c64, key)` — simulate keyboard input via CIA1 keyboard matrix.
+- `joystickInput(c64, port, directions)` — set joystick state (up/down/left/right/fire) on port 1 or 2.
+- `reset(c64)` — perform a hardware reset (set CPU to reset vector, clear state).
+
+## CPU Requirements
+
+- All official 6502 opcodes (56 instructions, 151 opcode variants) with correct cycle counts.
+- Decimal mode (BCD arithmetic) support.
+- IRQ and NMI interrupt handling with correct stack behaviour.
+- The 6510 I/O port at $00/$01 for ROM/RAM bank switching.
+- Undocumented/illegal opcodes are NOT required (may be implemented as NOP).
+
+## Memory Map
+
+- $0000–$00FF: Zero page
+- $0100–$01FF: Stack
+- $0200–$9FFF: Free RAM (programs load here)
+- $A000–$BFFF: BASIC ROM (banked, RAM underneath)
+- $C000–$CFFF: Free RAM
+- $D000–$D3FF: VIC-II registers
+- $D400–$D7FF: SID registers
+- $D800–$DBFF: Colour RAM (nibbles)
+- $DC00–$DCFF: CIA1 (keyboard, joystick, timer)
+- $DD00–$DDFF: CIA2 (serial, timer, VIC bank)
+- $E000–$FFFF: KERNAL ROM (banked, RAM underneath)
+
+## Video (VIC-II)
+
+- Standard text mode (mode 0) — 40x25 characters, 16 colours, character ROM.
+- Multicolour text mode.
+- Standard bitmap mode (320x200) and multicolour bitmap mode (160x200).
+- Hardware sprites (8 sprites, 24x21 pixels, multicolour optional).
+- Raster interrupt — trigger IRQ at a programmable scanline.
+- Border colour and background colour registers.
+- Correct raster timing is essential — Lords of Midnight uses raster effects.
+
+## Sound (SID — basic)
+
+- 3 oscillator voices with waveform selection (triangle, sawtooth, pulse, noise).
+- ADSR envelope per voice.
+- Frequency and pulse-width registers.
+- Audio output as PCM sample buffer suitable for Web Audio API playback.
+- Full filter emulation is NOT required (passthrough acceptable).
+
+## Input
+
+- CIA1 keyboard matrix scan — map browser `KeyboardEvent` codes to the C64 8x8 keyboard matrix.
+- Joystick via CIA1 ($DC01 port 1) and CIA1 ($DC00 port 2) — Lords of Midnight uses keyboard, but joystick support enables other games.
+
+## Lords of Midnight Compatibility
+
+The target game exercises these specific features:
+- Custom character sets (redefined at $3000 or similar)
+- Full keyboard input (directional + action keys)
+- Raster interrupts for split-screen effects
+- IRQ-driven game loop timing via CIA timer
+- PRG loading at the correct start address
+
+## Requirements
+
+- No external dependencies for the core emulator (Web Audio API and Canvas API are browser-provided).
+- KERNAL and BASIC ROMs must NOT be bundled (they are copyrighted). Provide a `loadROMs(c64, { kernal, basic, chargen })` function. Tests should use minimal stub ROMs.
+- Comprehensive unit tests for each subsystem:
+  - CPU: test each addressing mode and instruction, verify cycle counts, test interrupt handling.
+  - Memory: test bank switching, I/O area mapping.
+  - VIC-II: test mode switching, framebuffer output for known register states.
+  - Input: test keyboard matrix encoding/decoding.
+- Integration test: load a small test PRG that writes to screen memory and verify framebuffer output.
+- README with architecture overview, usage example, and instructions for obtaining legal ROM dumps.
+
+## Acceptance Criteria
+
+- [ ] CPU executes all 151 official opcodes with correct results and cycle counts
+- [ ] CPU handles IRQ and NMI interrupts correctly (push PC+flags, jump to vector)
+- [ ] Memory bank switching works ($01 register controls ROM/RAM visibility)
+- [ ] VIC-II text mode renders 40x25 character display to framebuffer
+- [ ] VIC-II raster interrupt fires at the programmed scanline
+- [ ] SID produces audible waveform output for at least triangle and pulse waves
+- [ ] CIA1 keyboard matrix correctly maps key presses to the scanned row/column
+- [ ] `loadPRG()` places data at the correct address from the PRG header
+- [ ] `runFrame()` executes approximately the right number of cycles per frame (PAL timing)
+- [ ] A test PRG that writes "HELLO" to screen RAM ($0400) produces correct framebuffer output
+- [ ] `reset()` returns the emulator to a known initial state
+- [ ] All unit tests pass
+- [ ] README documents architecture and ROM loading

package/src/seeds/zero-index.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>repository0</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; max-width: 800px; margin: 0 auto; padding: 2rem; color: #333; }
+    h1 { border-bottom: 2px solid #eee; padding-bottom: 0.5rem; }
+    a { color: #0366d6; }
+    .status { background: #f6f8fa; padding: 1rem; border-radius: 6px; margin: 1rem 0; }
+  </style>
+</head>
+<body>
+  <h1>repository0</h1>
+  <div class="status">
+    <p>This website is maintained by the autonomous pipeline. It showcases the library built from the project's mission.</p>
+  </div>
+  <h2>About</h2>
+  <p>See <a href="https://github.com/xn-intenton-z2a/repository0">the repository</a> for source code and mission details.</p>
+  <h2>Demo</h2>
+  <p><em>The pipeline will evolve this section to demonstrate the library's capabilities.</em></p>
+</body>
+</html>

package/src/seeds/zero-package.json

@@ -5,16 +5,18 @@
   "type": "module",
   "main": "src/lib/main.js",
   "scripts": {
-    "build": "echo \"Nothing to build\"",
+    "build": "npm run build:web",
+    "build:web": "mkdir -p docs && touch docs/.nojekyll && cp -r src/web/* docs/ 2>/dev/null || echo 'No web files to build'",
     "test": "vitest --run tests/unit/*.test.js",
     "test:unit": "vitest --run --coverage tests/unit/*.test.js",
-    "start": "node src/lib/main.js"
+    "start": "node src/lib/main.js",
+    "start:web": "npx serve docs"
   },
   "keywords": [],
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xn-intenton-z2a/agentic-lib": "^7.1.62"
+    "@xn-intenton-z2a/agentic-lib": "^7.1.63"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",

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

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2025-2026 Polycode Limited
+import { describe, test, expect } from "vitest";
+import { readFileSync, existsSync } from "fs";
+
+describe("Website", () => {
+  test("src/web/index.html exists", () => {
+    expect(existsSync("src/web/index.html")).toBe(true);
+  });
+
+  test("index.html contains valid HTML structure", () => {
+    const html = readFileSync("src/web/index.html", "utf8");
+    expect(html).toContain("<!DOCTYPE html>");
+    expect(html).toContain("<html");
+    expect(html).toContain("</html>");
+  });
+});