feat(web): add PostHog analytics with typed env + refresh README

.changeset/tidy-readme-refresh.md

@@ -0,0 +1,5 @@
+---
+"@docker-doctor/cli": patch
+---
+
+README refresh: real scan output demo, accurate rule count (25), CI usage with `--json`/`--score`, and a working programmatic API example

apps/web/components/providers/analytics.tsx

@@ -1,18 +1,27 @@
 import { DatabuddyDevtools } from "@databuddy/devtools/react";
 import { Databuddy } from "@databuddy/sdk/react";
 
+import { env } from "@/lib/env";
+
+import { PostHog } from "./posthog";
+
 export const Analytics = () => (
   <>
-    <DatabuddyDevtools enabled={process.env.NODE_ENV !== "production"} />
-    <Databuddy
-      clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID}
-      trackHashChanges
-      trackAttributes
-      trackOutgoingLinks
-      trackInteractions
-      trackWebVitals
-      trackErrors
-      disabled={process.env.NODE_ENV === "development"}
-    />
+    <PostHog />
+    {env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID && (
+      <>
+        <DatabuddyDevtools enabled={process.env.NODE_ENV !== "production"} />
+        <Databuddy
+          clientId={env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID}
+          disabled={process.env.NODE_ENV === "development"}
+          trackAttributes
+          trackErrors
+          trackHashChanges
+          trackInteractions
+          trackOutgoingLinks
+          trackWebVitals
+        />
+      </>
+    )}
   </>
 );

apps/web/components/providers/posthog.tsx

@@ -0,0 +1,22 @@
+"use client";
+
+import posthog from "posthog-js";
+import { useEffect } from "react";
+
+import { env } from "@/lib/env";
+
+export const PostHog = () => {
+  useEffect(() => {
+    if (process.env.NODE_ENV !== "production") {
+      return;
+    }
+
+    posthog.init(env.NEXT_PUBLIC_POSTHOG_KEY, {
+      api_host: "/ingest",
+      defaults: "2025-05-24",
+      ui_host: "https://us.posthog.com",
+    });
+  }, []);
+
+  return null;
+};

apps/web/lib/env.ts

@@ -0,0 +1,18 @@
+import { createEnv } from "@t3-oss/env-nextjs";
+import { z } from "zod";
+
+export const env = createEnv({
+  client: {
+    NEXT_PUBLIC_DATABUDDY_CLIENT_ID: z.string().min(1).optional(),
+    // Public client token — safe in the bundle; override per environment.
+    NEXT_PUBLIC_POSTHOG_KEY: z
+      .string()
+      .startsWith("phc_")
+      .default("phc_DjoT7pYmeZ5rhi65kHPRVnQUAweAqkfnJsMeVyQG6EvZ"),
+  },
+  experimental__runtimeEnv: {
+    NEXT_PUBLIC_DATABUDDY_CLIENT_ID:
+      process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID,
+    NEXT_PUBLIC_POSTHOG_KEY: process.env.NEXT_PUBLIC_POSTHOG_KEY,
+  },
+});

apps/web/next.config.ts

@@ -1,6 +1,9 @@
 import { createMDX } from "fumadocs-mdx/next";
 import type { NextConfig } from "next";
 
+// Validate environment variables at build time.
+import "./lib/env";
+
 const withMDX = createMDX();
 
 const nextConfig: NextConfig = {
@@ -14,7 +17,17 @@ const nextConfig: NextConfig = {
       destination: "/llms.mdx/docs/:path*",
       source: "/docs/:path*.md",
     },
+    {
+      destination: "https://us-assets.i.posthog.com/static/:path*",
+      source: "/ingest/static/:path*",
+    },
+    {
+      destination: "https://us.i.posthog.com/:path*",
+      source: "/ingest/:path*",
+    },
   ],
+
+  skipTrailingSlashRedirect: true,
 };
 
 export default withMDX(nextConfig);

apps/web/package.json

@@ -15,6 +15,7 @@
     "@base-ui/react": "^1.6.0",
     "@databuddy/sdk": "^2.6.0",
     "@docker-doctor/core": "workspace:*",
+    "@t3-oss/env-nextjs": "^0.13.11",
     "cnfast": "^0.0.8",
     "date-fns": "^4.4.0",
     "fumadocs-core": "^16.12.1",
@@ -23,11 +24,13 @@
     "motion": "^12.42.2",
     "next": "16.2.11",
     "next-themes": "^0.4.6",
+    "posthog-js": "^1.414.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "shiki": "^4.3.1",
     "sonner": "^2.0.7",
-    "tw-animate-css": "^1.4.0"
+    "tw-animate-css": "^1.4.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@databuddy/devtools": "^0.0.1-beta.0",

packages/docker-doctor/README.md

@@ -14,7 +14,7 @@
 
 Your Dockerfiles are probably wrong. Docker Doctor finds out why.
 
-Docker Doctor is an opinionated static analysis tool for Dockerfile and Docker Compose files. It scans your project, runs 21+ rules across security, performance, best practices, Compose, and image size — then gives you a health score and fix guidance.
+Docker Doctor is an opinionated static analysis tool for Dockerfile and Docker Compose files. It scans your project, runs 25 rules across security, performance, best practices, Compose, and image size — then gives you a health score and fix guidance.
 
 Works with any project that uses Docker.
 
@@ -28,6 +28,37 @@ Works with any project that uses Docker.
 npx @docker-doctor/cli@latest
 ```
 
+One scan gives you a category summary and a health score:
+
+```text
+  All 9 issues
+
+  Security › 2 issues
+  Performance › 2 issues
+  Best Practices › 3 issues
+  Compose › 0 issues
+  Image Size › 2 issues
+
+     .      68 / 100 Needs Work ⚠️
+   .---.    ██████████████████████████████████░░░░░░░░░░░░░░░░
+  ( • • )>  Docker Doctor
+   \___/
+```
+
+Add `--verbose` and every finding shows the offending line and how to fix it:
+
+```text
+  ⚠ WARN [docker-doctor/order-layers]:7
+  >     7 │ RUN npm install
+
+    Running package installation command 'npm install' after copying
+    application files (at line 5). This invalidates the cache on any
+    code changes.
+    Help: Copy dependency definition files (like package.json, lockfiles)
+    and run install commands BEFORE copying the rest of the application
+    source code.
+```
+
 ### 2. Install for agents
 
 Once you have an audit, install the skill so your coding agent learns the `/docker-doctor` triage workflow and can fix the issues for you:
@@ -42,12 +73,18 @@ Works with Claude Code, Cursor, Codex, OpenCode, and many more. After an interac
 
 ### 3. Run in CI
 
-Docker Doctor walks you through setting up a GitHub Actions workflow after your first scan:
+The CLI is non-interactive when stdin isn't a TTY, and two flags make it pipeline-friendly: `--json` emits a machine-readable report, `--score` prints just the numeric score.
 
 ```bash
-npx @docker-doctor/cli@latest
+# Machine-readable report as a build artifact
+npx @docker-doctor/cli@latest --json > docker-doctor-report.json
+
+# Fail the build below a minimum health score
+test "$(npx @docker-doctor/cli@latest --score)" -ge 75
 ```
 
+Prefer not to write the workflow yourself? Docker Doctor offers to set up a GitHub Actions workflow for you after your first interactive scan.
+
 ### 4. Configure
 
 ```ts
@@ -87,11 +124,34 @@ The label thresholds are unchanged: `>= 90` Excellent, `>= 75` Good, `>= 50` Nee
 
 ## API
 
+Everything the CLI does is exported as plain functions, so you can build your own tooling on top:
+
 ```ts
-import { discoverProject, toJsonReport } from "@docker-doctor/cli";
-import type { Diagnostic } from "@docker-doctor/cli";
+import { readFile } from "node:fs/promises";
+
+import {
+  calculateScore,
+  discoverProject,
+  parseDockerfile,
+  runDockerfileRules,
+} from "@docker-doctor/cli";
+
+const project = await discoverProject(".");
+
+const file = project.dockerfiles[0];
+const instructions = parseDockerfile(await readFile(file, "utf8"));
+const diagnostics = runDockerfileRules(
+  instructions,
+  file,
+  project.dockerignores ?? []
+);
+
+const { score, label } = calculateScore(diagnostics);
+console.log(`${score}/100 (${label})`);
 ```
 
+Also exported: `parseCompose` and `runComposeRules` for Compose files, `toJsonReport` for the JSON report shape, `defineConfig` and `loadConfig` for configuration, `allRules` and `findRule` for rule metadata, plus the `Diagnostic`, `DockerDoctorConfig`, `RuleCategory`, and `RuleSeverity` types.
+
 ## Contributing
 
 [MIT](LICENSE) and [Issues welcome!](https://github.com/PunGrumpy/docker-doctor/issues)