Clean docs and add Plausible tracking

.env.local.example

@@ -1,2 +1,6 @@
 # Created automatically by `bunx convex dev`:
 # VITE_CONVEX_URL=https://<your-deployment>.convex.cloud
+
+# Optional: enable Plausible Analytics in browser builds.
+# Use the exact site domain configured in Plausible.
+# VITE_PLAUSIBLE_DOMAIN=postwork.pcstyle.dev

AGENTS.md

@@ -76,30 +76,19 @@ friendly "configure a provider" message instead of crashing.
 
 ## Design Context
 
-Strategic design context lives in `PRODUCT.md` (register, users, brand
+Strategic design context lives in `docs/product.md` (register, users, brand
 personality, anti-references, design principles). Visual system is documented in
-`DESIGN.md`. These are maintained by the `impeccable` design skill
+`docs/design.md`. These are maintained by the `impeccable` design skill
 (`.agents/skills/impeccable/`); run `$impeccable` for the command menu, or e.g.
 `$impeccable critique <surface>` / `$impeccable polish <component>`. The concrete
 visual rules below remain the quick reference.
 
 ## Design conventions (style is derived from pcstyle.dev)
 
-Dark terminal/developer aesthetic. Tokens live in `src/index.css` `@theme`:
-
-- Warm near-black: `--color-bg #0a0a0b`, `--color-surface #121014`,
-  hairline `--color-border #252327`, text `--color-fg #e8e6e3`,
-  muted `--color-muted #8a8782`.
-- Single accent: deep wine `--color-accent #8c1862` (soft `#b53a82`). One accent
-  per page — use `accent`, never reintroduce indigo/blue.
-- **Monospace everywhere** (`--font-mono`). This is the defining trait.
-- Small radii (cards `rounded-lg` 8px, controls `rounded-md` 6px).
-- **Lowercase chrome** (nav, buttons, filters, labels). User content keeps its
-  own casing.
-- **No emoji / pictographs** in UI or code. Use mono text affordances
-  (`/` search prompt, `ai` tag, `active 5d ago`). Typographic arrows (`←` `→`) ok.
-- Priority colors are warm/muted state colors in `src/lib/format.ts`
-  (urgent coral, high gold, normal grey), not the page accent.
+Use `docs/design.md` as the canonical visual system. Quick reference: warm
+near-black surfaces, deep wine accent, Inter for product UI, mono for code/data
+affordances, small radii, lowercase chrome, no emoji/pictographs, and muted
+priority state colors from `src/lib/format.ts`.
 
 ## Code conventions
 
@@ -114,8 +103,9 @@ Dark terminal/developer aesthetic. Tokens live in `src/index.css` `@theme`:
 ## Deployment
 
 Frontend is a static Vite build (`dist/`) → deploy to Vercel. Convex Cloud hosts
-the backend; set the AI env vars on the Convex deployment, and `VITE_CONVEX_URL`
-on the frontend host.
+the backend; set the AI env vars on the Convex deployment. The committed Vercel
+build command injects `VITE_CONVEX_URL`; set `CONVEX_DEPLOY_KEY` and
+`VITE_PLAUSIBLE_DOMAIN=postwork.pcstyle.dev` in Vercel.
 
 <!-- convex-ai-start -->
 

README.md

@@ -135,13 +135,20 @@ Push the repo to GitHub and import it at vercel.com (or run `bunx vercel`). Set:
 | --- | --- |
 | Framework preset | **Vite** |
 | Install command | `bun install` |
-| Build command | `bunx convex deploy --cmd 'bun run build'` |
+| Build command | `bunx convex deploy --cmd-url-env-var-name VITE_CONVEX_URL --cmd 'bun run build'` |
 | Output directory | `dist` |
 | Environment variable | `CONVEX_DEPLOY_KEY` = the `prod:` key from step 2 |
+| Environment variable | `VITE_PLAUSIBLE_DOMAIN` = `postwork.pcstyle.dev` |
 
 Deploy. Do **not** set `VITE_CONVEX_URL` yourself — `convex deploy --cmd` sets it
 during the build to point at your production deployment.
 
+Plausible's NPM verifier expects the Vite build to include the same domain you
+registered in Plausible. For this Vercel demo, that domain is
+`postwork.pcstyle.dev`. Add that custom domain under Vercel Project → Domains,
+redeploy after setting `VITE_PLAUSIBLE_DOMAIN`, then verify the Plausible NPM
+installation against `postwork.pcstyle.dev`.
+
 ### 5. Seed the production data (one time)
 
 ```bash

docs/next.md

@@ -0,0 +1,43 @@
+# Next
+
+Postwork now has the core demo loop in place: a centered reading shell, routable feed filters, quick post creation, post detail with nested replies, spaces, walls, flash experiments, and AI summary/task surfaces. The next work should reduce prototype split-brain and make the deployed demo easier to evaluate.
+
+## 1. make spaces use real post threads
+
+**Why it matters:** `convex/schema.ts` and `convex/spaces.ts` already model spaces, memberships, visibility, and space feeds, but the frontend still renders shared-space content from `src/lib/spaces.tsx` as session-only cards in `src/routes/SpacePage.tsx`. Those cards do not open durable `/posts/$postId` threads, so spaces feel like a parallel mock product.
+
+**Done looks like:** creating or viewing a space post uses the same post detail, replies, unread, priority, search, and agent-summary mechanics as the main feed; visibility is legible; space feeds reuse post-card/thread primitives instead of inert local articles.
+
+**Main files / areas:** `convex/schema.ts`, `convex/posts.ts`, `convex/spaces.ts`, `src/lib/spaces.tsx`, `src/routes/SpacePage.tsx`, `src/routes/SpacesPage.tsx`, `src/components/PostCard.tsx`, `src/routes/PostPage.tsx`.
+
+## 2. consolidate composer surfaces
+
+**Why it matters:** the app has multiple creation paths with slightly different behavior: `QuickPostBar`, `NewPostDialog`, `WallPostDialog`, reply `Composer`, and the space-local composer. That makes the prototype harder to reason about and easier to regress.
+
+**Done looks like:** one composer vocabulary covers posts, replies, wall notes, and space posts where appropriate; validation, disabled states, priority controls, submit shortcuts, and navigation after creation are consistent.
+
+**Main files / areas:** `src/components/QuickPostBar.tsx`, `src/components/NewPostDialog.tsx`, `src/components/WallPostDialog.tsx`, `src/components/Composer.tsx`, `src/routes/SpacePage.tsx`, `src/lib/store.tsx`.
+
+## 3. harden the AI catch-up loop
+
+**Why it matters:** agent summaries and dispatched agent tasks are the clearest differentiator from chat, but they are still split between post summary regeneration, in-memory task state, and local reply injection.
+
+**Done looks like:** stale summaries are obvious after new replies; summary copy explains included context; agent-task results are easy to find from the post and `/agents`; failed/no-key states remain calm; transcripts include enough nested reply context to be useful.
+
+**Main files / areas:** `src/components/AgentSummary.tsx`, `src/components/AgentTasksPanel.tsx`, `src/components/ReplyTree.tsx`, `src/components/SendAgentButton.tsx`, `src/lib/agentTasks.tsx`, `convex/ai.ts`, `convex/agentTasks.ts`.
+
+## 4. prune or graduate flash experiments
+
+**Why it matters:** the lab still contains shipped, deprecated, and active ideas. That is useful while designing, but the demo should not make evaluators wonder which shell/composer is canonical.
+
+**Done looks like:** shipped experiments are clearly historical or removed from the active lab; deprecated experiments either explain their lesson briefly or move to archive; the default app shell remains the canonical experience.
+
+**Main files / areas:** `src/flashExperiments/*`, `src/routes/FlashExperimentsPage.tsx`, `src/components/AppShell.tsx`, `docs/archive/`.
+
+## 5. run a deployed-demo polish pass
+
+**Why it matters:** the product promise depends on immediate readability: quiet density, priority at a glance, and no rough prototype seams.
+
+**Done looks like:** feed, post detail, new post, replies, agents, spaces, walls, and flash lab are checked at desktop and narrow widths; focus states and keyboard paths work; lowercase chrome and single-accent discipline hold; empty/loading/error states share the same voice; Vercel/Plausible/Convex deploy notes are current.
+
+**Main files / areas:** `src/routes/*`, `src/components/*`, `src/index.css`, `README.md`, `docs/product.md`, `docs/design.md`.

package.json

@@ -18,6 +18,7 @@
     "@ai-sdk/openai": "^4.0.0-beta.77",
     "@ai-sdk/openai-compatible": "beta",
     "@fontsource-variable/inter": "^5.2.8",
+    "@plausible-analytics/tracker": "^0.4.5",
     "@shoojs/react": "^0.2.2",
     "@tanstack/react-router": "latest",
     "ai": "beta",

src/analytics.ts

@@ -0,0 +1,21 @@
+import { init } from "@plausible-analytics/tracker";
+
+const plausibleDomain = import.meta.env.VITE_PLAUSIBLE_DOMAIN;
+
+declare global {
+  interface Window {
+    __postworkPlausibleInitialized?: boolean;
+  }
+}
+
+if (plausibleDomain && typeof window !== "undefined" && !window.__postworkPlausibleInitialized) {
+  try {
+    init({
+      domain: plausibleDomain,
+      outboundLinks: true,
+    });
+    window.__postworkPlausibleInitialized = true;
+  } catch {
+    // Analytics is optional; never block app startup.
+  }
+}

src/main.tsx

@@ -10,6 +10,7 @@ import { SpacesProvider } from "./lib/spaces";
 import { router } from "./router";
 import { ExperimentProvider } from "./flashExperiments/active";
 import { useAuth } from "./shoo";
+import "./analytics";
 import "@fontsource-variable/inter/index.css";
 import "./index.css";
 

src/vite-env.d.ts

@@ -1 +1,9 @@
 /// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_PLAUSIBLE_DOMAIN?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}