Initial commit

packages/core-analytics/AGENTS.md

@@ -0,0 +1,32 @@
+# @repo/core-analytics
+
+Optional core package providing a vendor-neutral product analytics interface. Scaffold via `pnpm turbo gen core-package analytics`.
+
+## Structure
+
+```
+src/
+  analytics.interface.ts   # IAnalytics — track, identify, pageView, flush
+  noop-analytics.ts        # NoopAnalytics (default no-op implementation)
+  index.ts                 # Barrel export
+```
+
+## Design
+
+`IAnalytics` exposes four methods:
+
+- `track(event, attributes?)` — record a named event with optional attributes
+- `identify(user)` — associate subsequent events with a user
+- `pageView(path, attributes?)` — record a page-view event
+- `flush()` — drain any in-flight queued events (returns `Promise<void>`)
+
+The interface is vendor-neutral: no third-party analytics SDK is bundled. Feature
+packages depend on `IAnalytics` only; concrete implementations (e.g. a PostHog
+or Segment adapter) are wired at DI bind time in `bind-production`.
+
+`NoopAnalytics` is the default implementation — all methods are no-ops and
+`flush()` resolves immediately via `Promise.resolve()`. Use it in dev-seed
+bindings and unit tests.
+
+See `docs/architecture/agent-first-workflow-and-conformance.md` for the
+dependency-injection conventions.