docs: backfill analytics release-readiness files

AGENTS.md

@@ -0,0 +1,52 @@
+# Agent Instructions
+
+These instructions apply to the entire `vllnt/analytics` repository.
+
+## Scope
+
+`@vllnt/analytics` is a lightweight, privacy-first TypeScript analytics package with consent management and React integration.
+
+## Safety rules
+
+- Do not release, tag, publish to npm, merge, or announce without explicit maintainer approval.
+- Do not change `package.json` version as part of ordinary docs, tests, or implementation work.
+- Do not commit secrets, tokens, customer data, private URLs, or internal operating notes.
+- Preserve privacy-first behavior: consent checks, Do Not Track handling, SSR safety, and no default external analytics vendor dependency.
+
+## Development commands
+
+Use pnpm 9.x.
+
+```bash
+pnpm install --frozen-lockfile
+pnpm lint
+pnpm exec tsc --noEmit
+pnpm test:once
+```
+
+## Repository map
+
+- `src/analytics.ts`: core analytics singleton, queueing, identity, page/event/tutorial tracking helpers.
+- `src/consent.ts`: consent storage, cookie parsing, Do Not Track detection, consent constructors and validators.
+- `src/react.tsx`: React provider and consent hooks.
+- `src/types.ts`: public TypeScript types.
+- `src/__tests__/`: Vitest coverage for analytics, consent, React, exports, and SSR safety.
+- `.github/workflows/ci.yml`: pull-request quality gates.
+- `.github/workflows/publish.yml`: canary and manual release workflow. Treat this as release-critical.
+
+## Release-readiness gate
+
+Before any PR that prepares release work is merged or any publish/tag action is run, attach this gate with current evidence:
+
+```json
+{
+  "branch": "vllnt-oss",
+  "tenant": "releases",
+  "aor_fit": true,
+  "context_read": true,
+  "evidence_attached": true,
+  "opsec_checked": true,
+  "safe_for_next_step": true,
+  "blocking_findings": []
+}
+```

CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `@vllnt/analytics` are documented in this file.
+
+This project follows npm package versions and uses GitHub Releases for published release notes. Public release work must pass a maintainer release-review gate before any tag, publish, or announcement.
+
+## [0.1.1] - 2026-03-10
+
+### Fixed
+
+- Use the configured release checkout token for the release workflow so protected-branch release commits can be created by automation.
+
+### Release readiness
+
+- Latest npm tag: `0.1.1`.
+- Canary npm tag at the time of this backfill: `0.1.1-canary.106d5aa`.
+- Git tag: `v0.1.1`.
+- Release date reflects the public npm publish timestamp and GitHub Release publication date.
+
+## [0.1.0] - 2026-03-05
+
+### Added
+
+- Published the initial `@vllnt/analytics` package baseline extracted from the VLLNT monorepo.
+- Added privacy-first analytics primitives, consent helpers, React provider/hooks, SSR-safe storage/cookie utilities, and tutorial tracking helpers.
+- Added test coverage, public package metadata, and CI/publish workflows.
+
+[0.1.1]: https://github.com/vllnt/analytics/releases/tag/v0.1.1
+[0.1.0]: https://github.com/vllnt/analytics/releases/tag/v0.1.0

CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to @vllnt/analytics
+
+Thanks for helping improve `@vllnt/analytics`.
+
+This package is a small, privacy-first TypeScript library. Keep changes focused, easy to review, and safe for public npm consumers.
+
+## Development setup
+
+1. Install pnpm 9.x.
+2. Install dependencies:
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+3. Run the local quality gates before opening a pull request:
+
+```bash
+pnpm lint
+pnpm exec tsc --noEmit
+pnpm test:once
+```
+
+## Pull requests
+
+- Branch from `main` for ordinary changes.
+- Use focused branches such as `docs/...`, `fix/...`, `feat/...`, or `test/...`.
+- Keep public documentation, tests, and examples in sync with behavior changes.
+- Do not include secrets, customer data, private URLs, or internal operating notes.
+- Do not bump `package.json` versions, create git tags, publish to npm, or announce releases from a normal PR.
+
+## Release-review gate
+
+Before any release PR is merged, tagged, published, or announced, a maintainer must explicitly review the release readiness evidence:
+
+```json
+{
+  "branch": "vllnt-oss",
+  "tenant": "releases",
+  "aor_fit": true,
+  "context_read": true,
+  "evidence_attached": true,
+  "opsec_checked": true,
+  "safe_for_next_step": true,
+  "blocking_findings": []
+}
+```
+
+A passing gate means the change is in the VLLNT OSS release-readiness area of responsibility, relevant context has been read, evidence is attached, public-opsec has been checked, and there are no known blocking findings. It does not by itself authorize publishing; release dispatch remains a separate maintainer action.
+
+## Coding guidelines
+
+- Prefer TypeScript types over runtime ambiguity.
+- Keep browser APIs guarded so SSR imports remain safe.
+- Preserve consent-first behavior and Do Not Track handling.
+- Avoid adding analytics vendor dependencies to the core package.
+- Add or update Vitest coverage for behavior changes.
+
+## Reporting issues
+
+Open a GitHub issue with:
+
+- the package version,
+- runtime/framework details,
+- expected behavior,
+- actual behavior,
+- a minimal reproduction when possible.

SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+`@vllnt/analytics` is a public npm package for consent-aware analytics helpers. Security reports should be handled privately before public disclosure.
+
+## Supported versions
+
+| Version | Supported |
+| --- | --- |
+| `0.1.x` | Yes |
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities through GitHub private vulnerability reporting for this repository when available:
+
+https://github.com/vllnt/analytics/security/advisories/new
+
+If private vulnerability reporting is unavailable, open a minimal public issue that says a private security report is needed, without exploit details or sensitive data.
+
+## Scope
+
+Security-sensitive areas include:
+
+- consent persistence and cookie parsing,
+- SSR/browser boundary handling,
+- user identity and trait handling,
+- event queuing behavior,
+- package publishing/provenance workflow integrity.
+
+## Disclosure expectations
+
+- Do not publicly disclose exploit details until maintainers have had time to investigate and release a fix.
+- Include reproduction steps, affected versions, expected impact, and any suggested mitigation.
+- Never include real user data, private customer data, tokens, cookies, or credentials in a report.

llms-full.txt

@@ -0,0 +1,140 @@
+# @vllnt/analytics full context
+
+`@vllnt/analytics` is a lightweight, privacy-first analytics package with consent management and React integration. It is designed for applications that want a small analytics abstraction without taking a hard dependency on a vendor SDK.
+
+## Package metadata
+
+- npm package: `@vllnt/analytics`
+- Repository: https://github.com/vllnt/analytics
+- License: MIT
+- Type: ESM TypeScript package
+- Current package version in `package.json`: `0.1.1`
+- Peer dependency: `react ^18.0.0 || ^19.0.0`
+- Package manager: `pnpm@9.15.4`
+
+## Public exports
+
+The root export, `@vllnt/analytics`, re-exports:
+
+### Analytics functions
+
+- `initAnalytics(config)`: initialize the singleton analytics state.
+- `track(name, properties?)`: track a custom event.
+- `trackPage(properties?)`: track a page view.
+- `identify(userId, traits?)`: attach user identity and traits after initialization.
+- `resetAnalytics()`: clear in-memory identity and traits.
+- `enableAnalytics(config)`: enable analytics after consent is granted.
+- `disableAnalytics()`: block tracking and clear queued events after consent is revoked.
+- `isAnalyticsEnabled()`: report whether tracking is initialized and unblocked.
+- `getAnalyticsState()`: inspect advanced/debug state.
+
+### Tutorial/content tracking helpers
+
+- `trackTutorialStart(properties)`
+- `trackSectionView(properties)`
+- `trackSectionComplete(properties)`
+- `trackTutorialComplete(properties)`
+- `trackTutorialNavigation(properties)`
+- `trackTimeSpent(properties)`
+
+These helpers emit typed tutorial event names such as `tutorial_start`, `tutorial_section_view`, `tutorial_section_complete`, `tutorial_complete`, `tutorial_navigation`, and `tutorial_time_spent`.
+
+### Consent functions and constants
+
+- `CONSENT_VERSION`
+- `CONSENT_STORAGE_KEY`
+- `CONSENT_COOKIE_NAME`
+- `loadConsent()`
+- `saveConsent(state)`
+- `clearConsent()`
+- `createAcceptAllConsent()`
+- `createDeclineAnalyticsConsent()`
+- `updateConsentCategory(current, category, value)`
+- `needsRePrompt(consent, currentVersion)`
+- `getConsentFromCookie(cookieString)`
+- `isDoNotTrackEnabled()`
+- `isStorageAvailable()`
+- `isValidConsentState(value)`
+
+### Types
+
+- `AnalyticsConfig`
+- `AnalyticsEvent`
+- `ConsentCategory`
+- `ConsentState`
+- `TutorialEventName`
+- `TutorialEventProperties`
+- `UseConsentOptions`
+- `UseConsentReturn`
+
+The React subpath, `@vllnt/analytics/react`, exports:
+
+- `AnalyticsProvider`
+- `useAnalytics()`
+- `useConsent(options?)`
+- `initAnalytics` convenience re-export
+
+## Behavior model
+
+1. Browser-only tracking functions return early during SSR.
+2. Initialization checks Do Not Track first.
+3. Initialization then checks stored consent; declined analytics blocks tracking.
+4. Events fired before initialization are queued.
+5. Once analytics initializes, queued events are flushed.
+6. Consent utilities store state in localStorage and mirror analytics consent as a one-year cookie for SSR detection.
+7. Consent versions allow applications to re-prompt by increasing the version.
+8. Functional consent cannot be disabled through `updateConsentCategory`.
+
+## Privacy posture
+
+The package intentionally avoids a default external analytics dependency. `sendEvent` is the central integration point where an application can wire a custom backend, Vercel Analytics, Google Analytics, or another destination. The React provider coordinates consent and initialization but does not override Do Not Track or declined consent.
+
+## Repository map
+
+- `src/index.ts`: public root exports.
+- `src/analytics.ts`: singleton state, event queueing, initialization, custom/page/tutorial tracking, identity, reset, enable/disable logic.
+- `src/consent.ts`: consent state validation, localStorage/cookie persistence, Do Not Track detection, version re-prompt checks.
+- `src/react.tsx`: client React provider and hooks.
+- `src/types.ts`: public TypeScript definitions.
+- `src/__tests__/analytics.test.ts`: analytics behavior tests.
+- `src/__tests__/consent.test.ts`: consent behavior tests.
+- `src/__tests__/exports.test.ts`: export-surface tests.
+- `src/__tests__/react.test.tsx`: React provider/hook tests.
+- `src/__tests__/ssr.test.ts`: SSR safety tests.
+- `vitest.config.ts`: Vitest configuration.
+- `eslint.config.js`: ESLint configuration using `@vllnt/eslint-config`.
+- `.github/workflows/ci.yml`: pull-request lint, typecheck, and test gates.
+- `.github/workflows/publish.yml`: canary publishing on main pushes affecting package files and manual release publishing via workflow dispatch.
+
+## Development commands
+
+```bash
+pnpm install --frozen-lockfile
+pnpm lint
+pnpm exec tsc --noEmit
+pnpm test:once
+pnpm test:coverage
+```
+
+## Release and opsec notes
+
+- Ordinary changes must not bump the package version.
+- Release tags and npm publishing must only happen through approved release workflow actions.
+- The manual release workflow bumps `package.json`, commits, tags, publishes to npm with provenance, and creates a GitHub Release.
+- Public docs must not include secrets, private customer data, private URLs, or internal operating mechanics.
+- Release-preparation work must carry the VLLNT OSS release-review gate before merge, tag, publish, or announcement.
+
+## Release-review gate template
+
+```json
+{
+  "branch": "vllnt-oss",
+  "tenant": "releases",
+  "aor_fit": true,
+  "context_read": true,
+  "evidence_attached": true,
+  "opsec_checked": true,
+  "safe_for_next_step": true,
+  "blocking_findings": []
+}
+```

llms.txt

@@ -0,0 +1,59 @@
+# @vllnt/analytics
+
+> Lightweight, privacy-first analytics with consent management and React integration.
+
+This file helps AI coding tools and documentation systems understand the public package surface. For full context, see `llms-full.txt`.
+
+## Project
+
+- Package: `@vllnt/analytics`
+- Repository: https://github.com/vllnt/analytics
+- License: MIT
+- Runtime: TypeScript ESM package
+- Peer dependency: React `^18.0.0 || ^19.0.0`
+- Package manager: pnpm 9.x
+
+## Install
+
+```bash
+pnpm add @vllnt/analytics
+```
+
+## Public entry points
+
+- `@vllnt/analytics`: core analytics and consent APIs.
+- `@vllnt/analytics/react`: React provider and hooks.
+
+## Main capabilities
+
+- Consent-aware event tracking with pre-initialization queueing.
+- Page-view, identity, reset, and tutorial/content tracking helpers.
+- Consent persistence in localStorage plus SSR-readable cookie state.
+- Do Not Track detection.
+- SSR-safe guards around browser APIs.
+- React `AnalyticsProvider`, `useAnalytics`, and `useConsent` helpers.
+
+## Important files
+
+- `README.md`: install, usage examples, API summary.
+- `CHANGELOG.md`: public package history.
+- `CONTRIBUTING.md`: development and release-review expectations.
+- `SECURITY.md`: vulnerability reporting policy.
+- `AGENTS.md`: repository instructions for AI/code agents.
+- `src/index.ts`: root exports.
+- `src/analytics.ts`: analytics singleton and tracking helpers.
+- `src/consent.ts`: consent state utilities.
+- `src/react.tsx`: React integration.
+- `src/types.ts`: public types.
+
+## Local quality gates
+
+```bash
+pnpm lint
+pnpm exec tsc --noEmit
+pnpm test:once
+```
+
+## Release safety
+
+Do not tag, publish, merge release work, bump versions, or announce releases without explicit maintainer approval and a release-review gate.