@marlinjai/clearify 1.7.3 → 1.9.0

package/README.md

@@ -20,19 +20,19 @@ An open-source documentation site generator. Turn markdown into beautiful docs.
 Install Clearify as a dev dependency:
 
 ```bash
-npm install @marlinjai/clearify --save-dev
+pnpm add -D @marlinjai/clearify
 ```
 
 Scaffold your project:
 
 ```bash
-npx clearify init
+pnpm exec clearify init
 ```
 
 Start the dev server:
 
 ```bash
-npx clearify dev
+pnpm exec clearify dev
 ```
 
 Your docs are live at `http://localhost:4747`.

package/dist/node/{chunk-O3SK2A4H.js → chunk-77VHQV7W.js}

@@ -2,10 +2,10 @@ import {
   loadUserConfig,
   resolveConfig,
   resolveSections
-} from "./chunk-3ZYZ5G6Q.js";
+} from "./chunk-PQMKRFBQ.js";
 import {
   scanDocs
-} from "./chunk-6PUBRHS7.js";
+} from "./chunk-QNC5QRIO.js";
 
 // src/node/check.ts
 import { resolve } from "path";

package/dist/node/{chunk-B3LCE7QA.js → chunk-GGUDZD4K.js}

@@ -8,15 +8,15 @@ import {
 } from "./chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "./chunk-BXEU64R6.js";
+} from "./chunk-IF6GI4WU.js";
 import {
   loadUserConfig,
   resolveConfig,
   resolveSections
-} from "./chunk-3ZYZ5G6Q.js";
+} from "./chunk-PQMKRFBQ.js";
 import {
   buildSectionData
-} from "./chunk-6PUBRHS7.js";
+} from "./chunk-QNC5QRIO.js";
 
 // src/node/build.ts
 import { build as viteBuild } from "vite";

package/dist/node/{chunk-BXEU64R6.js → chunk-IF6GI4WU.js}

@@ -4,11 +4,12 @@ import {
 import {
   loadUserConfig,
   resolveConfig,
-  resolveSections
-} from "./chunk-3ZYZ5G6Q.js";
+  resolveSections,
+  scanHubProjects
+} from "./chunk-PQMKRFBQ.js";
 import {
   buildSectionData
-} from "./chunk-6PUBRHS7.js";
+} from "./chunk-QNC5QRIO.js";
 
 // src/vite-plugin/index.ts
 import { resolve } from "path";
@@ -26,6 +27,8 @@ var VIRTUAL_MERMAID_SVGS = "virtual:clearify/mermaid-svgs";
 var RESOLVED_VIRTUAL_MERMAID_SVGS = "\0" + VIRTUAL_MERMAID_SVGS;
 var VIRTUAL_OPENAPI_SPEC = "virtual:clearify/openapi-spec";
 var RESOLVED_VIRTUAL_OPENAPI_SPEC = "\0" + VIRTUAL_OPENAPI_SPEC;
+var VIRTUAL_HUB = "virtual:clearify/hub";
+var RESOLVED_VIRTUAL_HUB = "\0" + VIRTUAL_HUB;
 function findFirstNavPath(items) {
   for (const item of items) {
     if (item.path) return item.path;
@@ -218,6 +221,7 @@ ${routeEntries.join(",\n")}
       userRoot = options.root ?? process.cwd();
       const userConfig = await loadUserConfig(userRoot);
       config = resolveConfig(userConfig, userRoot);
+      config = await scanHubProjects(config, userRoot);
       const allSections = resolveSections(config, userRoot);
       const isDev = resolvedViteConfig.command === "serve";
       visibleSections = isDev ? allSections : allSections.filter((s) => !s.draft);
@@ -230,6 +234,7 @@ ${routeEntries.join(",\n")}
       if (id === VIRTUAL_SEARCH_INDEX) return RESOLVED_VIRTUAL_SEARCH_INDEX;
       if (id === VIRTUAL_MERMAID_SVGS) return RESOLVED_VIRTUAL_MERMAID_SVGS;
       if (id === VIRTUAL_OPENAPI_SPEC) return RESOLVED_VIRTUAL_OPENAPI_SPEC;
+      if (id === VIRTUAL_HUB) return RESOLVED_VIRTUAL_HUB;
       return null;
     },
     async load(id) {
@@ -251,6 +256,10 @@ ${routeEntries.join(",\n")}
       if (id === RESOLVED_VIRTUAL_OPENAPI_SPEC) {
         return await loadOpenAPISpec();
       }
+      if (id === RESOLVED_VIRTUAL_HUB) {
+        const hubData = config.hub ?? null;
+        return `export default ${JSON.stringify(hubData)};`;
+      }
       return null;
     },
     configureServer(server) {

package/dist/node/{chunk-3ZYZ5G6Q.js → chunk-PQMKRFBQ.js}

@@ -1,6 +1,6 @@
 // src/core/config.ts
 import { z } from "zod";
-import { resolve, basename } from "path";
+import { resolve, basename, dirname } from "path";
 import { pathToFileURL } from "url";
 import { existsSync, readFileSync, rmSync } from "fs";
 import { tmpdir } from "os";
@@ -31,6 +31,31 @@ var OpenAPIConfigSchema = z.object({
   basePath: z.string().default("/api"),
   generatePages: z.boolean().default(true)
 }).optional();
+var HubProjectSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  href: z.string().optional(),
+  repo: z.string().optional(),
+  status: z.enum(["active", "beta", "planned", "deprecated"]).default("active"),
+  icon: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  group: z.string().optional()
+});
+var HubProjectPartialSchema = z.object({
+  description: z.string(),
+  href: z.string().optional(),
+  repo: z.string().optional(),
+  status: z.enum(["active", "beta", "planned", "deprecated"]).default("active"),
+  icon: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  group: z.string().optional(),
+  hubUrl: z.string().optional(),
+  hubName: z.string().optional()
+}).optional();
+var HubConfigSchema = z.object({
+  projects: z.array(HubProjectSchema).default([]),
+  scan: z.string().optional()
+}).optional();
 var ClearifyConfigSchema = z.object({
   name: z.string().default("Documentation"),
   docsDir: z.string().default("./docs"),
@@ -51,6 +76,8 @@ var ClearifyConfigSchema = z.object({
   mermaid: MermaidConfigSchema,
   openapi: OpenAPIConfigSchema,
   links: z.record(z.string(), z.string()).optional(),
+  hub: HubConfigSchema,
+  hubProject: HubProjectPartialSchema,
   customCss: z.string().optional(),
   headTags: z.array(z.string()).optional()
 });
@@ -194,10 +221,49 @@ function resolveSections(config, root) {
     }
   ];
 }
+async function scanHubProjects(config, root) {
+  if (!config.hub?.scan) return config;
+  const { globbySync } = await import("globby");
+  const pattern = config.hub.scan;
+  const configPaths = globbySync(pattern, { cwd: root, absolute: true });
+  const scannedProjects = [];
+  for (const configPath of configPaths) {
+    try {
+      const childConfig = await loadUserConfig(dirname(configPath));
+      if (!childConfig.hubProject) continue;
+      const name = childConfig.name ?? basename(dirname(configPath));
+      const hp = childConfig.hubProject;
+      scannedProjects.push({
+        name,
+        description: hp.description,
+        href: hp.href ?? childConfig.siteUrl,
+        repo: hp.repo,
+        status: hp.status,
+        icon: hp.icon,
+        tags: hp.tags,
+        group: hp.group
+      });
+    } catch {
+    }
+  }
+  const manualNames = new Set((config.hub.projects ?? []).map((p) => p.name));
+  const merged = [
+    ...scannedProjects.filter((p) => !manualNames.has(p.name)),
+    ...config.hub.projects ?? []
+  ];
+  return {
+    ...config,
+    hub: {
+      ...config.hub,
+      projects: merged
+    }
+  };
+}
 
 export {
   defaultConfig,
   loadUserConfig,
   resolveConfig,
-  resolveSections
+  resolveSections,
+  scanHubProjects
 };

package/dist/node/{chunk-MWUXPDQK.js → chunk-QIAMD2Q6.js}

@@ -210,6 +210,30 @@ export default defineConfig({
   } else {
     console.log("  clearify.config.ts already exists, skipping");
   }
+  if (!options.noClaudeRules) {
+    const claudeRulesDir = resolve(cwd, ".claude/rules");
+    const claudeRulesPath = resolve(claudeRulesDir, "clearify-docs.md");
+    if (!existsSync(claudeRulesPath)) {
+      mkdirSync(claudeRulesDir, { recursive: true });
+      const hasInternal = !options.noInternal;
+      const rulesContent = `# Clearify Documentation Rules
+
+When making changes to this project, keep the documentation in sync:
+
+1. **Changelog** \u2014 After any user-facing change, add a bullet under \`## [Unreleased]\` in \`CHANGELOG.md\` using [Keep a Changelog](https://keepachangelog.com/) format (\`Added\`, \`Changed\`, \`Fixed\`, \`Removed\`).
+
+2. **Docs pages** \u2014 When a feature or behavior changes, update the relevant page in \`docs/public/\`. If a new feature has no page, create one.
+
+3. **Config docs** \u2014 When config options are added or changed, update \`docs/public/configuration.md\` with the new option, type, default, and description.
+${hasInternal ? `
+4. **Architecture decisions** \u2014 For significant design decisions, add an entry to \`docs/internal/\` explaining the context, decision, and trade-offs.
+` : ""}`;
+      writeFileSync(claudeRulesPath, rulesContent);
+      console.log("  Created .claude/rules/clearify-docs.md");
+    } else {
+      console.log("  .claude/rules/clearify-docs.md already exists, skipping");
+    }
+  }
   console.log(`
   Done! Next steps:
 

package/dist/node/{chunk-6PUBRHS7.js → chunk-QNC5QRIO.js}

@@ -47,9 +47,20 @@ function scanDocs(docsDir, exclude = [], basePath = "/") {
 }
 function buildNavigation(docs, basePath = "/") {
   const rootDir = basePath === "/" ? "/" : basePath.replace(/\/$/, "");
-  const groups = /* @__PURE__ */ new Map();
+  const indexPages = /* @__PURE__ */ new Map();
+  const nonIndexDocs = [];
   for (const doc of docs) {
     if (doc.routePath === rootDir || doc.routePath === "/") continue;
+    const parentDir = dirname(doc.routePath);
+    const fileName = basename(doc.filePath, extname(doc.filePath));
+    if (fileName === "index") {
+      indexPages.set(doc.routePath, doc);
+    } else {
+      nonIndexDocs.push(doc);
+    }
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const doc of nonIndexDocs) {
     const dir = dirname(doc.routePath);
     if (!groups.has(dir)) groups.set(dir, []);
     groups.get(dir).push(doc);
@@ -62,25 +73,51 @@ function buildNavigation(docs, basePath = "/") {
       return a.routePath.localeCompare(b.routePath);
     });
   }
-  const nav = [];
-  const rootFiles = groups.get(rootDir) ?? [];
-  for (const doc of rootFiles) {
-    const item = { label: doc.frontmatter.title, path: doc.routePath };
-    if (doc.frontmatter.icon) item.icon = doc.frontmatter.icon;
-    nav.push(item);
-  }
-  const dirs = [...groups.keys()].filter((d) => d !== rootDir).sort();
-  for (const dir of dirs) {
-    const files = groups.get(dir);
-    const label = toTitleCase(basename(dir));
-    const children = files.map((doc) => {
-      const child = { label: doc.frontmatter.title, path: doc.routePath };
-      if (doc.frontmatter.icon) child.icon = doc.frontmatter.icon;
-      return child;
+  function buildGroupChildren(parentDir) {
+    const items = [];
+    const directFiles = groups.get(parentDir) ?? [];
+    for (const doc of directFiles) {
+      const item = { label: doc.frontmatter.title, path: doc.routePath };
+      if (doc.frontmatter.icon) item.icon = doc.frontmatter.icon;
+      items.push(item);
+    }
+    const childDirs = /* @__PURE__ */ new Set();
+    for (const dir of groups.keys()) {
+      if (dir !== parentDir && dirname(dir) === parentDir) {
+        childDirs.add(dir);
+      }
+    }
+    for (const indexPath of indexPages.keys()) {
+      const dir = indexPath;
+      if (dirname(dir) === parentDir && !childDirs.has(dir)) {
+        childDirs.add(dir);
+      }
+    }
+    const sortedChildDirs = [...childDirs].sort((a, b) => {
+      const indexA = indexPages.get(a);
+      const indexB = indexPages.get(b);
+      const orderA = indexA?.frontmatter.order ?? 999;
+      const orderB = indexB?.frontmatter.order ?? 999;
+      if (orderA !== orderB) return orderA - orderB;
+      return a.localeCompare(b);
     });
-    nav.push({ label, children });
+    for (const childDir of sortedChildDirs) {
+      const indexPage = indexPages.get(childDir);
+      const label = indexPage?.frontmatter.title ?? toTitleCase(basename(childDir));
+      const children = buildGroupChildren(childDir);
+      if (children.length > 0) {
+        const group = { label, children };
+        if (indexPage?.frontmatter.icon) group.icon = indexPage.frontmatter.icon;
+        items.push(group);
+      } else if (indexPage) {
+        const item = { label, path: indexPage.routePath };
+        if (indexPage.frontmatter.icon) item.icon = indexPage.frontmatter.icon;
+        items.push(item);
+      }
+    }
+    return items;
   }
-  return nav;
+  return buildGroupChildren(rootDir);
 }
 function buildRoutes(docs, sectionId) {
   return docs.map((doc) => ({

package/dist/node/cli/index.js

@@ -18,9 +18,9 @@ cli.command("build", "Build static documentation site").action(async () => {
   const { build } = await import("../node/index.js");
   await build();
 });
-cli.command("init", "Scaffold a docs folder").option("--no-internal", "Skip creating the internal docs section").action(async (options) => {
+cli.command("init", "Scaffold a docs folder").option("--no-internal", "Skip creating the internal docs section").option("--no-claude-rules", "Skip creating .claude/rules/clearify-docs.md").action(async (options) => {
   const { init } = await import("../node/index.js");
-  await init({ noInternal: options.noInternal });
+  await init({ noInternal: options.noInternal, noClaudeRules: options.noClaudeRules });
 });
 cli.command("check", "Check for broken internal links").action(async () => {
   const { checkLinks } = await import("../node/check.js");
@@ -37,5 +37,5 @@ cli.command("openapi:generate", "Generate OpenAPI spec from NestJS app").option(
   });
 });
 cli.help();
-cli.version("1.5.1");
+cli.version("1.8.0");
 cli.parse();

package/dist/node/core/config.d.ts

@@ -5,5 +5,6 @@ declare const defaultConfig: ClearifyConfig;
 declare function loadUserConfig(root: string): Promise<Partial<ClearifyConfig>>;
 declare function resolveConfig(userConfig?: Partial<ClearifyConfig>, root?: string): ClearifyConfig;
 declare function resolveSections(config: ClearifyConfig, root: string): ResolvedSection[];
+declare function scanHubProjects(config: ClearifyConfig, root: string): Promise<ClearifyConfig>;
 
-export { defaultConfig, loadUserConfig, resolveConfig, resolveSections };
+export { defaultConfig, loadUserConfig, resolveConfig, resolveSections, scanHubProjects };

package/dist/node/core/config.js

@@ -2,8 +2,9 @@ import {
   defaultConfig,
   loadUserConfig,
   resolveConfig,
-  resolveSections
-} from "../chunk-3ZYZ5G6Q.js";
+  resolveSections,
+  scanHubProjects
+} from "../chunk-PQMKRFBQ.js";
 import {
   defineConfig
 } from "../chunk-V7LLYIRO.js";
@@ -12,5 +13,6 @@ export {
   defineConfig,
   loadUserConfig,
   resolveConfig,
-  resolveSections
+  resolveSections,
+  scanHubProjects
 };

package/dist/node/core/navigation.js

@@ -3,7 +3,7 @@ import {
   buildRoutes,
   buildSectionData,
   scanDocs
-} from "../chunk-6PUBRHS7.js";
+} from "../chunk-QNC5QRIO.js";
 import "../chunk-5TD7NQIW.js";
 export {
   buildNavigation,

package/dist/node/node/build.js

@@ -1,13 +1,13 @@
 import {
   buildSite
-} from "../chunk-B3LCE7QA.js";
+} from "../chunk-GGUDZD4K.js";
 import "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
-import "../chunk-BXEU64R6.js";
+import "../chunk-IF6GI4WU.js";
 import "../chunk-B2Q23JW3.js";
-import "../chunk-3ZYZ5G6Q.js";
+import "../chunk-PQMKRFBQ.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-6PUBRHS7.js";
+import "../chunk-QNC5QRIO.js";
 import "../chunk-5TD7NQIW.js";
 export {
   buildSite

package/dist/node/node/check.js

@@ -1,9 +1,9 @@
 import {
   checkLinks
-} from "../chunk-O3SK2A4H.js";
-import "../chunk-3ZYZ5G6Q.js";
+} from "../chunk-77VHQV7W.js";
+import "../chunk-PQMKRFBQ.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-6PUBRHS7.js";
+import "../chunk-QNC5QRIO.js";
 import "../chunk-5TD7NQIW.js";
 export {
   checkLinks

package/dist/node/node/index.js

@@ -1,26 +1,26 @@
 import {
   buildSite
-} from "../chunk-B3LCE7QA.js";
+} from "../chunk-GGUDZD4K.js";
 import {
   remarkMermaidToComponent
 } from "../chunk-PRTER35L.js";
 import "../chunk-SCZZB7OE.js";
 import {
   clearifyPlugin
-} from "../chunk-BXEU64R6.js";
+} from "../chunk-IF6GI4WU.js";
 import "../chunk-B2Q23JW3.js";
 import {
   init
-} from "../chunk-MWUXPDQK.js";
+} from "../chunk-QIAMD2Q6.js";
 import {
   checkLinks
-} from "../chunk-O3SK2A4H.js";
+} from "../chunk-77VHQV7W.js";
 import {
   loadUserConfig,
   resolveConfig
-} from "../chunk-3ZYZ5G6Q.js";
+} from "../chunk-PQMKRFBQ.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-6PUBRHS7.js";
+import "../chunk-QNC5QRIO.js";
 import "../chunk-5TD7NQIW.js";
 
 // src/node/index.ts

package/dist/node/node/init.d.ts

@@ -1,5 +1,6 @@
 interface InitOptions {
     noInternal?: boolean;
+    noClaudeRules?: boolean;
 }
 declare function init(options?: InitOptions): Promise<void>;
 

package/dist/node/node/init.js

@@ -1,6 +1,6 @@
 import {
   init
-} from "../chunk-MWUXPDQK.js";
+} from "../chunk-QIAMD2Q6.js";
 export {
   init
 };

package/dist/node/types/index.d.ts

@@ -50,6 +50,8 @@ interface ClearifyConfig {
         github?: string;
         [key: string]: string | undefined;
     };
+    hub?: HubConfig;
+    hubProject?: Omit<HubProject, 'name'>;
     customCss?: string;
     headTags?: string[];
 }
@@ -75,6 +77,22 @@ interface RouteEntry {
     componentPath?: string;
     redirectTo?: string;
 }
+interface HubProject {
+    name: string;
+    description: string;
+    href?: string;
+    repo?: string;
+    status?: 'active' | 'beta' | 'planned' | 'deprecated';
+    icon?: string;
+    tags?: string[];
+    group?: string;
+    hubUrl?: string;
+    hubName?: string;
+}
+interface HubConfig {
+    projects: HubProject[];
+    scan?: string;
+}
 declare function defineConfig(config: Partial<ClearifyConfig>): Partial<ClearifyConfig>;
 
-export { type ClearifyConfig, type NavigationItem, type PageFrontmatter, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };
+export { type ClearifyConfig, type HubConfig, type HubProject, type NavigationItem, type PageFrontmatter, type ResolvedSection, type RouteEntry, type SectionConfig, type SectionNavigation, defineConfig };

package/dist/node/vite-plugin/index.js

@@ -1,10 +1,10 @@
 import {
   clearifyPlugin
-} from "../chunk-BXEU64R6.js";
+} from "../chunk-IF6GI4WU.js";
 import "../chunk-B2Q23JW3.js";
-import "../chunk-3ZYZ5G6Q.js";
+import "../chunk-PQMKRFBQ.js";
 import "../chunk-V7LLYIRO.js";
-import "../chunk-6PUBRHS7.js";
+import "../chunk-QNC5QRIO.js";
 import "../chunk-5TD7NQIW.js";
 export {
   clearifyPlugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marlinjai/clearify",
-  "version": "1.7.3",
+  "version": "1.9.0",
   "description": "An open-source documentation site generator. Turn markdown into beautiful docs.",
   "type": "module",
   "bin": {
@@ -72,6 +72,7 @@
     "tsup": "^8.3.6",
     "typescript": "^5.7.3"
   },
+  "packageManager": "pnpm@9.15.0",
   "license": "MIT",
   "author": "MarlinJai",
   "repository": {

package/src/theme/Layout.tsx

@@ -33,6 +33,7 @@ export function Layout({ config, sections, children }: LayoutProps) {
             sections={sections}
             open={sidebarOpen}
             onClose={() => setSidebarOpen(false)}
+            hubProject={config.hubProject}
           />
           <Content>{children}</Content>
           <TableOfContents />

package/src/theme/MDXComponents.tsx

@@ -13,6 +13,9 @@ import { Badge } from './components/Badge.js';
 import { Tooltip } from './components/Tooltip.js';
 import { Columns, Column } from './components/Columns.js';
 import { Frame } from './components/Frame.js';
+import { StatusBadge } from './components/StatusBadge.js';
+import { ProjectCard } from './components/ProjectCard.js';
+import { ProjectGrid } from './components/ProjectGrid.js';
 import { CodeBlock } from './CodeBlock.js';
 
 export const mdxComponents = {
@@ -35,6 +38,9 @@ export const mdxComponents = {
   Columns,
   Column,
   Frame,
+  StatusBadge,
+  ProjectCard,
+  ProjectGrid,
   // Override default pre element with CodeBlock
   pre: (props: React.HTMLAttributes<HTMLPreElement>) => <CodeBlock {...props} />,
 };

package/src/theme/Sidebar.tsx

@@ -1,12 +1,13 @@
 import React, { useState, useEffect, useRef } from 'react';
 import { Link, useLocation, useNavigate } from 'react-router-dom';
 import clsx from 'clsx';
-import type { NavigationItem, SectionNavigation } from '../types/index.js';
+import type { NavigationItem, SectionNavigation, HubProject } from '../types/index.js';
 
 interface SidebarProps {
   sections: SectionNavigation[];
   open: boolean;
   onClose: () => void;
+  hubProject?: Omit<HubProject, 'name'>;
 }
 
 function findActiveSection(pathname: string, sections: SectionNavigation[]): string {
@@ -103,7 +104,7 @@ function SectionSwitcher({
   );
 }
 
-export function Sidebar({ sections, open, onClose }: SidebarProps) {
+export function Sidebar({ sections, open, onClose, hubProject }: SidebarProps) {
   const location = useLocation();
   const navigate = useNavigate();
 
@@ -246,6 +247,37 @@ export function Sidebar({ sections, open, onClose }: SidebarProps) {
         }}
         className={clsx('clearify-sidebar', open && 'clearify-sidebar-open')}
       >
+        {hubProject?.hubUrl && (
+          <a
+            href={hubProject.hubUrl}
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: '0.375rem',
+              padding: '0.375rem 0.75rem',
+              margin: '0 0.5rem 0.5rem',
+              fontSize: '0.75rem',
+              fontWeight: 500,
+              color: 'var(--clearify-text-tertiary)',
+              textDecoration: 'none',
+              borderRadius: 'var(--clearify-radius-sm)',
+              transition: 'color 0.15s, background-color 0.15s',
+            }}
+            onMouseEnter={(e) => {
+              e.currentTarget.style.color = 'var(--clearify-primary)';
+              e.currentTarget.style.backgroundColor = 'var(--clearify-primary-soft)';
+            }}
+            onMouseLeave={(e) => {
+              e.currentTarget.style.color = 'var(--clearify-text-tertiary)';
+              e.currentTarget.style.backgroundColor = 'transparent';
+            }}
+          >
+            <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <polyline points="15 18 9 12 15 6" />
+            </svg>
+            {hubProject.hubName ?? 'Hub'}
+          </a>
+        )}
         {showSwitcher && (
           <SectionSwitcher
             sections={sections}

package/src/theme/components/ProjectCard.tsx

@@ -0,0 +1,134 @@
+import React from 'react';
+import { Link } from 'react-router-dom';
+import { StatusBadge } from './StatusBadge.js';
+
+interface ProjectCardProps {
+  name: string;
+  description: string;
+  href?: string;
+  repo?: string;
+  status?: 'active' | 'beta' | 'planned' | 'deprecated';
+  icon?: string;
+  tags?: string[];
+  children?: React.ReactNode;
+}
+
+export function ProjectCard({ name, description, href, repo, status, icon, tags, children }: ProjectCardProps) {
+  const content = (
+    <div
+      style={{
+        border: '1px solid var(--clearify-border)',
+        borderRadius: 'var(--clearify-radius-lg)',
+        padding: '1.375rem',
+        transition: 'all 0.2s cubic-bezier(0.4, 0, 0.2, 1)',
+        cursor: href ? 'pointer' : 'default',
+        height: '100%',
+        background: 'var(--clearify-bg)',
+        position: 'relative',
+        overflow: 'hidden',
+        display: 'flex',
+        flexDirection: 'column' as const,
+      }}
+      className="clearify-project-card"
+    >
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', marginBottom: '0.625rem' }}>
+        {icon && (
+          <div
+            style={{
+              fontSize: '1.25rem',
+              width: 36,
+              height: 36,
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              borderRadius: 'var(--clearify-radius-sm)',
+              background: 'var(--clearify-gradient-subtle)',
+              border: '1px solid var(--clearify-border)',
+              flexShrink: 0,
+            }}
+          >
+            {icon}
+          </div>
+        )}
+        <div style={{ display: 'flex', alignItems: 'center', gap: '0.375rem' }}>
+          {status && <StatusBadge status={status} />}
+          {repo && (
+            <a
+              href={repo}
+              target="_blank"
+              rel="noopener noreferrer"
+              onClick={(e) => e.stopPropagation()}
+              style={{
+                color: 'var(--clearify-text-secondary)',
+                display: 'inline-flex',
+                alignItems: 'center',
+                transition: 'color 0.15s',
+              }}
+              className="clearify-project-card-repo"
+              title="View repository"
+            >
+              <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+                <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" />
+              </svg>
+            </a>
+          )}
+        </div>
+      </div>
+
+      <div style={{ fontWeight: 600, marginBottom: '0.25rem', fontSize: '0.9375rem', letterSpacing: '-0.01em' }}>
+        {name}
+      </div>
+      <div style={{ fontSize: '0.8125rem', color: 'var(--clearify-text-secondary)', lineHeight: 1.55, flex: 1 }}>
+        {description}
+      </div>
+
+      {children && <div style={{ marginTop: '0.625rem', fontSize: '0.8125rem' }}>{children}</div>}
+
+      {tags && tags.length > 0 && (
+        <div style={{ display: 'flex', flexWrap: 'wrap' as const, gap: '0.375rem', marginTop: '0.75rem' }}>
+          {tags.map((tag) => (
+            <span
+              key={tag}
+              style={{
+                display: 'inline-block',
+                padding: '0.0625rem 0.4375rem',
+                borderRadius: '9999px',
+                fontSize: '0.6875rem',
+                fontWeight: 500,
+                background: 'rgba(107, 114, 128, 0.08)',
+                color: 'var(--clearify-text-secondary)',
+                fontFamily: 'var(--font-sans)',
+              }}
+              className="clearify-project-card-tag"
+            >
+              {tag}
+            </span>
+          ))}
+        </div>
+      )}
+
+      <style>{`
+        .clearify-project-card:hover {
+          border-color: var(--clearify-border-strong) !important;
+          box-shadow: var(--clearify-shadow) !important;
+          transform: translateY(-1px);
+        }
+        .clearify-project-card-repo:hover {
+          color: var(--clearify-text) !important;
+        }
+        .dark .clearify-project-card-tag {
+          background: rgba(107, 114, 128, 0.15) !important;
+        }
+      `}</style>
+    </div>
+  );
+
+  if (href) {
+    if (href.startsWith('/')) {
+      return <Link to={href} style={{ textDecoration: 'none', color: 'inherit' }}>{content}</Link>;
+    }
+    return <a href={href} target="_blank" rel="noopener noreferrer" style={{ textDecoration: 'none', color: 'inherit' }}>{content}</a>;
+  }
+
+  return content;
+}

package/src/theme/components/ProjectGrid.tsx

@@ -0,0 +1,142 @@
+import React from 'react';
+import hub from 'virtual:clearify/hub';
+import { ProjectCard } from './ProjectCard.js';
+import type { HubProject } from '../../types/index.js';
+
+interface ProjectGridProps {
+  cols?: number;
+  children?: React.ReactNode;
+}
+
+function ProjectGridInner({ cols, projects }: { cols: number; projects: HubProject[] }) {
+  return (
+    <div
+      style={{
+        display: 'grid',
+        gridTemplateColumns: `repeat(${cols}, 1fr)`,
+        gap: '0.875rem',
+      }}
+      className="clearify-project-grid"
+    >
+      {projects.map((project) => (
+        <ProjectCard
+          key={project.name}
+          name={project.name}
+          description={project.description}
+          href={project.href}
+          repo={project.repo}
+          status={project.status}
+          icon={project.icon}
+          tags={project.tags}
+        />
+      ))}
+    </div>
+  );
+}
+
+export function ProjectGrid({ cols = 3, children }: ProjectGridProps) {
+  const hasChildren = React.Children.count(children) > 0;
+
+  if (hasChildren) {
+    return (
+      <div
+        style={{
+          display: 'grid',
+          gridTemplateColumns: `repeat(${cols}, 1fr)`,
+          gap: '0.875rem',
+          marginBottom: '1.5rem',
+        }}
+        className="clearify-project-grid"
+      >
+        {children}
+        <style>{gridResponsiveStyles}</style>
+      </div>
+    );
+  }
+
+  const projects: HubProject[] = hub?.projects ?? [];
+  const hasGroups = projects.some((p) => p.group);
+
+  if (!hasGroups) {
+    return (
+      <div style={{ marginBottom: '1.5rem' }}>
+        <ProjectGridInner cols={cols} projects={projects} />
+        <style>{gridResponsiveStyles}</style>
+      </div>
+    );
+  }
+
+  // Group projects by their group field, preserving insertion order
+  const groupOrder: string[] = [];
+  const grouped: Record<string, HubProject[]> = {};
+  const ungrouped: HubProject[] = [];
+
+  for (const project of projects) {
+    if (project.group) {
+      if (!grouped[project.group]) {
+        grouped[project.group] = [];
+        groupOrder.push(project.group);
+      }
+      grouped[project.group].push(project);
+    } else {
+      ungrouped.push(project);
+    }
+  }
+
+  return (
+    <div style={{ marginBottom: '1.5rem' }}>
+      {groupOrder.map((groupName) => (
+        <div key={groupName} style={{ marginBottom: '1.5rem' }}>
+          <h2
+            style={{
+              fontSize: '1.25rem',
+              fontWeight: 600,
+              marginBottom: '0.75rem',
+              marginTop: 0,
+              color: 'var(--clearify-text)',
+              letterSpacing: '-0.01em',
+            }}
+          >
+            {groupName}
+          </h2>
+          <ProjectGridInner cols={cols} projects={grouped[groupName]} />
+        </div>
+      ))}
+
+      {ungrouped.length > 0 && (
+        <div style={{ marginBottom: '1.5rem' }}>
+          {groupOrder.length > 0 && (
+            <h2
+              style={{
+                fontSize: '1.25rem',
+                fontWeight: 600,
+                marginBottom: '0.75rem',
+                marginTop: 0,
+                color: 'var(--clearify-text)',
+                letterSpacing: '-0.01em',
+              }}
+            >
+              Other Projects
+            </h2>
+          )}
+          <ProjectGridInner cols={cols} projects={ungrouped} />
+        </div>
+      )}
+
+      <style>{gridResponsiveStyles}</style>
+    </div>
+  );
+}
+
+const gridResponsiveStyles = `
+  @media (max-width: 900px) {
+    .clearify-project-grid {
+      grid-template-columns: repeat(2, 1fr) !important;
+    }
+  }
+  @media (max-width: 640px) {
+    .clearify-project-grid {
+      grid-template-columns: 1fr !important;
+    }
+  }
+`;

package/src/theme/components/StatusBadge.tsx

@@ -0,0 +1,70 @@
+import React from 'react';
+
+const statusStyles = {
+  active: {
+    bg: 'rgba(34, 197, 94, 0.08)',
+    bgDark: 'rgba(34, 197, 94, 0.15)',
+    color: '#16a34a',
+    colorDark: '#4ade80',
+    label: 'Active',
+  },
+  beta: {
+    bg: 'rgba(99, 102, 241, 0.08)',
+    bgDark: 'rgba(99, 102, 241, 0.15)',
+    color: '#6366f1',
+    colorDark: '#818cf8',
+    label: 'Beta',
+  },
+  planned: {
+    bg: 'rgba(245, 158, 11, 0.08)',
+    bgDark: 'rgba(245, 158, 11, 0.15)',
+    color: '#d97706',
+    colorDark: '#fbbf24',
+    label: 'Planned',
+  },
+  deprecated: {
+    bg: 'rgba(239, 68, 68, 0.08)',
+    bgDark: 'rgba(239, 68, 68, 0.15)',
+    color: '#dc2626',
+    colorDark: '#f87171',
+    label: 'Deprecated',
+  },
+};
+
+interface StatusBadgeProps {
+  status: 'active' | 'beta' | 'planned' | 'deprecated';
+}
+
+export function StatusBadge({ status }: StatusBadgeProps) {
+  const s = statusStyles[status];
+  const badgeClass = `clearify-status-badge-${status}`;
+
+  return (
+    <span
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        padding: '0.125rem 0.5rem',
+        borderRadius: '9999px',
+        fontSize: '0.6875rem',
+        fontWeight: 500,
+        lineHeight: 1.5,
+        backgroundColor: s.bg,
+        color: s.color,
+        fontFamily: 'var(--font-sans)',
+        whiteSpace: 'nowrap',
+        letterSpacing: '0.01em',
+      }}
+      className={badgeClass}
+    >
+      {s.label}
+
+      <style>{`
+        .dark .${badgeClass} {
+          background-color: ${s.bgDark} !important;
+          color: ${s.colorDark} !important;
+        }
+      `}</style>
+    </span>
+  );
+}

package/src/theme/components/index.ts

@@ -12,3 +12,6 @@ export { Badge } from './Badge.js';
 export { Tooltip } from './Tooltip.js';
 export { Columns, Column } from './Columns.js';
 export { Frame } from './Frame.js';
+export { StatusBadge } from './StatusBadge.js';
+export { ProjectCard } from './ProjectCard.js';
+export { ProjectGrid } from './ProjectGrid.js';