@rune-kit/rune 2.10.0 → 2.12.0

package/extensions/content/skills/blog-patterns.md

@@ -1,88 +1,88 @@
----
-name: "blog-patterns"
-pack: "@rune/content"
-description: "Post management, categories/tags, pagination, RSS feeds, reading time, related posts, comment systems."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# blog-patterns
-
-Blog system patterns — post management, categories/tags, pagination, RSS feeds, reading time, related posts, comment systems.
-
-#### Workflow
-
-**Step 1 — Detect blog architecture**
-Use Glob to find blog-related files: `blog/`, `posts/`, `articles/`, `*.mdx`, `*.md` in content directories. Use Grep to find blog utilities: `getStaticPaths`, `generateStaticParams`, `allPosts`, `contentlayer`, `reading-time`. Read the post listing page and individual post page to understand: data source, routing strategy, and rendering pipeline.
-
-**Step 2 — Audit blog completeness**
-Check for: missing RSS feed (`feed.xml` or `/api/rss`), no reading time estimation, pagination absent on listing pages (all posts loaded at once), no category/tag filtering, missing related posts, no draft/published state, and OG images not generated per-post.
-
-**Step 3 — Emit blog patterns**
-Emit: typed post schema with frontmatter validation, paginated listing with category filter, RSS feed generator, reading time calculator, and related posts by tag similarity.
-
-#### Example
-
-```typescript
-// Next.js App Router — blog listing with pagination and categories
-import { allPosts, type Post } from 'contentlayer/generated';
-
-function getPublishedPosts(category?: string): Post[] {
-  return allPosts
-    .filter(p => p.status === 'published')
-    .filter(p => !category || p.category === category)
-    .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
-}
-
-// Reading time utility
-function readingTime(content: string): string {
-  const words = content.trim().split(/\s+/).length;
-  const minutes = Math.ceil(words / 238);
-  return `${minutes} min read`;
-}
-
-// RSS feed — app/feed.xml/route.ts
-export async function GET() {
-  const posts = getPublishedPosts();
-  const xml = `<?xml version="1.0" encoding="UTF-8"?>
-<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
-  <channel>
-    <title>My Blog</title>
-    <link>${process.env.SITE_URL}</link>
-    <atom:link href="${process.env.SITE_URL}/feed.xml" rel="self" type="application/rss+xml"/>
-    ${posts.slice(0, 20).map(p => `<item>
-      <title>${escapeXml(p.title)}</title>
-      <link>${process.env.SITE_URL}${p.url}</link>
-      <pubDate>${new Date(p.date).toUTCString()}</pubDate>
-      <description>${escapeXml(p.excerpt)}</description>
-    </item>`).join('\n')}
-  </channel>
-</rss>`;
-  return new Response(xml, { headers: { 'Content-Type': 'application/xml' } });
-}
-
-// Related posts by tag overlap — score by number of shared tags
-function getRelatedPosts(current: Post, all: Post[], limit = 3): Post[] {
-  const currentTags = new Set(current.tags ?? []);
-  return all
-    .filter(p => p.slug !== current.slug && p.status === 'published')
-    .map(p => ({ post: p, score: (p.tags ?? []).filter(t => currentTags.has(t)).length }))
-    .filter(({ score }) => score > 0)
-    .sort((a, b) => b.score - a.score)
-    .slice(0, limit)
-    .map(({ post }) => post);
-}
-
-// Paginated listing
-const PAGE_SIZE = 10;
-function paginatePosts(posts: Post[], page: number) {
-  const start = (page - 1) * PAGE_SIZE;
-  return {
-    posts: posts.slice(start, start + PAGE_SIZE),
-    total: posts.length,
-    totalPages: Math.ceil(posts.length / PAGE_SIZE),
-    hasNext: start + PAGE_SIZE < posts.length,
-    hasPrev: page > 1,
-  };
-}
-```
+---
+name: "blog-patterns"
+pack: "@rune/content"
+description: "Post management, categories/tags, pagination, RSS feeds, reading time, related posts, comment systems."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# blog-patterns
+
+Blog system patterns — post management, categories/tags, pagination, RSS feeds, reading time, related posts, comment systems.
+
+#### Workflow
+
+**Step 1 — Detect blog architecture**
+Use Glob to find blog-related files: `blog/`, `posts/`, `articles/`, `*.mdx`, `*.md` in content directories. Use Grep to find blog utilities: `getStaticPaths`, `generateStaticParams`, `allPosts`, `contentlayer`, `reading-time`. Read the post listing page and individual post page to understand: data source, routing strategy, and rendering pipeline.
+
+**Step 2 — Audit blog completeness**
+Check for: missing RSS feed (`feed.xml` or `/api/rss`), no reading time estimation, pagination absent on listing pages (all posts loaded at once), no category/tag filtering, missing related posts, no draft/published state, and OG images not generated per-post.
+
+**Step 3 — Emit blog patterns**
+Emit: typed post schema with frontmatter validation, paginated listing with category filter, RSS feed generator, reading time calculator, and related posts by tag similarity.
+
+#### Example
+
+```typescript
+// Next.js App Router — blog listing with pagination and categories
+import { allPosts, type Post } from 'contentlayer/generated';
+
+function getPublishedPosts(category?: string): Post[] {
+  return allPosts
+    .filter(p => p.status === 'published')
+    .filter(p => !category || p.category === category)
+    .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
+}
+
+// Reading time utility
+function readingTime(content: string): string {
+  const words = content.trim().split(/\s+/).length;
+  const minutes = Math.ceil(words / 238);
+  return `${minutes} min read`;
+}
+
+// RSS feed — app/feed.xml/route.ts
+export async function GET() {
+  const posts = getPublishedPosts();
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>My Blog</title>
+    <link>${process.env.SITE_URL}</link>
+    <atom:link href="${process.env.SITE_URL}/feed.xml" rel="self" type="application/rss+xml"/>
+    ${posts.slice(0, 20).map(p => `<item>
+      <title>${escapeXml(p.title)}</title>
+      <link>${process.env.SITE_URL}${p.url}</link>
+      <pubDate>${new Date(p.date).toUTCString()}</pubDate>
+      <description>${escapeXml(p.excerpt)}</description>
+    </item>`).join('\n')}
+  </channel>
+</rss>`;
+  return new Response(xml, { headers: { 'Content-Type': 'application/xml' } });
+}
+
+// Related posts by tag overlap — score by number of shared tags
+function getRelatedPosts(current: Post, all: Post[], limit = 3): Post[] {
+  const currentTags = new Set(current.tags ?? []);
+  return all
+    .filter(p => p.slug !== current.slug && p.status === 'published')
+    .map(p => ({ post: p, score: (p.tags ?? []).filter(t => currentTags.has(t)).length }))
+    .filter(({ score }) => score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(({ post }) => post);
+}
+
+// Paginated listing
+const PAGE_SIZE = 10;
+function paginatePosts(posts: Post[], page: number) {
+  const start = (page - 1) * PAGE_SIZE;
+  return {
+    posts: posts.slice(start, start + PAGE_SIZE),
+    total: posts.length,
+    totalPages: Math.ceil(posts.length / PAGE_SIZE),
+    hasNext: start + PAGE_SIZE < posts.length,
+    hasPrev: page > 1,
+  };
+}
+```

package/extensions/content/skills/cms-integration.md

@@ -1,131 +1,131 @@
----
-name: "cms-integration"
-pack: "@rune/content"
-description: "Sanity, Contentful, Strapi, PocketBase. Content modeling, preview mode, webhook-triggered rebuilds, draft/published workflows."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# cms-integration
-
-CMS integration — Sanity, Contentful, Strapi, PocketBase. Content modeling, preview mode, webhook-triggered rebuilds, draft/published workflows.
-
-#### Workflow
-
-**Step 1 — Detect CMS setup**
-Use Grep to find CMS SDK usage: `createClient` (Sanity), `contentful`, `strapi`, `PocketBase`, `GROQ`, `graphql` in content-fetching files. Read the CMS client initialization and content queries to understand: CMS provider, content types, preview mode setup, and caching strategy.
-
-**Step 2 — Audit CMS integration**
-Check for: no preview/draft mode (editors can't preview before publish), missing webhook for on-demand ISR (content updates require full rebuild), no content validation (malformed CMS data crashes the page), stale cache without revalidation strategy, images served from CMS without optimization (no next/image or equivalent), and missing error boundary for CMS fetch failures.
-
-**Step 3 — Emit CMS patterns**
-For Sanity: emit typed GROQ queries with Zod validation, preview mode toggle, and webhook handler. For Contentful: emit typed GraphQL queries, draft/published content switching. For any CMS: emit ISR revalidation endpoint and image optimization pipeline.
-
-#### Example — Sanity
-
-```typescript
-// Sanity — typed client with preview mode and ISR webhook
-import { createClient, type QueryParams } from '@sanity/client';
-import { z } from 'zod';
-
-const client = createClient({
-  projectId: process.env.SANITY_PROJECT_ID!,
-  dataset: 'production',
-  apiVersion: '2024-01-01',
-  useCdn: true,
-});
-
-const previewClient = client.withConfig({ useCdn: false, token: process.env.SANITY_PREVIEW_TOKEN });
-
-const PostSchema = z.object({
-  _id: z.string(),
-  title: z.string(),
-  slug: z.string(),
-  body: z.array(z.any()),
-  publishedAt: z.string().datetime(),
-  author: z.object({ name: z.string(), image: z.string().url().optional() }),
-});
-
-export async function getPost(slug: string, preview = false) {
-  const query = `*[_type == "post" && slug.current == $slug][0]{
-    _id, title, "slug": slug.current, body, publishedAt,
-    "author": author->{ name, "image": image.asset->url }
-  }`;
-  const result = await (preview ? previewClient : client).fetch(query, { slug });
-  return PostSchema.parse(result);
-}
-
-// Webhook handler for on-demand ISR — app/api/revalidate/route.ts
-export async function POST(req: Request) {
-  const body = await req.json();
-  const secret = req.headers.get('x-sanity-webhook-secret');
-  if (secret !== process.env.SANITY_WEBHOOK_SECRET) {
-    return new Response('Unauthorized', { status: 401 });
-  }
-  const { revalidatePath } = await import('next/cache');
-  revalidatePath(`/blog/${body.slug.current}`);
-  return Response.json({ revalidated: true });
-}
-```
-
-#### Example — Contentful
-
-```typescript
-// Contentful — typed GraphQL with draft/published switching
-import { createClient } from 'contentful';
-
-const client = createClient({
-  space: process.env.CONTENTFUL_SPACE_ID!,
-  accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
-});
-
-const previewClient = createClient({
-  space: process.env.CONTENTFUL_SPACE_ID!,
-  accessToken: process.env.CONTENTFUL_PREVIEW_TOKEN!,
-  host: 'preview.contentful.com',
-});
-
-export async function getArticle(slug: string, preview = false) {
-  const c = preview ? previewClient : client;
-  const entries = await c.getEntries({
-    content_type: 'article',
-    'fields.slug': slug,
-    include: 2,
-    limit: 1,
-  });
-  if (!entries.items.length) return null;
-  const entry = entries.items[0];
-  return {
-    title: entry.fields.title as string,
-    slug: entry.fields.slug as string,
-    body: entry.fields.body,
-    publishedAt: entry.sys.createdAt,
-  };
-}
-```
-
-#### Example — Strapi
-
-```typescript
-// Strapi v5 — REST with populate and draft/live modes
-const STRAPI = process.env.STRAPI_URL ?? 'http://localhost:1337';
-const TOKEN = process.env.STRAPI_API_TOKEN!;
-
-async function strapiGet<T>(path: string, params: Record<string, string> = {}): Promise<T> {
-  const url = new URL(`${STRAPI}/api${path}`);
-  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
-  const res = await fetch(url.toString(), {
-    headers: { Authorization: `Bearer ${TOKEN}` },
-    next: { revalidate: 60 },
-  });
-  if (!res.ok) throw new Error(`Strapi error: ${res.status}`);
-  return res.json();
-}
-
-export const getArticles = () =>
-  strapiGet<{ data: StrapiArticle[] }>('/articles', {
-    'filters[publishedAt][$notNull]': 'true',
-    'populate': 'cover,author,category',
-    'sort': 'publishedAt:desc',
-  });
-```
+---
+name: "cms-integration"
+pack: "@rune/content"
+description: "Sanity, Contentful, Strapi, PocketBase. Content modeling, preview mode, webhook-triggered rebuilds, draft/published workflows."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# cms-integration
+
+CMS integration — Sanity, Contentful, Strapi, PocketBase. Content modeling, preview mode, webhook-triggered rebuilds, draft/published workflows.
+
+#### Workflow
+
+**Step 1 — Detect CMS setup**
+Use Grep to find CMS SDK usage: `createClient` (Sanity), `contentful`, `strapi`, `PocketBase`, `GROQ`, `graphql` in content-fetching files. Read the CMS client initialization and content queries to understand: CMS provider, content types, preview mode setup, and caching strategy.
+
+**Step 2 — Audit CMS integration**
+Check for: no preview/draft mode (editors can't preview before publish), missing webhook for on-demand ISR (content updates require full rebuild), no content validation (malformed CMS data crashes the page), stale cache without revalidation strategy, images served from CMS without optimization (no next/image or equivalent), and missing error boundary for CMS fetch failures.
+
+**Step 3 — Emit CMS patterns**
+For Sanity: emit typed GROQ queries with Zod validation, preview mode toggle, and webhook handler. For Contentful: emit typed GraphQL queries, draft/published content switching. For any CMS: emit ISR revalidation endpoint and image optimization pipeline.
+
+#### Example — Sanity
+
+```typescript
+// Sanity — typed client with preview mode and ISR webhook
+import { createClient, type QueryParams } from '@sanity/client';
+import { z } from 'zod';
+
+const client = createClient({
+  projectId: process.env.SANITY_PROJECT_ID!,
+  dataset: 'production',
+  apiVersion: '2024-01-01',
+  useCdn: true,
+});
+
+const previewClient = client.withConfig({ useCdn: false, token: process.env.SANITY_PREVIEW_TOKEN });
+
+const PostSchema = z.object({
+  _id: z.string(),
+  title: z.string(),
+  slug: z.string(),
+  body: z.array(z.any()),
+  publishedAt: z.string().datetime(),
+  author: z.object({ name: z.string(), image: z.string().url().optional() }),
+});
+
+export async function getPost(slug: string, preview = false) {
+  const query = `*[_type == "post" && slug.current == $slug][0]{
+    _id, title, "slug": slug.current, body, publishedAt,
+    "author": author->{ name, "image": image.asset->url }
+  }`;
+  const result = await (preview ? previewClient : client).fetch(query, { slug });
+  return PostSchema.parse(result);
+}
+
+// Webhook handler for on-demand ISR — app/api/revalidate/route.ts
+export async function POST(req: Request) {
+  const body = await req.json();
+  const secret = req.headers.get('x-sanity-webhook-secret');
+  if (secret !== process.env.SANITY_WEBHOOK_SECRET) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+  const { revalidatePath } = await import('next/cache');
+  revalidatePath(`/blog/${body.slug.current}`);
+  return Response.json({ revalidated: true });
+}
+```
+
+#### Example — Contentful
+
+```typescript
+// Contentful — typed GraphQL with draft/published switching
+import { createClient } from 'contentful';
+
+const client = createClient({
+  space: process.env.CONTENTFUL_SPACE_ID!,
+  accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
+});
+
+const previewClient = createClient({
+  space: process.env.CONTENTFUL_SPACE_ID!,
+  accessToken: process.env.CONTENTFUL_PREVIEW_TOKEN!,
+  host: 'preview.contentful.com',
+});
+
+export async function getArticle(slug: string, preview = false) {
+  const c = preview ? previewClient : client;
+  const entries = await c.getEntries({
+    content_type: 'article',
+    'fields.slug': slug,
+    include: 2,
+    limit: 1,
+  });
+  if (!entries.items.length) return null;
+  const entry = entries.items[0];
+  return {
+    title: entry.fields.title as string,
+    slug: entry.fields.slug as string,
+    body: entry.fields.body,
+    publishedAt: entry.sys.createdAt,
+  };
+}
+```
+
+#### Example — Strapi
+
+```typescript
+// Strapi v5 — REST with populate and draft/live modes
+const STRAPI = process.env.STRAPI_URL ?? 'http://localhost:1337';
+const TOKEN = process.env.STRAPI_API_TOKEN!;
+
+async function strapiGet<T>(path: string, params: Record<string, string> = {}): Promise<T> {
+  const url = new URL(`${STRAPI}/api${path}`);
+  Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
+  const res = await fetch(url.toString(), {
+    headers: { Authorization: `Bearer ${TOKEN}` },
+    next: { revalidate: 60 },
+  });
+  if (!res.ok) throw new Error(`Strapi error: ${res.status}`);
+  return res.json();
+}
+
+export const getArticles = () =>
+  strapiGet<{ data: StrapiArticle[] }>('/articles', {
+    'filters[publishedAt][$notNull]': 'true',
+    'populate': 'cover,author,category',
+    'sort': 'publishedAt:desc',
+  });
+```

package/extensions/content/skills/content-scoring.md

@@ -1,107 +1,107 @@
----
-name: "content-scoring"
-pack: "@rune/content"
-description: "Engagement and virality scoring for content pieces. Analyze hooks, readability, shareability, and platform fit."
-model: sonnet
-tools: [Read, Edit, Write, Grep, Glob, Bash]
----
-
-# content-scoring
-
-Engagement and virality scoring for content pieces. Analyze hooks, readability, shareability, and platform fit. Works for both video clips and written articles.
-
-#### Workflow
-
-**Step 1 — Detect content type**
-Determine if scoring target is:
-- **Video clip** (from video-repurpose pipeline or standalone)
-- **Blog post / article** (markdown, MDX, or CMS content)
-- **Social post** (short-form text, tweet, thread)
-
-**Step 2 — Score across 4 dimensions**
-```typescript
-interface ContentScore {
-  hook: {
-    score: number;        // 0-25
-    type: 'question' | 'statistic' | 'story' | 'contrast' | 'bold-claim' | 'how-to';
-    assessment: string;   // Why this hook works or doesn't
-  };
-  engagement: {
-    score: number;        // 0-25
-    readability: number;  // Flesch-Kincaid grade level
-    pacing: string;       // 'too-slow' | 'good' | 'too-fast'
-    callToAction: boolean;
-  };
-  value: {
-    score: number;        // 0-25
-    teaches: boolean;
-    entertains: boolean;
-    uniqueInsight: boolean;
-  };
-  shareability: {
-    score: number;        // 0-25
-    emotionalTrigger: string | null;  // 'surprise' | 'anger' | 'joy' | 'fear'
-    quotable: string[];   // Extract quotable one-liners
-    platformFit: Record<Platform, number>;  // 0-10 per platform
-  };
-  total: number;          // 0-100
-  tier: 'viral' | 'strong' | 'average' | 'weak';  // >80 viral, >60 strong, >40 average
-}
-```
-
-**Step 3 — Platform-specific optimization hints**
-Each platform has different engagement patterns:
-| Platform | Hook Window | Optimal Length | Key Factor |
-|----------|-------------|---------------|------------|
-| TikTok | 0-1s | 15-30s | Pattern interrupt, trend audio |
-| YouTube | 0-3s | 8-12 min (long), 30-60s (Shorts) | Curiosity gap, retention graph |
-| Twitter/X | First line | 280 chars or 4-tweet thread | Hot take, data point |
-| LinkedIn | First 2 lines | 150-300 words | Professional insight, personal story |
-| Blog | Title + first paragraph | 1500-2500 words | SEO keyword + value promise |
-
-**Step 4 — Emit improvement suggestions**
-For each dimension scoring < 20/25, emit specific actionable improvement:
-- Hook weak → suggest rewrite with stronger opening pattern
-- Engagement low → identify pacing issues, suggest cuts or restructures
-- Value low → identify where content is generic, suggest unique angle
-- Shareability low → suggest quotable reformulations, emotional triggers
-
-#### Example
-
-```typescript
-// Scoring a blog post
-const score = await scoreContent({
-  type: 'article',
-  title: 'How We Cut Our AWS Bill by 60%',
-  content: articleMarkdown,
-  targetPlatforms: ['blog', 'twitter', 'linkedin'],
-});
-
-// Result:
-// {
-//   hook: { score: 22, type: 'statistic', assessment: 'Strong — specific number creates curiosity' },
-//   engagement: { score: 18, readability: 8.2, pacing: 'good', callToAction: true },
-//   value: { score: 20, teaches: true, entertains: false, uniqueInsight: true },
-//   shareability: {
-//     score: 19, emotionalTrigger: 'surprise',
-//     quotable: ['We were paying $12K/mo for a service we used 3% of'],
-//     platformFit: { blog: 9, twitter: 8, linkedin: 9 }
-//   },
-//   total: 79, tier: 'strong'
-// }
-
-// Improvement suggestions:
-// - Shareability: Add a contrarian angle ("Everyone says X, but we found Y")
-// - Engagement: Add a visual comparison (before/after cost graph)
-```
-
-```typescript
-// Scoring a video clip
-const clipScore = await scoreContent({
-  type: 'video-clip',
-  transcript: clipTranscript,
-  duration: 28_000,  // 28 seconds
-  hookType: 'question',
-  targetPlatforms: ['tiktok', 'youtube-shorts', 'instagram-reels'],
-});
-```
+---
+name: "content-scoring"
+pack: "@rune/content"
+description: "Engagement and virality scoring for content pieces. Analyze hooks, readability, shareability, and platform fit."
+model: sonnet
+tools: [Read, Edit, Write, Grep, Glob, Bash]
+---
+
+# content-scoring
+
+Engagement and virality scoring for content pieces. Analyze hooks, readability, shareability, and platform fit. Works for both video clips and written articles.
+
+#### Workflow
+
+**Step 1 — Detect content type**
+Determine if scoring target is:
+- **Video clip** (from video-repurpose pipeline or standalone)
+- **Blog post / article** (markdown, MDX, or CMS content)
+- **Social post** (short-form text, tweet, thread)
+
+**Step 2 — Score across 4 dimensions**
+```typescript
+interface ContentScore {
+  hook: {
+    score: number;        // 0-25
+    type: 'question' | 'statistic' | 'story' | 'contrast' | 'bold-claim' | 'how-to';
+    assessment: string;   // Why this hook works or doesn't
+  };
+  engagement: {
+    score: number;        // 0-25
+    readability: number;  // Flesch-Kincaid grade level
+    pacing: string;       // 'too-slow' | 'good' | 'too-fast'
+    callToAction: boolean;
+  };
+  value: {
+    score: number;        // 0-25
+    teaches: boolean;
+    entertains: boolean;
+    uniqueInsight: boolean;
+  };
+  shareability: {
+    score: number;        // 0-25
+    emotionalTrigger: string | null;  // 'surprise' | 'anger' | 'joy' | 'fear'
+    quotable: string[];   // Extract quotable one-liners
+    platformFit: Record<Platform, number>;  // 0-10 per platform
+  };
+  total: number;          // 0-100
+  tier: 'viral' | 'strong' | 'average' | 'weak';  // >80 viral, >60 strong, >40 average
+}
+```
+
+**Step 3 — Platform-specific optimization hints**
+Each platform has different engagement patterns:
+| Platform | Hook Window | Optimal Length | Key Factor |
+|----------|-------------|---------------|------------|
+| TikTok | 0-1s | 15-30s | Pattern interrupt, trend audio |
+| YouTube | 0-3s | 8-12 min (long), 30-60s (Shorts) | Curiosity gap, retention graph |
+| Twitter/X | First line | 280 chars or 4-tweet thread | Hot take, data point |
+| LinkedIn | First 2 lines | 150-300 words | Professional insight, personal story |
+| Blog | Title + first paragraph | 1500-2500 words | SEO keyword + value promise |
+
+**Step 4 — Emit improvement suggestions**
+For each dimension scoring < 20/25, emit specific actionable improvement:
+- Hook weak → suggest rewrite with stronger opening pattern
+- Engagement low → identify pacing issues, suggest cuts or restructures
+- Value low → identify where content is generic, suggest unique angle
+- Shareability low → suggest quotable reformulations, emotional triggers
+
+#### Example
+
+```typescript
+// Scoring a blog post
+const score = await scoreContent({
+  type: 'article',
+  title: 'How We Cut Our AWS Bill by 60%',
+  content: articleMarkdown,
+  targetPlatforms: ['blog', 'twitter', 'linkedin'],
+});
+
+// Result:
+// {
+//   hook: { score: 22, type: 'statistic', assessment: 'Strong — specific number creates curiosity' },
+//   engagement: { score: 18, readability: 8.2, pacing: 'good', callToAction: true },
+//   value: { score: 20, teaches: true, entertains: false, uniqueInsight: true },
+//   shareability: {
+//     score: 19, emotionalTrigger: 'surprise',
+//     quotable: ['We were paying $12K/mo for a service we used 3% of'],
+//     platformFit: { blog: 9, twitter: 8, linkedin: 9 }
+//   },
+//   total: 79, tier: 'strong'
+// }
+
+// Improvement suggestions:
+// - Shareability: Add a contrarian angle ("Everyone says X, but we found Y")
+// - Engagement: Add a visual comparison (before/after cost graph)
+```
+
+```typescript
+// Scoring a video clip
+const clipScore = await scoreContent({
+  type: 'video-clip',
+  transcript: clipTranscript,
+  duration: 28_000,  // 28 seconds
+  hookType: 'question',
+  targetPlatforms: ['tiktok', 'youtube-shorts', 'instagram-reels'],
+});
+```