docs: bootstrap knowledge files for rudder-sdk-js (#3031)

Co-authored-by: tech-infra-rudderstack <tech-infra+github-signing@rudderstack.com>

Author: rudder-devbox[bot]

.agents/knowledge/architecture.md

@@ -0,0 +1,27 @@
+# Architecture
+
+> Component layout, internal relationships, data flow.
+> Append-only. Agent-authored sections may optionally carry an HTML-comment tag
+> (e.g., `<!-- pr:<id> -->`) identifying the writer/PR/run; human-authored
+> sections are conventionally left untouched by automated runs.
+
+## Baseline Architecture (RUD-2781)
+<!-- linear:RUD-2781 -->
+
+- The modern SDK (v3) is a facade-plus-core split: `RudderAnalytics` normalizes overloaded public APIs and delegates to one or more `Analytics` core instances (`packages/analytics-js/src/app/RudderAnalytics.ts::RudderAnalytics`, `packages/analytics-js/src/components/core/Analytics.ts::Analytics`).
+- v3 startup is lifecycle-driven via reactive state transitions (`mounted -> ... -> ready`) in `Analytics.startLifecycle`, with each phase initializing a subsystem (`packages/analytics-js/src/components/core/Analytics.ts::Analytics.startLifecycle`).
+- Global state is centralized and slice-based (`state.lifecycle`, `state.plugins`, `state.nativeDestinations`, etc.), enabling cross-service coordination without direct hard coupling (`packages/analytics-js/src/state/index.ts::state`).
+- Config resolution feeds architecture decisions: `ConfigManager.init/processConfig` computes CDN paths, source config URL, and destination/plugin selection before moving to `configured` state (`packages/analytics-js/src/components/configManager/ConfigManager.ts::ConfigManager.init`, `packages/analytics-js/src/components/configManager/ConfigManager.ts::ConfigManager.processConfig`).
+- Event ingestion and delivery are layered as `EventManager -> EventRepository -> plugin extension points`, where queues are plugin-provided and controlled by consent/destination readiness (`packages/analytics-js/src/components/eventManager/EventManager.ts::EventManager.addEvent`, `packages/analytics-js/src/components/eventRepository/EventRepository.ts::EventRepository.init`).
+- Plugin orchestration is first-class in v3: `PluginsManager` derives active plugins from source/load options, registers local+remote plugins, and gates lifecycle on plugin readiness (`packages/analytics-js/src/components/pluginsManager/PluginsManager.ts::PluginsManager.init`).
+- Legacy v1.1 remains as a separate line with a monolithic `Analytics` class handling config fetch, integrations loading, and queues in one class graph (`packages/analytics-v1.1/src/core/analytics.js::Analytics`, `packages/analytics-v1.1/project.json:1`).
+- Monorepo tags explicitly encode the split (`scope:analytics-v3` vs `scope:analytics-v1.1`) so build/test/release flows can target modern and legacy independently (`packages/analytics-js/project.json:8`, `packages/analytics-v1.1/project.json:6`).
+
+## Cross-cutting
+<!-- linear:RUD-2781 -->
+
+- Lifecycle state is the central coordination contract across architecture, patterns, and concerns: facade/core initialization, plugin readiness, and queue start conditions all hinge on shared signal slices (`packages/analytics-js/src/components/core/Analytics.ts::Analytics.startLifecycle`, `packages/analytics-js/src/state/index.ts::state`, `packages/analytics-js/src/components/eventRepository/EventRepository.ts::EventRepository.init`).
+- Plugin extensibility is both an architecture strength and an operational risk: the same extension-point model that enables transport/consent/destination modularity also concentrates TODOs around retry/failure behavior (`packages/analytics-js/src/components/pluginsManager/PluginsManager.ts::PluginsManager.init`, `packages/analytics-js/src/services/PluginEngine/PluginEngine.ts::PluginEngine.invoke`, `packages/analytics-js/src/components/pluginsManager/PluginsManager.ts:37`).
+- The snippet/preload buffering model couples entry points to core event processing guarantees; preserving buffered-call semantics is critical whenever boot or loader logic changes (`packages/loading-scripts/src/index.ts:31`, `packages/analytics-js/src/components/core/Analytics.ts::Analytics.processDataInPreloadBuffer`, `packages/analytics-js/src/app/RudderAnalytics.ts::RudderAnalytics.triggerBufferedLoadEvent`).
+- Modern-vs-legacy split appears in stack, conventions, and concerns simultaneously: versioned project scopes and separate entry files are intentional boundaries that should be preserved in future changes (`packages/analytics-js/project.json:8`, `packages/analytics-v1.1/project.json:6`, `packages/analytics-v1.1/src/core/analytics.js::Analytics`).
+- Security posture is tied to architectural choices around remote loading and dynamic execution; CSP handling in error/state flows partially mitigates but does not remove this dependency (`packages/loading-scripts/src/index.ts::window.rudderAnalyticsAddScript`, `packages/analytics-js/src/services/ErrorHandler/ErrorHandler.ts::ErrorHandler.attachErrorListeners`, `packages/analytics-js-integrations/src/integrations/Braze/nativeSdkLoader.js:11`).

.agents/knowledge/concerns.md

@@ -0,0 +1,44 @@
+# Concerns
+
+> Technical debt, TODOs, FIXMEs, security concerns, architectural issues.
+> Append-only. Agent-authored sections may optionally carry an HTML-comment tag
+> (e.g., `<!-- pr:<id> -->`) identifying the writer/PR/run; human-authored
+> sections are conventionally left untouched by automated runs.
+> Top-5–8 highest-signal items per category, not exhaustive.
+
+## TODO/FIXME Density Clusters (RUD-2781)
+<!-- linear:RUD-2781 -->
+
+- Plugin lifecycle resilience is explicitly incomplete (retry/timeout/failure handling TODO cluster), increasing risk of partial initialization states (`packages/analytics-js/src/components/pluginsManager/PluginsManager.ts:37`, `packages/analytics-js/src/components/pluginsManager/PluginsManager.ts:83`, `packages/analytics-js/src/components/pluginsManager/PluginsManager.ts:282`).
+- Config fetch robustness has known gap: no retry/backoff in `processConfig` on transient failures (`packages/analytics-js/src/components/configManager/ConfigManager.ts:156`).
+- Facade/session lifecycle debt is documented in core API (`restart/reset` and multi-instance follow-ups), suggesting state-reset edge cases remain (`packages/analytics-js/src/app/RudderAnalytics.ts:53`, `packages/analytics-js/src/app/RudderAnalytics.ts:159`).
+- StoreManager has unresolved design TODOs around validation and cross-version behavior, which can affect persistence compatibility (`packages/analytics-js/src/services/StoreManager/StoreManager.ts:93`).
+- Legacy v1.1 still carries TODOs in URL validation and queue timing validation, indicating weaker guardrails in older runtime path (`packages/analytics-v1.1/src/utils/cdnPaths.js:16`, `packages/analytics-v1.1/src/utils/xhrModule.js:33`).
+
+## Security-Adjacent Concerns (RUD-2781)
+<!-- linear:RUD-2781 -->
+
+- Dynamic script loading from runtime-computed CDN paths is foundational; misconfiguration or policy drift can affect integrity if hosting controls weaken (`packages/loading-scripts/src/index.ts::window.rudderAnalyticsAddScript`, `packages/analytics-js/src/components/configManager/ConfigManager.ts::ConfigManager.init`).
+- Dynamic code execution via `new Function(...)` is present for feature detection and in some integration loaders; this is CSP-sensitive and should stay tightly scoped (`packages/loading-scripts/src/index.ts:59`, `packages/analytics-js-integrations/src/integrations/Braze/nativeSdkLoader.js:11`).
+- Session/auth token persistence is part of state and storage flows; local persistence options require careful downstream hardening to avoid token exposure in hostile browser contexts (`packages/analytics-js/src/state/slices/session.ts:14`, `packages/analytics-js/src/components/userSessionManager/UserSessionManager.ts:1014`).
+- Hashing choices in integration utilities include `md5`; while used for compatibility with partner SDK expectations, this should remain constrained to non-security-critical hashing use cases (`packages/analytics-js-integrations/src/integrations/Criteo/utils.js:16`, `packages/analytics-js-integrations/package.json:80`).
+
+## Architectural Smells (RUD-2781)
+<!-- linear:RUD-2781 -->
+
+- Dual runtime lines (v3 modern + v1.1 legacy) increase cognitive and release complexity; architectural guidance must keep explicit boundaries to avoid accidental parity assumptions (`packages/analytics-js/project.json:8`, `packages/analytics-v1.1/project.json:6`).
+- Legacy `Analytics` class is large and multi-responsibility (config, loading, queueing, integrations), which raises change-risk and test-surface breadth (`packages/analytics-v1.1/src/core/analytics.js::Analytics`).
+- Plugin engine defaults to `throws: true`; if plugin failure paths are not consistently isolated by callers, boot failures can propagate abruptly (`packages/analytics-js/src/services/PluginEngine/PluginEngine.ts::defaultPluginEngine`).
+- The modern state object spans many cross-domain slices in one mutable graph, which helps coordination but can blur ownership boundaries over time (`packages/analytics-js/src/state/index.ts::state`).
+
+## Stale/Commented-Out/Compatibility Burden (RUD-2781)
+<!-- linear:RUD-2781 -->
+
+- Legacy package still targets IE11-era browser matrix and compatibility constraints, which can limit simplification/refactor options for shared utilities (`packages/analytics-v1.1/package.json:101`).
+- Browser support configs differ between root and package scopes, increasing risk of accidental regressions across build targets (`package.json:232`, `packages/analytics-js-integrations/package.json:100`, `packages/analytics-v1.1/package.json:101`).
+- Service-worker distribution was split to another package (documented deprecation), so contributor assumptions based on older docs can be stale without explicit checks (`README.md:36`).
+
+## RUD-2781 — Nx Command Preconditions
+<!-- linear:RUD-2781 -->
+
+- Root quality commands that delegate to Nx (for example lint/check scripts) depend on the workspace toolchain being installed so `nx` resolves at runtime; without provisioned dependencies these checks fail before actual lint/test evaluation.

.agents/knowledge/conventions.md

@@ -0,0 +1,21 @@
+# Conventions
+
+> Coding conventions and naming schemes — things a linter can't catch.
+> Append-only. Agent-authored sections may optionally carry an HTML-comment tag
+> (e.g., `<!-- pr:<id> -->`) identifying the writer/PR/run; human-authored
+> sections are conventionally left untouched by automated runs.
+
+## Repository Conventions (RUD-2781)
+<!-- linear:RUD-2781 -->
+
+- Package-level boundaries are encoded via Nx tags (`type:*`, `scope:*`) and enforced centrally; new modules should preserve this tag taxonomy to keep dependency constraints meaningful (`nx.json:58`, `packages/analytics-js/project.json:7`).
+- Modern SDK naming prefers explicit manager/service suffixes (`ConfigManager`, `PluginsManager`, `UserSessionManager`) and `default*` singleton exports for shared instances (`packages/analytics-js/src/components/configManager/ConfigManager.ts::ConfigManager`, `packages/analytics-js/src/services/PluginEngine/PluginEngine.ts::defaultPluginEngine`).
+- Public API surfaces preserve Segment-style overloads at facade level, while core methods consume normalized payload objects (`packages/analytics-js/src/app/RudderAnalytics.ts::RudderAnalytics.track`, `packages/analytics-js/src/components/core/Analytics.ts::Analytics.track`).
+- The repo intentionally keeps both modern TypeScript-heavy code (`analytics-js`) and legacy JavaScript (`analytics-v1.1`); avoid “normalizing” one line to the other unless a task explicitly spans both (`packages/analytics-js/src/index.ts:1`, `packages/analytics-v1.1/src/core/analytics.js:1`).
+- Commit scopes are treated as repository API: scopes should be Nx project names or approved custom scopes (`release`, `monorepo`, `examples`, `deps`) (`commitlint.config.js:1`).
+- File layout convention is package-local (`src`, `__tests__`, `__fixtures__`, `rollup.config.mjs`), and top-level scripts prefer `nx run-many` / `nx affected` wrappers instead of ad hoc per-package loops (`package.json:8`).
+
+## RUD-2781 — Automation Guidance Location
+<!-- linear:RUD-2781 -->
+
+- Repository automation guidance is anchored in `CLAUDE.md`; no `AGENTS.md` file exists in this repo, so agent workflows should default to `CLAUDE.md` as the canonical instructions source.

.agents/knowledge/entry-points.md

@@ -0,0 +1,18 @@
+# Entry points
+
+> Key entry-point files: read these first to orient in this repo.
+> Append-only. Agent-authored sections may optionally carry an HTML-comment tag
+> (e.g., `<!-- pr:<id> -->`) identifying the writer/PR/run; human-authored
+> sections are conventionally left untouched by automated runs.
+
+## First-Read Map (RUD-2781)
+<!-- linear:RUD-2781 -->
+
+- `README.md` — product-level SDK usage, migration context, and v3 behavior notes (explicit `page` call, install paths) (`README.md:1`).
+- `CLAUDE.md` — repo-specific development commands, package map, and architecture hints used by automation agents (`CLAUDE.md:1`).
+- `package.json` (root) — authoritative task runner surface (`setup`, `build:*`, `test:*`, lint/size/security checks) and top-level dependency versions (`package.json:1`).
+- `packages/analytics-js/src/browser.ts` — modern v3 browser bundle export surface wiring global singleton methods (`packages/analytics-js/src/browser.ts:1`).
+- `packages/analytics-js/src/app/RudderAnalytics.ts` — v3 public facade and preload/global bootstrap behavior (`packages/analytics-js/src/app/RudderAnalytics.ts::RudderAnalytics`).
+- `packages/analytics-js/src/components/core/Analytics.ts` — v3 lifecycle engine, service composition, and initialization sequence (`packages/analytics-js/src/components/core/Analytics.ts::Analytics`).
+- `packages/analytics-v1.1/src/core/analytics.js` — legacy line core implementation (class-centric runtime still shipped as `rudder-sdk-js`) (`packages/analytics-v1.1/src/core/analytics.js::Analytics`).
+- `packages/loading-scripts/src/index.ts` — snippet loader that buffers calls and chooses modern vs legacy runtime script dynamically (`packages/loading-scripts/src/index.ts:1`).

.agents/knowledge/mistakes.md

@@ -0,0 +1,7 @@
+# Mistakes
+
+> Post-mortem entries from observed failures: CI failures, reverts on prior PRs,
+> prod incidents. Accrues over time — bootstrap leaves this empty.
+> Append-only. Agent-authored sections may optionally carry an HTML-comment tag
+> (e.g., `<!-- pr:<id> -->`) identifying the writer/PR/run; human-authored
+> sections are conventionally left untouched by automated runs.

.agents/knowledge/patterns.md

@@ -0,0 +1,19 @@
+# Patterns
+
+> Recurring idioms specific to this repo (error handling, state management,
+> retries, logging, DI, request lifecycle).
+> Append-only. Agent-authored sections may optionally carry an HTML-comment tag
+> (e.g., `<!-- pr:<id> -->`) identifying the writer/PR/run; human-authored
+> sections are conventionally left untouched by automated runs.
+> Every observed idiom includes a `file:line` reference.
+
+## Core Runtime Patterns (RUD-2781)
+<!-- linear:RUD-2781 -->
+
+- Public API guards use `try/catch` with centralized dispatch (`dispatchErrorEvent`) so facade methods fail soft instead of throwing to callers (`packages/analytics-js/src/app/RudderAnalytics.ts::RudderAnalytics.load`).
+- Lifecycle orchestration uses `@preact/signals-core` effects rather than imperative state machines; side effects subscribe to lifecycle and destination readiness transitions (`packages/analytics-js/src/components/core/Analytics.ts::Analytics.startLifecycle`, `packages/analytics-js/src/components/eventRepository/EventRepository.ts::EventRepository.init`).
+- Internal services are composed in one place (`prepareInternalServices`) and injected into managers, giving lightweight DI without a framework container (`packages/analytics-js/src/components/core/Analytics.ts::Analytics.prepareInternalServices`).
+- Event flow separates creation and transport: factory-built events are queued first, then queue plugins handle delivery/transform/retry (`packages/analytics-js/src/components/eventManager/EventManager.ts::EventManager.addEvent`, `packages/analytics-js/src/components/eventRepository/EventRepository.ts::EventRepository.enqueue`).
+- Plugin calls prefer extension-point invocation (`invokeSingle`/`invokeMultiple`) to keep queue and destination behaviors swappable (`packages/analytics-js/src/services/PluginEngine/PluginEngine.ts::PluginEngine.invokeSingle`).
+- Load-time buffering is a consistent behavior: preload snippet arrays and in-memory queues are drained after initialization to preserve call order (`packages/loading-scripts/src/index.ts:12`, `packages/analytics-js/src/components/core/Analytics.ts::Analytics.processDataInPreloadBuffer`).
+- Legacy v1.1 still follows class-centric mutable state and explicit polling for integration readiness (`allModulesInitialized` Promise loop), unlike v3 reactive effects (`packages/analytics-v1.1/src/core/analytics.js::Analytics.allModulesInitialized`).

.agents/knowledge/stack.md

@@ -0,0 +1,19 @@
+# Stack
+
+> Dependencies, frameworks, tooling.
+> Append-only. Agent-authored sections may optionally carry an HTML-comment tag
+> (e.g., `<!-- pr:<id> -->`) identifying the writer/PR/run; human-authored
+> sections are conventionally left untouched by automated runs.
+
+## Stack Baseline (RUD-2781)
+<!-- linear:RUD-2781 -->
+
+- Language/runtime: Node workspace monorepo with TypeScript + JavaScript packages; root package is `@rudderstack/analytics-js-monorepo@3.110.0` (`package.json:2`).
+- Monorepo/build orchestration: Nx `22.7.1` with `run-many` and `affected` workflows for build/test/lint/release (`package.json:13`, `package.json:24`, `nx.json:1`).
+- Bundling/transpilation: Rollup `4.60.3`, Babel `7.29.0`, TypeScript `6.0.3`, SWC tooling for TS/Jest paths (`package.json:170`, `package.json:112`, `package.json:196`, `package.json:138`).
+- Reactive/state core: `@preact/signals-core@1.14.1` powers modern SDK lifecycle/state reactions (`package.json:81`, `packages/analytics-js/src/components/core/Analytics.ts:2`).
+- HTTP + retry layer: `axios@1.16.0` + `axios-retry@4.5.0` are baseline network dependencies (`package.json:86`, `package.json:87`).
+- Browser persistence and crypto-related dependencies include `storejs@2.1.1`, `crypto-es@2.1.0`, `crypto-js@4.2.0`, `md5@2.3.0` (`package.json:104`, `package.json:89`, `package.json:90`, `package.json:99`).
+- Testing/quality toolchain: Jest `30.4.1`, ESLint `9.39.4`, size-limit `12.1.0`, madge `8.0.0`, jscpd `4.0.9` (`package.json:159`, `package.json:128`, `package.json:137`, `package.json:166`, `package.json:165`).
+- Release topology: packages are independently versioned with Nx release tag pattern `{projectName}@{version}` (`nx.json:7`).
+- Product lines: modern npm package `@rudderstack/analytics-js`, legacy package `rudder-sdk-js` (`v1.1`), plus dedicated plugins/integrations/loading-script packages (`packages/analytics-js/project.json:2`, `packages/analytics-v1.1/package.json:2`, `packages/analytics-js-plugins/package.json:2`, `packages/analytics-js-integrations/package.json:2`, `packages/loading-scripts/package.json:2`).