feat: implement product-led adoption foundation

[pmcelhaney]

Summary

Implements the product-led adoption foundation for Counterfact: a measurable 90-day program, privacy-preserving CLI activation telemetry, a stronger homepage activation path, runnable React/Vite and Playwright examples, and CI that keeps those examples working.

This revision moves framework-specific walkthroughs into a packaged Examples collection, gives React/Vite a complete two-terminal browser workflow, makes the Playwright project directly discoverable, and preserves the old Pattern URLs with static compatibility redirects.

Telemetry remains anonymous and provider-independent at the runtime boundary. OpenAPI source identifiers now use HMAC-SHA-256 with a private per-installation key that rotates with the installation identity, while Counterfact's composition layer accepts only an enumerated event/property allow-list. The installed-package acceptance path captures the real packed CLI's telemetry on loopback and proves required package contents and opt-out behavior.

Original Prompt

Develop a marketing plan for Counterfact, including OKRs. Implement the proposed plan.

Manual acceptance tests

• From the Counterfact homepage or Examples documentation, a developer can reach the React/Vite and Playwright example directories and their setup instructions without searching the repository.
• Following the React/Vite README starts Counterfact and Vite, and opening the documented browser URL displays the Ada Lovelace profile returned by the local API.
• Running the Playwright example verifies deterministic success, not-found, and service-unavailable screens through Counterfact.
• A loopback collector receives the expected enabled lifecycle events while unique OpenAPI-location, request URL/query, header, body, token, private hash-key, and error-message sentinels are absent from every captured payload.
• COUNTERFACT_TELEMETRY_DISABLED=true and CI=true each produce no telemetry requests and no telemetry identity file while ordinary CLI work still succeeds.
• The locally packed and installed counterfact artifact contains the three docs/examples/ guides and contains no docs/marketing/ files.

Repository learning check

• Learning found: Yes
• Guidance updated: Yes
• Updated file(s): .github/skills/counterfact-cli-runtime/SKILL.md, .github/skills/counterfact-maintenance/SKILL.md
• Rationale: Telemetry privacy requires private per-install location keys and loopback wire verification, while framework-specific runnable applications belong under Examples with complete human run instructions.

Verification

• Focused telemetry, CLI, runtime, and REPL suites
• yarn build
• yarn typecheck
• yarn test
• All five black-box behaviors (the combined macOS run's already-passed stateful scenario required interruption in the pre-existing PTY cleanup; the remaining scenarios passed independently)
• yarn test:packed-consumer
• Clean React/Vite and Playwright installations and verification, including Chromium
• Site build and recursive internal-link check
• Direct counterfact-2.16.5.tgz inspection for the three required Examples guides and absence of docs/marketing/
• Manual React two-terminal browser walkthrough
• yarn lint:fix, yarn lint, and git diff --check

Scope notes

• “Published package” acceptance here means the candidate tarball produced and installed from this PR. Registry publication and post-release verification are separate.
• The site deploys static output to GitHub Pages. The legacy Pattern paths are durable canonical/meta-refresh compatibility pages served with HTTP 200; literal hosting-level HTTP 301/308 redirects would require deployment infrastructure support outside this repository change.
• This PR does not merge, release, publish to npm, or change live analytics configuration.

[Copilot]

🟡 Changes recommended

Runtime request telemetry can be dropped while still suppressing later valid events (and can throw into request handling) due to unvalidated status bucketing in routesMiddleware.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Implements the “product-led adoption foundation” by adding privacy-preserving activation telemetry (CLI + runtime boundary), strengthening the website’s activation path, and introducing verified React/Vite + Playwright runnable examples with CI coverage, alongside packaged documentation updates and internal operating docs.

Changes:

• Add allow-listed, privacy-preserving telemetry for CLI lifecycle, first served API request, file-change categories, and REPL command categories.
• Improve website homepage activation flow + intent tracking, and add docs redirects for moved guides.
• Add runnable React/Vite + Playwright examples plus a CI workflow to keep them executable.

File summaries

File	Description
site/src/styles/main.css	Adds layout styles for new homepage workflow/examples sections.
site/src/scripts/main.js	Adds client-side PostHog capture wrapper + intent/copy tracking hooks.
site/src/pages/index.astro	Expands homepage sections and adds analytics attributes to key links/actions.
site/src/pages/docs/[...slug].astro	Adds permanent redirects for legacy /docs/patterns/* example URLs.
site/src/layouts/MainLayout.astro	Adjusts PostHog config to avoid person profiles.
site/public/llms.txt	Adds links to new runnable examples docs.
README.md	Links to new runnable examples and packaged example guides.
packages/runtime/test/server/create-koa-app.test.ts	Adds coverage ensuring only first API request telemetry is reported and no private data leaks.
packages/runtime/src/server/web-server/routes-middleware.ts	Injects runtime event reporter + emits first_api_request_served status class.
packages/runtime/src/server/web-server/create-koa-app.ts	Adds one-per-process suppression for first_api_request_served reporting.
packages/counterfact/test/package/fixtures/pack-files.json	Ensures example guides are included in packed counterfact package fixtures.
packages/counterfact/test/package/counterfact-consumer-smoke.mjs	Extends packed-consumer smoke test to verify telemetry privacy + opt-out + packaging exclusions.
packages/counterfact/test/cli/telemetry.test.ts	Adds unit coverage for identity rotation, allow-list sanitization, and awaited telemetry failure paths.
packages/counterfact/test/cli/telemetry-opt-out.test.ts	Adds provider-construction opt-out test for CI and explicit disable.
packages/counterfact/test/cli/run.test.ts	Updates startup telemetry property expectations (source kind/spec count + keyed hashing).
packages/counterfact/src/cli/telemetry.ts	Implements rotating install identity + keyed location hashing + allow-list sanitization + opt-out safe transport.
packages/counterfact/src/cli/run.ts	Integrates startup/failed/started telemetry flows and adds source classification properties.
packages/counterfact/src/app.ts	Injects runtime telemetry adapter into Koa app and routes REPL command events through allow-list adapter.
packages/counterfact/src/api-runner.ts	Routes runtime event reporting through new facade adapter boundary.
packages/counterfact/README.md	Adds documentation link to runnable examples guides.
packages/counterfact/package.json	Ensures docs/examples is published in the npm package.
packages/counterfact/llms.txt	Documents packaged example guides.
packages/counterfact/docs/usage.md	Adds runnable examples section + expands telemetry/privacy description.
packages/counterfact/docs/patterns/index.md	Updates patterns landing page to point to runnable examples.
packages/counterfact/docs/examples/react-vite.md	Adds packaged guide for React/Vite runnable example.
packages/counterfact/docs/examples/playwright-error-states.md	Adds packaged guide for Playwright error-state runnable example.
packages/counterfact/docs/examples/index.md	Adds packaged index page for runnable examples.
examples/react-vite/tsconfig.json	Adds example TypeScript config.
examples/react-vite/test/api.test.mjs	Adds node:test-based verification of example API behavior.
examples/react-vite/src/style.css	Adds example UI styling.
examples/react-vite/src/main.tsx	Adds React entrypoint.
examples/react-vite/src/App.tsx	Adds example screen with loading/error/success states.
examples/react-vite/src/api.ts	Adds typed API client for the example.
examples/react-vite/README.md	Adds runnable + verification instructions for the example.
examples/react-vite/package.json	Adds runnable + verification scripts and deps for the example.
examples/react-vite/openapi.yaml	Adds example OpenAPI contract.
examples/react-vite/index.html	Adds example HTML entrypoint.
examples/react-vite/api/routes/profiles/{profileId}.ts	Adds authored route handler for deterministic example behavior.
examples/react-vite/api/.gitignore	Ignores generated cache under example API folder.
examples/react-vite/.gitignore	Ignores generated Counterfact artifacts + build output.
examples/playwright-error-states/test/profile.spec.mjs	Adds Playwright journeys asserting three deterministic UI states.
examples/playwright-error-states/src/style.css	Adds example UI styling.
examples/playwright-error-states/src/main.js	Adds example app logic to map API responses into UI states.
examples/playwright-error-states/README.md	Adds runnable + verification instructions for Playwright example.
examples/playwright-error-states/playwright.config.mjs	Configures Playwright web servers and base URL.
examples/playwright-error-states/package.json	Adds runnable + verification scripts and dev deps.
examples/playwright-error-states/openapi.yaml	Adds OpenAPI contract for 200/404/503 states.
examples/playwright-error-states/index.html	Adds example HTML entrypoint.
examples/playwright-error-states/api/routes/profiles/{profileId}.ts	Adds deterministic handler for Playwright states.
examples/playwright-error-states/api/.gitignore	Ignores generated cache under example API folder.
examples/playwright-error-states/.gitignore	Ignores generated Counterfact artifacts + Playwright results.
docs/marketing/weekly-scorecard.md	Adds internal weekly scorecard template.
docs/marketing/README.md	Adds internal adoption program operating doc + OKRs + funnel definitions.
docs/marketing/experiment-register.md	Adds experiment register template.
docs/marketing/campaigns.md	Adds approved campaign briefs and UTM conventions.
.github/workflows/ecosystem-examples.yml	Adds CI workflow to verify runnable examples stay working.
.github/skills/counterfact-maintenance/SKILL.md	Records repo guidance about example placement/docs and test port practices.
.github/skills/counterfact-cli-runtime/SKILL.md	Updates telemetry privacy contract and runtime injection boundary guidance.
.changeset/tidy-cups-listen.md	Declares minor releases for counterfact and @counterfact/runtime covering telemetry + examples/docs.

Review details

• Files reviewed: 59/61 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.