@dzhechkov/keysarium 1.3.0 → 1.5.0

package/templates/.claude/skills/knowledge-extractor/references/quality-gates.md

@@ -0,0 +1,98 @@
+# Quality Gates Reference
+
+Gates applied to every candidate finding during the harvest process.
+All 8 gates must be evaluated before a finding can be accepted into the toolkit.
+A gate failure is a hard block unless overridden by the user (see Override Protocol).
+
+## Gate Definitions
+
+| Gate | Name | Check | Type | Pass Criteria | Failure Message |
+|------|------|-------|------|---------------|-----------------|
+| G1 | When-To-Use | Finding has a "When to use" section or equivalent guidance | deterministic | Section exists and is non-empty | Missing "When to use" guidance |
+| G2 | When-Not-To-Use | Finding has a "When NOT to use" section or equivalent anti-guidance | deterministic | Section exists and is non-empty | Missing "When NOT to use" guidance |
+| G3 | Decontextualized | No project-specific names, paths, slugs, dates, or hardcoded values remain | semantic | Haiku confirms no project-specific references | Project-specific references remain: {details} |
+| G4 | Concrete Example | At least one concrete usage example is provided | semantic | Haiku confirms example is concrete and actionable | No concrete example provided |
+| G5 | Reusability Threshold | Reusability confidence score meets minimum | deterministic | confidence >= 0.5 | Confidence {score} < 0.5 threshold |
+| G6 | Not Duplicate | Finding is not a duplicate of an existing toolkit entry | deterministic | No existing entry with content similarity > 0.85 | Duplicate of existing entry: {existing_name} |
+| G7 | Maturity Label | Finding has a maturity level assigned | deterministic | maturity field is one of: alpha, beta, stable | Missing maturity label |
+| G8 | Brutal Honesty | Finding survives self-critical review — is it genuinely useful or just noise? | semantic | Haiku confirms finding has genuine reuse value beyond the source project | Fails brutal-honesty review: {reason} |
+
+## Gate Types
+
+**Deterministic gates** (G1, G2, G5, G6, G7) are checked by the orchestrator without LLM calls.
+They operate on the structured finding JSON: presence of fields, numeric thresholds, set membership.
+
+**Semantic gates** (G3, G4, G8) require a haiku LLM call with a focused single-question prompt.
+The prompt must ask for a binary YES/NO answer plus a short explanation (1-2 sentences max).
+Use haiku — these are high-frequency, pattern-matching evaluations that do not require deep reasoning.
+
+## Pass Assignment (which pass each gate belongs to)
+
+Gates are evaluated in two passes to minimize unnecessary LLM cost.
+
+### Pass 1 — Deterministic (zero LLM cost)
+
+Run all deterministic gates first. If any deterministic gate fails, reject immediately.
+Do NOT proceed to Pass 2 for a rejected finding.
+
+Gates in Pass 1 (in evaluation order):
+1. G7 — Maturity Label (cheapest check: field presence)
+2. G5 — Reusability Threshold (numeric comparison)
+3. G1 — When-To-Use (section presence)
+4. G2 — When-Not-To-Use (section presence)
+5. G6 — Not Duplicate (similarity comparison against existing entries)
+
+### Pass 2 — Semantic (haiku LLM calls, parallelizable)
+
+Run only after all Pass 1 gates pass.
+Gates G3, G4, G8 may be evaluated in parallel (3 concurrent haiku calls).
+
+Gates in Pass 2:
+- G3 — Decontextualized
+- G4 — Concrete Example
+- G8 — Brutal Honesty
+
+## Override Protocol
+
+A user may override a gate for a specific finding using the syntax:
+
+```
+пропусти G3 для #X
+```
+
+Where `#X` is the finding number (1-indexed, matching the extraction output list).
+
+### Override Rules
+
+- Multiple gates may be overridden in a single command using comma-separated syntax: `"пропусти G3,G4 для #14"`.
+- G8 (Brutal Honesty) cannot be overridden. If a finding fails G8, it must be revised or dropped.
+- G6 (Not Duplicate) cannot be overridden. If a finding is a duplicate, either update the existing entry or drop the new one.
+- G5 (Reusability Threshold) can be overridden only if the user provides a rationale explaining why low-confidence is acceptable for this finding.
+- All overrides are logged in the harvest output with the gate ID, finding number, and user rationale.
+
+### Override Log Format
+
+When an override is applied, append to the harvest session log:
+
+```
+OVERRIDE: G{N} skipped for finding #{X} — user rationale: "{rationale}"
+```
+
+## Scoring
+
+After all gates are evaluated for a finding:
+
+```
+gate_pass_rate = gates_passed / 8
+```
+
+This score is recorded in the finding's metadata alongside the per-gate pass/fail results.
+
+| gate_pass_rate | Interpretation |
+|----------------|----------------|
+| 1.0 | Clean pass — add to toolkit |
+| 0.875 (7/8) | One gate overridden — add with override note |
+| < 0.875 | Rejected — do not add to toolkit |
+
+The gate_pass_rate is surfaced in the harvest summary table for each finding.
+It is not used as a quality score for ranking — a finding either passes all required gates or it does not.

package/templates/.claude/skills/knowledge-extractor/templates/artifact-card.md

@@ -0,0 +1,63 @@
+# Artifact Card Template
+
+## Usage
+This template is rendered once per approved finding during Module 04 (Integrate).
+Replace all {PLACEHOLDER} values with finding data.
+
+## Template
+
+---
+
+### {NAME}
+
+**Category:** {CATEGORY}
+**Maturity:** {MATURITY_BADGE} {MATURITY_LEVEL}
+**Reusability Confidence:** {CONFIDENCE}
+**Extracted from:** {SOURCE_PROJECT}
+**Last updated:** {DATE}
+
+#### Description
+
+{DESCRIPTION}
+
+#### When to use
+
+{WHEN_TO_USE}
+
+#### When NOT to use
+
+{WHEN_NOT_TO_USE}
+
+#### Example
+
+{EXAMPLE}
+
+#### Changelog
+
+- v1: Initial extraction from {SOURCE_PROJECT} ({DATE})
+
+---
+
+## Placeholder Reference
+
+| Placeholder | Source | Example |
+|-------------|--------|---------|
+| {NAME} | finding.title | "Agent Swarm Topology" |
+| {CATEGORY} | finding.category | "patterns" |
+| {MATURITY_BADGE} | maturity-model.md lookup | "🔴" |
+| {MATURITY_LEVEL} | finding.maturity | "Alpha" |
+| {CONFIDENCE} | finding.confidence | "0.85" |
+| {SOURCE_PROJECT} | session.slug | "bank-kc-automation" |
+| {DATE} | current date | "2026-03-03" |
+| {DESCRIPTION} | finding.content (first paragraph) | "..." |
+| {WHEN_TO_USE} | finding.when_to_use | "..." |
+| {WHEN_NOT_TO_USE} | finding.when_not_to_use | "..." |
+| {EXAMPLE} | finding.example | "..." |
+
+## Placement Rules
+
+For **skills** category: This template becomes the initial SKILL.md skeleton
+For **commands** category: This template becomes the command .md file body
+For **rules** category: Convert to rule table format (see .claude/rules/ convention)
+For **templates/patterns/snippets** category: This card is appended to TOOLKIT_HARVEST.md under the relevant section
+For **hooks** category: This card is appended to TOOLKIT_HARVEST.md hooks section (or created inline)

package/templates/.claude/skills/knowledge-extractor/templates/harvest-report.md

@@ -0,0 +1,102 @@
+# Harvest Report Template
+
+## Usage
+Generated at the end of Module 04 (Integrate) to summarize the harvest session.
+All {PLACEHOLDER} values are computed from the findings registry.
+
+## Template
+
+---
+
+# Harvest Report: {SESSION_ID}
+
+**Date:** {DATE}
+**Target:** {TARGET_PATHS}
+**Scope:** {SCOPE_FILTER_OR_ALL}
+**Steps completed:** {STEPS_COMPLETED} (Extract → Classify → Checkpoint → Gate → Integrate)
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total findings extracted | {TOTAL_EXTRACTED} |
+| After deduplication | {AFTER_DEDUP} |
+| User removals | {USER_REMOVALS} |
+| User merges | {USER_MERGES} |
+| Approved (passed gates) | {APPROVED_COUNT} |
+| Blocked (failed gates) | {BLOCKED_COUNT} |
+| Gate overrides | {OVERRIDE_COUNT} |
+| Placed artifacts | {PLACED_COUNT} |
+
+## Findings by Category
+
+| Category | Extracted | Approved | Placed | Destination |
+|----------|-----------|----------|--------|-------------|
+| skills | {N} | {N} | {N} | .claude/skills/ |
+| commands | {N} | {N} | {N} | .claude/commands/ |
+| hooks | {N} | {N} | {N} | TOOLKIT_HARVEST.md |
+| rules | {N} | {N} | {N} | .claude/rules/ |
+| templates | {N} | {N} | {N} | TOOLKIT_HARVEST.md |
+| patterns | {N} | {N} | {N} | TOOLKIT_HARVEST.md |
+| snippets | {N} | {N} | {N} | TOOLKIT_HARVEST.md |
+
+## Quality Gate Results
+
+| Gate | Pass | Fail | Override | Pass Rate |
+|------|------|------|----------|-----------|
+| G1 When-To-Use | {N} | {N} | {N} | {%} |
+| G2 When-Not-To-Use | {N} | {N} | {N} | {%} |
+| G3 Decontextualized | {N} | {N} | {N} | {%} |
+| G4 Concrete Example | {N} | {N} | {N} | {%} |
+| G5 Reusability | {N} | {N} | {N} | {%} |
+| G6 Not Duplicate | {N} | {N} | {N} | {%} |
+| G7 Maturity Label | {N} | {N} | {N} | {%} |
+| G8 Brutal Honesty | {N} | {N} | {N} | {%} |
+
+## Coverage Gaps
+
+| Item | Reason |
+|------|--------|
+| {SKIPPED_FILES_TABLE_OR_NONE} | |
+
+**Failed extractors:** {FAILED_EXTRACTORS_OR_NONE}
+
+## Confidence Distribution
+
+| Range | Count | Percentage |
+|-------|-------|------------|
+| 0.9 - 1.0 (Excellent) | {N} | {%} |
+| 0.7 - 0.89 (Good) | {N} | {%} |
+| 0.5 - 0.69 (Acceptable) | {N} | {%} |
+| < 0.5 (Below threshold) | {N} | {%} |
+
+## Memory Integration
+
+- Patterns loaded from memory: {MEMORY_PATTERNS_COUNT}
+- Reward stored: {REWARD_SCORE} ({REWARD_LABEL})
+- Dream trigger updated: {YES_NO}
+
+---
+
+## Placeholder Reference
+
+| Placeholder | Computation |
+|-------------|-------------|
+| {SESSION_ID} | HarvestSession.session_id |
+| {DATE} | Current date (YYYY-MM-DD) |
+| {TARGET_PATHS} | Directory path(s) scanned |
+| {SCOPE_FILTER_OR_ALL} | Scope filter value or "all categories" |
+| {STEPS_COMPLETED} | Count of pipeline steps that ran successfully |
+| {TOTAL_EXTRACTED} | count(all findings at extraction) |
+| {AFTER_DEDUP} | count(findings after Module 02 dedup) |
+| {USER_REMOVALS} | count(findings removed by user at checkpoint) |
+| {USER_MERGES} | count(findings with non-null merged_from) |
+| {APPROVED_COUNT} | count(findings where status = approved) |
+| {BLOCKED_COUNT} | count(findings where status = blocked) |
+| {OVERRIDE_COUNT} | sum(length of all gate_overrides arrays) |
+| {PLACED_COUNT} | count(findings where status = integrated) |
+| {SKIPPED_FILES_TABLE_OR_NONE} | Table of files skipped (>100KB or binary), or "None" |
+| {FAILED_EXTRACTORS_OR_NONE} | List of failed agent lenses, or "None" |
+| {MEMORY_PATTERNS_COUNT} | count(patterns loaded from memory_query) |
+| {REWARD_SCORE} | User checkpoint response mapped to 0.0-1.0 |
+| {REWARD_LABEL} | excellent/good/needs_work/failed (see reward-learning.md) |

package/templates/.claude/skills/transcript-site-generator/SKILL.md

@@ -0,0 +1,287 @@
+# transcript-site-generator — Interactive Transcript Site Generator
+
+<!-- Trust Tier: 2 — Validated | BTO Layer 2 Score: 7.82/10 | Promoted: 2026-03-05 -->
+
+> Generate a modern, interactive, mobile-friendly, SEO-optimized static website from a transcript or YouTube video link, ready for GitHub Pages deployment. Zero build step required.
+
+## When To Activate
+
+Trigger on:
+- "generate transcript site from [content]"
+- "create interactive transcript [topic]"
+- "build transcript website from YouTube [url]"
+- "сгенерируй сайт из транскрипта"
+- "сделай сайт из видео [url]"
+- `/transcript-site [content or YouTube URL]`
+
+## Overview
+
+This skill transforms text transcripts, content, or YouTube video links into production-ready interactive websites. The **default output is a pure static site** (single HTML + JS file) that deploys to GitHub Pages with zero build step — no React, no Vite, no npm install needed.
+
+### Features
+
+- **Interactive transcript** with section navigation, scroll-spy TOC, full-text search (Ctrl+K)
+- **YouTube embed** with clickable timestamps for video synchronization (if URL provided)
+- **Dark/Light mode** toggle with localStorage persistence
+- **Reading progress bar** and back-to-top button
+- **Copy-quote** buttons per section (copies section text to clipboard)
+- **Reading statistics** (word count, estimated reading time, section count)
+- **SEO optimization** — Open Graph, Twitter Cards, JSON-LD (VideoObject/Article)
+- **Print-friendly** CSS media queries
+- **GitHub Pages** deployment via `docs/` folder (zero build) or GitHub Actions
+- **Mobile-friendly** — responsive layout, hamburger menu, 44px touch targets
+- **Speaker labels** — automatic speaker detection and visual differentiation
+
+## Architecture
+
+```
+.claude/skills/transcript-site-generator/
+├── SKILL.md                           <- This file (orchestrator)
+├── modules/
+│   ├── 00-input-analysis.md           <- Step 0: Detect input type, extract transcript
+│   ├── 01-content-parsing.md          <- Step 1: Split into sections, extract timestamps
+│   ├── 02-site-generation.md          <- Step 2: Generate index.html with all content
+│   ├── 03-interactivity.md            <- Step 3: Generate app.js (search, TOC, dark mode)
+│   ├── 04-deploy.md                   <- Step 4: GitHub Pages config + Actions workflow
+│   └── 05-verification.md             <- Step 5: Validate output, open in browser
+├── references/
+│   ├── tech-stack.md                  <- Stack: Tailwind CDN, vanilla JS, static HTML
+│   ├── data-schemas.md                <- Section data structure, metadata schema
+│   └── component-catalog.md           <- HTML sections and JS modules catalog
+└── examples/
+    ├── sample-transcript-site.md      <- Example: YouTube + Russian podcast
+    └── sample-text-only-site.md       <- Example: text-only, English, no YouTube
+```
+
+## Pipeline
+
+```
+Step 0          Step 1           Step 2           Step 3
+INPUT      ->  PARSE       ->  GENERATE     ->  INTERACTIVITY
+(text/URL/     (split into     (index.html       (app.js:
+ yt-dlp)        sections +      with Tailwind     search, TOC,
+                timestamps)     CDN + content)    dark mode)
+
+     |
+     v
+Step 4          Step 5
+DEPLOY     ->  VERIFY
+(docs/ +        (file check
+ GH Actions     + open)
+ workflow)
+```
+
+## Input Requirements
+
+The skill accepts one of:
+1. **Text transcript** — pasted directly or as a file path
+2. **YouTube URL** — extracts transcript via `yt-dlp --write-auto-sub --sub-lang ru,en --skip-download`
+3. **Both** — YouTube URL for embed + custom/edited transcript text
+
+Minimum: enough content for 3 sections. No maximum (long transcripts benefit most from navigation).
+
+### YouTube Transcript Extraction
+
+When a YouTube URL is provided:
+```bash
+# Check yt-dlp availability
+which yt-dlp || pip install yt-dlp
+
+# Extract auto-generated subtitles (prefer manual, fallback to auto)
+yt-dlp --write-sub --sub-lang ru,en --skip-download --sub-format vtt -o "/tmp/transcript" "<URL>" 2>/dev/null \
+  || yt-dlp --write-auto-sub --sub-lang ru,en --skip-download --sub-format vtt -o "/tmp/transcript" "<URL>"
+
+# Extract video metadata
+yt-dlp --print title --print channel --print duration --skip-download "<URL>"
+```
+
+If `yt-dlp` is not installed:
+```
+yt-dlp not found. Install with: pip install yt-dlp
+Alternatively, paste the transcript text directly.
+```
+
+## Output
+
+A **pure static site** in the `docs/` directory — zero build step, deploys directly via GitHub Pages:
+
+```
+<project-root>/
+├── docs/                             <- GitHub Pages source
+│   ├── index.html                    (99KB+ single-file: HTML + inline Tailwind + SEO)
+│   └── static/
+│       ├── app.js                    (search, TOC scroll-spy, dark mode, progress bar)
+│       └── style.css                 (minimal overrides)
+├── .github/workflows/deploy.yml      (GitHub Pages deployment workflow)
+└── README.md                         (project description + link to live site)
+```
+
+### index.html Structure
+
+The HTML file is self-contained with:
+- **Tailwind CSS via CDN** (`<script src="https://cdn.tailwindcss.com">`) with dark mode config
+- **Font Awesome via CDN** for icons (moon/sun, search, copy, hamburger)
+- **Full SEO head**: Open Graph, Twitter Cards, JSON-LD structured data
+- **Semantic HTML**: `<header>`, `<nav>`, `<main>`, `<article>`, `<section>`, `<footer>`
+- **All transcript content** rendered as HTML sections with anchor IDs
+- **Responsive layout**: fixed sidebar TOC (desktop) + hamburger menu (mobile)
+- **YouTube embed** (if video URL provided): responsive iframe with aspect-ratio container
+
+### app.js Features
+
+Vanilla JavaScript (no frameworks) implementing:
+- **Full-text search** — Ctrl+K modal, 300ms debounce, highlighted results with context
+- **TOC scroll-spy** — IntersectionObserver highlights the active section in sidebar
+- **Dark/Light mode** — toggle with localStorage persistence, icon switch (moon/sun)
+- **Reading progress bar** — requestAnimationFrame-based scroll tracking
+- **Back-to-top button** — appears after 500px scroll
+- **Copy-quote** — per-section copy button with "Copied!" feedback
+- **Mobile navigation** — hamburger toggle with slide-out sidebar
+- **Keyboard shortcuts** — Ctrl/Cmd+K (search), Escape (close modal)
+- **Timestamp links** — clickable timestamps that seek YouTube player (if embedded)
+
+## Execution Protocol
+
+### Step 0: Input Analysis
+```
+Read: modules/00-input-analysis.md
+```
+- Detect input type (text / YouTube URL / both)
+- If YouTube URL: extract transcript via yt-dlp, get video metadata
+- If text: accept as-is
+- Detect language (Russian / English)
+- **Output:** Raw transcript text + optional video metadata + language
+
+### Step 1: Content Parsing
+```
+Read: modules/01-content-parsing.md
+```
+- Split transcript into logical sections (by topic shifts, speaker changes, or markers)
+- Extract timestamps if present (from VTT or inline `[HH:MM:SS]`)
+- Generate section titles from content
+- Detect speakers if multi-speaker transcript
+- Calculate word counts and reading time
+- **Output:** Structured section list with titles, content, timestamps, speakers
+
+### Step 2: Site Generation
+```
+Read: modules/02-site-generation.md
+Read: references/data-schemas.md
+```
+- Generate `docs/index.html` — complete self-contained page:
+  - Tailwind CSS + Font Awesome via CDN
+  - Full SEO meta tags (OG, Twitter, JSON-LD)
+  - Header with title, stats, dark mode toggle, search button
+  - Sidebar TOC with all section links
+  - YouTube embed (if video URL provided)
+  - All transcript sections as HTML with anchor IDs
+  - Footer with author credits and source link
+- Generate `docs/static/style.css` — minimal CSS overrides
+- **Output:** Complete HTML + CSS files
+
+### Step 3: Interactivity
+```
+Read: modules/03-interactivity.md
+Read: references/component-catalog.md
+```
+- Generate `docs/static/app.js` — vanilla JS:
+  - Search modal with highlighting and context snippets
+  - TOC scroll-spy (IntersectionObserver)
+  - Dark mode toggle with localStorage
+  - Reading progress bar
+  - Back-to-top button
+  - Copy-quote buttons
+  - Mobile hamburger menu
+  - Keyboard shortcuts
+  - YouTube timestamp sync (if video embedded)
+- **Output:** Complete JS file
+
+### Step 4: Deployment
+```
+Read: modules/04-deploy.md
+```
+- Create `.github/workflows/deploy.yml` for GitHub Pages from `docs/`
+- Create or update `README.md` with project description and live site link
+- Configure GitHub Pages source as `docs/` on `main` branch
+- **Output:** Deploy config + README
+
+### Step 5: Verification
+```
+Read: modules/05-verification.md
+```
+- Verify `docs/index.html` exists and has valid HTML structure
+- Verify `docs/static/app.js` exists and has no syntax errors
+- Check all section IDs are unique
+- Check SEO meta tags are present
+- Verify mobile responsiveness classes
+- Check dark mode CSS works
+- **Output:** Verification report
+
+## Customization Points
+
+| Parameter | Default | How to specify | Description |
+|-----------|---------|---------------|-------------|
+| Language | auto-detect | "language: en" in prompt | UI language (ru/en) |
+| Theme color | Indigo | "use green theme" in prompt | Primary Tailwind color palette |
+| YouTube URL | none | Include URL in input | Optional video embed with timestamps |
+| Author | from transcript/video | "author: John Doe" in prompt | Attribution in footer |
+| Show timestamps | auto (if available) | "hide timestamps" in prompt | Toggle timestamp display |
+| Show stats | yes | "no stats" in prompt | Word count, reading time in header |
+| Show copy buttons | yes | "no copy buttons" in prompt | Copy-quote per section |
+| Output dir | docs/ | "output to site/" in prompt | Static site output directory |
+| Deploy method | docs/ folder | "use GitHub Actions" in prompt | `docs/` (zero build) or GitHub Actions |
+
+Customization is passed via natural language in the user's prompt. The agent parses these from the initial request during Step 0. If the output directory is not `docs/`, update the deploy workflow `path` accordingly.
+
+### Conflict Detection
+
+Before writing to the output directory, check if it already exists:
+- If `docs/` has existing content, warn: `"docs/ already exists. Overwrite? (yes/no/use different dir)"`
+- Never silently overwrite existing files
+
+## Large Transcript Strategy
+
+For transcripts exceeding 30,000 words (~150 KB HTML output), the generated `index.html` may exceed single-file output limits. In this case:
+
+1. **Generate the HTML shell first** — `<head>`, header, sidebar TOC, search modal, footer (without section content)
+2. **Generate transcript sections in batches** — 5-10 sections per Write operation, appending to the HTML file
+3. **Close the HTML** — add closing `</main>`, `</div>`, `</body>`, `</html>` tags
+4. **Verify integrity** — check that `</html>` appears exactly once and all section IDs are present
+
+This chunked approach ensures complete output regardless of transcript length.
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Using React/Vite for simple transcript | Unnecessary complexity | Use static HTML + vanilla JS (default) |
+| Transcript split into too many files | Multiple HTML pages | Single index.html with anchor navigation |
+| Missing Tailwind CDN script | No styling | Always include `<script src="https://cdn.tailwindcss.com">` |
+| Missing dark mode config in Tailwind | Dark mode broken | Add `tailwind.config = { darkMode: 'class' }` |
+| Too few sections (<3) | Not enough for navigation | Merge more content or split deeper |
+| Giant monolithic section | Section > 3000 words | Split into sub-sections |
+| No search results feedback | Empty search shows nothing | Show "no results" message |
+| Missing print styles | Page breaks mid-section | Add `@media print` rules |
+| No mobile TOC | Desktop-only sidebar | Add hamburger menu for screens < 768px |
+| YouTube embed not responsive | Fixed-width iframe | Use padding-bottom aspect-ratio trick |
+| Missing fallback for yt-dlp | Script crashes if not installed | Check availability, offer text paste |
+| No Font Awesome CDN | Missing icons | Include FA CDN link in `<head>` |
+| Content in separate JS files | Unnecessary indirection for static site | Inline content directly in HTML |
+| Using npm/build step | Over-engineering for static content | Deploy `docs/` directly, zero build |
+
+## Dependencies
+
+- **Tech stack:** Pure HTML + Tailwind CSS (CDN) + Vanilla JavaScript
+- **External CDNs:** Tailwind CSS, Font Awesome
+- **Optional:** yt-dlp (for YouTube transcript extraction)
+- **Skills used:** None (standalone skill)
+- **Deployment:** GitHub Pages via `docs/` folder (no build step)
+
+## Checkpoint Protocol
+
+After each step, output:
+```
+Step N/5: [Name] Complete
+Artifacts: [list]
+"ok" to continue | "[feedback]" to adjust
+```

package/templates/.claude/skills/transcript-site-generator/examples/sample-text-only-site.md

@@ -0,0 +1,123 @@
+# Example: Text-Only Transcript Site (No YouTube)
+
+## Input
+
+```
+Input type: Pasted text
+Title: "AI in Healthcare: Panel Discussion at TechConf 2025"
+Language: English
+YouTube: none
+```
+
+## Parsed Sections (Step 1 Output)
+
+```
+Section 1: "Opening Remarks" - 480 words
+Section 2: "Current State of Medical AI" - 1120 words
+Section 3: "Regulatory Challenges" - 890 words
+Section 4: "Patient Data Privacy" - 1050 words
+Section 5: "Clinical Decision Support Systems" - 1340 words
+Section 6: "AI-Assisted Diagnostics in Radiology" - 960 words
+Section 7: "Audience Q&A" - 720 words
+Section 8: "Closing Thoughts" - 410 words
+
+Total: 6,970 words, ~35 min read, 3 speakers
+```
+
+## Generated File Structure
+
+```
+project-root/
+├── docs/
+│   ├── index.html       (52 KB)
+│   └── static/
+│       ├── app.js        (9 KB)   <- smaller: no YouTube seek code
+│       └── style.css     (0.4 KB)
+├── .github/
+│   └── workflows/
+│       └── deploy.yml
+└── README.md
+```
+
+## Key Differences from YouTube Example
+
+| Aspect | YouTube Example | Text-Only Example |
+|--------|----------------|-------------------|
+| Video embed | Yes (`<iframe>`) | Omitted |
+| Timestamp links | Yes (`seekTo()`) | Omitted |
+| `seekTo` function | In app.js | Not generated |
+| `onYouTubeIframeAPIReady` | In app.js | Not generated |
+| `og:type` | `video.other` | `article` |
+| JSON-LD VideoObject | Yes | Omitted |
+| `og:image` | YouTube thumbnail | Not set (or custom) |
+| app.js size | ~11 KB | ~9 KB |
+
+## Sample Section HTML (No Timestamp)
+
+```html
+<section id="section-regulatory-challenges" class="mb-12 scroll-mt-20">
+  <div class="flex items-start justify-between mb-4">
+    <h2 class="text-2xl font-bold text-gray-900 dark:text-white">
+      3. Regulatory Challenges
+    </h2>
+    <button data-copy="section-regulatory-challenges"
+            class="copy-btn flex-shrink-0 p-2 rounded-lg hover:bg-gray-100 dark:hover:bg-gray-800
+                   text-gray-400 hover:text-gray-600 dark:hover:text-gray-300 no-print"
+            aria-label="Copy">
+      <i class="far fa-copy"></i>
+    </button>
+  </div>
+  <div class="mb-3 flex items-center gap-2">
+    <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium
+                 bg-primary-100 text-primary-800 dark:bg-primary-900 dark:text-primary-200">
+      Dr. Sarah Chen &middot; Panelist
+    </span>
+  </div>
+  <div class="prose prose-lg dark:prose-invert max-w-none">
+    <p>The FDA's approach to AI-based medical devices has evolved significantly...</p>
+    <p>We're seeing a shift from traditional 510(k) pathways to the new PCCP framework...</p>
+  </div>
+</section>
+```
+
+## SEO Head (Article-only, no VideoObject)
+
+```html
+<title>AI in Healthcare: Panel Discussion at TechConf 2025</title>
+<meta name="description" content="Panel discussion transcript covering medical AI, regulatory challenges, patient data privacy, and clinical decision support systems." />
+<meta property="og:type" content="article" />
+<!-- No og:image (no YouTube thumbnail available) -->
+```
+
+## JSON-LD (Article only)
+
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "Article",
+  "headline": "AI in Healthcare: Panel Discussion at TechConf 2025",
+  "author": { "@type": "Organization", "name": "TechConf" },
+  "datePublished": "2025-11-15",
+  "description": "Panel discussion transcript covering medical AI...",
+  "wordCount": 6970
+}
+```
+
+## Stats Displayed in Header
+
+```
+35 min read · 6,970 words · 8 sections
+```
+
+## Verification Results
+
+```
+File checks: 5/5 passed
+HTML structure: 11/11 passed  (no YouTube-specific checks)
+Content: 6/6 passed
+Interactivity: 8/8 passed    (no seekTo/YouTube checks)
+Responsive: 6/6 passed
+Dark mode: 6/6 passed
+SEO: 5/5 passed              (no VideoObject checks)
+Print: 4/4 passed
+```