4.5.0

.changeset/agent-metadata-readmes.md

@@ -0,0 +1,11 @@
+---
+'@walkeros/mcp': patch
+'@walkeros/mcp-source-browser': patch
+'@walkeros/cli': patch
+'@walkeros/transformer-validate': patch
+'@walkeros/server-transformer-fingerprint': patch
+---
+
+Add package READMEs and npm keywords. The MCP packages now ship install
+instructions for Claude Code, Cursor, and VS Code plus MCP registry metadata
+(mcpName).

.changeset/cli-path-authoritative-pin.md

@@ -0,0 +1,7 @@
+---
+'@walkeros/cli': patch
+---
+
+A `path` entry in `config.bundle.packages` now counts as the package pin, so
+bundling and setup use the local package instead of failing when steps still
+declare conflicting inline versions of it.

.changeset/cli-unified-setup-resolution.md

@@ -0,0 +1,8 @@
+---
+'@walkeros/cli': minor
+---
+
+`walkeros setup` now resolves a component's package the same way
+`walkeros bundle` does: the flow's pinned version is downloaded from the
+registry (sharing the bundle cache) and imported from there. Setup works via npx
+without a local install; `path:` packages are supported for local development.

.changeset/express-async-per-method.md

@@ -0,0 +1,13 @@
+---
+'@walkeros/server-source-express': minor
+'@walkeros/core': minor
+---
+
+The Express source's `async` option now resolves per HTTP method: a boolean
+still applies to the whole source, and a record like `{ "GET": true }` or
+`{ "POST": false }` overrides one method while the other keeps its default. The
+default changed: GET is now synchronous, so a step such as the file transformer
+or a cache can serve real content instead of the tracking GIF, while POST keeps
+the fast respond-first acknowledgement. To restore respond-first GET set
+`async: true` or `async: { "GET": true }`; configs that set `async: false` only
+to fix asset serving can drop it.

.changeset/gtag-gtm-bootstrap-push.md

@@ -0,0 +1,8 @@
+---
+'@walkeros/web-destination-gtag': minor
+---
+
+The GTM destination no longer pushes the `gtm.js` start event into the dataLayer
+unless it loads the container itself. Set `loadScript: true` to have walkerOS
+install GTM, start event included. Without it, walkerOS only pushes your mapped
+events, so an existing container's triggers are left alone.

.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "elbwalker",
+  "owner": {
+    "name": "elbwalker",
+    "url": "https://github.com/elbwalker"
+  },
+  "description": "Claude Code plugins for walkerOS, the open-source event data collection platform.",
+  "plugins": [
+    {
+      "name": "walkeros",
+      "source": "./",
+      "description": "Skills and MCP tools for walkerOS - build sources, destinations, transformers, and flows."
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -2,7 +2,10 @@
   "name": "walkeros",
   "version": "0.2.0",
   "description": "Skills and MCP tools for walkerOS - the open-source event data collection platform. Learn architecture, create sources/destinations/transformers, validate events, bundle flows, and manage projects via API.",
-  "author": "elbwalker",
+  "author": {
+    "name": "elbwalker",
+    "url": "https://github.com/elbwalker"
+  },
   "repository": "https://github.com/elbwalker/walkerOS",
   "license": "MIT",
   "keywords": [
@@ -21,28 +24,28 @@
     "mcp"
   ],
   "skills": [
-    "skills/walkeros-understanding-events",
-    "skills/walkeros-understanding-mapping",
-    "skills/walkeros-understanding-flow",
-    "skills/walkeros-understanding-destinations",
-    "skills/walkeros-understanding-sources",
-    "skills/walkeros-understanding-transformers",
-    "skills/walkeros-understanding-stores",
-    "skills/walkeros-understanding-development",
-    "skills/walkeros-using-logger",
-    "skills/walkeros-using-cli",
-    "skills/walkeros-using-store-cache",
-    "skills/walkeros-using-transformer-ga4",
-    "skills/walkeros-mcp-actions",
-    "skills/walkeros-create-cmp-source",
-    "skills/walkeros-create-destination",
-    "skills/walkeros-create-source",
-    "skills/walkeros-create-transformer",
-    "skills/walkeros-mapping-configuration",
-    "skills/walkeros-testing-strategy",
-    "skills/walkeros-debugging",
-    "skills/walkeros-writing-documentation",
-    "skills/walkeros-using-step-examples"
+    "./skills/walkeros-understanding-events",
+    "./skills/walkeros-understanding-mapping",
+    "./skills/walkeros-understanding-flow",
+    "./skills/walkeros-understanding-destinations",
+    "./skills/walkeros-understanding-sources",
+    "./skills/walkeros-understanding-transformers",
+    "./skills/walkeros-understanding-stores",
+    "./skills/walkeros-understanding-development",
+    "./skills/walkeros-using-logger",
+    "./skills/walkeros-using-cli",
+    "./skills/walkeros-using-store-cache",
+    "./skills/walkeros-using-transformer-ga4",
+    "./skills/walkeros-mcp-actions",
+    "./skills/walkeros-create-cmp-source",
+    "./skills/walkeros-create-destination",
+    "./skills/walkeros-create-source",
+    "./skills/walkeros-create-transformer",
+    "./skills/walkeros-mapping-configuration",
+    "./skills/walkeros-testing-strategy",
+    "./skills/walkeros-debugging",
+    "./skills/walkeros-writing-documentation",
+    "./skills/walkeros-using-step-examples"
   ],
   "mcpServers": {
     "walkeros-flow": {

README.md

@@ -168,6 +168,36 @@ walkerOS exposes a Model Context Protocol (MCP) interface. AI agents can read
 your event schema, suggest tracking definitions, and generate integration code -
 making your event layer programmable, not just configurable.
 
+In Claude Code, one plugin installs both MCP servers and the walkerOS skills:
+
+```
+/plugin marketplace add elbwalker/walkerOS
+/plugin install walkeros@elbwalker
+```
+
+For any other MCP client, add the servers to its configuration:
+
+```json
+{
+  "mcpServers": {
+    "walkeros-flow": {
+      "command": "npx",
+      "args": ["@walkeros/mcp"]
+    },
+    "walkeros-source-browser": {
+      "command": "npx",
+      "args": ["@walkeros/mcp-source-browser"]
+    }
+  }
+}
+```
+
+Loading a flow, validating it, and simulating an event all run locally, no
+account needed. See the [MCP docs](https://www.walkeros.io/docs/apps/mcp).
+
+Coming from Google Tag Manager? See
+[walkerOS vs. GTM](https://www.walkeros.io/docs/comparisons/gtm).
+
 ## Contributing
 
 ⭐️ Help us grow and star us. See our

apps/scripts/generate-skills-index.ts

@@ -36,7 +36,9 @@ function parseFrontmatter(input: string): Record<string, string> {
     if (top && !indented) {
       flush();
       key = top[1];
-      parts.push(top[2]);
+      // A block-scalar indicator (">-", "|", ...) is syntax, not value; the
+      // value is the indented continuation lines that follow.
+      if (!/^[>|][+-]?$/.test(top[2].trim())) parts.push(top[2]);
     } else if (key !== null) {
       parts.push(raw.trim());
     }

apps/scripts/validate-llms.ts

@@ -27,15 +27,42 @@ const BUILD_DIR = join(ROOT, 'website', 'build');
 // production builds resolve identically.
 const BASE_URL = (process.env.DOCUSAURUS_BASEURL || '/').replace(/\/*$/, '/');
 
+// The export stamps the site url on every link (`content.relativePaths: false`)
+// so llms.txt survives being pasted into a model's context or chunked away from
+// the site. Read that url from the Docusaurus config rather than repeating it,
+// so the guard and the build cannot disagree on what "absolute" means.
+function readSiteUrl(): string {
+  const config = readFileSync(
+    join(ROOT, 'website', 'docusaurus.config.ts'),
+    'utf-8',
+  );
+  // Top-level config key, two-space indented, so a nested plugin option named
+  // `url` can never be picked up instead.
+  const match = /^ {2}url: '([^']+)'/m.exec(config);
+  if (!match) {
+    console.log(
+      '❌ LLM export validation failed: no site `url` in website/docusaurus.config.ts.\n',
+    );
+    process.exit(1);
+  }
+  return match[1].replace(/\/+$/, '');
+}
+
+const SITE_URL = readSiteUrl();
+
 function emittedPath(target: string): string {
+  const pathname = target.startsWith(SITE_URL)
+    ? target.slice(SITE_URL.length)
+    : target;
   const relativeTarget =
-    BASE_URL !== '/' && target.startsWith(BASE_URL)
-      ? target.slice(BASE_URL.length)
-      : target.replace(/^\//, '');
+    BASE_URL !== '/' && pathname.startsWith(BASE_URL)
+      ? pathname.slice(BASE_URL.length)
+      : pathname.replace(/^\//, '');
   return join(BUILD_DIR, relativeTarget);
 }
 const LLMS_INDEX = join(BUILD_DIR, 'llms.txt');
 const LLMS_FULL = join(BUILD_DIR, 'llms-full.txt');
+const SITEMAP = join(BUILD_DIR, 'sitemap.xml');
 
 // How many issues of one kind to print before summarising the rest.
 const MAX_REPORTED_PER_CHECK = 15;
@@ -47,27 +74,37 @@ interface LinkRef {
   line: number;
 }
 
-// Extract the link targets from `[text](target)` pairs, keeping only the
-// root-relative Markdown pages the plugin emits (e.g. `/docs/...md`,
-// `/docs.md`). External URLs, anchors, and non-.md targets are not part of the
-// export contract this guard protects.
-function extractMarkdownLinks(content: string): LinkRef[] {
+// Every `[text](target)` pair in the document, targets kept verbatim.
+function extractLinks(content: string): LinkRef[] {
   const links: LinkRef[] = [];
   const regex = /\[[^\]]*\]\(([^)]+)\)/g;
-  const lines = content.split('\n');
-  lines.forEach((line, index) => {
+  content.split('\n').forEach((line, index) => {
     let match: RegExpExecArray | null;
     regex.lastIndex = 0;
     while ((match = regex.exec(line)) !== null) {
-      const target = match[1].split('#')[0].split('?')[0];
-      if (target.startsWith('/') && target.endsWith('.md')) {
-        links.push({ target, line: index + 1 });
-      }
+      links.push({ target: match[1], line: index + 1 });
     }
   });
   return links;
 }
 
+// The links pointing at the Markdown pages the plugin emits. Targets carry the
+// site url (`https://site/docs/...md`); a root-relative one still counts here so
+// a stale link gets reported rather than skipped. Off-site URLs, anchors, and
+// non-.md targets are not part of the export contract this guard protects.
+function extractMarkdownLinks(content: string): LinkRef[] {
+  return extractLinks(content)
+    .map(({ target, line }) => ({
+      target: target.split('#')[0].split('?')[0],
+      line,
+    }))
+    .filter(
+      ({ target }) =>
+        (target.startsWith('/') || target.startsWith(`${SITE_URL}/`)) &&
+        target.endsWith('.md'),
+    );
+}
+
 // Every emitted Markdown page, relative to website/build.
 function collectMarkdownPages(dir: string, acc: string[] = []): string[] {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -114,6 +151,91 @@ function checkIndexLinks(): void {
   }
 }
 
+// llms.txt is read detached from the site: pasted into a model's context, split
+// into chunks by a retriever, fetched on its own. A root-relative target has no
+// document to resolve against there, so every link the index hands out has to
+// carry the origin or it is dead on arrival.
+function checkIndexLinksAbsolute(): void {
+  // Absolute links are a production-only guarantee. Preview builds emit
+  // relative links on purpose: the llms-txt plugin appends the baseUrl to the
+  // site url while route paths already carry it, doubling any non-root prefix
+  // (see the plugin block in website/docusaurus.config.ts).
+  if (BASE_URL !== '/') return;
+  const content = readFileSync(LLMS_INDEX, 'utf-8');
+  const found = extractLinks(content)
+    .filter(({ target }) => !target.startsWith('https://'))
+    .map(({ target, line }) => ({
+      file: `website/build/llms.txt:${line}`,
+      message: `relative link target ${target} (llms.txt links must be fully qualified, e.g. ${SITE_URL}${target.startsWith('/') ? target : `/${target}`})`,
+    }));
+  pushCapped('relative links in llms.txt', found);
+}
+
+// Internal planning documents live under website/docs/plans/. One left there is
+// published: it gets a public page, a sitemap entry, and its own section in
+// llms.txt, which is the copy every agent reads. Deleting the source file fixes
+// one leak; asserting on the published artifacts prevents the next one.
+const INTERNAL_ROUTE = /[^\s<>"'()[\]]*\/docs\/plans(?![\w-])[^\s<>"'()[\]]*/g;
+
+function findInternalRoutes(content: string): LinkRef[] {
+  const found: LinkRef[] = [];
+  let match: RegExpExecArray | null;
+  INTERNAL_ROUTE.lastIndex = 0;
+  while ((match = INTERNAL_ROUTE.exec(content)) !== null) {
+    found.push({
+      target: match[0],
+      line: content.slice(0, match.index).split('\n').length,
+    });
+  }
+  return found;
+}
+
+function checkNoInternalPlans(): void {
+  const found: Issue[] = [];
+
+  // The index renders one heading per route category, so a "plans" section
+  // means the whole directory shipped, not a single stray page.
+  readFileSync(LLMS_INDEX, 'utf-8')
+    .split('\n')
+    .forEach((line, index) => {
+      if (!/^#{1,6}\s+plans\s*$/i.test(line.trim())) return;
+      found.push({
+        file: `website/build/llms.txt:${index + 1}`,
+        message: `internal "${line.trim()}" section published in the LLM export (delete the page from website/docs/plans/)`,
+      });
+    });
+
+  const artifacts = [
+    { rel: 'website/build/llms.txt', abs: LLMS_INDEX, optional: false },
+    { rel: 'website/build/llms-full.txt', abs: LLMS_FULL, optional: true },
+    { rel: 'website/build/sitemap.xml', abs: SITEMAP, optional: false },
+  ];
+
+  for (const { rel, abs, optional } of artifacts) {
+    if (!existsSync(abs)) {
+      // A guard whose input is missing is a guard that is switched off.
+      if (!optional) {
+        issues.push({
+          file: rel,
+          message:
+            'not emitted, so the internal-plans check could not run against it',
+        });
+      }
+      continue;
+    }
+    for (const { target, line } of findInternalRoutes(
+      readFileSync(abs, 'utf-8'),
+    )) {
+      found.push({
+        file: `${rel}:${line}`,
+        message: `internal plans route published: ${target} (delete the page from website/docs/plans/)`,
+      });
+    }
+  }
+
+  pushCapped('published internal plans', found);
+}
+
 // Every internal Markdown link in every emitted page body must resolve to a
 // file that was actually emitted. A link the export mangles (most commonly a
 // trailing-slash route turned into `/docs/mapping/.md`) 404s for every reader
@@ -370,6 +492,8 @@ function main(): void {
   console.log(`   ${pages.length} exported pages\n`);
 
   checkIndexLinks();
+  checkIndexLinksAbsolute();
+  checkNoInternalPlans();
   checkBodyLinks(pages);
   checkPlaceholders(pages);
   checkCodeIndentation();

apps/scripts/validate-skills-index.ts

@@ -35,8 +35,9 @@ function readPluginSkillNames(): string[] {
     skills?: string[];
   };
   const skills = plugin.skills ?? [];
-  // Entries look like "skills/walkeros-using-cli"; reduce to the basename.
-  return skills.map((entry) => entry.replace(/^skills\//, ''));
+  // Entries look like "./skills/walkeros-using-cli" (the plugin schema
+  // requires the "./" prefix); reduce to the basename.
+  return skills.map((entry) => entry.replace(/^(\.\/)?skills\//, ''));
 }
 
 // 1. Regenerate-and-compare: a hand edit to INDEX.json that was not produced by