Moved briefs to category-specific subfolders.

CLAUDE.md

@@ -63,6 +63,21 @@ The repository includes a justfile for convenient local development:
 
 4. **GitHub Pages deployment**: Push changes to the main branch and GitHub Actions will automatically build and deploy via the `.github/workflows/deploy.yml` workflow
 
+### Code Style and Linting
+
+**IMPORTANT**: This project enforces strict linting rules via ESLint. Always run the linter before committing:
+
+```bash
+npm run lint        # Check for linting errors
+npm run lint:fix    # Auto-fix linting errors where possible
+```
+
+Key linting requirements:
+- **Use double quotes for strings** - NOT single quotes (TypeScript/JavaScript)
+- The project uses ESLint with strict quote rules
+- CI/CD will fail if linting errors are present
+- Always verify with `npm run lint` before pushing changes
+
 ### Content Structure
 
 #### Blog Posts
@@ -75,11 +90,14 @@ src/content/blog/my-new-post/
 Posts should include front matter with relevant metadata.
 
 #### Briefs (Short Notes)
-Create brief notes in `src/content/briefs/` as individual markdown files:
+Create brief notes in category subfolders within `src/content/briefs/`:
 ```
-src/content/briefs/my-brief.md
+src/content/briefs/swift-warts/my-swift-brief.md
+src/content/briefs/claude-code/my-claude-brief.md
 ```
 
+Categories are auto-discovered from folder names. To add a new category, simply create a new folder. You can optionally add a `category.yaml` file in the folder to customize the category metadata (display name, description, sort priority).
+
 #### Projects
 Create project pages in `src/content/projects/` as folders with an `index.md` file:
 ```

package.json

@@ -40,7 +40,8 @@
     "sharp": "^0.33.3",
     "tailwind-merge": "^2.2.2",
     "tailwindcss": "^3.4.1",
-    "typescript": "^5.4.2"
+    "typescript": "^5.4.2",
+    "yaml": "^2.8.1"
   },
   "devDependencies": {
     "eslint-plugin-jsx-a11y": "^6.10.2"

src/content/blog/meso-optimization/index.md

@@ -47,7 +47,7 @@ When someone says an app feels "native" or "polished," they're often responding
 
 [^1]: Many of the best "native apps" aren't even native—there's lots of world-class, incredibly-polished Reactive Native out there.
 
-The frustrating part? This stuff is hard to teach, hard to measure, and incredibly easy to break. One well-meaning refactor can silently undo a meso-optimization, or even several. [Your beautiful lazy sequence chains suddenly become eager](/briefs/lazy-sequences-decay-easily). Your carefully-managed view updates start firing twice. The app still works, all your tests pass, but somehow it doesn't feel quite as good anymore.
+The frustrating part? This stuff is hard to teach, hard to measure, and incredibly easy to break. One well-meaning refactor can silently undo a meso-optimization, or even several. [Your beautiful lazy sequence chains suddenly become eager](/briefs/swift-warts/lazy-sequences-decay-easily). Your carefully-managed view updates start firing twice. The app still works, all your tests pass, but somehow it doesn't feel quite as good anymore.
 
 ## The Point of All This
 

src/content/briefs/claude-code/category.yaml

@@ -0,0 +1,4 @@
+displayName: "Claude Code"
+titlePrefix: "Claude Code"
+description: "Briefs about using and optimizing Claude Code, the agentic coding assistant"
+sortPriority: 2

src/content/briefs/claude-code-never-compact.md → src/content/briefs/claude-code/claude-code-never-compact.md

@@ -1,7 +1,6 @@
 ---
 title: "Never `compact`"
 description: "Claude Code's `/compact` command exists and seems useful, but should *rarely* be used."
-category: "Claude Code"
 date: "2025-07-25"
 ---
 

src/content/briefs/claude-code-pricing.md → src/content/briefs/claude-code/claude-code-pricing.md

@@ -2,7 +2,6 @@
 title: "Claude Code's Subscription Pricing vs GPT-5"
 cardTitle: "Subscription Pricing vs GPT-5"
 description: "Anthropics subscriptions are economical, but so GPT-5."
-category: "Claude Code"
 date: "2025-08-08"
 ---
 

src/content/briefs/swift-warts/category.yaml

@@ -0,0 +1,4 @@
+displayName: "Swift Warts"
+titlePrefix: "Swift Wart"
+description: "Briefs about unfortunate pain points in the Swift language and standard library"
+sortPriority: 3

src/content/briefs/first-trailing-closure-cannot-have-a-label.md → src/content/briefs/swift-warts/first-trailing-closure-cannot-have-a-label.md

@@ -2,7 +2,6 @@
 title: "Swift's First Trailing Closure Cannot Have a Label"
 cardTitle: "First Trailing Closure Cannot Have a Label"
 description: "Swift forbids labeling the first trailing closure, which can be a surprising obstacle to idiomatic API design."
-category: "Swift Wart"
 date: "2025-07-16"
 ---
 

src/content/briefs/lazy-sequences-decay-easily.md → src/content/briefs/swift-warts/lazy-sequences-decay-easily.md

@@ -1,7 +1,6 @@
 ---
 title: "Lazy Sequences \"Decay\" Easily"
 description: "Swift's lazy functional API is elegant, but prone to silently decaying back to its eager equivalent."
-category: "Swift Wart"
 date: "2025-07-15"
 ---
 

src/content/briefs/lazy-sequences-lack-primary-associated-types.md → src/content/briefs/swift-warts/lazy-sequences-lack-primary-associated-types.md

@@ -1,7 +1,6 @@
 ---
 title: "Lazy Sequences Lack Primary Associated Types"
 description: "You can write `Sequence<Element>` but not `LazySequenceProtocol<Element>`"
-category: "Swift Wart"
 date: "2025-07-18"
 ---
 

src/content/briefs/name-collisions-in-result-builders.md → src/content/briefs/swift-warts/name-collisions-in-result-builders.md

@@ -1,7 +1,6 @@
 ---
 title: "Name Collisions in Result Builders"
 description: "You get a `ForEach`, and you get a `ForEach`, and..."
-category: "Swift Wart"
 date: "2025-07-17"
 ---
 

src/content/briefs/no-concept-of-generic-actor-isolation-parameters.md → src/content/briefs/swift-warts/no-concept-of-generic-actor-isolation-parameters.md

@@ -2,7 +2,6 @@
 title: "Swift Cannot Express Generic Actor Isolation Parameters"
 cardTitle: "You Cannot Express Generic Actor Isolation Parameters"
 description: "Swift lets you write `@MainActor` and `@SomeOtherActor`, but not `@'A`, where `A` is a generic actor parameter."
-category: "Swift Wart"
 date: "2025-07-20"
 ---
 

src/content/briefs/sendable-custom-cow-and-lazy-cached-properties.md → src/content/briefs/swift-warts/sendable-custom-cow-and-lazy-cached-properties.md

@@ -1,7 +1,6 @@
 ---
 title: "Lazy Sequences Lack Primary Associated Types"
 description: "You can write `Sequence<Element>` but not `LazySequenceProtocol<Element>`"
-category: "Swift Wart"
 date: "2025-07-18"
 ---
 

src/content/config.ts

@@ -20,7 +20,6 @@ const briefs = defineCollection({
     title: z.string(),
     cardTitle: z.string().optional(),
     description: z.string(),
-    category: z.string(),
     date: z.coerce.date(),
     draft: z.boolean().optional()
   }).transform((data) => ({

src/lib/category.ts

@@ -0,0 +1,96 @@
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { parse } from "yaml";
+
+export interface BriefCategory {
+  slug: string;
+  displayName: string;
+  titlePrefix?: string;
+  description?: string;
+  sortPriority?: number;
+}
+
+/**
+ * Convert a kebab-case slug to a display name
+ * e.g., "swift-warts" -> "Swift Warts"
+ */
+function slugToDisplayName(slug: string): string {
+  return slug
+    .split("-")
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+/**
+ * Create a default category from a directory name
+ */
+export function getCategoryFromSlug(slug: string): BriefCategory {
+  const displayName = slugToDisplayName(slug);
+  return {
+    slug,
+    displayName,
+    titlePrefix: displayName,
+    sortPriority: 0
+  };
+}
+
+/**
+ * Load category overrides from a category.yaml file if it exists
+ */
+export function loadCategoryOverrides(categoryPath: string): Partial<BriefCategory> | null {
+  const overridePath = join(categoryPath, "category.yaml");
+
+  if (!existsSync(overridePath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(overridePath, "utf-8");
+    return parse(content) as Partial<BriefCategory>;
+  } catch (error) {
+    console.warn(`Failed to parse category.yaml in ${categoryPath}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Get the full category metadata, combining defaults with overrides
+ */
+export function getCategory(slug: string, categoryPath: string): BriefCategory {
+  const defaultCategory = getCategoryFromSlug(slug);
+  const overrides = loadCategoryOverrides(categoryPath);
+
+  if (!overrides) {
+    return defaultCategory;
+  }
+
+  return {
+    ...defaultCategory,
+    ...overrides,
+    slug // Always preserve the original slug
+  };
+}
+
+/**
+ * Extract category slug from a brief's slug
+ * e.g., "swift-warts/lazy-sequences" -> "swift-warts"
+ */
+export function extractCategoryFromSlug(briefSlug: string): string | null {
+  const parts = briefSlug.split("/");
+  if (parts.length > 1) {
+    return parts[0];
+  }
+  return null; // Uncategorized brief
+}
+
+/**
+ * Extract the brief's relative slug within its category
+ * e.g., "swift-warts/lazy-sequences" -> "lazy-sequences"
+ */
+export function extractBriefSlugFromPath(fullSlug: string): string {
+  const parts = fullSlug.split("/");
+  if (parts.length > 1) {
+    return parts.slice(1).join("/");
+  }
+  return fullSlug; // Uncategorized brief
+}

src/lib/contentCardHelpers.ts

@@ -1,4 +1,5 @@
 import type { CollectionEntry } from "astro:content";
+import { extractCategoryFromSlug, getCategory } from "./category";
 
 /**
  * Transform a blog or project entry into ContentCard props
@@ -36,8 +37,17 @@ export function getProjectCardProps(entry: CollectionEntry<"blog"> | CollectionE
 export function getBriefCardProps(entry: CollectionEntry<"briefs">, includeCategory = true, maxLines?: number | "none") {
   const displayTitle = entry.data.cardTitle || entry.data.title;
 
+  // Extract category from slug path
+  const categorySlug = extractCategoryFromSlug(entry.slug);
+  let categoryPrefix: string | undefined;
+
+  if (includeCategory && categorySlug) {
+    const category = getCategory(categorySlug, `src/content/briefs/${categorySlug}`);
+    categoryPrefix = category.titlePrefix || category.displayName;
+  }
+
   return {
-    titlePrefix: includeCategory ? entry.data.category : undefined,
+    titlePrefix: categoryPrefix,
     title: displayTitle,
     subtitle: entry.data.description,
     link: `/${entry.collection}/${entry.slug}`,

src/pages/briefs/[...slug].astro

@@ -4,6 +4,7 @@ import PageLayout from "@layouts/PageLayout.astro";
 import Container from "@components/Container.astro";
 import FormattedDate from "@components/FormattedDate.astro";
 import BackToPrev from "@components/BackToPrev.astro";
+import { extractCategoryFromSlug, getCategory } from "@lib/category";
 
 export async function getStaticPaths() {
   const briefs = (await getCollection("briefs"))
@@ -18,24 +19,32 @@ type Props = CollectionEntry<"briefs">;
 
 const brief = Astro.props;
 const { Content } = await brief.render();
+
+// Extract category from the slug
+const categorySlug = extractCategoryFromSlug(brief.slug);
+const category = categorySlug ? getCategory(categorySlug, `src/content/briefs/${categorySlug}`) : null;
 ---
 
 <PageLayout title={brief.data.title} description={brief.data.description}>
   <Container>
     <div class="animate">
-      <BackToPrev href="/briefs">
-        Back to briefs
+      <BackToPrev href={categorySlug ? `/briefs/${categorySlug}` : "/briefs"}>
+        Back to {categorySlug ? category?.displayName + " briefs" : "briefs"}
       </BackToPrev>
     </div>
     <div class="space-y-1 my-10">
       <div class="animate flex items-center gap-1.5">
         <div class="font-base text-sm">
           <FormattedDate date={brief.data.date} />
         </div>
-        &bull;
-        <div class="font-base text-sm">
-          {brief.data.category}
-        </div>
+        {category && (
+          <>
+            &bull;
+            <div class="font-base text-sm">
+              {category.titlePrefix || category.displayName}
+            </div>
+          </>
+        )}
       </div>
       <div class="animate text-2xl font-semibold text-black dark:text-white">
         {brief.data.title}