joelclaw-web

joelclaw.com Web App

Next.js app at apps/​web/ in the joelclaw monorepo (~/​Code/​joelhooks/​joelclaw/). Deployed to Vercel on push to main. Dark theme, minimal, system-y aesthetic.

OPSEC Rules

Never expose real infrastructure details on public pages.

• Node/​host names: Use Stephen King universe aliases, never real tailnet hostnames
• Ports: Do not publish port numbers for any service
• Usernames: Strip com.joel. or similar prefixes from service identifiers
• IPs/​subnets: Never show real IP addresses or CIDR ranges
• Brands/​models of network gear: Generalize (e.g. "NAS" not "Synology DS1821+")
• Tailscale: OK to mention as the mesh VPN product, but no tailnet name or node IPs

Current King universe mapping (network page):

Content Model (Convex-first)

Canonical runtime content lives in Convex contentResources:

• article:<slug> (type = article)
• adr:<slug> (type = adr)
• discovery:<slug> (type = discovery)

Filesystem content under apps/​web/​content/ is seed/​backfill material, not runtime source.

Runtime read policy:

• apps/​web/​lib/​posts.ts → Convex-first articles (article:*)
• apps/​web/​lib/​adrs.ts → Convex-first ADRs (adr:*)
• apps/​web/​lib/​discoveries.ts → Convex-first discoveries (discovery:*)
• Optional local escape hatches (non-production only):
  • JOELCLAW_ALLOW_FILESYSTEM_POSTS_FALLBACK=1 (articles)
  • JOELCLAW_ALLOW_FILESYSTEM_CONTENT_FALLBACK=1 (ADRs/​discoveries)

Article fields still mirror MDX frontmatter shape:

---
title: "Post Title"
type: "article" | "essay" | "note" | "tutorial"
date: "2026-02-19T11:00:00"        # ISO datetime, NOT just date
updated: "2026-02-19T14:30:00"     # optional, bumps sort position
description: "One-liner for cards and meta"
tags: ["tag1", "tag2"]
draft: true                         # optional, hides from prod
source: "https://..."               # optional, for video-notes
channel: "Channel Name"             # optional, for video-notes
duration: "00:42:02"                # optional, for video-notes
---

Sorting: Posts sort by updated ?? date descending. Use full ISO datetimes (not bare dates) for deterministic ordering. Setting updated bumps a post to the top without changing its original publish date.

Slugs: Derived from fields.slug in Convex (resourceId = article:<slug>).

Hard Trigger Workflow

write article about X

1. Generate slug from title/​topic.
2. Upsert contentResources with resourceId = article:<slug>, type = "article", full MDX body in fields.content, and fields.draft = true.
3. Set fields.date to current ISO timestamp.
4. Return slug + draft preview link (/<slug> if draft-visible in dev).

publish article <slug>

1. Read article:<slug> from Convex.
2. Patch/​upsert with fields.draft = false and fields.updated = now.
3. Revalidate all affected surfaces via POST /​api/​revalidate with:
   • tags: post:<slug>, article:<slug>, articles
   • paths: /, /<slug>, /<slug>.md, /<slug>/​md, /​feed.xml, /​sitemap.md
4. Verify /, /<slug>, /<slug>.md, and /​feed.xml include the published post.

Media Embeds

Always embed YouTube videos in /​cool discoveries and articles when they add context. Use the <YouTube id="VIDEO_ID" /> MDX component (available in both .mdx articles and .md discoveries). Extract the video ID from the URL (youtube.com/​watch?v=VIDEO_ID). Place embeds near the top of the relevant section, before the prose discussion.

Writing Voice

Use the canonical joel-writing-style skill for prose. Key traits: direct, first-person when the claim is actually Joel's, strategic profanity, short paragraphs, bold emphasis, conversational but technical. Never corporate-speak and never fabricate Joel's beliefs or philosophy.

Design System

• Theme: Dark (bg-[#0a0a0a]), neutral grays, --color-claw: #ff1493 (hot pink accent)
• Fonts: Geist Sans (body), Geist Mono (code/​data), Dank Mono (code blocks with ligatures)
• Content width: max-w-2xl (672px) — intentionally narrow for reading
• Header: Single row — claw icon + "JoelClaw" left, nav links + search right. No tagline in header.
• Nav items: Writing (/), Cool (/​cool), ADRs (/​adrs), Network (/​network)
• Active nav: White text vs neutral-500 for inactive, detected via usePathname()
• Search: ⌘K dialog using pagefind, type-based icons/​badges
• Mobile: Full-screen overlay nav via MobileNav component
• Code blocks: Catppuccin Macchiato theme, rehype-pretty-code
• Sidenotes: Tufte-style CSS sidenotes (pure CSS, no JS)

Key Files

ADR Display Rules

• ADR runtime source is Convex (contentResources with resourceId = adr:<slug>)
• Vault sync still updates repo snapshots under apps/​web/​content/​adrs/
• Project snapshots into Convex with: bun scripts/​seed-adrs-discoveries.ts
• The detail page (app/​adrs/[slug]/​page.tsx) strips the H1 from markdown content because the page already renders the title with ADR number prefix
• Regex: content.replace(/^#\s+(?:ADR-\d+:\s*)?.*$/​m, "").trim()

Adding a New Post

1. Draft in Convex (contentResources.upsert, resourceId = article:<slug>, draft: true).
2. Use ISO datetime in date field.
3. Add images to apps/​web/​public/​images/<slug>/ if needed and reference /​images/<slug>/​... in MDX.
4. Publish by setting draft: false, then revalidate tags + paths (post:<slug>, article:<slug>, articles, /, /<slug>, /<slug>.md, /<slug>/​md, /​feed.xml, /​sitemap.md).
5. Verify route + markdown twin + homepage + feed consistency.

Backfill scripts:

• scripts/​seed-articles.ts for article resources
• scripts/​seed-adrs-discoveries.ts for ADR + discovery resources

Network Page

The network page (app/​network/​page.tsx) shows real infrastructure with aliased names. When updating:

1. Check actual system state (kubectl get pods, tailscale status, launchctl print, etc.)
2. Apply OPSEC rules — alias all hostnames, strip ports/​IPs/​usernames
3. Keep data arrays at top of file for easy updates
4. Status dots: green (Online) with ping animation, yellow (Idle), gray (Offline)