@xn-intenton-z2a/agentic-lib 7.1.66 → 7.1.68

package/agentic-lib.toml

@@ -70,7 +70,7 @@ infinite-sessions = false        # set to true for long sessions with compaction
 # Fast & cheap — CI testing, quick validation, budget-conscious iteration.
 reasoning-effort = "low"                # low | medium | high | none
 infinite-sessions = false               # enable session compaction for long runs
-transformation-budget = 4              # max code-changing cycles per run
+transformation-budget = 16             # max code-changing cycles per run
 max-feature-files = 3                      # max feature files included in prompts
 max-source-files = 3                        # max source files included in prompts
 max-source-chars = 1000                  # max chars of each source file's content included in prompts
@@ -91,7 +91,7 @@ library-limit = 8                      # max library entries in library/ directo
 # Balanced — good results without excessive cost. Default for consumer repos.
 reasoning-effort = "medium"            # low | medium | high | none
 infinite-sessions = true               # enable session compaction for long runs
-transformation-budget = 8             # max code-changing cycles per run
+transformation-budget = 32             # max code-changing cycles per run
 max-feature-files = 10                     # max feature files included in prompts
 max-source-files = 10                       # max source files included in prompts
 max-source-chars = 5000                  # max chars of each source file's content included in prompts
@@ -112,7 +112,7 @@ library-limit = 32                     # max library entries in library/ directo
 # Thorough — maximum context, highest quality. For complex missions.
 reasoning-effort = "high"              # low | medium | high | none
 infinite-sessions = true               # enable session compaction for long runs
-transformation-budget = 32            # max code-changing cycles per run
+transformation-budget = 128           # max code-changing cycles per run
 max-feature-files = 50                     # max feature files included in prompts
 max-source-files = 50                       # max source files included in prompts
 max-source-chars = 20000                 # max chars of each source file's content included in prompts

package/package.json

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

package/src/actions/agentic-step/config-loader.js

@@ -35,7 +35,7 @@ import { parse as parseToml } from "smol-toml";
  */
 
 // Keys whose paths are writable by agents
-const WRITABLE_KEYS = ["source", "tests", "features", "dependencies", "docs", "readme", "examples"];
+const WRITABLE_KEYS = ["source", "tests", "features", "dependencies", "docs", "readme", "examples", "web"];
 
 // Default paths — every key that task handlers might access
 const PATH_DEFAULTS = {
@@ -50,6 +50,7 @@ const PATH_DEFAULTS = {
   library: "library/",
   librarySources: "SOURCES.md",
   contributing: "CONTRIBUTING.md",
+  web: "src/web/",
 };
 
 // Default limits for path-specific constraints
@@ -63,7 +64,7 @@ const LIMIT_DEFAULTS = {
 const FALLBACK_TUNING = {
   reasoningEffort: "medium",
   infiniteSessions: true,
-  transformationBudget: 8,
+  transformationBudget: 32,
   featuresScan: 10,
   sourceScan: 10,
   sourceContent: 5000,
@@ -92,7 +93,7 @@ function parseTuningProfile(profileSection) {
   return {
     reasoningEffort: profileSection["reasoning-effort"] || "medium",
     infiniteSessions: profileSection["infinite-sessions"] ?? true,
-    transformationBudget: profileSection["transformation-budget"] || 8,
+    transformationBudget: profileSection["transformation-budget"] || 32,
     featuresScan: profileSection["max-feature-files"] || 10,
     sourceScan: profileSection["max-source-files"] || 10,
     sourceContent: profileSection["max-source-chars"] || 5000,

package/src/actions/agentic-step/index.js

@@ -101,7 +101,7 @@ async function run() {
 
     // Compute limits status for enriched logging
     const limitsStatus = [
-      { name: "transformation-budget", valueNum: 0, capacityNum: config.transformationBudget || 0, value: `0/${config.transformationBudget || 0}`, remaining: `${config.transformationBudget || 0} remaining`, status: "" },
+      { name: "transformation-budget", valueNum: 0, capacityNum: config.transformationBudget || 0, value: `0/${config.transformationBudget || 0}`, remaining: `${config.transformationBudget || 0}`, status: "" },
       { name: "max-feature-issues", valueNum: 0, capacityNum: config.featureDevelopmentIssuesWipLimit, value: `?/${config.featureDevelopmentIssuesWipLimit}`, remaining: "?", status: "" },
       { name: "max-maintenance-issues", valueNum: 0, capacityNum: config.maintenanceIssuesWipLimit, value: `?/${config.maintenanceIssuesWipLimit}`, remaining: "?", status: "" },
       { name: "max-attempts-per-issue", valueNum: 0, capacityNum: config.attemptsPerIssue, value: `?/${config.attemptsPerIssue}`, remaining: "?", status: task === "resolve-issue" ? "" : "n/a" },
@@ -122,7 +122,7 @@ async function run() {
     const profileName = config.tuning?.profileName || "unknown";
 
     // Transformation cost: 1 for code-changing tasks, 0 otherwise
-    const COST_TASKS = ["transform", "fix-code"];
+    const COST_TASKS = ["transform", "fix-code", "maintain-features", "maintain-library"];
     const isNop = result.outcome === "nop" || result.outcome === "error";
     const transformationCost = COST_TASKS.includes(task) && !isNop ? 1 : 0;
 
@@ -151,6 +151,7 @@ async function run() {
         promptBudget: result.promptBudget,
         closingNotes,
         transformationCost,
+        narrative: result.narrative,
       });
     }
 

package/src/actions/agentic-step/logging.js

@@ -34,6 +34,7 @@ import * as core from "@actions/core";
  * @param {Array} [options.promptBudget] - Prompt budget entries { section, size, files, notes }
  * @param {string} [options.closingNotes] - Auto-generated limit concern notes
  * @param {number} [options.transformationCost] - Transformation cost for this entry (0 or 1)
+ * @param {string} [options.narrative] - LLM-generated narrative description of the change
  */
 export function logActivity({
   filepath,
@@ -57,6 +58,7 @@ export function logActivity({
   promptBudget,
   closingNotes,
   transformationCost,
+  narrative,
 }) {
   const dir = dirname(filepath);
   if (!existsSync(dir)) {
@@ -110,6 +112,10 @@ export function logActivity({
     parts.push("", "### Closing Notes");
     parts.push(closingNotes);
   }
+  if (narrative) {
+    parts.push("", "### Narrative");
+    parts.push(narrative);
+  }
   if (details) {
     parts.push("");
     parts.push(details);

package/src/actions/agentic-step/tasks/fix-code.js

@@ -98,7 +98,7 @@ async function resolveConflicts({ config, pr, prNumber, instructions, model, wri
   ].join("\n");
 
   const t = config.tuning || {};
-  const { tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
+  const { tokensUsed, inputTokens, outputTokens, cost, content: resultContent } = await runCopilotTask({
     model,
     systemMessage: `You are resolving git merge conflicts on PR #${prNumber}. Write resolved versions of each conflicted file, removing all conflict markers. Preserve the PR's feature intent while incorporating main's updates.`,
     prompt,
@@ -116,6 +116,7 @@ async function resolveConflicts({ config, pr, prNumber, instructions, model, wri
     cost,
     model,
     details: `Resolved ${conflicts.length} conflicted file(s) on PR #${prNumber}`,
+    narrative: (resultContent || "").substring(0, 2000),
   };
 }
 
@@ -186,7 +187,7 @@ export async function fixCode(context) {
   ].join("\n");
 
   const t = config.tuning || {};
-  const { tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
+  const { tokensUsed, inputTokens, outputTokens, cost, content: resultContent } = await runCopilotTask({
     model,
     systemMessage: `You are an autonomous coding agent fixing failing tests on PR #${prNumber}. Make minimal, targeted changes to fix the test failures.`,
     prompt,
@@ -204,5 +205,6 @@ export async function fixCode(context) {
     cost,
     model,
     details: `Applied fix for ${failedChecks.length} failing check(s) on PR #${prNumber}`,
+    narrative: (resultContent || "").substring(0, 2000),
   };
 }

package/src/actions/agentic-step/tasks/resolve-issue.js

@@ -99,5 +99,6 @@ export async function resolveIssue(context) {
     model,
     commitUrl: null,
     details: `Generated code for issue #${issueNumber}: ${resultContent.substring(0, 200)}`,
+    narrative: (resultContent || "").substring(0, 2000),
   };
 }

package/src/actions/agentic-step/tasks/review-issue.js

@@ -46,6 +46,13 @@ async function reviewSingleIssue({ octokit, repo, config, targetIssueNumber, ins
     sortByMtime: true,
     clean: true,
   });
+  const webFiles = scanDirectory(config.paths.web?.path || "src/web/", [".html", ".css", ".js"], {
+    fileLimit: t.sourceScan || 20,
+    contentLimit: t.sourceContent || 5000,
+    recursive: true,
+    sortByMtime: true,
+    clean: true,
+  });
   const docsFiles = scanDirectory(config.paths.documentation?.path || "docs/", [".md"], {
     fileLimit: t.featuresScan || 10,
     contentLimit: t.documentSummary || 2000,
@@ -66,6 +73,14 @@ async function reviewSingleIssue({ octokit, repo, config, targetIssueNumber, ins
     `## Current Tests (${testFiles.length} files)`,
     ...testFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
     "",
+    ...(webFiles.length > 0
+      ? [
+          `## Website Files (${webFiles.length} files)`,
+          "The website in `src/web/` uses the JS library.",
+          ...webFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
+          "",
+        ]
+      : []),
     ...(docsFiles.length > 0
       ? [`## Documentation (${docsFiles.length} files)`, ...docsFiles.map((f) => `- ${f.name}`), ""]
       : []),

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

@@ -41,6 +41,13 @@ export async function transform(context) {
     clean: true,
     outline: true,
   });
+  const webFiles = scanDirectory(config.paths.web?.path || "src/web/", [".html", ".css", ".js"], {
+    fileLimit: t.sourceScan || 10,
+    contentLimit: t.sourceContent || 5000,
+    recursive: true,
+    sortByMtime: true,
+    clean: true,
+  });
 
   const { data: rawIssues } = await octokit.rest.issues.listForRepo({
     ...repo,
@@ -79,6 +86,7 @@ export async function transform(context) {
       mission,
       features,
       sourceFiles,
+      webFiles,
       openIssues,
       tuning: t,
     });
@@ -107,6 +115,16 @@ export async function transform(context) {
     `## Current Source Files (${sourceFiles.length})`,
     ...sourceFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
     "",
+    ...(webFiles.length > 0
+      ? [
+          `## 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.",
+          ...webFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
+          "",
+        ]
+      : []),
     `## Open Issues (${openIssues.length})`,
     ...openIssues.slice(0, t.issuesScan || 20).map((i) => summariseIssue(i, t.issueBodyLimit || 500)),
     "",
@@ -183,6 +201,7 @@ export async function transform(context) {
     cost,
     model,
     details: resultContent.substring(0, 500),
+    narrative: (resultContent || "").substring(0, 2000),
     promptBudget,
     contextNotes: `Transformed with ${sourceFiles.length} source files (mtime-sorted, cleaned), ${features.length} features, ${openIssues.length} issues (${rawIssues.length - openIssues.length} stale filtered).`,
   };
@@ -201,6 +220,7 @@ async function transformTdd({
   mission,
   features,
   sourceFiles,
+  webFiles,
   openIssues,
   tuning: t,
 }) {
@@ -228,6 +248,14 @@ async function transformTdd({
     `## Current Source Files (${sourceFiles.length})`,
     ...sourceFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
     "",
+    ...(webFiles.length > 0
+      ? [
+          `## Website Files (${webFiles.length})`,
+          "The website in `src/web/` uses the JS library.",
+          ...webFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
+          "",
+        ]
+      : []),
     `## Open Issues (${openIssues.length})`,
     ...openIssues.slice(0, t.issuesScan || 20).map((i) => summariseIssue(i, t.issueBodyLimit || 500)),
     "",
@@ -272,6 +300,14 @@ async function transformTdd({
     `## Current Source Files (${sourceFiles.length})`,
     ...sourceFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
     "",
+    ...(webFiles.length > 0
+      ? [
+          `## Website Files (${webFiles.length})`,
+          "The website in `src/web/` uses the JS library. Update it to reflect any new features.",
+          ...webFiles.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
+          "",
+        ]
+      : []),
     formatPathsSection(writablePaths, readOnlyPaths, _config),
     "",
     "## Output Artifacts",

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

@@ -12,6 +12,9 @@ You may complete the implementation of a feature and/or bring the code output in
 or other documentation. Do as much as you can all at once so that the build runs (even with nothing
 to build) and the tests pass and the main at least doesn't output an error.
 
+The repository has a website in `src/web/` that uses the JS library. If a fix affects library
+exports or behaviour, also update the website files to stay in sync.
+
 ## Merge Conflict Resolution
 
 When resolving merge conflicts (files containing <<<<<<< / ======= / >>>>>>> markers):

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

@@ -57,11 +57,11 @@ 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 feedback** — The project has a website that uses the JS library, 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.
+The repository publishes a website via GitHub Pages that uses the JS library. The URL follows the pattern `https://<owner>.github.io/<repo>/`. The website imports the library and displays its output. When discussing the project, mention the website as a way to see the library in action.
 
 ## Conversation Style
 

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

@@ -22,16 +22,29 @@ 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
+## Website
 
-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`).
+The repository has a website in `src/web/` that uses the JS library. It 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
+### 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
+
+### What to do with the website
+
+- **Use the library**: Import the library (or its browser-compatible parts) and call its functions on the page
+- **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
+
+### Guidelines
+
+- `src/web/index.html` is the main page — update it as the library grows
 - 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
+- The website tests in `tests/unit/web.test.js` verify structure and library wiring — extend them as needed
+- The website is not the mission — it supports the library. Don't over-invest in the website at the expense of the library

package/src/agents/agent-maintain-features.md

@@ -27,3 +27,4 @@ Features must be achievable in a single software repository not part of a corpor
 The feature spec should be a multiline markdown with a few level 1 headings.
 The feature must be compatible with the mission statement in MISSION.md and ideally realise part of the value in the mission.
 The feature must be something that can be realised in a single source file (as below), ideally just as a library, CLI tool or possibly an HTTP API in combination with infrastructure as code deployment.
+The repository also has a website in `src/web/` that uses the JS library. When proposing features, consider both the library API and how the feature could be shown on the website.

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

@@ -1,5 +1,6 @@
-Does the combination source file, test file, README file and dependencies file show a solution
+Does the combination source file, test file, website files, README file and dependencies file show a solution
 with a reasonable likelihood of including a high-impact resolution to the following issue? Evaluate whether the solution delivers substantial user value, addresses core functionality needs, and directly enhances the product's primary purpose rather than implementing superficial improvements or excessive validation.
+Note: The repository has a website in `src/web/` that uses the JS library. When reviewing, check that website files are updated alongside library changes.
 
 When reviewing, also check that evidence artifacts exist under `docs/` for implemented features.
 If a feature works but has no evidence (no example outputs, test results, or walkthroughs in `docs/`),

package/src/agents/agent-supervisor.md

@@ -38,7 +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>/`.
+Include the website URL in the announcement — the site is at `https://<owner>.github.io/<repo>/` and runs the library.
 
 ### Mission Accomplished (bounded missions)
 When ALL of the following conditions are met, the mission is accomplished:
@@ -48,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. Include the website URL (`https://<owner>.github.io/<repo>/`) so users can see the finished product.
+1. `dispatch:agentic-lib-bot` — announce mission accomplished in the discussions thread. Include the website URL (`https://<owner>.github.io/<repo>/`) where 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.
 

package/src/agents/agentic-lib.yml

@@ -25,6 +25,9 @@ paths:
   targetSourcePath:
     path: "src/lib/"
     permissions: ["write"]
+  targetWebPath:
+    path: "src/web/"
+    permissions: ["write"]
   dependenciesFilepath:
     path: "package.json"
     permissions: ["write"]

package/src/seeds/zero-index.html

@@ -4,21 +4,59 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>repository0</title>
+  <meta property="og:title" content="repository0">
+  <meta property="og:description" content="An autonomous repository powered by agentic-lib">
+  <meta property="og:type" content="website">
   <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; }
+    .identity { background: #f6f8fa; padding: 1rem; border-radius: 6px; margin: 1rem 0; font-family: monospace; }
+    .identity dt { font-weight: bold; color: #666; }
+    .identity dd { margin: 0 0 0.5rem 0; font-size: 1.1rem; }
+    .social { display: flex; gap: 1rem; margin: 1rem 0; flex-wrap: wrap; }
+    .social a { display: inline-block; padding: 0.4rem 0.8rem; border: 1px solid #ddd; border-radius: 4px; text-decoration: none; font-size: 0.9rem; }
+    .social a:hover { background: #f6f8fa; }
+    #demo-output { background: #1e1e1e; color: #d4d4d4; padding: 1rem; border-radius: 6px; font-family: monospace; white-space: pre-wrap; min-height: 2rem; }
   </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>
+  <h1 id="lib-name">repository0</h1>
+  <div class="identity">
+    <dl>
+      <dt>Version</dt>
+      <dd id="lib-version">loading...</dd>
+      <dt>Description</dt>
+      <dd id="lib-description">loading...</dd>
+    </dl>
+  </div>
+  <h2>Output</h2>
+  <div id="demo-output">Loading library...</div>
+  <h2>Links</h2>
+  <div class="social">
+    <a id="share-github" href="https://github.com/xn-intenton-z2a/repository0" target="_blank" rel="noopener">GitHub</a>
+    <a id="share-twitter" href="#" target="_blank" rel="noopener">X/Twitter</a>
+    <a id="share-linkedin" href="#" target="_blank" rel="noopener">LinkedIn</a>
   </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>
+  <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');
+      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;
+      const pageUrl = encodeURIComponent(window.location.href);
+      const text = encodeURIComponent('Check out ' + name + ' v' + version + ' — ' + description);
+      document.getElementById('share-twitter').href = 'https://x.com/intent/tweet?url=' + pageUrl + '&text=' + text;
+      document.getElementById('share-linkedin').href = 'https://www.linkedin.com/sharing/share-offsite/?url=' + pageUrl;
+    } 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';
+    }
+  </script>
 </body>
 </html>

package/src/seeds/zero-main.js

@@ -3,10 +3,30 @@
 // Copyright (C) 2025-2026 Polycode Limited
 // src/lib/main.js
 
+import { createRequire } from "module";
 import { fileURLToPath } from "url";
 
+const require = createRequire(import.meta.url);
+const pkg = require("../../package.json");
+
+export const name = pkg.name;
+export const version = pkg.version;
+export const description = pkg.description;
+
+export function getIdentity() {
+  return { name, version, description };
+}
+
 export function main(args) {
-  console.log(`Run with: ${JSON.stringify(args)}`);
+  if (args?.includes("--version")) {
+    console.log(version);
+    return;
+  }
+  if (args?.includes("--identity")) {
+    console.log(JSON.stringify(getIdentity(), null, 2));
+    return;
+  }
+  console.log(`${name}@${version}`);
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (C) 2025-2026 Polycode Limited
-import { describe, test } from "vitest";
-import { main } from "../../src/lib/main.js";
+import { describe, test, expect } from "vitest";
+import { main, getIdentity, name, version, description } from "../../src/lib/main.js";
 
 describe("Main Output", () => {
   test("should terminate without error", () => {
@@ -9,3 +9,18 @@ describe("Main Output", () => {
     main();
   });
 });
+
+describe("Library Identity", () => {
+  test("exports name, version, and description", () => {
+    expect(typeof name).toBe("string");
+    expect(typeof version).toBe("string");
+    expect(typeof description).toBe("string");
+    expect(name.length).toBeGreaterThan(0);
+    expect(version).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  test("getIdentity returns correct structure", () => {
+    const identity = getIdentity();
+    expect(identity).toEqual({ name, version, description });
+  });
+});

package/src/seeds/zero-package.json

@@ -6,17 +6,17 @@
   "main": "src/lib/main.js",
   "scripts": {
     "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'",
+    "build:web": "mkdir -p docs && touch docs/.nojekyll && cp -r src/web/* docs/ 2>/dev/null || true && node --input-type=commonjs -p \"var p=require('./package.json');['name','version','description'].map(function(k){return 'export const '+k+' = '+JSON.stringify(p[k])+';'}).join('\\n')\" > docs/lib-meta.js",
     "test": "vitest --run tests/unit/*.test.js",
     "test:unit": "vitest --run --coverage tests/unit/*.test.js",
-    "start": "node src/lib/main.js",
-    "start:web": "npx serve docs"
+    "start": "npm run build:web && npx serve docs",
+    "start:cli": "node src/lib/main.js"
   },
   "keywords": [],
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xn-intenton-z2a/agentic-lib": "^7.1.66"
+    "@xn-intenton-z2a/agentic-lib": "^7.1.68"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",

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

@@ -14,4 +14,20 @@ describe("Website", () => {
     expect(html).toContain("<html");
     expect(html).toContain("</html>");
   });
+
+  test("index.html imports the library via lib-meta.js", () => {
+    const html = readFileSync("src/web/index.html", "utf8");
+    expect(html).toContain("lib-meta.js");
+  });
+
+  test("index.html displays library identity elements", () => {
+    const html = readFileSync("src/web/index.html", "utf8");
+    expect(html).toContain("lib-name");
+    expect(html).toContain("lib-version");
+  });
+
+  test("index.html has social share links", () => {
+    const html = readFileSync("src/web/index.html", "utf8");
+    expect(html).toMatch(/share.*(twitter|x\.com|linkedin)/is);
+  });
 });