third-audience-mdx 1.0.0

package/README.md

@@ -0,0 +1,303 @@
+# third-audience-mdx
+
+For two decades, websites were built for two audiences: **humans** and **search engines**. Today there is a third audience rapidly growing: **AI agents and LLM crawlers**.
+
+AI systems like ChatGPT, Perplexity, Claude, and Gemini actively crawl the web to answer questions, generate summaries, and provide recommendations. Most sites serve these bots the same HTML built for humans — full of navigation menus, scripts, ads, and layout markup that adds noise and reduces accuracy.
+
+**third-audience-mdx** automatically serves clean, structured Markdown versions of your MDX content to AI crawlers, while humans continue to see your normal site. Think of it as **SEO for the AI era** — Generative Engine Optimization (GEO).
+
+Drop-in npm package for Next.js App Router. Tracks bot visits and AI citations. Zero external services. Everything stored in flat JSONL files.
+
+> Inspired by [third-audience-wordpress-plugin](https://github.com/spcaeo/third-audience-wordpress-plugin) by [@spcaeo](https://github.com/spcaeo).
+
+---
+
+## Features
+
+- **`.md` URL for every page** — `GET /your-post.md` returns clean Markdown of the matching MDX file
+- **Content negotiation** — `Accept: text/markdown` header serves Markdown to any AI crawler automatically
+- **`/llms.txt`** — auto-generated AI content index from your MDX frontmatter
+- **`/sitemap-ai.xml`** — AI-specific sitemap with title and description metadata
+- **`/okf/` bundle** — Open Knowledge Format: all content as self-navigable `.md` files
+- **Bot detection** — 20+ known AI crawlers (ClaudeBot, GPTBot, PerplexityBot, Gemini, etc.) plus heuristic detection
+- **Bot analytics** — every crawler visit logged to `data/ta-visits.jsonl`
+- **Citation tracking** — server-side referrer detection + client-side JS for ChatGPT, Perplexity, Claude, Gemini, Copilot
+- **Citation alerts** — notifies on first citation, new platform, citation spikes
+- **Dashboard** — React web UI at `/third-audience/` with 4 pages
+- **CLI** — `npx third-audience init/health/export`
+- **JSX stripping** — serves clean Markdown to AI; removes imports, component tags, expressions
+- **File-system cache** — memory LRU + disk cache, invalidated when MDX source changes
+
+---
+
+## Install
+
+```bash
+npm install third-audience-mdx
+```
+
+---
+
+## Quick Setup
+
+```bash
+npx third-audience init
+```
+
+The wizard detects your Next.js project, asks for your content directory, and writes the required files.
+
+---
+
+## Manual Setup
+
+### 1. Wrap your Next.js config
+
+**`next.config.ts`**
+```ts
+import { withThirdAudience } from 'third-audience-mdx'
+
+export default withThirdAudience({
+  contentDir: 'content',       // where your .mdx files live
+  dataDir: 'data',             // where analytics logs go
+  dashboard: true,
+  dashboardSecret: process.env.THIRD_AUDIENCE_SECRET,
+})
+```
+
+### 2. Add middleware
+
+**`middleware.ts`** (project root)
+```ts
+export { thirdAudienceMiddleware as middleware } from 'third-audience-mdx'
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+}
+```
+
+### 3. Add API routes
+
+Create these files in your `app/` directory:
+
+**`app/api/third-audience/markdown/[...slug]/route.ts`**
+```ts
+export { GET } from 'third-audience-mdx/routes/markdown'
+```
+
+**`app/api/third-audience/okf/[...path]/route.ts`**
+```ts
+export { GET } from 'third-audience-mdx/routes/okf'
+```
+
+**`app/api/third-audience/llms-txt/route.ts`**
+```ts
+export { GET } from 'third-audience-mdx/routes/llms-txt'
+```
+
+**`app/api/third-audience/sitemap-ai/route.ts`**
+```ts
+export { GET } from 'third-audience-mdx/routes/sitemap-ai'
+```
+
+**`app/api/third-audience/citation/route.ts`**
+```ts
+export { GET, POST } from 'third-audience-mdx/routes/citation'
+```
+
+**`app/api/third-audience/analytics/route.ts`**
+```ts
+export { GET } from 'third-audience-mdx/routes/analytics'
+```
+
+**`app/api/third-audience/bots-config/route.ts`**
+```ts
+export { GET, POST } from 'third-audience-mdx/routes/bots-config'
+```
+
+### 4. Add the dashboard
+
+**`app/third-audience/layout.tsx`**
+```tsx
+import type { ReactNode } from 'react'
+import { Sidebar } from 'third-audience-mdx/dashboard/ui/components/Sidebar'
+import 'third-audience-mdx/dashboard/ui/globals.css'
+
+export default function DashboardLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <div className="ta-layout">
+          <Sidebar />
+          <main className="ta-main">{children}</main>
+        </div>
+      </body>
+    </html>
+  )
+}
+```
+
+**`app/third-audience/page.tsx`** — Bot Analytics
+```tsx
+import { BotAnalyticsPage } from 'third-audience-mdx/dashboard/ui/pages/BotAnalyticsPage'
+export const dynamic = 'force-dynamic'
+export default function Page() { return <BotAnalyticsPage /> }
+```
+
+**`app/third-audience/citations/page.tsx`** — LLM Traffic
+```tsx
+import { LlmTrafficPage } from 'third-audience-mdx/dashboard/ui/pages/LlmTrafficPage'
+export const dynamic = 'force-dynamic'
+export default function Page() { return <LlmTrafficPage /> }
+```
+
+**`app/third-audience/bots/page.tsx`** — Bot Management
+```tsx
+import { BotManagementPage } from 'third-audience-mdx/dashboard/ui/pages/BotManagementPage'
+export const dynamic = 'force-dynamic'
+export default function Page() { return <BotManagementPage config={{ allowlist: [], blocklist: [], track_unknown: true }} /> }
+```
+
+**`app/third-audience/health/page.tsx`** — System Health
+```tsx
+import { SystemHealthPage } from 'third-audience-mdx/dashboard/ui/pages/SystemHealthPage'
+export const dynamic = 'force-dynamic'
+export default function Page() { return <SystemHealthPage /> }
+```
+
+### 5. Add client-side citation tracker
+
+Copy `node_modules/third-audience-mdx/src/public/citation-tracker.js` to `public/` and add to your root layout:
+
+```tsx
+// app/layout.tsx
+<script src="/citation-tracker.js" async />
+```
+
+### 6. Environment variables
+
+**`.env.local`**
+```
+THIRD_AUDIENCE_SECRET=your-secret-here
+NEXT_PUBLIC_SITE_URL=https://yoursite.com
+TA_CONTENT_DIR=content
+TA_DATA_DIR=data
+```
+
+### 7. Add to `.gitignore`
+
+```
+data/ta-visits.jsonl
+data/ta-citations.jsonl
+data/ta-cache/
+```
+
+---
+
+## Dashboard
+
+Visit `/third-audience/` on your site. Protected by `THIRD_AUDIENCE_SECRET` (HTTP Basic or Bearer token).
+
+| Page | URL | Description |
+|---|---|---|
+| Bot Analytics | `/third-audience/` | Hero metrics, daily visits chart, top bots, top pages |
+| LLM Traffic | `/third-audience/citations` | Citations per platform, country, page |
+| Bot Management | `/third-audience/bots` | Known bots list, allowlist/blocklist editor |
+| System Health | `/third-audience/health` | Node version, file status, cache stats, quick links |
+
+---
+
+## Endpoints
+
+| Endpoint | Description |
+|---|---|
+| `GET /your-page.md` | Clean Markdown of any MDX file |
+| `Accept: text/markdown` | Auto-serves Markdown to AI crawlers |
+| `GET /llms.txt` | AI content index from frontmatter |
+| `GET /sitemap-ai.xml` | AI sitemap with metadata |
+| `GET /okf/` | OKF bundle index |
+| `GET /okf/[slug].md` | Individual page as Markdown |
+| `POST /api/third-audience/citation` | Client-side citation report receiver |
+
+---
+
+## CLI
+
+```bash
+npx third-audience init              # interactive setup wizard
+npx third-audience health            # system health check
+npx third-audience export            # export visits as CSV
+npx third-audience export citations  # export citations as CSV
+```
+
+---
+
+## Configuration
+
+```ts
+withThirdAudience({
+  contentDir: 'content',          // .mdx source directory (default: 'content')
+  dataDir: 'data',                // analytics log directory (default: 'data')
+  dashboard: true,                // mount /third-audience/ (default: true)
+  dashboardSecret: '...',         // protect dashboard with a secret
+  notifications: {
+    email: { smtp: '...', to: '...' },
+    slack: { webhookUrl: '...' },
+  },
+  bots: {
+    allowlist: [],                // always track these UAs
+    blocklist: [],                // never track these UAs
+  },
+  cache: {
+    ttl: 3600,                    // cache TTL in seconds (default: 3600)
+    maxMemoryEntries: 500,        // max in-memory entries (default: 500)
+  },
+})
+```
+
+---
+
+## Data Files
+
+```
+data/
+  ta-visits.jsonl       # one JSON line per bot visit
+  ta-citations.jsonl    # one JSON line per citation click
+  ta-bots-config.json   # allowlist/blocklist overrides (edited via dashboard)
+  ta-cache/             # rendered Markdown cache files
+```
+
+Each line in `ta-visits.jsonl`:
+```json
+{ "timestamp": "2026-06-20T10:00:00Z", "bot_name": "ClaudeBot", "bot_category": "ai_crawler", "confidence": "high", "url": "/blog/my-post", "country": "US", "response_ms": 42, "cache_hit": true }
+```
+
+Each line in `ta-citations.jsonl`:
+```json
+{ "timestamp": "2026-06-20T10:00:00Z", "platform": "ChatGPT", "query": "how to do X", "url": "/blog/my-post", "country": "US" }
+```
+
+---
+
+## Detected AI Crawlers
+
+ClaudeBot, GPTBot, ChatGPT-User, PerplexityBot, Googlebot-AI (Google-Extended), Applebot-Extended, CCBot, CohereCrawler, AI2Bot, Bytespider, Diffbot, YouBot, FacebookBot — plus heuristic detection for unknown bots.
+
+---
+
+## Project Structure
+
+```
+src/
+  core/         MDX reader, Markdown renderer (JSX stripper), middleware, Next.js config wrapper
+  detection/    Bot detection pipeline — known patterns → heuristics → auto-learner
+  analytics/    Visit tracker, geolocation (geoip-lite), performance stats
+  citations/    Citation tracker, citation alerts
+  cache/        Two-tier cache (memory LRU + file system)
+  discovery/    llms.txt generator, sitemap-ai generator
+  okf/          OKF bundle — index + per-page + internal link rewriting
+  dashboard/    Auth, API route handlers, React UI pages and components
+  cli/          init, health, export commands
+  public/       citation-tracker.js (client-side, framework-agnostic)
+  nextjs-app/   Ready-to-copy Next.js App Router files
+```
+

package/WORKLOG.md

@@ -0,0 +1,162 @@
+# Work Log
+
+Newest entries at top.
+
+---
+
+## 2026-06-21 (session 6 — git init + push)
+
+**Asked:** Commit and merge to https://github.com/pooran/third-audience-mdx-plugin
+
+**Done:**
+- `git init` — project had no git repo yet
+- Added remote `origin` pointing to the GitHub URL
+- Staged all 80 project files (excluded `data/` per .gitignore)
+- Created initial commit with full Next.js npm package
+- Fetched remote `main` (had existing WP plugin history)
+- Resolved merge conflicts in README.md and INSTALLATION.md by keeping our Next.js versions (`git checkout --ours`)
+- Pushed merged history to `https://github.com/pooran/third-audience-mdx-plugin`
+
+**Files touched:** .git/ (created), all tracked files now in git
+
+---
+
+## 2026-06-21 (session 5 — API key + settings page)
+
+**Asked:** Check how WP plugin handles auth, implement same approach.
+
+**Learned from WP plugin:**
+- WP uses `current_user_can('manage_options')` — relies entirely on WP's own login, no custom login page
+- For headless/external API calls: `X-TA-Api-Key` header, key stored encrypted in `wp_options` using AES-256 keyed on `SECURE_AUTH_KEY`
+- Settings page shows masked key with "Copy" clipboard button and "Regenerate" button
+- Nonce verification on all AJAX/state-changing requests
+
+**What we added to match:**
+- `admin-store.ts`: AES-256-GCM encrypted API key field in `ta-admin.json`; `generateApiKey()`, `getApiKey()`, `rotateApiKey()`, `verifyApiKey()`; `initAdmin()` now also generates API key on first setup
+- `auth.ts`: Replaced `checkDashboardAuth` with `checkApiAuth()` — accepts `X-TA-Api-Key` header, `Authorization: Bearer`, or valid session cookie (in that order). Added `unauthorizedResponse()` helper.
+- `routes/api-key-route.ts`: GET returns masked key; POST `{action:"rotate"}` rotates and returns new key once
+- `ui/pages/SettingsPage.tsx`: API key display (masked), copy button, rotate button (with confirm dialog), change password link; mirrors WP settings page pattern
+- `ui/components/Sidebar.tsx`: Added Settings nav item with gear icon
+- Consumer files: `app/api/third-audience/api-key/route.ts`, `app/third-audience/settings/page.tsx`
+- `package.json` + `tsup.config.ts`: exports and build entries updated
+
+**Files touched:** src/dashboard/admin-store.ts, auth.ts, routes/api-key-route.ts, ui/pages/SettingsPage.tsx, ui/components/Sidebar.tsx, nextjs-app/app/api/third-audience/api-key/route.ts, nextjs-app/app/third-audience/settings/page.tsx, package.json, tsup.config.ts
+
+---
+
+## 2026-06-21 (session 5 — admin auth)
+
+**Asked:** Dashboard should require login. Default password `Chang3M3Now!`. Force reset on first login. `/setup-ta-admin` slash command.
+
+**Done:**
+- `src/dashboard/admin-store.ts` — password hashing (SHA-256 keyed on secret), HMAC-signed session tokens, `initAdmin()` / `verifyPassword()` / `updatePassword()` / `signSession()` / `verifySession()`
+- Default password hardcoded as `Chang3M3Now!`, `isDefaultPassword: true` until changed
+- `src/dashboard/routes/login-route.ts` — GET: login form HTML; POST: verify password → set HttpOnly cookie; force-reset redirect if default password still active; reset form validates length + confirmation
+- `src/core/middleware.ts` — auth guard on all `/third-audience/*` except `/login`; rewrite `/third-audience/login` → API handler
+- `src/nextjs-app/app/third-audience/layout.tsx` — red sticky warning banner when `isDefaultPassword: true`
+- `src/nextjs-app/app/api/third-audience/login/route.ts` — consumer route re-export
+- `package.json` — added `routes/login` and `dashboard/admin-store` exports
+- `tsup.config.ts` — added `admin-store.ts` to build entries
+- `.gitignore` — added `data/ta-admin.json`
+- `plugin/skills/setup-ta-admin/SKILL.md` — `/setup-ta-admin` slash command: 7-step checklist, init script, credential printout, verify curl, security notes
+- `INSTALLATION.md` — added Step 9 for admin login setup
+
+**Files touched:** src/dashboard/admin-store.ts, routes/login-route.ts, core/middleware.ts, nextjs-app/app/third-audience/layout.tsx, nextjs-app/app/api/third-audience/login/route.ts, package.json, tsup.config.ts, .gitignore, plugin/skills/setup-ta-admin/SKILL.md, INSTALLATION.md
+
+---
+
+## 2026-06-21 (session 5 — continued)
+
+**Asked:** Make the plugin work for other LLMs (Perplexity, Codex).
+
+**Done:**
+- Added `.codex-plugin/plugin.json` — Codex/Perplexity manifest with full interface metadata
+- Added `.cursor-plugin/plugin.json` — Cursor manifest
+- Added `.kimi-plugin/plugin.json` — Kimi Code manifest with skillInstructions tool mapping
+- Added `gemini-extension.json` + `GEMINI.md` — Gemini CLI support (loads skills via @-includes)
+- Added `hooks/hooks.json`, `hooks-codex.json`, `hooks-cursor.json` — empty hook stubs required by runtimes
+- Added `AGENTS.md` → symlink to `CLAUDE.md` (OpenAI Codex/Perplexity context file convention)
+- Updated `plugin/README.md` with runtime support table
+
+**Files touched:** plugin/.codex-plugin/plugin.json, .cursor-plugin/plugin.json, .kimi-plugin/plugin.json, gemini-extension.json, GEMINI.md, AGENTS.md, hooks/*, README.md
+
+---
+
+## 2026-06-21 (session 5)
+
+**Asked:** Package as a Claude Code plugin. Update README/plugin with "third audience" origin story from the original repo (remove WordPress references).
+
+**Done:**
+- Built Claude Code plugin at `plugin/` — package.json with `pi.skills`, CLAUDE.md, README.md
+- Wrote 3 skills: `setup-third-audience` (11-step install wizard), `add-ai-route` (detect + create missing routes), `debug-bot-detection` (full pipeline diagnosis with curl test matrix)
+- Fetched origin story from https://github.com/spcaeo/third-audience-wordpress-plugin: "For two decades, websites were built for two audiences: humans and search engines. Today there is a third: AI agents and LLM crawlers."
+- Updated README.md header with origin concept + GEO framing, removing old tagline
+- Updated plugin/README.md and plugin/CLAUDE.md with same concept, no WordPress references
+
+**Files touched:** plugin/package.json, plugin/CLAUDE.md, plugin/README.md, plugin/skills/setup-third-audience/SKILL.md, plugin/skills/add-ai-route/SKILL.md, plugin/skills/debug-bot-detection/SKILL.md, README.md
+
+---
+
+## 2026-06-20 (session 4)
+
+**Asked:** Update README and INSTALLATION.md. Remove WordPress plugin references. Delete wordpress-plugin/. Add attribution to original repo.
+
+**Done:**
+- Rewrote README.md — full features list, complete manual setup section, all API routes, dashboard pages, CLI, config reference, data schema, detected bots list, project structure
+- Rewrote INSTALLATION.md — 10-step guide, troubleshooting section, final directory structure
+- Removed "Differences from the WordPress Plugin" table from README
+- Added attribution to https://github.com/spcaeo/third-audience-wordpress-plugin
+- wordpress-plugin/ deleted (user ran rm -rf manually)
+
+**Files touched:** README.md, INSTALLATION.md
+
+---
+
+## 2026-06-20 (session 3)
+
+**Asked:** Complete the MDX plugin for Next.js — dashboard UI, consumer route files, sitemap route.
+
+**Done:**
+- Built 4 dashboard React pages (Next.js App Router server components): BotAnalyticsPage, LlmTrafficPage, BotManagementPage, SystemHealthPage
+- Built shared UI components: Sidebar, Card, HeroCard, VisitsChart (SVG bar chart)
+- Built Apple-inspired design system CSS (globals.css, 200+ lines)
+- Added missing sitemap-ai route handler (src/dashboard/routes/sitemap-ai-route.ts)
+- Created full Next.js consumer app structure (src/nextjs-app/) with all route.ts and page.tsx files
+- Added bots-config API route (GET/POST for allowlist/blocklist)
+- Added dashboard layout.tsx with Sidebar + CSS import
+- Expanded package.json exports map (16 subpath exports)
+- Added tsup.config.ts for JSX + CSS build
+- Created INSTALLATION.md with step-by-step setup guide
+
+**Files touched:** src/dashboard/ui/globals.css, components/Sidebar.tsx, Card.tsx, HeroCard.tsx, VisitsChart.tsx, pages/BotAnalyticsPage.tsx, LlmTrafficPage.tsx, BotManagementPage.tsx, SystemHealthPage.tsx, routes/sitemap-ai-route.ts, src/nextjs-app/app/** (12 files), package.json, tsup.config.ts, INSTALLATION.md
+
+---
+
+## 2026-06-20 (session 2)
+
+**Asked:** Clone WordPress plugin, move to /wordpress-plugin, create MDX-ready plugin.
+
+**Done:**
+- Cloned https://github.com/pooran/third-audience-mdx-plugin (123 files) into `wordpress-plugin/`
+- Scaffolded full MDX npm package structure in `src/`
+- Wrote all core modules: config, middleware, mdx-reader, markdown-renderer, bot-detection-pipeline, known-patterns, visit-tracker, geolocation, performance-stats, citation-tracker, citation-alerts, cache-manager, llms-txt, sitemap-ai, okf-bundle, all route handlers, auth, CLI (init/health/export), client citation-tracker.js
+- Created package.json, tsconfig.json, .gitignore, README.md
+- Wrote spec doc at docs/superpowers/specs/2026-06-20-third-audience-mdx-design.md
+
+**Files touched:** wordpress-plugin/ (123 files), src/ (30+ TypeScript files), package.json, tsconfig.json, .gitignore, README.md, docs/superpowers/specs/2026-06-20-third-audience-mdx-design.md
+
+**Still pending:** Dashboard React UI pages (Bot Analytics, LLM Traffic, Bot Management, System Health), sitemap-ai route handler, Next.js app/api route files for consumers.
+
+---
+
+## 2026-06-20
+
+**Asked:** Set up project tracking — CLAUDE.md, WORKLOG.md, memory entries.
+
+**Done:**
+- Created CLAUDE.md with: scope rules, worklog note, global rules, Execution (ultracode & workflows) section, and Discipline (verify, don't guess) section.
+- Created WORKLOG.md (this file).
+- Wrote memory entries: project-scope, ultracode-workflows reference, and verify-dont-guess behavior.
+- Added all three entries to MEMORY.md index.
+
+**Files touched:** CLAUDE.md, WORKLOG.md, /Users/pooran/.claude/projects/-Users-pooran-Downloads-Com-N-third/memory/project_scope.md, ultracode_workflows.md, verify_dont_guess.md, MEMORY.md

package/dist/cli/index.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli/commands/init.ts
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+var import_readline = __toESM(require("readline"));
+async function init() {
+  const cwd = process.cwd();
+  console.log("\n\u{1F3AF} third-audience-mdx setup\n");
+  const pkgPath = import_path.default.join(cwd, "package.json");
+  if (!import_fs.default.existsSync(pkgPath)) {
+    console.error("No package.json found. Run this from your Next.js project root.");
+    process.exit(1);
+  }
+  const pkg = JSON.parse(import_fs.default.readFileSync(pkgPath, "utf-8"));
+  if (!pkg.dependencies?.next && !pkg.devDependencies?.next) {
+    console.warn("\u26A0  next not found in package.json \u2014 make sure this is a Next.js project.");
+  }
+  const rl = import_readline.default.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q, def) => new Promise(
+    (r) => rl.question(`${q} (${def}): `, (ans) => r(ans.trim() || def))
+  );
+  const contentDir = await ask("Content directory (where your .mdx files live)", "content");
+  const dataDir = await ask("Data directory (for analytics logs)", "data");
+  const secret = await ask("Dashboard secret (leave blank to disable auth in dev)", "");
+  rl.close();
+  const middlewarePath = import_path.default.join(cwd, "middleware.ts");
+  if (!import_fs.default.existsSync(middlewarePath)) {
+    import_fs.default.writeFileSync(middlewarePath, `export { thirdAudienceMiddleware as middleware } from 'third-audience-mdx'
+export const config = { matcher: ['/((?!_next|api).*)'] }
+`);
+    console.log("\u2705 Created middleware.ts");
+  } else {
+    console.log("\u26A0  middleware.ts already exists \u2014 add thirdAudienceMiddleware manually.");
+  }
+  const envPath = import_path.default.join(cwd, ".env.local");
+  const envLines = [`THIRD_AUDIENCE_SECRET=${secret}`, `NEXT_PUBLIC_SITE_URL=http://localhost:3000`];
+  const envContent = envLines.join("\n") + "\n";
+  if (!import_fs.default.existsSync(envPath)) {
+    import_fs.default.writeFileSync(envPath, envContent);
+    console.log("\u2705 Created .env.local");
+  } else {
+    import_fs.default.appendFileSync(envPath, "\n# Third Audience\n" + envContent);
+    console.log("\u2705 Appended to .env.local");
+  }
+  import_fs.default.mkdirSync(import_path.default.join(cwd, dataDir, "ta-cache"), { recursive: true });
+  const gitignorePath = import_path.default.join(cwd, ".gitignore");
+  const gitignoreAdditions = `
+# Third Audience analytics (local only)
+${dataDir}/ta-visits.jsonl
+${dataDir}/ta-citations.jsonl
+${dataDir}/ta-cache/
+`;
+  if (import_fs.default.existsSync(gitignorePath)) {
+    import_fs.default.appendFileSync(gitignorePath, gitignoreAdditions);
+  } else {
+    import_fs.default.writeFileSync(gitignorePath, gitignoreAdditions.trimStart());
+  }
+  console.log(`\u2705 Created ${dataDir}/ and updated .gitignore`);
+  console.log(`
+\u2705 Setup complete!
+
+Next steps:
+  1. Add to next.config.ts:
+       import { withThirdAudience } from 'third-audience-mdx'
+       export default withThirdAudience({ contentDir: '${contentDir}', dataDir: '${dataDir}' })
+
+  2. Add API routes in app/api/third-audience/ (see docs)
+
+  3. Visit /third-audience/ for your dashboard
+`);
+}
+
+// src/cli/commands/health.ts
+var import_fs2 = __toESM(require("fs"));
+var import_path2 = __toESM(require("path"));
+async function health() {
+  const cwd = process.cwd();
+  const checks = [];
+  const nodeVersion = process.versions.node;
+  const [nodeMajor] = nodeVersion.split(".").map(Number);
+  checks.push({ label: `Node.js ${nodeVersion}`, ok: nodeMajor >= 18, note: nodeMajor < 18 ? "requires Node 18+" : void 0 });
+  const pkgPath = import_path2.default.join(cwd, "package.json");
+  checks.push({ label: "package.json", ok: import_fs2.default.existsSync(pkgPath) });
+  const nextPath = import_path2.default.join(cwd, "node_modules", "next");
+  checks.push({ label: "next installed", ok: import_fs2.default.existsSync(nextPath) });
+  const middlewarePath = import_path2.default.join(cwd, "middleware.ts");
+  checks.push({ label: "middleware.ts", ok: import_fs2.default.existsSync(middlewarePath) });
+  const contentDir = process.env.TA_CONTENT_DIR ?? "content";
+  const contentPath = import_path2.default.join(cwd, contentDir);
+  const contentExists = import_fs2.default.existsSync(contentPath);
+  const mdxCount = contentExists ? countFiles(contentPath, [".mdx", ".md"]) : 0;
+  checks.push({ label: `contentDir (${contentDir})`, ok: contentExists, note: contentExists ? `${mdxCount} MDX files` : "directory not found" });
+  const dataDir = process.env.TA_DATA_DIR ?? "data";
+  const dataPath = import_path2.default.join(cwd, dataDir);
+  checks.push({ label: `dataDir (${dataDir})`, ok: import_fs2.default.existsSync(dataPath) });
+  const visitsPath = import_path2.default.join(cwd, dataDir, "ta-visits.jsonl");
+  const citationsPath = import_path2.default.join(cwd, dataDir, "ta-citations.jsonl");
+  const visitLines = import_fs2.default.existsSync(visitsPath) ? countLines(visitsPath) : 0;
+  const citationLines = import_fs2.default.existsSync(citationsPath) ? countLines(citationsPath) : 0;
+  checks.push({ label: "ta-visits.jsonl", ok: true, note: `${visitLines} records` });
+  checks.push({ label: "ta-citations.jsonl", ok: true, note: `${citationLines} records` });
+  checks.push({ label: "THIRD_AUDIENCE_SECRET", ok: !!process.env.THIRD_AUDIENCE_SECRET, note: !process.env.THIRD_AUDIENCE_SECRET ? "not set (dashboard is open)" : "set" });
+  console.log("\n\u{1F3E5} third-audience health check\n");
+  for (const c of checks) {
+    const icon = c.ok ? "\u2705" : "\u274C";
+    const note = c.note ? `  (${c.note})` : "";
+    console.log(`  ${icon}  ${c.label}${note}`);
+  }
+  console.log();
+}
+function countFiles(dir, exts) {
+  let count = 0;
+  for (const entry of import_fs2.default.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) count += countFiles(import_path2.default.join(dir, entry.name), exts);
+    else if (exts.some((e) => entry.name.endsWith(e))) count++;
+  }
+  return count;
+}
+function countLines(filePath) {
+  return import_fs2.default.readFileSync(filePath, "utf-8").split("\n").filter(Boolean).length;
+}
+
+// src/cli/commands/export.ts
+var import_fs3 = __toESM(require("fs"));
+var import_path3 = __toESM(require("path"));
+async function exportData(args2) {
+  const dataDir = process.env.TA_DATA_DIR ?? "data";
+  const type = args2[0] ?? "visits";
+  const outPath = args2[1] ?? `ta-${type}-export.csv`;
+  const file = type === "citations" ? "ta-citations.jsonl" : "ta-visits.jsonl";
+  const jsonlPath = import_path3.default.join(process.cwd(), dataDir, file);
+  if (!import_fs3.default.existsSync(jsonlPath)) {
+    console.error(`No data found at ${jsonlPath}`);
+    process.exit(1);
+  }
+  const records = import_fs3.default.readFileSync(jsonlPath, "utf-8").split("\n").filter(Boolean).map((l) => {
+    try {
+      return JSON.parse(l);
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+  if (records.length === 0) {
+    console.log("No records to export.");
+    return;
+  }
+  const headers = Object.keys(records[0]);
+  const csv = [
+    headers.join(","),
+    ...records.map((r) => headers.map((h) => csvCell(r[h])).join(","))
+  ].join("\n") + "\n";
+  import_fs3.default.writeFileSync(outPath, csv);
+  console.log(`\u2705 Exported ${records.length} records to ${outPath}`);
+}
+function csvCell(val) {
+  if (val === null || val === void 0) return "";
+  const s = String(val);
+  if (/[",\n]/.test(s)) return `"${s.replace(/"/g, '""')}"`;
+  return s;
+}
+
+// src/cli/index.ts
+var [, , command, ...args] = process.argv;
+switch (command) {
+  case "init":
+    init().catch(console.error);
+    break;
+  case "health":
+    health().catch(console.error);
+    break;
+  case "export":
+    exportData(args).catch(console.error);
+    break;
+  default:
+    console.log(`third-audience CLI
+
+Commands:
+  init      Set up third-audience-mdx in your Next.js project
+  health    Show system health status
+  export    Export analytics data as CSV
+
+Usage: npx third-audience <command>`);
+}
+//# sourceMappingURL=index.js.map