Merge pull request #23 from jtrackingai/dev/zzc/v1.0.17

Improve preview click verification and subdomain crawling

Author: jtrackingai

SKILL.md

@@ -70,6 +70,7 @@ Once `site-analysis.json` indicates Shopify, keep discovery and grouping shared,
 - Use `./event-tracking runs <output-root>` when the artifact directory is unknown but the output root is known.
 - Prefer high-level entry commands for user-facing flows: `run-new-setup`, `run-tracking-update`, `run-upkeep`, `run-health-audit`.
 - Telemetry consent is a required user-choice checkpoint for richer diagnostics. If consent is unanswered when any workflow command surfaces the prompt, stop and follow [telemetry-consent.md](references/telemetry-consent.md) as the single-source interaction contract. Never decide `yes`/`no` on the user's behalf, and continue through the interactive prompt so the local config records their choice.
+- Explain the purpose, what `yes` does, what `no` does, and the remaining privacy tradeoff before asking the user to reply `yes` or `no`. Do not ask a bare `yes`/`no` question with no context.
 - Treat workflow mode metadata as an internal workflow-state layer, not a user-facing command surface.
 - `analyze`, `validate-schema --check-selectors`, `preview`, and `sync` each need outbound HTTP and a real Chromium; `sync` additionally needs a local loopback callback on `127.0.0.1` for Google's OAuth consent redirect. Run them in an environment that permits those capabilities so Playwright and the OAuth callback can complete.
 - Run prompt-driven GTM sync with an interactive TTY from the start unless exact `--account-id`, `--container-id`, and `--workspace-id` values are already confirmed.

VERSION

@@ -1 +1 @@
-1.0.16
+1.0.17

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "analytics-tracking-automation",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "Automated web event tracking skill for GA4 + GTM",
   "main": "dist/cli.js",
   "bin": {
@@ -18,7 +18,7 @@
     "install:skills": "node scripts/install-skills.mjs",
     "sync:skill-docs": "node scripts/sync-skill-docs.mjs",
     "test": "npm run build && npm run test:built",
-    "test:built": "node --test tests/workflow-state.test.mjs tests/live-gtm-parser.test.mjs tests/skill-family.test.mjs tests/skill-contract.test.mjs tests/auto-update.test.mjs tests/workflow-enhancements.test.mjs tests/telemetry.test.mjs tests/oauth-embedded-config.test.mjs",
+    "test:built": "node --test tests/workflow-state.test.mjs tests/live-gtm-parser.test.mjs tests/skill-family.test.mjs tests/skill-contract.test.mjs tests/auto-update.test.mjs tests/workflow-enhancements.test.mjs tests/telemetry.test.mjs tests/oauth-embedded-config.test.mjs tests/crawler-url-utils.test.mjs",
     "postinstall": "playwright install chromium"
   },
   "dependencies": {

package.json

@@ -11,10 +11,12 @@ Set these expectations with the user before crawling:
 - Only a limited number of child pages are sampled within the same section or path, so deeper links may not be captured
 - Large sites may hit the **40-page total cap**; partial coverage is normal
 - **E-commerce sites** trigger smarter URL ordering — category/listing pages before product pages
+- Same registered-domain subdomains are in scope when they carry business-critical journeys. Prioritize linked subdomains such as `app.example.com`, `account.example.com`, `auth.example.com`, checkout/billing/payment hosts, login, signup, trial, pricing, contact-sales, and password-reset pages before broad blog or resource sampling.
+- Do not blindly deep-crawl every subdomain. Support/docs/help-center subdomains, WAF-protected pages, and unrelated operational hosts should be listed as skipped or grouped separately only when they are reachable and relevant to the tracking goal.
 
 ## Partial Mode Rules
 
-- All URLs must belong to the same domain as the root `<URL>`
+- All URLs must belong to the same registered domain as the root `<URL>`; subdomains such as `app.example.com/login` are valid when they share the root registered domain.
 - Maximum 20 URLs per call — split into batches or use full-site mode for more
 
 ## Execution Environment
@@ -36,6 +38,7 @@ Set these expectations with the user before crawling:
 
 - How many pages were analyzed
 - Any skipped URLs and why (login pages, WAF blocks, errors)
+- Any same-domain business subdomains that were analyzed or intentionally skipped, especially app/login/signup/checkout flows
 - Any `crawlWarnings`
 - Detected platform (`generic` or `shopify`) and detection signals when available
 - **Detected dataLayer events** — if the site already pushes events via `dataLayer.push()` (e.g. e-commerce `purchase`, `add_to_cart`), list them. These can be leveraged as `custom` triggerType events in Step 2 instead of re-instrumenting with click triggers.

references/crawl-guide.md

@@ -80,6 +80,8 @@ Use this coverage checklist when deciding whether the plan is complete enough:
 - **Live baseline first**: when `existingTrackingBaseline` is present, treat it as the current production baseline. Reuse existing live event names when the intent already matches, and add new events only where the live setup has real gaps.
 - **Solve live problems, do not just add events**: each new event or parameter upgrade should address a specific live tracking issue such as missing coverage, inconsistent naming, sparse context, or fragmented reporting targets.
 - **Global elements first**: Process the `global_elements` group (contentType `global`) **before** other groups. Shared header, footer, and nav elements get `pageUrlPattern: ""` and are generated **exactly once**. Other groups **skip** elements with `parentSection` of `header`, `footer`, or `nav`.
+- **Locale-aware page scopes**: when crawl evidence shows localized URL prefixes such as `/en`, `/zh`, `/de`, or hreflang/alternate links, generate one language-agnostic event for the shared business intent and make `pageUrlPattern` accept the optional locale prefix. Do not create separate events per language, and do not scope the event only to the default-language path unless the interaction truly exists only there. Prefer explicit discovered locale alternation, for example `example\\.com/(?:(?:en|zh|de)/)?affiliate`, over a broad `.*` pattern.
+- **Subdomain-aware page scopes**: when login, signup, app onboarding, checkout, billing, or account flows live on a same registered-domain subdomain such as `app.example.com`, create one business-intent event that spans the relevant root and subdomain pages as needed. Use explicit host-aware `pageUrlPattern` values such as `^https://app\\.example\\.com/(?:login|signup)(?:[/?#]|$)` instead of defaulting to only the marketing host.
 - Do **not** generate default `page_view` or `scroll` events. The GTM configuration tag already sends `page_view`, and `scroll` is usually auto-collected by GA4 Enhanced Measurement.
 - Only add a custom scroll-depth event if there is a clear analysis need. If you do, use a distinct custom event name such as `scroll_depth`, not the reserved `scroll`.
 - Click events for meaningful buttons: login, signup, CTA, download, share, outbound links

references/event-schema-guide.md

@@ -47,7 +47,9 @@ Typical site-wide shared elements include login or sign-up buttons in the top na
 ## Coverage Expectations
 
 - **Language**: Groups reflect the site's **main language**. Other language versions may not fully appear because sitemaps usually favor pages in the site's primary language.
-- **Can't group what wasn't crawled**: Deep links, gated content, login-protected pages won't appear.
+- **Business subdomains**: Same registered-domain subdomains that host login, signup, app onboarding, checkout, billing, account, trial, or contact-sales journeys should be grouped when they were discovered or manually verified as reachable. Put them in explicit groups such as `auth_pages`, `checkout_pages`, or `app_pages` rather than hiding them inside generic marketing groups.
+- **Unreachable subdomains**: Do not create groups for support/docs/help-center subdomains that are WAF-blocked, timeout, or are not relevant to the tracking goal. Keep them as skipped evidence instead.
+- **Can't group what wasn't crawled or verified**: Deep links, gated content, and login-protected pages won't appear unless they were crawled or manually verified and added with enough representative HTML/elements for schema generation.
 - **Don't claim completeness**: Groups represent crawled and sampled pages, not every URL on the site.
 
 ## Compute urlPattern

references/page-grouping-guide.md

@@ -167,10 +167,6 @@ function buildCliPackageJson() {
 }
 
 function copyBundledCliRuntime(outputPath, profile) {
-  if (profile === EXPORT_PROFILE_CLAWHUB) {
-    return;
-  }
-
   copyDirectory('runtime/cli-runtime', path.join(outputPath, 'runtime', 'cli-runtime'));
 
   const cliPackagePath = path.join(outputPath, 'runtime', 'cli-package');

scripts/export-skills.mjs

@@ -163,10 +163,6 @@ function listBundledCliFiles(repoRoot) {
 }
 
 function listBundledCliFilesForProfile(repoRoot, profile) {
-  if (profile === EXPORT_PROFILE_CLAWHUB) {
-    return [];
-  }
-
   return listBundledCliFiles(repoRoot);
 }
 

scripts/skill-bundles.mjs

@@ -3,6 +3,7 @@ import { chromium, Browser, Page, Response } from 'playwright';
 import {
   extractDomain, isSameDomain, normalizeUrl, getSectionPrefix,
   sampleUrlsBySection, detectEcommerceSite, reorderForEcommerce,
+  prioritizeBusinessCriticalUrls,
   discoverNavLinks, discoverAllLinks,
 } from './url-utils';
 import { extractCleanedHtml } from './html-cleaner';
@@ -701,6 +702,7 @@ export async function analyzeSite(
         if (isEcommerce) {
           level1Candidates = reorderForEcommerce(level1Candidates);
         }
+        level1Candidates = prioritizeBusinessCriticalUrls(level1Candidates, rootDomain);
 
         const level1Urls = sampleUrlsBySection(
           level1Candidates,
@@ -727,6 +729,7 @@ export async function analyzeSite(
           if (isEcommerce) {
             level2Filtered = reorderForEcommerce(level2Filtered);
           }
+          level2Filtered = prioritizeBusinessCriticalUrls(level2Filtered, rootDomain);
 
           const level2Urls = sampleUrlsBySection(
             level2Filtered,