[Karanvir1729]

The owner asked that coding agents and users always end up on the newest runtime: "The most recent, most advanced version should ALWAYS be used." Today npm's latest is 0.2.2, so a bare npm install @genclass/runtime or npx @genclass/runtime init installs the line with no token, dashboard, analytics, visual checks or agent link. This PR makes every path a user or agent copies name the newest line. It also makes analytics: true fail loudly wherever code from the newest line can see the problem.

The one command that ends this for good (not run)

Once 0.3.0 is stable, push the tag v0.3.0 (with packages/runtime/package.json at 0.3.0). release.yml publishes a non-prerelease straight to latest, so no hand step is needed for latest. Then run the one hand step the release comment now lists, so the @beta lines never resolve to an older prerelease:

npm dist-tag add @genclass/runtime@0.3.0 beta

If you decide to make the current beta the default before 0.3.0 ships, the existing step in the release.yml comment ("the owner moves latest") is:

npm dist-tag add @genclass/runtime@0.3.0-beta.1 latest

After either one, drop @beta from the install lines in a single change (the new AGENTS.md convention). Set SNIPPET_RUNTIME/RUNTIME_PKG in telemetry-worker/src/pages.ts and RUNTIME_ON_NPM in wrangler.toml, then deploy the worker. I ran neither command, and nothing here publishes.

Also for you, outside this PR: npm's genclass-runtime alias is still at 0.1.0-beta.3, and no workflow publishes it, so npx genclass-runtime init runs that old CLI. Its README now points to npx @genclass/runtime@beta init until the alias is published again.

The analytics bug, reproduced on 0.2.2

I installed @genclass/runtime@0.2.2 in a temp dir and ran GenClass.init({ analytics: true }) in jsdom, with and without a token. It throws nothing, prints no warning (only the telemetry notice), creates no runtime.analytics and sends nothing. TypeScript apps get a type error for the unknown option, because 0.2.2's types have no analytics. 0.3.0-beta.0 has no analytics either. Neither release can change, so the newest line says it everywhere its code runs:

• Runtime (src/cdn/analytics-loader.ts, src/analytics/index.ts): the script tag loads dist/analytics/index.js by URL, so a self-hosted dist/ can lack it or mix releases (the ESM entries can't: the bundler ships the chunk with its runtime). The tag's loader warns once per failed load: [GenClass] analytics: <url> (@genclass/runtime <version>) did not load; nothing is recorded. Serve every file of this version's dist/. (reason: "error", as before). It passes the tag's version to the chunk, which warns once per page when its own differs, naming both versions and the install line, and still records. The stub (src/analytics/start.ts) is unchanged from main, so the ESM first load carries none of this. Measured first-load growth over main, all from the @beta console hints below: +16 B gzip on /auto, +13 B on the main entry, under test/bundle.test.ts's owner-approved limits. An earlier version of this PR put the warning in the stub and went over them after PR 98.
• Dashboard (telemetry-worker/src/pages.ts): the Visitors view is now always shown. For an app without interaction data it has an empty state: analytics need 0.3.0-beta.1 or later, the app's older runtime versions from its own runtime breakdown, and npm install @genclass/runtime@beta plus GenClass.init({ token, analytics: true }). The Connect panel says the same.
• CLI and genclass_setup: covered below.
• Documented in docs/runtime/ANALYTICS.md section 4.1, the runtime README, API.md and the analytics JSDoc.

The CLI on the newest line (bin/lib/version.mjs, new)

• init, login and connect print Version @genclass/runtime 0.3.0-beta.1 (npm dist-tag beta).
• They ask npm view @genclass/runtime dist-tags --json once, with a 3 s timeout. They skip it with --dry-run, the new --no-network, --no-token or --no-telemetry (keeping the README's "no token, no network" promise), and when npm_config_offline is set or npm fails. When any dist-tag points at a newer version they say Newer ... 0.3.0-beta.2 is on npm (dist-tag beta): run npx @genclass/runtime@beta init instead. This also covers a @beta tag left behind after 0.3.0 ships.
• A project that already has an older runtime is upgraded. Before, init skipped the install whenever package.json listed the package, so an app set up by 0.2.2's init stayed on 0.2.2 even after npx @genclass/runtime@beta init. The version is read from node_modules first, then from the declared range. The upgrade appears in the diff and the question.
• Every command the CLI prints says npx @genclass/runtime@beta while its own version is a prerelease (derived from package.json, so it drops @beta on its own at 0.3.0). The same goes for the console messages that name a command (invalid token, blocked model, mode and token hints). The "install it by hand" hint now includes the version.
• I can't change what npx @genclass/runtime init resolves to today (npm's latest, 0.2.2). That is the command above.

Files whose install line or pin changed

• Script tags pinned to @0.3.0-beta.1: packages/runtime/README.md (the unpinned script-tag example), telemetry-worker/README.md (was @beta), packages/runtime/test/install/INSTALL-README-SNIPPET.md, the src/cdn/global.ts header.
• @beta on npm/npx lines:
  • README.md and packages/runtime/README.md (the two-line explanation now puts the newest first, with 0.2.x as the exception; new "Which version" section)
  • packages/runtime/TELEMETRY.md, packages/runtime/INTERCEPTION.md, PRIVACY.md
  • docs/runtime/API.md, docs/runtime/THREAT-MODEL.md
  • docs/adoption/listings/svelte.md, sveltesociety.md, vue-and-angular.md
  • templates/{angular,astro,nextjs,nuxt,react-router,react-vite,sveltekit,vue-vite}/README.md
  • packages/sv/README.md, packages/nuxt/README.md, packages/astro/README.md
  • packages/nuxt/src/source.ts and packages/astro/src/index.ts (JSDoc), packages/playwright/README.md and src/install.ts (error message)
  • packages/mcp/README.md, packages/genclass-runtime/README.md, packages/runtime-model/README.md
  • telemetry-worker/README.md, demos/src/site/landing.ts
  • runtime console messages in src/index.ts, src/token.ts, src/model/blocked.ts, src/runtime.ts, plus src/types.ts (JSDoc) and the src/cdn/sinks.ts comment
• Ranges that resolve to the beta (checked with npm view: both resolve to 0.3.0-beta.1):
  • templates' package.json: ^0.2.0 → ^0.3.0-beta.1
  • packages/nuxt and packages/astro peer: >=0.2.0 || ^0.3.0-beta.0 → >=0.3.0-beta.1, with package-lock.json synced; npm's auto-installed peer was 0.2.2 before
• genclass_setup (packages/mcp/src/tools.ts): prints npm install @genclass/runtime@beta for 0.2.x, for */latest/empty ranges (which npm resolves to 0.2.2; before, these counted as "installed"), and for an older copy in node_modules.
• Dashboard: SNIPPET_RUNTIME 0.3.0-beta.0 → 0.3.0-beta.1, new ANALYTICS_RUNTIME. RUNTIME_ON_NPM 0.3.0-beta.0 → 0.3.0-beta.1 in wrangler.toml and wrangler.selfhost.toml, with the release.yml note.
• AGENTS.md: one convention, so install lines name the newest line and stable is the exception.

Deliberately unchanged:

• CHANGELOG history
• SECURITY.md and CONTRIBUTING.md (@<version> placeholders)
• the marker header init and the sv add-on write into users' files (it describes the file; sv's tests pin it byte for byte)
• the compat/ evaluation apps, whose harness swaps in the packed runtime
• FAQ.md, llms.txt, INSTALL.md and DASHBOARD.md are not on main (llms.txt is generated by the site build in genclass-site); llms-install.md already said @beta.

Checks

• npm run typecheck -w @genclass/runtime and npm run build -w @genclass/runtime: clean.
• Runtime vitest (main step, after merging main with PRs 95 and 98): 100 files, 1185 passed, 14 skipped (model parity).
• test/review-perf.test.ts --retry=2: 3/4. "redux-style dispatch on a normalized store with 5,000 entities" went 17 → 8 → 1.3 ms against a 1 ms budget on a machine running several other sessions. No file in that path changed; CI reports this step without blocking.
• packages/mcp: typecheck, build, vitest 130 passed (manifests included).
• telemetry-worker vitest 297 passed.
• sv unit 24, nuxt 8, astro 10, playwright 108: typecheck, build and vitest for each.
• node packages/runtime/test/first-load-size.mjs against a build of origin/main (with PR 98): +16 B gzip (/auto), +13 B (main).

Not run (AGENTS.md says ask first, or they need the network/browsers): the install suite (test/install/run-all.sh), the model Playwright suite, the sv/playwright/mcp e2e runs, compat/templates-check.mjs. I did run the real npm view dist-tag lookup once by hand: it answered in about 1 s and printed (npm dist-tag beta). No model-visible text changed (situation-v2.3). Nothing was published, and no dist-tag was changed.

🤖 Generated with Claude Code