diff --git a/skills/.experimental/clone-website/LICENSE.txt b/skills/.experimental/clone-website/LICENSE.txt
new file mode 100644
index 00000000..285e414f
--- /dev/null
+++ b/skills/.experimental/clone-website/LICENSE.txt
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JCodesMore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/skills/.experimental/clone-website/SKILL.md b/skills/.experimental/clone-website/SKILL.md
new file mode 100644
index 00000000..3b2bfffe
--- /dev/null
+++ b/skills/.experimental/clone-website/SKILL.md
@@ -0,0 +1,486 @@
+---
+name: clone-website
+description: Reverse-engineer and clone one or more websites in one shot — extracts assets, CSS, and content section-by-section and proactively dispatches parallel builder agents in worktrees as it goes. Use this whenever the user wants to clone, replicate, rebuild, reverse-engineer, or copy any website. Also triggers on phrases like "make a copy of this site", "rebuild this page", "pixel-perfect clone". Provide one or more target URLs as arguments.
+argument-hint: "<url1> [<url2> ...]"
+user-invocable: true
+---
+
+# Clone Website
+
+You are about to reverse-engineer and rebuild **$ARGUMENTS** as pixel-perfect clones.
+
+## Scope
+
+- Input: one or more publicly reachable page URLs plus optional fidelity or customization instructions
+- Output: implementation-ready frontend specs, extracted assets, and reconstructed UI code
+- Use when: the task is layout recreation, design analysis, component extraction, or frontend prototyping
+- Do not use when: the task is copying backend behavior, reproducing private systems, bypassing access controls, or bulk content scraping without a rebuild goal
+
+When multiple URLs are provided, process them independently and in parallel where possible, while keeping each site's extraction artifacts isolated in dedicated folders (for example, `docs/research/<hostname>/`).
+
+This is not a two-phase process (inspect then build). You are a **foreman walking the job site** — as you inspect each section of the page, you write a detailed specification to a file, then hand that file to a specialist builder agent with everything they need. Extraction and construction happen in parallel, but extraction is meticulous and produces auditable artifacts.
+
+## Scope Defaults
+
+The target is whatever page `$ARGUMENTS` resolves to. Clone exactly what's visible at that URL. Unless the user specifies otherwise, use these defaults:
+
+- **Fidelity level:** Pixel-perfect — exact match in colors, spacing, typography, animations
+- **In scope:** Visual layout and styling, component structure and interactions, responsive design, mock data for demo purposes
+- **Out of scope:** Real backend / database, authentication, real-time features, SEO optimization, accessibility audit
+- **Customization:** None — pure emulation
+
+If the user provides additional instructions (specific fidelity level, customizations, extra context), honor those over the defaults.
+
+## Pre-Flight
+
+1. **Browser automation is required.** Check for available browser MCP tools (Chrome MCP, Playwright MCP, Browserbase MCP, Puppeteer MCP, etc.). Use whichever is available — if multiple exist, prefer Chrome MCP. If none are detected, ask the user which browser tool they have and how to connect it. This skill cannot work without browser automation.
+2. Parse `$ARGUMENTS` as one or more URLs. Normalize and validate each URL; if any are invalid, ask the user to correct them before proceeding. For each valid URL, verify it is accessible via your browser MCP tool.
+3. Verify the base project builds: `npm run build`. The Next.js + shadcn/ui + Tailwind v4 scaffold should already be in place. If not, tell the user to set it up first.
+4. Create the output directories if they don't exist: `docs/research/`, `docs/research/components/`, `docs/design-references/`, `scripts/`. For multiple clones, also prepare per-site folders like `docs/research/<hostname>/` and `docs/design-references/<hostname>/`.
+5. When working with multiple sites in one command, optionally confirm whether to run them in parallel (recommended, if resources allow) or sequentially to avoid overload.
+
+## Guiding Principles
+
+These are the truths that separate a successful clone from a "close enough" mess. Internalize them — they should inform every decision you make.
+
+### 1. Completeness Beats Speed
+
+Every builder agent must receive **everything** it needs to do its job perfectly: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess anything — a color, a font size, a padding value — you have failed at extraction. Take the extra minute to extract one more property rather than shipping an incomplete brief.
+
+### 2. Small Tasks, Perfect Results
+
+When an agent gets "build the entire features section," it glosses over details — it approximates spacing, guesses font sizes, and produces something "close enough" but clearly wrong. When it gets a single focused component with exact CSS values, it nails it every time.
+
+Look at each section and judge its complexity. A simple banner with a heading and a button? One agent. A complex section with 3 different card variants, each with unique hover states and internal layouts? One agent per card variant plus one for the section wrapper. When in doubt, make it smaller.
+
+**Complexity budget rule:** If a builder prompt exceeds ~150 lines of spec content, the section is too complex for one agent. Break it into smaller pieces. This is a mechanical check — don't override it with "but it's all related."
+
+### 3. Real Content, Real Assets
+
+Extract the actual text, images, videos, and SVGs from the live site. This is a clone, not a mockup. Use `element.textContent`, download every `<img>` and `<video>`, extract inline `<svg>` elements as React components. The only time you generate content is when something is clearly server-generated and unique per session.
+
+**Layered assets matter.** A section that looks like one image is often multiple layers — a background watercolor/gradient, a foreground UI mockup PNG, an overlay icon. Inspect each container's full DOM tree and enumerate ALL `<img>` elements and background images within it, including absolutely-positioned overlays. Missing an overlay image makes the clone look empty even if the background is correct.
+
+### 4. Foundation First
+
+Nothing can be built until the foundation exists: global CSS with the target site's design tokens (colors, fonts, spacing), TypeScript types for the content structures, and global assets (fonts, favicons). This is sequential and non-negotiable. Everything after this can be parallel.
+
+### 5. Extract How It Looks AND How It Behaves
+
+A website is not a screenshot — it's a living thing. Elements move, change, appear, and disappear in response to scrolling, hovering, clicking, resizing, and time. If you only extract the static CSS of each element, your clone will look right in a screenshot but feel dead when someone actually uses it.
+
+For every element, extract its **appearance** (exact computed CSS via `getComputedStyle()`) AND its **behavior** (what changes, what triggers the change, and how the transition happens). Not "it looks like 16px" — extract the actual computed value. Not "the nav changes on scroll" — document the exact trigger (scroll position, IntersectionObserver threshold, viewport intersection), the before and after states (both sets of CSS values), and the transition (duration, easing, CSS transition vs. JS-driven vs. CSS `animation-timeline`).
+
+Examples of behaviors to watch for — these are illustrative, not exhaustive. The page may do things not on this list, and you must catch those too:
+- A navbar that shrinks, changes background, or gains a shadow after scrolling past a threshold
+- Elements that animate into view when they enter the viewport (fade-up, slide-in, stagger delays)
+- Sections that snap into place on scroll (`scroll-snap-type`)
+- Parallax layers that move at different rates than the scroll
+- Hover states that animate (not just change — the transition duration and easing matter)
+- Dropdowns, modals, accordions with enter/exit animations
+- Scroll-driven progress indicators or opacity transitions
+- Auto-playing carousels or cycling content
+- Dark-to-light (or any theme) transitions between page sections
+- **Tabbed/pill content that cycles** — buttons that switch visible card sets with transitions
+- **Scroll-driven tab/accordion switching** — sidebars where the active item auto-changes as content scrolls past (IntersectionObserver, NOT click handlers)
+- **Smooth scroll libraries** (Lenis, Locomotive Scroll) — check for `.lenis` class or scroll container wrappers
+
+### 6. Identify the Interaction Model Before Building
+
+This is the single most expensive mistake in cloning: building a click-based UI when the original is scroll-driven, or vice versa. Before writing any builder prompt for an interactive section, you must definitively answer: **Is this section driven by clicks, scrolls, hovers, time, or some combination?**
+
+How to determine this:
+1. **Don't click first.** Scroll through the section slowly and observe if things change on their own as you scroll.
+2. If they do, it's scroll-driven. Extract the mechanism: `IntersectionObserver`, `scroll-snap`, `position: sticky`, `animation-timeline`, or JS scroll listeners.
+3. If nothing changes on scroll, THEN click/hover to test for click/hover-driven interactivity.
+4. Document the interaction model explicitly in the component spec: "INTERACTION MODEL: scroll-driven with IntersectionObserver" or "INTERACTION MODEL: click-to-switch with opacity transition."
+
+A section with a sticky sidebar and scrolling content panels is fundamentally different from a tabbed interface where clicking switches content. Getting this wrong means a complete rewrite, not a CSS tweak.
+
+### 7. Extract Every State, Not Just the Default
+
+Many components have multiple visual states — a tab bar shows different cards per tab, a header looks different at scroll position 0 vs 100, a card has hover effects. You must extract ALL states, not just whatever is visible on page load.
+
+For tabbed/stateful content:
+- Click each tab/button via browser MCP
+- Extract the content, images, and card data for EACH state
+- Record which content belongs to which state
+- Note the transition animation between states (opacity, slide, fade, etc.)
+
+For scroll-dependent elements:
+- Capture computed styles at scroll position 0 (initial state)
+- Scroll past the trigger threshold and capture computed styles again (scrolled state)
+- Diff the two to identify exactly which CSS properties change
+- Record the transition CSS (duration, easing, properties)
+- Record the exact trigger threshold (scroll position in px, or viewport intersection ratio)
+
+### 8. Spec Files Are the Source of Truth
+
+Every component gets a specification file in `docs/research/components/` BEFORE any builder is dispatched. This file is the contract between your extraction work and the builder agent. The builder receives the spec file contents inline in its prompt — the file also persists as an auditable artifact that the user (or you) can review if something looks wrong.
+
+The spec file is not optional. It is not a nice-to-have. If you dispatch a builder without first writing a spec file, you are shipping incomplete instructions based on whatever you can remember from a browser MCP session, and the builder will guess to fill gaps.
+
+### 9. Build Must Always Compile
+
+Every builder agent must verify `npx tsc --noEmit` passes before finishing. After merging worktrees, you verify `npm run build` passes. A broken build is never acceptable, even temporarily.
+
+## Phase 1: Reconnaissance
+
+Navigate to the target URL with browser MCP.
+
+### Screenshots
+- Take **full-page screenshots** at desktop (1440px) and mobile (390px) viewports
+- Save to `docs/design-references/` with descriptive names
+- These are your master reference — builders will receive section-specific crops/screenshots later
+
+### Global Extraction
+Extract these from the page before doing anything else:
+
+**Fonts** — Inspect `<link>` tags for Google Fonts or self-hosted fonts. Check computed `font-family` on key elements (headings, body, code, labels). Document every family, weight, and style actually used. Configure them in `src/app/layout.tsx` using `next/font/google` or `next/font/local`.
+
+**Colors** — Extract the site's color palette from computed styles across the page. Update `src/app/globals.css` with the target's actual colors in the `:root` and `.dark` CSS variable blocks. Map them to shadcn's token names (background, foreground, primary, muted, etc.) where they fit. Add custom properties for colors that don't map to shadcn tokens.
+
+**Favicons & Meta** — Download favicons, apple-touch-icons, OG images, webmanifest to `public/seo/`. Update `layout.tsx` metadata.
+
+**Global UI patterns** — Identify any site-wide CSS or JS: custom scrollbar hiding, scroll-snap on the page container, global keyframe animations, backdrop filters, gradients used as overlays, **smooth scroll libraries** (Lenis, Locomotive Scroll — check for `.lenis`, `.locomotive-scroll`, or custom scroll container classes). Add these to `globals.css` and note any libraries that need to be installed.
+
+### Mandatory Interaction Sweep
+
+This is a dedicated pass AFTER screenshots and BEFORE anything else. Its purpose is to discover every behavior on the page — many of which are invisible in a static screenshot.
+
+**Scroll sweep:** Scroll the page slowly from top to bottom via browser MCP. At each section, pause and observe:
+- Does the header change appearance? Record the scroll position where it triggers.
+- Do elements animate into view? Record which ones and the animation type.
+- Does a sidebar or tab indicator auto-switch as you scroll? Record the mechanism.
+- Are there scroll-snap points? Record which containers.
+- Is there a smooth scroll library active? Check for non-native scroll behavior.
+
+**Click sweep:** Click every element that looks interactive:
+- Every button, tab, pill, link, card
+- Record what happens: does content change? Does a modal open? Does a dropdown appear?
+- For tabs/pills: click EACH ONE and record the content that appears for each state
+
+**Hover sweep:** Hover over every element that might have hover states:
+- Buttons, cards, links, images, nav items
+- Record what changes: color, scale, shadow, underline, opacity
+
+**Responsive sweep:** Test at 3 viewport widths via browser MCP:
+- Desktop: 1440px
+- Tablet: 768px
+- Mobile: 390px
+- At each width, note which sections change layout (column → stack, sidebar disappears, etc.) and at approximately which breakpoint the change occurs.
+
+Save all findings to `docs/research/BEHAVIORS.md`. This is your behavior bible — reference it when writing every component spec.
+
+### Page Topology
+Map out every distinct section of the page from top to bottom. Give each a working name. Document:
+- Their visual order
+- Which are fixed/sticky overlays vs. flow content
+- The overall page layout (scroll container, column structure, z-index layers)
+- Dependencies between sections (e.g., a floating nav that overlays everything)
+- **The interaction model** of each section (static, click-driven, scroll-driven, time-driven)
+
+Save this as `docs/research/PAGE_TOPOLOGY.md` — it becomes your assembly blueprint.
+
+## Phase 2: Foundation Build
+
+This is sequential. Do it yourself (not delegated to an agent) since it touches many files:
+
+1. **Update fonts** in `layout.tsx` to match the target site's actual fonts
+2. **Update globals.css** with the target's color tokens, spacing values, keyframe animations, utility classes, and any **global scroll behaviors** (Lenis, smooth scroll CSS, scroll-snap on body)
+3. **Create TypeScript interfaces** in `src/types/` for the content structures you've observed
+4. **Extract SVG icons** — find all inline `<svg>` elements on the page, deduplicate them, and save as named React components in `src/components/icons.tsx`. Name them by visual function (e.g., `SearchIcon`, `ArrowRightIcon`, `LogoIcon`).
+5. **Download global assets** — write and run a Node.js script (`scripts/download-assets.mjs`) that downloads all images, videos, and other binary assets from the page to `public/`. Preserve meaningful directory structure.
+6. Verify: `npm run build` passes
+
+### Asset Discovery Script Pattern
+
+Use browser MCP to enumerate all assets on the page:
+
+```javascript
+// Run this via browser MCP to discover all assets
+JSON.stringify({
+  images: [...document.querySelectorAll('img')].map(img => ({
+    src: img.src || img.currentSrc,
+    alt: img.alt,
+    width: img.naturalWidth,
+    height: img.naturalHeight,
+    // Include parent info to detect layered compositions
+    parentClasses: img.parentElement?.className,
+    siblings: img.parentElement ? [...img.parentElement.querySelectorAll('img')].length : 0,
+    position: getComputedStyle(img).position,
+    zIndex: getComputedStyle(img).zIndex
+  })),
+  videos: [...document.querySelectorAll('video')].map(v => ({
+    src: v.src || v.querySelector('source')?.src,
+    poster: v.poster,
+    autoplay: v.autoplay,
+    loop: v.loop,
+    muted: v.muted
+  })),
+  backgroundImages: [...document.querySelectorAll('*')].filter(el => {
+    const bg = getComputedStyle(el).backgroundImage;
+    return bg && bg !== 'none';
+  }).map(el => ({
+    url: getComputedStyle(el).backgroundImage,
+    element: el.tagName + '.' + el.className?.split(' ')[0]
+  })),
+  svgCount: document.querySelectorAll('svg').length,
+  fonts: [...new Set([...document.querySelectorAll('*')].slice(0, 200).map(el => getComputedStyle(el).fontFamily))],
+  favicons: [...document.querySelectorAll('link[rel*="icon"]')].map(l => ({ href: l.href, sizes: l.sizes?.toString() }))
+});
+```
+
+Then write a download script that fetches everything to `public/`. Use batched parallel downloads (4 at a time) with proper error handling.
+
+## Phase 3: Component Specification & Dispatch
+
+This is the core loop. For each section in your page topology (top to bottom), you do THREE things: **extract**, **write the spec file**, then **dispatch builders**.
+
+### Step 1: Extract
+
+For each section, use browser MCP to extract everything:
+
+1. **Screenshot** the section in isolation (scroll to it, screenshot the viewport). Save to `docs/design-references/`.
+
+2. **Extract CSS** for every element in the section. Use the extraction script below — don't hand-measure individual properties. Run it once per component container and capture the full output:
+
+```javascript
+// Per-component extraction — run via browser MCP
+// Replace SELECTOR with the actual CSS selector for the component
+(function(selector) {
+  const el = document.querySelector(selector);
+  if (!el) return JSON.stringify({ error: 'Element not found: ' + selector });
+  const props = [
+    'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
+    'textTransform','textDecoration','backgroundColor','background',
+    'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
+    'margin','marginTop','marginRight','marginBottom','marginLeft',
+    'width','height','maxWidth','minWidth','maxHeight','minHeight',
+    'display','flexDirection','justifyContent','alignItems','gap',
+    'gridTemplateColumns','gridTemplateRows',
+    'borderRadius','border','borderTop','borderBottom','borderLeft','borderRight',
+    'boxShadow','overflow','overflowX','overflowY',
+    'position','top','right','bottom','left','zIndex',
+    'opacity','transform','transition','cursor',
+    'objectFit','objectPosition','mixBlendMode','filter','backdropFilter',
+    'whiteSpace','textOverflow','WebkitLineClamp'
+  ];
+  function extractStyles(element) {
+    const cs = getComputedStyle(element);
+    const styles = {};
+    props.forEach(p => { const v = cs[p]; if (v && v !== 'none' && v !== 'normal' && v !== 'auto' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v; });
+    return styles;
+  }
+  function walk(element, depth) {
+    if (depth > 4) return null;
+    const children = [...element.children];
+    return {
+      tag: element.tagName.toLowerCase(),
+      classes: element.className?.toString().split(' ').slice(0, 5).join(' '),
+      text: element.childNodes.length === 1 && element.childNodes[0].nodeType === 3 ? element.textContent.trim().slice(0, 200) : null,
+      styles: extractStyles(element),
+      images: element.tagName === 'IMG' ? { src: element.src, alt: element.alt, naturalWidth: element.naturalWidth, naturalHeight: element.naturalHeight } : null,
+      childCount: children.length,
+      children: children.slice(0, 20).map(c => walk(c, depth + 1)).filter(Boolean)
+    };
+  }
+  return JSON.stringify(walk(el, 0), null, 2);
+})('SELECTOR');
+```
+
+3. **Extract multi-state styles** — for any element with multiple states (scroll-triggered, hover, active tab), capture BOTH states:
+
+```javascript
+// State A: capture styles at current state (e.g., scroll position 0)
+// Then trigger the state change (scroll, click, hover via browser MCP)
+// State B: re-run the extraction script on the same element
+// The diff between A and B IS the behavior specification
+```
+
+Record the diff explicitly: "Property X changes from VALUE_A to VALUE_B, triggered by TRIGGER, with transition: TRANSITION_CSS."
+
+4. **Extract real content** — all text, alt attributes, aria labels, placeholder text. Use `element.textContent` for each text node. For tabbed/stateful content, **click each tab and extract content per state**.
+
+5. **Identify assets** this section uses — which downloaded images/videos from `public/`, which icon components from `icons.tsx`. Check for **layered images** (multiple `<img>` or background-images stacked in the same container).
+
+6. **Assess complexity** — how many distinct sub-components does this section contain? A distinct sub-component is an element with its own unique styling, structure, and behavior (e.g., a card, a nav item, a search panel).
+
+### Step 2: Write the Component Spec File
+
+For each section (or sub-component, if you're breaking it up), create a spec file in `docs/research/components/`. This is NOT optional — every builder must have a corresponding spec file.
+
+**File path:** `docs/research/components/<component-name>.spec.md`
+
+**Template:**
+
+```markdown
+# <ComponentName> Specification
+
+## Overview
+- **Target file:** `src/components/<ComponentName>.tsx`
+- **Screenshot:** `docs/design-references/<screenshot-name>.png`
+- **Interaction model:** <static | click-driven | scroll-driven | time-driven>
+
+## DOM Structure
+<Describe the element hierarchy — what contains what>
+
+## Computed Styles (exact values from getComputedStyle)
+
+### Container
+- display: ...
+- padding: ...
+- maxWidth: ...
+- (every relevant property with exact values)
+
+### <Child element 1>
+- fontSize: ...
+- color: ...
+- (every relevant property)
+
+### <Child element N>
+...
+
+## States & Behaviors
+
+### <Behavior name, e.g., "Scroll-triggered floating mode">
+- **Trigger:** <exact mechanism — scroll position 50px, IntersectionObserver rootMargin "-30% 0px", click on .tab-button, hover>
+- **State A (before):** maxWidth: 100vw, boxShadow: none, borderRadius: 0
+- **State B (after):** maxWidth: 1200px, boxShadow: 0 4px 20px rgba(0,0,0,0.1), borderRadius: 16px
+- **Transition:** transition: all 0.3s ease
+- **Implementation approach:** <CSS transition + scroll listener | IntersectionObserver | CSS animation-timeline | etc.>
+
+### Hover states
+- **<Element>:** <property>: <before> → <after>, transition: <value>
+
+## Per-State Content (if applicable)
+
+### State: "Featured"
+- Title: "..."
+- Subtitle: "..."
+- Cards: [{ title, description, image, link }, ...]
+
+### State: "Productivity"
+- Title: "..."
+- Cards: [...]
+
+## Assets
+- Background image: `public/images/<file>.webp`
+- Overlay image: `public/images/<file>.png`
+- Icons used: <ArrowIcon>, <SearchIcon> from icons.tsx
+
+## Text Content (verbatim)
+<All text content, copy-pasted from the live site>
+
+## Responsive Behavior
+- **Desktop (1440px):** <layout description>
+- **Tablet (768px):** <what changes — e.g., "maintains 2-column, gap reduces to 16px">
+- **Mobile (390px):** <what changes — e.g., "stacks to single column, images full-width">
+- **Breakpoint:** layout switches at ~<N>px
+```
+
+Fill every section. If a section doesn't apply (e.g., no states for a static footer), write "N/A" — but think twice before marking States & Behaviors as N/A. Even a footer might have hover states on links.
+
+### Step 3: Dispatch Builders
+
+Based on complexity, dispatch builder agent(s) in worktree(s):
+
+**Simple section** (1-2 sub-components): One builder agent gets the entire section.
+
+**Complex section** (3+ distinct sub-components): Break it up. One agent per sub-component, plus one agent for the section wrapper that imports them. Sub-component builders go first since the wrapper depends on them.
+
+**What every builder agent receives:**
+- The full contents of its component spec file (inline in the prompt — don't say "go read the spec file")
+- Path to the section screenshot in `docs/design-references/`
+- Which shared components to import (`icons.tsx`, `cn()`, shadcn primitives)
+- The target file path (e.g., `src/components/HeroSection.tsx`)
+- Instruction to verify with `npx tsc --noEmit` before finishing
+- For responsive behavior: the specific breakpoint values and what changes
+
+**Don't wait.** As soon as you've dispatched the builder(s) for one section, move to extracting the next section. Builders work in parallel in their worktrees while you continue extraction.
+
+### Step 4: Merge
+
+As builder agents complete their work:
+- Merge their worktree branches into main
+- You have full context on what each agent built, so resolve any conflicts intelligently
+- After each merge, verify the build still passes: `npm run build`
+- If a merge introduces type errors, fix them immediately
+
+The extract → spec → dispatch → merge cycle continues until all sections are built.
+
+## Phase 4: Page Assembly
+
+After all sections are built and merged, wire everything together in `src/app/page.tsx`:
+
+- Import all section components
+- Implement the page-level layout from your topology doc (scroll containers, column structures, sticky positioning, z-index layering)
+- Connect real content to component props
+- Implement page-level behaviors: scroll snap, scroll-driven animations, dark-to-light transitions, intersection observers, smooth scroll (Lenis etc.)
+- Verify: `npm run build` passes clean
+
+## Phase 5: Visual QA Diff
+
+After assembly, do NOT declare the clone complete. Take side-by-side comparison screenshots:
+
+1. Open the original site and your clone side-by-side (or take screenshots at the same viewport widths)
+2. Compare section by section, top to bottom, at desktop (1440px)
+3. Compare again at mobile (390px)
+4. For each discrepancy found:
+   - Check the component spec file — was the value extracted correctly?
+   - If the spec was wrong: re-extract from browser MCP, update the spec, fix the component
+   - If the spec was right but the builder got it wrong: fix the component to match the spec
+5. Test all interactive behaviors: scroll through the page, click every button/tab, hover over interactive elements
+6. Verify smooth scroll feels right, header transitions work, tab switching works, animations play
+
+Only after this visual QA pass is the clone complete.
+
+## Pre-Dispatch Checklist
+
+Before dispatching ANY builder agent, verify you can check every box. If you can't, go back and extract more.
+
+- [ ] Spec file written to `docs/research/components/<name>.spec.md` with ALL sections filled
+- [ ] Every CSS value in the spec is from `getComputedStyle()`, not estimated
+- [ ] Interaction model is identified and documented (static / click / scroll / time)
+- [ ] For stateful components: every state's content and styles are captured
+- [ ] For scroll-driven components: trigger threshold, before/after styles, and transition are recorded
+- [ ] For hover states: before/after values and transition timing are recorded
+- [ ] All images in the section are identified (including overlays and layered compositions)
+- [ ] Responsive behavior is documented for at least desktop and mobile
+- [ ] Text content is verbatim from the site, not paraphrased
+- [ ] The builder prompt is under ~150 lines of spec; if over, the section needs to be split
+
+## What NOT to Do
+
+These are lessons from previous failed clones — each one cost hours of rework:
+
+- **Don't build click-based tabs when the original is scroll-driven (or vice versa).** Determine the interaction model FIRST by scrolling before clicking. This is the #1 most expensive mistake — it requires a complete rewrite, not a CSS fix.
+- **Don't extract only the default state.** If there are tabs showing "Featured" on load, click Productivity, Creative, Lifestyle and extract each one's cards/content. If the header changes on scroll, capture styles at position 0 AND position 100+.
+- **Don't miss overlay/layered images.** A background watercolor + foreground UI mockup = 2 images. Check every container's DOM tree for multiple `<img>` elements and positioned overlays.
+- **Don't build mockup components for content that's actually videos/animations.** Check if a section uses `<video>`, Lottie, or canvas before building elaborate HTML mockups of what the video shows.
+- **Don't approximate CSS classes.** "It looks like `text-lg`" is wrong if the computed value is `18px` and `text-lg` is `18px/28px` but the actual line-height is `24px`. Extract exact values.
+- **Don't build everything in one monolithic commit.** The whole point of this pipeline is incremental progress with verified builds at each step.
+- **Don't reference docs from builder prompts.** Each builder gets the CSS spec inline in its prompt — never "see DESIGN_TOKENS.md for colors." The builder should have zero need to read external docs.
+- **Don't skip asset extraction.** Without real images, videos, and fonts, the clone will always look fake regardless of how perfect the CSS is.
+- **Don't give a builder agent too much scope.** If you're writing a builder prompt and it's getting long because the section is complex, that's a signal to break it into smaller tasks.
+- **Don't bundle unrelated sections into one agent.** A CTA section and a footer are different components with different designs — don't hand them both to one agent and hope for the best.
+- **Don't skip responsive extraction.** If you only inspect at desktop width, the clone will break at tablet and mobile. Test at 1440, 768, and 390 during extraction.
+- **Don't forget smooth scroll libraries.** Check for Lenis (`.lenis` class), Locomotive Scroll, or similar. Default browser scrolling feels noticeably different and the user will spot it immediately.
+- **Don't dispatch builders without a spec file.** The spec file forces exhaustive extraction and creates an auditable artifact. Skipping it means the builder gets whatever you can fit in a prompt from memory.
+
+## Completion
+
+When done, report:
+- Total sections built
+- Total components created
+- Total spec files written (should match components)
+- Total assets downloaded (images, videos, SVGs, fonts)
+- Build status (`npm run build` result)
+- Visual QA results (any remaining discrepancies)
+- Any known gaps or limitations
+
+---
+
+## Source
+
+Adapted from `JCodesMore/ai-website-cloner-template/.codex/skills/clone-website`.
diff --git a/skills/.experimental/gpt-researcher/LICENSE.txt b/skills/.experimental/gpt-researcher/LICENSE.txt
new file mode 100644
index 00000000..261eeb9e
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/LICENSE.txt
@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/skills/.experimental/gpt-researcher/SKILL.md b/skills/.experimental/gpt-researcher/SKILL.md
new file mode 100644
index 00000000..1bbfb58f
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/SKILL.md
@@ -0,0 +1,239 @@
+---
+name: gpt-researcher
+description: Repository-specific development skill for GPT Researcher. Use this when understanding, extending, debugging, or integrating with the GPT Researcher codebase itself, including architecture, APIs, retrievers, MCP integrations, and report-generation pipelines. Do not use this as a generic research or summarization skill.
+---
+
+# GPT Researcher Development Skill
+
+GPT Researcher is an LLM-based autonomous agent using a planner-executor-publisher pattern with parallelized agent work for speed and reliability.
+
+## Scope
+
+- Input: a GPT Researcher repository, feature request, bug report, integration task, or architecture question
+- Output: code changes, architecture guidance, integration guidance, debugging steps, or repository-specific implementation plans
+- Use when: the task is about building on top of GPT Researcher or changing how GPT Researcher works
+- Do not use when: the task is generic web research, literature review, or summarizing documents the user already has
+
+## Quick Start
+
+### Basic Python Usage
+
+```python
+from gpt_researcher import GPTResearcher
+import asyncio
+
+async def main():
+    researcher = GPTResearcher(
+        query="What are the latest AI developments?",
+        report_type="research_report",  # or detailed_report, deep, outline_report
+        report_source="web",            # or local, hybrid
+    )
+    await researcher.conduct_research()
+    report = await researcher.write_report()
+    print(report)
+
+asyncio.run(main())
+```
+
+### Run Servers
+
+```bash
+# Backend
+python -m uvicorn backend.server.server:app --reload --port 8000
+
+# Frontend
+cd frontend/nextjs && npm install && npm run dev
+```
+
+---
+
+## Key File Locations
+
+| Need | Primary File | Key Classes |
+|------|--------------|-------------|
+| Main orchestrator | `gpt_researcher/agent.py` | `GPTResearcher` |
+| Research logic | `gpt_researcher/skills/researcher.py` | `ResearchConductor` |
+| Report writing | `gpt_researcher/skills/writer.py` | `ReportGenerator` |
+| All prompts | `gpt_researcher/prompts.py` | `PromptFamily` |
+| Configuration | `gpt_researcher/config/config.py` | `Config` |
+| Config defaults | `gpt_researcher/config/variables/default.py` | `DEFAULT_CONFIG` |
+| API server | `backend/server/app.py` | FastAPI `app` |
+| Search engines | `gpt_researcher/retrievers/` | Various retrievers |
+
+---
+
+## Architecture Overview
+
+```
+User Query → GPTResearcher.__init__()
+                │
+                ▼
+         choose_agent() → (agent_type, role_prompt)
+                │
+                ▼
+         ResearchConductor.conduct_research()
+           ├── plan_research() → sub_queries
+           ├── For each sub_query:
+           │     └── _process_sub_query() → context
+           └── Aggregate contexts
+                │
+                ▼
+         [Optional] ImageGenerator.plan_and_generate_images()
+                │
+                ▼
+         ReportGenerator.write_report() → Markdown report
+```
+
+**For detailed architecture diagrams**: See [references/architecture.md](references/architecture.md)
+
+---
+
+## Core Patterns
+
+### Adding a New Feature (8-Step Pattern)
+
+1. **Config** → Add to `gpt_researcher/config/variables/default.py`
+2. **Provider** → Create in `gpt_researcher/llm_provider/my_feature/`
+3. **Skill** → Create in `gpt_researcher/skills/my_feature.py`
+4. **Agent** → Integrate in `gpt_researcher/agent.py`
+5. **Prompts** → Update `gpt_researcher/prompts.py`
+6. **WebSocket** → Events via `stream_output()`
+7. **Frontend** → Handle events in `useWebSocket.ts`
+8. **Docs** → Create `docs/docs/gpt-researcher/gptr/my_feature.md`
+
+**For complete feature addition guide with Image Generation case study**: See [references/adding-features.md](references/adding-features.md)
+
+### Adding a New Retriever
+
+```python
+# 1. Create: gpt_researcher/retrievers/my_retriever/my_retriever.py
+class MyRetriever:
+    def __init__(self, query: str, headers: dict = None):
+        self.query = query
+    
+    async def search(self, max_results: int = 10) -> list[dict]:
+        # Return: [{"title": str, "href": str, "body": str}]
+        pass
+
+# 2. Register in gpt_researcher/actions/retriever.py
+case "my_retriever":
+    from gpt_researcher.retrievers.my_retriever import MyRetriever
+    return MyRetriever
+
+# 3. Export in gpt_researcher/retrievers/__init__.py
+```
+
+**For complete retriever documentation**: See [references/retrievers.md](references/retrievers.md)
+
+---
+
+## Configuration
+
+Config keys are **lowercased** when accessed:
+
+```python
+# In default.py: "SMART_LLM": "gpt-4o"
+# Access as: self.cfg.smart_llm  # lowercase!
+```
+
+Priority: Environment Variables → JSON Config File → Default Values
+
+**For complete configuration reference**: See [references/config-reference.md](references/config-reference.md)
+
+---
+
+## Common Integration Points
+
+### WebSocket Streaming
+
+```python
+class WebSocketHandler:
+    async def send_json(self, data):
+        print(f"[{data['type']}] {data.get('output', '')}")
+
+researcher = GPTResearcher(query="...", websocket=WebSocketHandler())
+```
+
+### MCP Data Sources
+
+```python
+researcher = GPTResearcher(
+    query="Open source AI projects",
+    mcp_configs=[{
+        "name": "github",
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-github"],
+        "env": {"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")}
+    }],
+    mcp_strategy="deep",  # or "fast", "disabled"
+)
+```
+
+**For MCP integration details**: See [references/mcp.md](references/mcp.md)
+
+### Deep Research Mode
+
+```python
+researcher = GPTResearcher(
+    query="Comprehensive analysis of quantum computing",
+    report_type="deep",  # Triggers recursive tree-like exploration
+)
+```
+
+**For deep research configuration**: See [references/deep-research.md](references/deep-research.md)
+
+---
+
+## Error Handling
+
+Always use graceful degradation in skills:
+
+```python
+async def execute(self, ...):
+    if not self.is_enabled():
+        return []  # Don't crash
+    
+    try:
+        result = await self.provider.execute(...)
+        return result
+    except Exception as e:
+        await stream_output("logs", "error", f"⚠️ {e}", self.websocket)
+        return []  # Graceful degradation
+```
+
+---
+
+## Critical Gotchas
+
+| ❌ Mistake | ✅ Correct |
+|-----------|-----------|
+| `config.MY_VAR` | `config.my_var` (lowercased) |
+| Editing pip-installed package | `pip install -e .` |
+| Forgetting async/await | All research methods are async |
+| `websocket.send_json()` on None | Check `if websocket:` first |
+| Not registering retriever | Add to `retriever.py` match statement |
+
+---
+
+## Reference Documentation
+
+| Topic | File |
+|-------|------|
+| System architecture & diagrams | [references/architecture.md](references/architecture.md) |
+| Core components & signatures | [references/components.md](references/components.md) |
+| Research flow & data flow | [references/flows.md](references/flows.md) |
+| Prompt system | [references/prompts.md](references/prompts.md) |
+| Retriever system | [references/retrievers.md](references/retrievers.md) |
+| MCP integration | [references/mcp.md](references/mcp.md) |
+| Deep research mode | [references/deep-research.md](references/deep-research.md) |
+| Multi-agent system | [references/multi-agents.md](references/multi-agents.md) |
+| Adding features guide | [references/adding-features.md](references/adding-features.md) |
+| Advanced patterns | [references/advanced-patterns.md](references/advanced-patterns.md) |
+| REST & WebSocket API | [references/api-reference.md](references/api-reference.md) |
+| Configuration variables | [references/config-reference.md](references/config-reference.md) |
+
+---
+
+## Source
+
+Adapted from `assafelovic/gpt-researcher/.claude`.
diff --git a/skills/.experimental/gpt-researcher/references/adding-features.md b/skills/.experimental/gpt-researcher/references/adding-features.md
new file mode 100644
index 00000000..fc5a5299
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/references/adding-features.md
@@ -0,0 +1,361 @@
+# Adding Features Guide
+
+## Table of Contents
+- [The 8-Step Pattern](#the-8-step-pattern)
+- [Image Generation Case Study](#image-generation-case-study)
+- [Testing New Features](#testing-new-features)
+
+---
+
+## The 8-Step Pattern
+
+```
+┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐
+│1.CONFIG│ →  │2.PROVIDER│ → │3.SKILL │ →  │4.AGENT │
+└────────┘    └────────┘    └────────┘    └────────┘
+     ↓             ↓             ↓             ↓
+┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐
+│5.PROMPTS│ → │6.WEBSOCKET│→ │7.FRONTEND│→ │8.DOCS  │
+└────────┘    └────────┘    └────────┘    └────────┘
+```
+
+### Step 1: Add Configuration
+
+**File:** `gpt_researcher/config/variables/default.py`
+
+```python
+DEFAULT_CONFIG: BaseConfig = {
+    "MY_FEATURE_ENABLED": False,
+    "MY_FEATURE_MODEL": "model-name",
+    "MY_FEATURE_MAX_ITEMS": 3,
+}
+```
+
+**File:** `gpt_researcher/config/variables/base.py`
+
+```python
+class BaseConfig(TypedDict):
+    "MY_FEATURE_ENABLED": bool
+    "MY_FEATURE_MODEL": Union[str, None]
+    "MY_FEATURE_MAX_ITEMS": int
+```
+
+### Step 2: Create Provider
+
+**File:** `gpt_researcher/llm_provider/my_feature/my_provider.py`
+
+```python
+class MyFeatureProvider:
+    def __init__(self, api_key: str = None, model: str = None):
+        self.api_key = api_key or os.getenv("MY_API_KEY")
+        self.model = model
+    
+    def is_enabled(self) -> bool:
+        return bool(self.api_key and self.model)
+    
+    async def execute(self, input_data: str) -> Dict[str, Any]:
+        # API implementation
+        pass
+```
+
+Export in `gpt_researcher/llm_provider/__init__.py`.
+
+### Step 3: Create Skill
+
+**File:** `gpt_researcher/skills/my_feature.py`
+
+```python
+class MyFeatureSkill:
+    def __init__(self, researcher):
+        self.researcher = researcher
+        self.config = researcher.cfg
+        self.provider = MyFeatureProvider(...)
+    
+    def is_enabled(self) -> bool:
+        return getattr(self.config, 'my_feature_enabled', False) and self.provider.is_enabled()
+    
+    async def execute(self, context: str, query: str) -> List[Dict]:
+        if not self.is_enabled():
+            return []
+        
+        await stream_output("logs", "my_feature_start", "🚀 Starting...", self.researcher.websocket)
+        results = await self.provider.execute(context)
+        await stream_output("logs", "my_feature_complete", "✅ Done", self.researcher.websocket)
+        
+        return results
+```
+
+Export in `gpt_researcher/skills/__init__.py`.
+
+### Step 4: Integrate into Agent
+
+**File:** `gpt_researcher/agent.py`
+
+```python
+def __init__(self, ...):
+    if self.cfg.my_feature_enabled:
+        from gpt_researcher.skills import MyFeatureSkill
+        self.my_feature = MyFeatureSkill(self)
+    else:
+        self.my_feature = None
+    self.my_feature_results = []
+
+async def conduct_research(self, ...):
+    # ... existing ...
+    if self.my_feature and self.my_feature.is_enabled():
+        self.my_feature_results = await self.my_feature.execute(self.context, self.query)
+```
+
+### Step 5: Update Prompts
+
+**File:** `gpt_researcher/prompts.py`
+
+```python
+@staticmethod
+def generate_my_feature_prompt(context: str, query: str) -> str:
+    return f"""..."""
+```
+
+### Step 6: WebSocket Events
+
+Already handled via `stream_output()` in skill.
+
+### Step 7: Frontend (if needed)
+
+**File:** `frontend/nextjs/hooks/useWebSocket.ts`
+
+```typescript
+if (data.content === 'my_feature_start') {
+    setStatus('processing');
+}
+```
+
+### Step 8: Documentation
+
+Create `docs/docs/gpt-researcher/gptr/my_feature.md`.
+
+---
+
+## Image Generation Case Study
+
+This section shows the **actual implementation** of the Image Generation feature as a reference.
+
+### 1. Configuration Added
+
+**File:** `gpt_researcher/config/variables/default.py`
+
+```python
+DEFAULT_CONFIG: BaseConfig = {
+    # ... existing ...
+    "IMAGE_GENERATION_MODEL": "models/gemini-2.5-flash-image",
+    "IMAGE_GENERATION_MAX_IMAGES": 3,
+    "IMAGE_GENERATION_ENABLED": False,
+    "IMAGE_GENERATION_STYLE": "dark",  # dark, light, auto
+}
+```
+
+### 2. Provider Created
+
+**File:** `gpt_researcher/llm_provider/image/image_generator.py`
+
+```python
+class ImageGeneratorProvider:
+    def __init__(self, api_key: str = None, model: str = None):
+        self.api_key = api_key or os.getenv("GOOGLE_API_KEY")
+        self.model = model or "models/gemini-2.5-flash-image"
+        self._client = None
+    
+    def is_enabled(self) -> bool:
+        return bool(self.api_key and self.model)
+    
+    def _build_enhanced_prompt(self, prompt: str, context: str = "", style: str = "dark") -> str:
+        """Add styling instructions to prompt."""
+        if style == "dark":
+            style_instructions = """
+            Style: Dark mode professional infographic
+            - Background: Dark (#0d1117)
+            - Accents: Teal/cyan (#14b8a6)
+            - Clean, modern, minimalist
+            """
+        # ... handle light, auto
+        return f"{style_instructions}\n\nCreate: {prompt}\n\nContext: {context}"
+    
+    async def generate_image(
+        self,
+        prompt: str,
+        context: str = "",
+        research_id: str = "",
+        style: str = "dark",
+    ) -> List[Dict[str, Any]]:
+        """Generate image using Gemini."""
+        full_prompt = self._build_enhanced_prompt(prompt, context, style)
+        
+        # Call Gemini API
+        response = await self._generate_with_gemini(full_prompt, output_path, ...)
+        
+        return [{"url": f"/outputs/images/{research_id}/img_{hash}.png", ...}]
+```
+
+### 3. Skill Created
+
+**File:** `gpt_researcher/skills/image_generator.py`
+
+```python
+class ImageGenerator:
+    def __init__(self, researcher):
+        self.researcher = researcher
+        self.config = researcher.cfg
+        self.image_provider = ImageGeneratorProvider(
+            api_key=os.getenv("GOOGLE_API_KEY"),
+            model=getattr(self.config, 'image_generation_model', None),
+        )
+        self.max_images = getattr(self.config, 'image_generation_max_images', 3)
+        self.style = getattr(self.config, 'image_generation_style', 'dark')
+    
+    def is_enabled(self) -> bool:
+        enabled = getattr(self.config, 'image_generation_enabled', False)
+        return enabled and self.image_provider.is_enabled()
+    
+    async def plan_and_generate_images(
+        self,
+        research_context: str,
+        research_query: str,
+        research_id: str,
+        websocket: Any,
+    ) -> List[Dict[str, Any]]:
+        """
+        1. Use LLM to identify visual concepts from context
+        2. Generate images in parallel
+        3. Return list of image metadata
+        """
+        # Stream progress
+        await stream_output("logs", "image_planning", "🎨 Planning images...", websocket)
+        
+        # LLM identifies concepts
+        concepts = await self._plan_image_concepts(research_context, research_query)
+        
+        # Generate images in parallel
+        generated_images = []
+        for i, concept in enumerate(concepts[:self.max_images]):
+            await stream_output("logs", "image_generating", 
+                f"🖼️ Generating image {i+1}/{len(concepts)}...", websocket)
+            
+            images = await self.image_provider.generate_image(
+                prompt=concept["prompt"],
+                context=concept.get("context", ""),
+                research_id=research_id,
+                style=self.style,
+            )
+            generated_images.extend(images)
+        
+        await stream_output("logs", "images_ready", 
+            f"✅ Generated {len(generated_images)} images", websocket)
+        
+        return generated_images
+```
+
+### 4. Agent Integration
+
+**File:** `gpt_researcher/agent.py`
+
+```python
+class GPTResearcher:
+    def __init__(self, ...):
+        # ... existing init ...
+        
+        # Initialize image generator if enabled
+        if self.cfg.image_generation_enabled:
+            from gpt_researcher.skills import ImageGenerator
+            self.image_generator = ImageGenerator(self)
+        else:
+            self.image_generator = None
+        
+        self.available_images: List[Dict[str, Any]] = []
+        self.research_id = self._generate_research_id(query)
+    
+    async def conduct_research(self, on_progress=None):
+        # ... existing research ...
+        
+        self.context = await self.research_conductor.conduct_research()
+        
+        # Pre-generate images after research, before report writing
+        if self.cfg.image_generation_enabled and self.image_generator and self.image_generator.is_enabled():
+            self.available_images = await self.image_generator.plan_and_generate_images(
+                research_context=self.context,
+                research_query=self.query,
+                research_id=self.research_id,
+                websocket=self.websocket,
+            )
+        
+        return self.context
+    
+    async def write_report(self, ...):
+        report = await self.report_generator.write_report(
+            # ... existing params ...
+            available_images=self.available_images,  # Pass to report writer
+        )
+        return report
+```
+
+### 5. Prompt Updated
+
+**File:** `gpt_researcher/prompts.py`
+
+```python
+@staticmethod
+def generate_report_prompt(..., available_images: List[Dict[str, Any]] = []):
+    image_instruction = ""
+    if available_images:
+        image_list = "\n".join([
+            f"- Title: {img.get('title', 'Untitled')}\n  URL: {img['url']}"
+            for img in available_images
+        ])
+        image_instruction = f"""
+AVAILABLE IMAGES - Embed where relevant using ![Title](URL):
+{image_list}
+"""
+    
+    return f"""...(existing prompt)...
+{image_instruction}
+"""
+```
+
+---
+
+## Testing New Features
+
+```python
+# tests/test_my_feature.py
+import pytest
+from gpt_researcher import GPTResearcher
+
+@pytest.mark.asyncio
+async def test_my_feature_disabled():
+    """Test that feature is skipped when disabled."""
+    researcher = GPTResearcher(query="test")
+    # MY_FEATURE_ENABLED defaults to False
+    assert researcher.my_feature is None
+
+@pytest.mark.asyncio
+async def test_my_feature_enabled(monkeypatch):
+    """Test feature execution when enabled."""
+    monkeypatch.setenv("MY_FEATURE_ENABLED", "true")
+    monkeypatch.setenv("MY_API_KEY", "test-key")
+    
+    researcher = GPTResearcher(query="test")
+    assert researcher.my_feature is not None
+    assert researcher.my_feature.is_enabled()
+```
+
+### Running Tests
+
+```bash
+# All tests
+python -m pytest tests/
+
+# Specific test
+python -m pytest tests/test_my_feature.py -v
+
+# With coverage
+python -m pytest tests/ --cov=gpt_researcher
+```
diff --git a/skills/.experimental/gpt-researcher/references/advanced-patterns.md b/skills/.experimental/gpt-researcher/references/advanced-patterns.md
new file mode 100644
index 00000000..5c71d7e7
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/references/advanced-patterns.md
@@ -0,0 +1,140 @@
+# Advanced Patterns Reference
+
+## Table of Contents
+- [Custom Callbacks](#custom-callbacks)
+- [Custom WebSocket Handler](#custom-websocket-handler)
+- [LangChain Integration](#langchain-integration)
+- [Search Restrictions](#search-restrictions)
+- [Error Handling Patterns](#error-handling-patterns)
+
+---
+
+## Custom Callbacks
+
+```python
+def cost_callback(cost: float):
+    print(f"API call cost: ${cost}")
+
+researcher = GPTResearcher(query="...")
+researcher.add_costs = cost_callback  # Override cost tracking
+```
+
+---
+
+## Custom WebSocket Handler
+
+```python
+class CustomWebSocket:
+    def __init__(self):
+        self.messages = []
+    
+    async def send_json(self, data):
+        self.messages.append(data)
+        if data['type'] == 'logs':
+            print(f"Progress: {data['output']}")
+
+researcher = GPTResearcher(query="...", websocket=CustomWebSocket())
+```
+
+---
+
+## LangChain Integration
+
+### Using with LangChain Documents
+
+```python
+from langchain.document_loaders import DirectoryLoader
+
+loader = DirectoryLoader('./docs', glob="**/*.md")
+documents = loader.load()
+
+researcher = GPTResearcher(
+    query="Summarize the documentation",
+    report_source="langchain_documents",
+    documents=documents,
+)
+```
+
+### Using with Vector Store
+
+```python
+from langchain.vectorstores import Chroma
+
+vectorstore = Chroma.from_documents(documents, embeddings)
+
+researcher = GPTResearcher(
+    query="Find relevant information",
+    report_source="langchain_vectorstore",
+    vector_store=vectorstore,
+    vector_store_filter={"source": "docs"},
+)
+```
+
+---
+
+## Search Restrictions
+
+### Restricting Search Domains
+
+```python
+researcher = GPTResearcher(
+    query="Company news",
+    query_domains=["reuters.com", "bloomberg.com", "wsj.com"],
+)
+```
+
+### Using Specific Source URLs
+
+```python
+researcher = GPTResearcher(
+    query="Analyze these articles",
+    source_urls=[
+        "https://example.com/article1",
+        "https://example.com/article2",
+    ],
+    complement_source_urls=True,  # Also do web search
+)
+```
+
+---
+
+## Error Handling Patterns
+
+### Graceful Degradation
+
+```python
+# In skills, always check is_enabled()
+async def execute(self, ...):
+    if not self.is_enabled():
+        logger.warning("Feature not enabled, skipping")
+        return []  # Return empty, don't crash
+    
+    try:
+        result = await self.provider.execute(...)
+        return result
+    except Exception as e:
+        logger.error(f"Feature error: {e}")
+        await stream_output("logs", "feature_error", f"⚠️ Error: {e}", self.websocket)
+        return []  # Graceful degradation
+```
+
+### API Rate Limiting
+
+```python
+# Providers should handle rate limits
+async def execute(self, ...):
+    try:
+        return await self._call_api(...)
+    except RateLimitError as e:
+        logger.warning(f"Rate limited, waiting...")
+        await asyncio.sleep(60)
+        return await self._call_api(...)  # Retry
+```
+
+### WebSocket None Check
+
+```python
+# Always check websocket before sending
+if self.researcher.websocket:
+    await stream_output("logs", "event", "message", self.researcher.websocket)
+```
diff --git a/skills/.experimental/gpt-researcher/references/api-reference.md b/skills/.experimental/gpt-researcher/references/api-reference.md
new file mode 100644
index 00000000..d22be776
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/references/api-reference.md
@@ -0,0 +1,251 @@
+# API Reference
+
+## Table of Contents
+- [REST API](#rest-api)
+- [WebSocket API](#websocket-api)
+- [Python Client](#python-client)
+- [Output Files](#output-files)
+
+---
+
+## REST API
+
+Base URL: `http://localhost:8000`
+
+### Generate Report
+
+**POST `/report/`**
+
+```json
+{
+    "task": "What are the latest AI developments?",
+    "report_type": "research_report",
+    "report_source": "web",
+    "tone": "Objective",
+    "source_urls": [],
+    "query_domains": [],
+    "generate_in_background": false
+}
+```
+
+**Response:**
+
+```json
+{
+    "report": "# Research Report\n\n...",
+    "research_id": "task_1234567890_query",
+    "costs": 0.05,
+    "pdf_path": "outputs/task_123.pdf",
+    "docx_path": "outputs/task_123.docx"
+}
+```
+
+### Chat with Report
+
+**POST `/api/chat`**
+
+```json
+{
+    "report": "The full report text...",
+    "messages": [
+        {"role": "user", "content": "What are the key findings?"}
+    ]
+}
+```
+
+### Report Management
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/reports` | List all reports |
+| GET | `/api/reports/{id}` | Get single report |
+| POST | `/api/reports` | Create/update report |
+| PUT | `/api/reports/{id}` | Update report |
+| DELETE | `/api/reports/{id}` | Delete report |
+
+### File Operations
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/upload/` | Upload document |
+| DELETE | `/delete/{filename}` | Delete file |
+| GET | `/outputs/{filename}` | Get output file |
+
+### Configuration
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/getConfig` | Get current config |
+| POST | `/setConfig` | Update config |
+
+---
+
+## WebSocket API
+
+**Endpoint:** `ws://localhost:8000/ws`
+
+### Send Research Request
+
+```json
+{
+    "task": "Research query",
+    "report_type": "research_report",
+    "report_source": "web",
+    "tone": "Objective",
+    "source_urls": [],
+    "mcp_enabled": false,
+    "mcp_strategy": "fast",
+    "mcp_configs": []
+}
+```
+
+### Message Types (Server → Client)
+
+| Type | Content | Description |
+|------|---------|-------------|
+| `logs` | `starting_research` | Research initiated |
+| `logs` | `planning_research` | Generating sub-queries |
+| `logs` | `running_subquery_research` | Researching sub-query |
+| `logs` | `research_step_finalized` | Research complete |
+| `logs` | `agent_generated` | Agent role selected |
+| `logs` | `scraping_urls` | Scraping web pages |
+| `logs` | `mcp_optimization` | MCP processing |
+| `logs` | `image_planning` | Planning images |
+| `logs` | `images_ready` | Images generated |
+| `report` | - | Streaming report chunks |
+| `report_complete` | - | Final complete report |
+| `path` | `pdf`, `docx`, `md` | Output file paths |
+| `error` | - | Error messages |
+| `human_feedback` | `request` | Request user input |
+
+### Message Format
+
+```json
+{
+    "type": "logs",
+    "content": "starting_research",
+    "output": "🔍 Starting the research task...",
+    "metadata": null
+}
+```
+
+### Frontend Handler Example
+
+```typescript
+ws.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+    
+    switch (data.type) {
+        case 'logs':
+            setLogs(prev => [...prev, data]);
+            break;
+        case 'report':
+            setAnswer(prev => prev + data.output);
+            break;
+        case 'report_complete':
+            setAnswer(data.output);
+            break;
+        case 'path':
+            setPaths(prev => ({...prev, [data.content]: data.output}));
+            break;
+        case 'error':
+            setError(data.output);
+            break;
+    }
+};
+```
+
+---
+
+## Python Client
+
+### Basic Usage
+
+```python
+from gpt_researcher import GPTResearcher
+import asyncio
+
+async def main():
+    researcher = GPTResearcher(
+        query="What are the latest AI developments?",
+        report_type="research_report",
+    )
+    
+    await researcher.conduct_research()
+    report = await researcher.write_report()
+    
+    print(f"Report: {report}")
+    print(f"Costs: ${researcher.get_costs()}")
+
+asyncio.run(main())
+```
+
+### With MCP
+
+```python
+researcher = GPTResearcher(
+    query="Research topic",
+    mcp_configs=[{
+        "name": "github",
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-github"],
+        "env": {"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")}
+    }],
+    mcp_strategy="deep",
+)
+```
+
+### With WebSocket Streaming
+
+```python
+class MockWebSocket:
+    async def send_json(self, data):
+        print(f"[{data['type']}] {data.get('output', '')}")
+
+researcher = GPTResearcher(
+    query="Research topic",
+    websocket=MockWebSocket(),
+)
+```
+
+### GPTResearcher Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | str | required | Research question |
+| `report_type` | str | `research_report` | Type of report |
+| `report_source` | str | `web` | Data source |
+| `tone` | Tone | `Objective` | Writing tone |
+| `source_urls` | list | `[]` | Specific URLs to research |
+| `document_urls` | list | `[]` | Document URLs |
+| `query_domains` | list | `[]` | Restrict to domains |
+| `config_path` | str | None | Path to JSON config |
+| `websocket` | WebSocket | None | For streaming |
+| `mcp_configs` | list | `[]` | MCP server configs |
+| `mcp_strategy` | str | `fast` | MCP strategy |
+| `verbose` | bool | `True` | Verbose output |
+
+---
+
+## Output Files
+
+```
+outputs/
+├── task_{timestamp}_{query}.md
+├── task_{timestamp}_{query}.pdf
+├── task_{timestamp}_{query}.docx
+└── images/
+    └── {research_id}/
+        └── img_{hash}_{index}.png
+```
+
+---
+
+## Error Codes
+
+| Code | Description |
+|------|-------------|
+| 400 | Bad Request - Invalid parameters |
+| 404 | Not Found - Report not found |
+| 429 | Rate Limited - API quota exceeded |
+| 500 | Internal Server Error |
diff --git a/skills/.experimental/gpt-researcher/references/architecture.md b/skills/.experimental/gpt-researcher/references/architecture.md
new file mode 100644
index 00000000..98c59f5e
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/references/architecture.md
@@ -0,0 +1,115 @@
+# Architecture Reference
+
+## Table of Contents
+- [System Layers](#system-layers)
+- [Key File Locations](#key-file-locations)
+
+---
+
+## System Layers
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              USER REQUEST                                    │
+│              (query, report_type, report_source, tone, mcp_configs)         │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         BACKEND API LAYER                                    │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐          │
+│  │  FastAPI Server  │  │ WebSocket Manager│  │  Report Store    │          │
+│  │  backend/server/ │  │ Real-time events │  │  JSON persistence│          │
+│  │  app.py          │  │ websocket_mgr.py │  │  report_store.py │          │
+│  └──────────────────┘  └──────────────────┘  └──────────────────┘          │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    GPTResearcher (gpt_researcher/agent.py)                   │
+│                                                                              │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │                         SKILLS LAYER                                   │  │
+│  │  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐         │  │
+│  │  │ ResearchConductor│ │ ReportGenerator │ │ ContextManager  │         │  │
+│  │  │ Plan & gather   │ │ Write reports   │ │ Similarity search│         │  │
+│  │  │ researcher.py   │ │ writer.py       │ │ context_manager │         │  │
+│  │  └─────────────────┘ └─────────────────┘ └─────────────────┘         │  │
+│  │  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐         │  │
+│  │  │ BrowserManager  │ │ SourceCurator   │ │ ImageGenerator  │         │  │
+│  │  │ Web scraping    │ │ Rank sources    │ │ Gemini images   │         │  │
+│  │  │ browser.py      │ │ curator.py      │ │ image_generator │         │  │
+│  │  └─────────────────┘ └─────────────────┘ └─────────────────┘         │  │
+│  │  ┌─────────────────┐                                                  │  │
+│  │  │ DeepResearchSkill│                                                 │  │
+│  │  │ Recursive depth │                                                  │  │
+│  │  │ deep_research.py│                                                  │  │
+│  │  └─────────────────┘                                                  │  │
+│  └───────────────────────────────────────────────────────────────────────┘  │
+│                                                                              │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │                        ACTIONS LAYER                                   │  │
+│  │  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐         │  │
+│  │  │ report_generation│ │ query_processing│ │ web_scraping    │         │  │
+│  │  │ LLM report write│ │ Sub-query plan  │ │ URL scraping    │         │  │
+│  │  └─────────────────┘ └─────────────────┘ └─────────────────┘         │  │
+│  │  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐         │  │
+│  │  │ retriever.py    │ │ agent_creator   │ │ markdown_process│         │  │
+│  │  │ Get retrievers  │ │ Choose agent    │ │ Parse markdown  │         │  │
+│  │  └─────────────────┘ └─────────────────┘ └─────────────────┘         │  │
+│  └───────────────────────────────────────────────────────────────────────┘  │
+│                                                                              │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │                       PROVIDERS LAYER                                  │  │
+│  │  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐         │  │
+│  │  │ LLM Provider    │ │ Retrievers      │ │ Scrapers        │         │  │
+│  │  │ OpenAI,Anthropic│ │ Tavily,Google   │ │ BS4,Playwright  │         │  │
+│  │  │ Google,Groq...  │ │ Bing,MCP...     │ │ PDF,DOCX...     │         │  │
+│  │  │ llm_provider/   │ │ retrievers/     │ │ scraper/        │         │  │
+│  │  └─────────────────┘ └─────────────────┘ └─────────────────┘         │  │
+│  │  ┌─────────────────┐                                                  │  │
+│  │  │ ImageGenerator  │                                                  │  │
+│  │  │ Gemini/Imagen   │                                                  │  │
+│  │  │ llm_provider/   │                                                  │  │
+│  │  │ image/          │                                                  │  │
+│  │  └─────────────────┘                                                  │  │
+│  └───────────────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        CONFIGURATION LAYER                                   │
+│                     gpt_researcher/config/                                   │
+│                                                                              │
+│     Environment Variables  →  JSON Config File  →  Default Values            │
+│           (highest)              (medium)            (lowest)                │
+│                                                                              │
+│     config.py loads and merges all sources                                   │
+│     variables/default.py contains all defaults                               │
+│     variables/base.py defines TypedDict for type safety                      │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Key File Locations
+
+| Need | Primary File | Key Classes/Functions |
+|------|--------------|----------------------|
+| Main orchestrator | `gpt_researcher/agent.py` | `GPTResearcher` |
+| Research logic | `gpt_researcher/skills/researcher.py` | `ResearchConductor` |
+| Report writing | `gpt_researcher/skills/writer.py` | `ReportGenerator` |
+| Context/embeddings | `gpt_researcher/skills/context_manager.py` | `ContextManager` |
+| Source ranking | `gpt_researcher/skills/curator.py` | `SourceCurator` |
+| Deep research | `gpt_researcher/skills/deep_research.py` | `DeepResearchSkill` |
+| Image generation | `gpt_researcher/skills/image_generator.py` | `ImageGenerator` |
+| All prompts | `gpt_researcher/prompts.py` | `PromptFamily` |
+| Configuration | `gpt_researcher/config/config.py` | `Config` |
+| Config defaults | `gpt_researcher/config/variables/default.py` | `DEFAULT_CONFIG` |
+| Config types | `gpt_researcher/config/variables/base.py` | `BaseConfig` |
+| API server | `backend/server/app.py` | FastAPI `app` |
+| WebSocket mgmt | `backend/server/websocket_manager.py` | `WebSocketManager`, `run_agent` |
+| Report types | `backend/report_type/` | `BasicReport`, `DetailedReport` |
+| Search engines | `gpt_researcher/retrievers/` | `TavilySearch`, `GoogleSearch`, etc. |
+| Web scraping | `gpt_researcher/scraper/` | Various scrapers |
+| Enums | `gpt_researcher/utils/enum.py` | `ReportType`, `ReportSource`, `Tone` |
diff --git a/skills/.experimental/gpt-researcher/references/components.md b/skills/.experimental/gpt-researcher/references/components.md
new file mode 100644
index 00000000..06b831c5
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/references/components.md
@@ -0,0 +1,200 @@
+# Core Components & Method Signatures
+
+## Table of Contents
+- [GPTResearcher](#gptresearcher)
+- [ResearchConductor](#researchconductor)
+- [ReportGenerator](#reportgenerator)
+
+---
+
+## GPTResearcher
+
+**File:** `gpt_researcher/agent.py`
+
+The main orchestrator class. Full initialization signature:
+
+```python
+class GPTResearcher:
+    def __init__(
+        self,
+        query: str,                              # Research question (required)
+        report_type: str = "research_report",    # research_report, detailed_report, deep, outline_report, resource_report
+        report_format: str = "markdown",         # Output format
+        report_source: str = "web",              # web, local, hybrid, azure, langchain_documents, langchain_vectorstore
+        tone: Tone = Tone.Objective,             # Writing tone (see Tone enum)
+        source_urls: list[str] | None = None,    # Specific URLs to research
+        document_urls: list[str] | None = None,  # Document URLs to include
+        complement_source_urls: bool = False,    # Add web search to source_urls
+        query_domains: list[str] | None = None,  # Restrict search to domains
+        documents=None,                          # LangChain document objects
+        vector_store=None,                       # LangChain vector store
+        vector_store_filter=None,                # Filter for vector store
+        config_path=None,                        # Path to JSON config file
+        websocket=None,                          # WebSocket for streaming
+        agent=None,                              # Pre-defined agent type
+        role=None,                               # Pre-defined agent role
+        parent_query: str = "",                  # Parent query for subtopics
+        subtopics: list | None = None,           # Subtopics to research
+        visited_urls: set | None = None,         # Already visited URLs
+        verbose: bool = True,                    # Verbose logging
+        context=None,                            # Pre-loaded context
+        headers: dict | None = None,             # HTTP headers
+        max_subtopics: int = 5,                  # Max subtopics for detailed
+        log_handler=None,                        # Custom log handler
+        prompt_family: str | None = None,        # Custom prompt family
+        mcp_configs: list[dict] | None = None,   # MCP server configurations
+        mcp_max_iterations: int | None = None,   # Deprecated, use mcp_strategy
+        mcp_strategy: str | None = None,         # fast, deep, disabled
+        **kwargs
+    ):
+```
+
+### Key Methods
+
+```python
+async def conduct_research(self, on_progress=None) -> str:
+    """
+    Main research orchestration.
+    
+    1. Selects agent role via LLM (choose_agent)
+    2. Delegates to ResearchConductor
+    3. Optionally generates images if enabled
+    
+    Returns: Accumulated research context as string
+    """
+
+async def write_report(
+    self, 
+    existing_headers: list = [],           # Headers to avoid duplication
+    relevant_written_contents: list = [],  # Previous content for context
+    ext_context=None,                      # External context override
+    custom_prompt=""                       # Custom prompt override
+) -> str:
+    """
+    Generate final report from context.
+    
+    Returns: Markdown report string
+    """
+
+def get_costs(self) -> float:
+    """Returns total accumulated API costs."""
+
+def add_costs(self, cost: float) -> None:
+    """Add to running cost total (used as callback)."""
+```
+
+---
+
+## ResearchConductor
+
+**File:** `gpt_researcher/skills/researcher.py`
+
+Manages the research process:
+
+```python
+class ResearchConductor:
+    def __init__(self, researcher: GPTResearcher):
+        self.researcher = researcher
+        self.logger = logging.getLogger(__name__)
+
+    async def plan_research(self, query: str, query_domains=None) -> list:
+        """
+        Generate sub-queries from main query using LLM.
+        
+        1. Gets initial search results
+        2. Calls plan_research_outline() to generate sub-queries
+        
+        Returns: List of sub-query strings
+        """
+
+    async def conduct_research(self) -> str:
+        """
+        Main research execution based on report_source.
+        
+        Handles: web, local, hybrid, azure, langchain_documents, langchain_vectorstore
+        
+        For each source type:
+        1. Load/search data
+        2. Process sub-queries
+        3. Combine context
+        4. Optionally curate sources
+        
+        Returns: Combined research context string
+        """
+
+    async def _process_sub_query(
+        self, 
+        sub_query: str, 
+        scraped_data: list = [], 
+        query_domains: list = []
+    ) -> str:
+        """
+        Process a single sub-query.
+        
+        1. Get MCP context (if configured, based on strategy)
+        2. Scrape URLs from search results
+        3. Get similar content via embeddings
+        4. Combine MCP + web context
+        
+        Returns: Combined context for this sub-query
+        """
+
+    async def _get_context_by_web_search(
+        self, 
+        query: str, 
+        scraped_data: list = [], 
+        query_domains: list = []
+    ) -> str:
+        """Web-based research with sub-query planning."""
+
+    async def _scrape_data_by_urls(
+        self, 
+        sub_query: str, 
+        query_domains: list = []
+    ) -> list:
+        """Search and scrape URLs for a sub-query."""
+```
+
+---
+
+## ReportGenerator
+
+**File:** `gpt_researcher/skills/writer.py`
+
+```python
+class ReportGenerator:
+    def __init__(self, researcher: GPTResearcher):
+        self.researcher = researcher
+        self.research_params = {
+            "query": researcher.query,
+            "agent_role_prompt": researcher.cfg.agent_role or researcher.role,
+            "report_type": researcher.report_type,
+            "report_source": researcher.report_source,
+            "tone": researcher.tone,
+            "websocket": researcher.websocket,
+            "cfg": researcher.cfg,
+            "headers": researcher.headers,
+        }
+
+    async def write_report(
+        self,
+        existing_headers: list = [],
+        relevant_written_contents: list = [],
+        ext_context=None,
+        custom_prompt="",
+        available_images: list = [],  # Pre-generated images to embed
+    ) -> str:
+        """
+        Generate report using LLM.
+        
+        Calls generate_report() action with context and images.
+        
+        Returns: Markdown report
+        """
+
+    async def write_introduction(self, ...) -> str:
+        """Write report introduction section."""
+
+    async def write_conclusion(self, ...) -> str:
+        """Write report conclusion with references."""
+```
diff --git a/skills/.experimental/gpt-researcher/references/config-reference.md b/skills/.experimental/gpt-researcher/references/config-reference.md
new file mode 100644
index 00000000..8f74d1c0
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/references/config-reference.md
@@ -0,0 +1,176 @@
+# Configuration Reference
+
+## Table of Contents
+- [Required Variables](#required-variables)
+- [LLM Configuration](#llm-configuration)
+- [Provider API Keys](#provider-api-keys)
+- [Retriever Configuration](#retriever-configuration)
+- [Report Configuration](#report-configuration)
+- [Feature Toggles](#feature-toggles)
+- [Configuration Priority](#configuration-priority)
+- [Example .env](#example-env)
+
+---
+
+## Required Variables
+
+```bash
+OPENAI_API_KEY=sk-...          # Or another LLM provider key
+TAVILY_API_KEY=tvly-...        # Or another retriever key
+```
+
+---
+
+## LLM Configuration
+
+```bash
+LLM_PROVIDER=openai            # openai, anthropic, google, groq, together, etc.
+FAST_LLM=gpt-4o-mini           # Quick tasks (summarization)
+SMART_LLM=gpt-4o               # Complex reasoning (report writing)
+STRATEGIC_LLM=o3-mini          # Planning (agent selection)
+TEMPERATURE=0.4                # 0.0-1.0
+MAX_TOKENS=4000
+REASONING_EFFORT=medium        # For o-series: low, medium, high
+```
+
+---
+
+## Provider API Keys
+
+```bash
+# OpenAI
+OPENAI_API_KEY=sk-...
+OPENAI_BASE_URL=https://api.openai.com/v1
+
+# Anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Google
+GOOGLE_API_KEY=AIza...
+
+# Groq
+GROQ_API_KEY=gsk_...
+
+# Azure OpenAI
+AZURE_OPENAI_API_KEY=...
+AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
+```
+
+---
+
+## Retriever Configuration
+
+```bash
+RETRIEVER=tavily               # Single or comma-separated: tavily,google,mcp
+MAX_SEARCH_RESULTS_PER_QUERY=5
+MAX_URLS_TO_SCRAPE=10
+SIMILARITY_THRESHOLD=0.42
+```
+
+### Retriever API Keys
+
+```bash
+TAVILY_API_KEY=tvly-...
+GOOGLE_API_KEY=AIza...
+GOOGLE_CX_KEY=...
+BING_API_KEY=...
+SERPER_API_KEY=...
+SERPAPI_API_KEY=...
+EXA_API_KEY=...
+```
+
+---
+
+## Report Configuration
+
+```bash
+REPORT_FORMAT=apa              # apa, mla, chicago, harvard, ieee
+TOTAL_WORDS=1000
+LANGUAGE=english
+CURATE_SOURCES=true
+```
+
+---
+
+## Feature Toggles
+
+### Image Generation
+
+```bash
+IMAGE_GENERATION_ENABLED=true
+GOOGLE_API_KEY=AIza...
+IMAGE_GENERATION_MODEL=models/gemini-2.5-flash-image
+IMAGE_GENERATION_MAX_IMAGES=3
+IMAGE_GENERATION_STYLE=dark    # dark, light, auto
+```
+
+### Deep Research
+
+```bash
+DEEP_RESEARCH_BREADTH=4        # Subtopics per level
+DEEP_RESEARCH_DEPTH=2          # Recursion levels
+DEEP_RESEARCH_CONCURRENCY=2    # Parallel tasks
+```
+
+### MCP
+
+```bash
+MCP_STRATEGY=fast              # fast, deep, disabled
+```
+
+### Local Documents
+
+```bash
+DOC_PATH=./my-docs
+# Supports: PDF, DOCX, TXT, CSV, XLSX, PPTX, MD
+```
+
+### Server
+
+```bash
+HOST=0.0.0.0
+PORT=8000
+VERBOSE=true
+```
+
+---
+
+## Configuration Priority
+
+```
+Environment Variables (highest)
+        ↓
+JSON Config File (if provided)
+        ↓
+Default Values (lowest)
+```
+
+**Important:** Config keys are lowercased when accessed:
+
+```python
+# In default.py: "SMART_LLM": "gpt-4o"
+# Access as: self.cfg.smart_llm  # lowercase!
+```
+
+---
+
+## Example .env
+
+```bash
+# Required
+OPENAI_API_KEY=sk-your-key
+TAVILY_API_KEY=tvly-your-key
+
+# LLM
+FAST_LLM=gpt-4o-mini
+SMART_LLM=gpt-4o
+
+# Report
+TOTAL_WORDS=1000
+LANGUAGE=english
+
+# Optional: Images
+IMAGE_GENERATION_ENABLED=true
+GOOGLE_API_KEY=AIza-your-key
+IMAGE_GENERATION_STYLE=dark
+```
diff --git a/skills/.experimental/gpt-researcher/references/deep-research.md b/skills/.experimental/gpt-researcher/references/deep-research.md
new file mode 100644
index 00000000..c8f00726
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/references/deep-research.md
@@ -0,0 +1,83 @@
+# Deep Research Mode Reference
+
+## Table of Contents
+- [Overview](#overview)
+- [Configuration](#configuration)
+- [DeepResearchSkill](#deepresearchskill)
+- [Usage](#usage)
+
+---
+
+## Overview
+
+Deep Research uses recursive tree-like exploration with configurable depth and breadth.
+
+---
+
+## Configuration
+
+```bash
+DEEP_RESEARCH_BREADTH=4    # Subtopics per level
+DEEP_RESEARCH_DEPTH=2      # Recursion levels
+DEEP_RESEARCH_CONCURRENCY=2  # Parallel tasks
+```
+
+---
+
+## DeepResearchSkill
+
+**File:** `gpt_researcher/skills/deep_research.py`
+
+```python
+class DeepResearchSkill:
+    def __init__(self, researcher):
+        self.researcher = researcher
+        self.breadth = getattr(researcher.cfg, 'deep_research_breadth', 4)
+        self.depth = getattr(researcher.cfg, 'deep_research_depth', 2)
+        self.concurrency_limit = getattr(researcher.cfg, 'deep_research_concurrency', 2)
+        self.learnings = []
+        self.research_sources = []
+        self.context = []
+
+    async def deep_research(self, query: str, on_progress=None) -> str:
+        """
+        Recursive research with depth and breadth.
+        
+        1. Research main topic
+        2. Generate subtopics (breadth)
+        3. For each subtopic, recursively research (depth)
+        4. Aggregate all findings
+        5. Generate comprehensive report
+        """
+```
+
+---
+
+## Usage
+
+```python
+researcher = GPTResearcher(
+    query="Comprehensive analysis of quantum computing",
+    report_type="deep",  # Triggers deep research
+)
+await researcher.conduct_research()
+report = await researcher.write_report()
+```
+
+### Research Tree Structure
+
+```
+Query: "Quantum Computing"
+├── Subtopic 1: Hardware (depth 1)
+│   ├── Subtopic 1.1: Superconducting qubits (depth 2)
+│   └── Subtopic 1.2: Ion traps (depth 2)
+├── Subtopic 2: Algorithms (depth 1)
+│   ├── Subtopic 2.1: Shor's algorithm (depth 2)
+│   └── Subtopic 2.2: Grover's algorithm (depth 2)
+├── Subtopic 3: Applications (depth 1)
+│   └── ...
+└── Subtopic 4: Challenges (depth 1)
+    └── ...
+```
+
+With `DEEP_RESEARCH_BREADTH=4` and `DEEP_RESEARCH_DEPTH=2`, this explores 4 subtopics at each level, going 2 levels deep.
diff --git a/skills/.experimental/gpt-researcher/references/flows.md b/skills/.experimental/gpt-researcher/references/flows.md
new file mode 100644
index 00000000..efa9260f
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/references/flows.md
@@ -0,0 +1,272 @@
+# Research Flow & Data Flow
+
+## Table of Contents
+- [End-to-End Research Flow](#end-to-end-research-flow)
+- [Data Flow Between Components](#data-flow-between-components)
+
+---
+
+## End-to-End Research Flow
+
+### 1. Request Entry
+
+**File:** `backend/server/app.py`
+
+```python
+# REST API endpoint
+@app.post("/report/")
+async def generate_report(research_request: ResearchRequest, background_tasks: BackgroundTasks):
+    research_id = sanitize_filename(f"task_{int(time.time())}_{research_request.task}")
+    # Calls write_report() which uses run_agent()
+
+# WebSocket endpoint
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    await manager.connect(websocket)
+    await handle_websocket_communication(websocket, manager)
+```
+
+### 2. Agent Runner
+
+**File:** `backend/server/websocket_manager.py`
+
+```python
+async def run_agent(task, report_type, report_source, source_urls, ...):
+    """Main entry point for research execution."""
+    # Create logs handler
+    logs_handler = CustomLogsHandler(websocket, task)
+    
+    # Configure MCP if enabled
+    if mcp_enabled and mcp_configs:
+        os.environ["RETRIEVER"] = f"{current_retriever},mcp"
+        os.environ["MCP_STRATEGY"] = mcp_strategy
+    
+    # Route based on report type
+    if report_type == "multi_agents":
+        report = await run_research_task(query=task, websocket=logs_handler, ...)
+    elif report_type == ReportType.DetailedReport.value:
+        researcher = DetailedReport(query=task, ...)
+        report = await researcher.run()
+    else:
+        researcher = BasicReport(query=task, ...)
+        report = await researcher.run()
+    
+    return report
+```
+
+### 3. Research Phase
+
+**File:** `gpt_researcher/agent.py`
+
+```python
+async def conduct_research(self, on_progress=None):
+    # Handle deep research separately
+    if self.report_type == ReportType.DeepResearch.value and self.deep_researcher:
+        return await self._handle_deep_research(on_progress)
+    
+    # Choose agent role via LLM
+    if not (self.agent and self.role):
+        self.agent, self.role = await choose_agent(
+            query=self.query,
+            cfg=self.cfg,
+            parent_query=self.parent_query,
+            cost_callback=self.add_costs,
+            headers=self.headers,
+            prompt_family=self.prompt_family,
+        )
+    
+    # Conduct research
+    self.context = await self.research_conductor.conduct_research()
+    
+    # Generate images if enabled (pre-generation for seamless UX)
+    if self.cfg.image_generation_enabled and self.image_generator:
+        self.available_images = await self.image_generator.plan_and_generate_images(
+            research_context=self.context,
+            research_query=self.query,
+            research_id=self.research_id,
+            websocket=self.websocket,
+        )
+    
+    return self.context
+```
+
+### 4. Sub-Query Processing
+
+**File:** `gpt_researcher/skills/researcher.py`
+
+```python
+async def _process_sub_query(self, sub_query: str, scraped_data: list = [], query_domains: list = []):
+    # MCP Strategy handling
+    mcp_retrievers = [r for r in self.researcher.retrievers if "mcpretriever" in r.__name__.lower()]
+    mcp_strategy = self._get_mcp_strategy()
+    
+    if mcp_retrievers:
+        if mcp_strategy == "fast" and self._mcp_results_cache is not None:
+            # Reuse cached MCP results
+            mcp_context = self._mcp_results_cache.copy()
+        elif mcp_strategy == "deep":
+            # Run MCP for every sub-query
+            mcp_context = await self._execute_mcp_research_for_queries([sub_query], mcp_retrievers)
+    
+    # Get web search context
+    if not scraped_data:
+        scraped_data = await self._scrape_data_by_urls(sub_query, query_domains)
+    
+    # Get similar content via embeddings
+    if scraped_data:
+        web_context = await self.researcher.context_manager.get_similar_content_by_query(
+            sub_query, scraped_data
+        )
+    
+    # Combine MCP + web context
+    combined_context = self._combine_mcp_and_web_context(mcp_context, web_context, sub_query)
+    return combined_context
+```
+
+### 5. Report Generation
+
+**File:** `gpt_researcher/actions/report_generation.py`
+
+```python
+async def generate_report(
+    query: str,
+    context: str,
+    agent_role_prompt: str,
+    report_type: str,
+    websocket=None,
+    cfg=None,
+    tone=None,
+    headers=None,
+    cost_callback=None,
+    prompt_family=None,
+    available_images: list = [],
+    **kwargs
+) -> str:
+    """Generate report using LLM."""
+    # Get prompt generator
+    generate_prompt = prompt_family.get_prompt_by_report_type(report_type)
+    
+    # Build prompt with context and available images
+    content = generate_prompt(
+        query, context, report_source,
+        report_format=cfg.report_format,
+        tone=tone,
+        total_words=cfg.total_words,
+        language=cfg.language,
+        available_images=available_images,
+    )
+    
+    # Call LLM
+    report = await create_chat_completion(
+        model=cfg.smart_llm,
+        messages=[{"role": "user", "content": content}],
+        temperature=cfg.temperature,
+        llm_provider=cfg.smart_llm_provider,
+        max_tokens=cfg.smart_token_limit,
+        llm_kwargs=cfg.llm_kwargs,
+        cost_callback=cost_callback,
+    )
+    
+    return report
+```
+
+---
+
+## Data Flow Between Components
+
+```
+User Query
+    │
+    ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ GPTResearcher.__init__()                                         │
+│   • Loads Config (env → json → defaults)                        │
+│   • Initializes skills: ResearchConductor, ReportGenerator, etc │
+│   • Initializes retrievers based on RETRIEVER env var           │
+│   • Initializes ImageGenerator if IMAGE_GENERATION_ENABLED      │
+└─────────────────────────────────────────────────────────────────┘
+    │
+    │  researcher.conduct_research()
+    ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ choose_agent()                                                   │
+│   Input: query, config                                          │
+│   Output: (agent_type: str, role_prompt: str)                   │
+│   • LLM selects best agent role for the query                   │
+└─────────────────────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ ResearchConductor.conduct_research()                             │
+│   Input: self.researcher (has query, config, retrievers)        │
+│   Output: context: str                                          │
+│                                                                  │
+│   ┌─────────────────────────────────────────────────────────┐   │
+│   │ plan_research()                                          │   │
+│   │   Input: query                                           │   │
+│   │   Output: sub_queries: list[str]                         │   │
+│   │   • Calls LLM to generate 3-5 sub-queries                │   │
+│   └─────────────────────────────────────────────────────────┘   │
+│                          │                                       │
+│                          ▼                                       │
+│   ┌─────────────────────────────────────────────────────────┐   │
+│   │ For each sub_query:                                      │   │
+│   │   _process_sub_query()                                   │   │
+│   │     Input: sub_query                                     │   │
+│   │     Output: sub_context: str                             │   │
+│   │                                                          │   │
+│   │     1. MCP retrieval (if configured)                     │   │
+│   │        → mcp_context: list[dict]                         │   │
+│   │                                                          │   │
+│   │     2. Web search via retrievers                         │   │
+│   │        → search_results: list[dict]                      │   │
+│   │                                                          │   │
+│   │     3. Scrape URLs                                       │   │
+│   │        → scraped_content: list[dict]                     │   │
+│   │                                                          │   │
+│   │     4. Similarity search via embeddings                  │   │
+│   │        → relevant_context: str                           │   │
+│   │                                                          │   │
+│   │     5. Combine MCP + web context                         │   │
+│   │        → combined_context: str                           │   │
+│   └─────────────────────────────────────────────────────────┘   │
+│                          │                                       │
+│                          ▼                                       │
+│   Aggregate all sub_contexts → final context: str               │
+└─────────────────────────────────────────────────────────────────┘
+    │
+    │  If IMAGE_GENERATION_ENABLED:
+    ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ ImageGenerator.plan_and_generate_images()                        │
+│   Input: context, query, research_id                            │
+│   Output: available_images: list[dict]                          │
+│     [{"url": "/outputs/images/.../img.png",                     │
+│       "title": "...", "description": "..."}]                    │
+│                                                                  │
+│   1. LLM analyzes context for visual concepts                   │
+│   2. Generates 2-3 images in parallel via Gemini                │
+│   3. Saves to outputs/images/{research_id}/                     │
+└─────────────────────────────────────────────────────────────────┘
+    │
+    │  researcher.write_report()
+    ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ ReportGenerator.write_report()                                   │
+│   Input: context, available_images                              │
+│   Output: report: str (markdown)                                │
+│                                                                  │
+│   → generate_report() action                                    │
+│       • Builds prompt with context + image list                 │
+│       • LLM generates report with embedded images               │
+└─────────────────────────────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Output                                                           │
+│   • Streamed via WebSocket (type: "report")                     │
+│   • Final via WebSocket (type: "report_complete")               │
+│   • Exported to PDF, DOCX, Markdown                             │
+│   • Saved to outputs/ directory                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
diff --git a/skills/.experimental/gpt-researcher/references/mcp.md b/skills/.experimental/gpt-researcher/references/mcp.md
new file mode 100644
index 00000000..bf6b3200
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/references/mcp.md
@@ -0,0 +1,91 @@
+# MCP Integration Reference
+
+## Table of Contents
+- [Overview](#overview)
+- [Configuration](#configuration)
+- [Strategy Options](#strategy-options)
+- [Processing Logic](#processing-logic)
+
+---
+
+## Overview
+
+MCP (Model Context Protocol) enables research from specialized data sources (GitHub, databases, APIs) alongside web search.
+
+---
+
+## Configuration
+
+```python
+researcher = GPTResearcher(
+    query="...",
+    mcp_configs=[
+        {
+            "name": "github",                    # Server name
+            "command": "npx",                    # Command to start
+            "args": ["-y", "@modelcontextprotocol/server-github"],
+            "env": {"GITHUB_TOKEN": "..."},      # Environment vars
+        },
+        {
+            "name": "filesystem",
+            "command": "npx",
+            "args": ["-y", "@anthropic/mcp-server-filesystem", "/docs"],
+        },
+        {
+            "name": "remote",
+            "connection_url": "ws://server:8080",  # WebSocket connection
+            "connection_type": "websocket",
+            "connection_token": "auth_token",
+        }
+    ],
+    mcp_strategy="fast",  # fast, deep, disabled
+)
+```
+
+---
+
+## Strategy Options
+
+| Strategy | Behavior | Use Case |
+|----------|----------|----------|
+| `fast` (default) | Run MCP once with original query, cache results | Performance-focused |
+| `deep` | Run MCP for every sub-query | Maximum thoroughness |
+| `disabled` | Skip MCP entirely | Web-only research |
+
+---
+
+## Processing Logic
+
+**File:** `gpt_researcher/skills/researcher.py`
+
+```python
+# At start of research (for 'fast' strategy)
+if mcp_strategy == "fast":
+    mcp_context = await self._execute_mcp_research_for_queries([query], mcp_retrievers)
+    self._mcp_results_cache = mcp_context  # Cache for reuse
+
+# During sub-query processing
+if mcp_strategy == "fast" and self._mcp_results_cache is not None:
+    mcp_context = self._mcp_results_cache.copy()  # Reuse cache
+elif mcp_strategy == "deep":
+    mcp_context = await self._execute_mcp_research_for_queries([sub_query], mcp_retrievers)
+```
+
+### WebSocket Request Example
+
+```json
+{
+    "task": "Research query",
+    "report_type": "research_report",
+    "mcp_enabled": true,
+    "mcp_strategy": "fast",
+    "mcp_configs": [
+        {
+            "name": "github",
+            "command": "npx",
+            "args": ["-y", "@modelcontextprotocol/server-github"],
+            "env": {"GITHUB_TOKEN": "..."}
+        }
+    ]
+}
+```
diff --git a/skills/.experimental/gpt-researcher/references/multi-agents.md b/skills/.experimental/gpt-researcher/references/multi-agents.md
new file mode 100644
index 00000000..2c78dfcd
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/references/multi-agents.md
@@ -0,0 +1,83 @@
+# Multi-Agent System Reference
+
+## Table of Contents
+- [Overview](#overview)
+- [Agent Roles](#agent-roles)
+- [Workflow](#workflow)
+- [Usage](#usage)
+
+---
+
+## Overview
+
+**Directory:** `multi_agents/`
+
+LangGraph-based system inspired by [STORM paper](https://arxiv.org/abs/2402.14207). Generates 5-6 page reports with multiple agents collaborating.
+
+---
+
+## Agent Roles
+
+| Agent | File | Role |
+|-------|------|------|
+| Human | - | Oversees and provides feedback |
+| Chief Editor | `agents/editor.py` | Master coordinator via LangGraph |
+| Researcher | Uses GPTResearcher | Deep research on topics |
+| Editor | `agents/editor.py` | Plans outline and structure |
+| Reviewer | `agents/reviewer.py` | Validates research correctness |
+| Revisor | `agents/revisor.py` | Revises based on feedback |
+| Writer | `agents/writer.py` | Compiles final report |
+| Publisher | `agents/publisher.py` | Exports to PDF, DOCX, Markdown |
+
+---
+
+## Workflow
+
+```
+1. Browser (GPTResearcher) → Initial research
+2. Editor → Plans report outline
+3. For each outline topic (parallel):
+   a. Researcher → In-depth subtopic research
+   b. Reviewer → Validates draft
+   c. Revisor → Revises until satisfactory
+4. Writer → Compiles final report
+5. Publisher → Exports to multiple formats
+```
+
+---
+
+## Usage
+
+### Via API
+
+```python
+report_type = "multi_agents"
+```
+
+### Via WebSocket
+
+```json
+{
+    "task": "Research query",
+    "report_type": "multi_agents",
+    "tone": "Analytical"
+}
+```
+
+### Directly in Python
+
+```python
+from multi_agents import run_research_task
+
+report = await run_research_task(
+    query="Comprehensive analysis of market trends",
+    websocket=handler,
+    tone=Tone.Analytical,
+)
+```
+
+### Configuration File
+
+**File:** `multi_agents/task.json`
+
+Configure the multi-agent research task parameters and agent behaviors.
diff --git a/skills/.experimental/gpt-researcher/references/prompts.md b/skills/.experimental/gpt-researcher/references/prompts.md
new file mode 100644
index 00000000..1597a301
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/references/prompts.md
@@ -0,0 +1,148 @@
+# Prompt System Reference
+
+## Table of Contents
+- [PromptFamily Class](#promptfamily-class)
+- [Key Prompt Examples](#key-prompt-examples)
+
+---
+
+## PromptFamily Class
+
+**File:** `gpt_researcher/prompts.py`
+
+All prompts are centralized in the `PromptFamily` class. This allows for model-specific prompt variations.
+
+```python
+class PromptFamily:
+    """
+    General purpose class for prompt formatting.
+    Can be overwritten with model-specific derived classes.
+    """
+
+    def __init__(self, config: Config):
+        self.cfg = config
+
+    @staticmethod
+    def get_prompt_by_report_type(report_type: str):
+        """Returns the appropriate prompt generator for the report type."""
+        match report_type:
+            case ReportType.ResearchReport.value:
+                return PromptFamily.generate_report_prompt
+            case ReportType.DetailedReport.value:
+                return PromptFamily.generate_report_prompt
+            case ReportType.OutlineReport.value:
+                return PromptFamily.generate_outline_report_prompt
+            # ... etc
+```
+
+---
+
+## Key Prompt Examples
+
+### Agent Selection Prompt
+
+```python
+@staticmethod
+def generate_agent_role_prompt(query: str, parent_query: str = "") -> str:
+    return f"""Analyze the research query and select the most appropriate agent role.
+
+Query: "{query}"
+{f'Parent Query: "{parent_query}"' if parent_query else ''}
+
+Based on the query, determine:
+1. The domain expertise needed
+2. The research approach required
+3. The appropriate agent persona
+
+Return a JSON object with:
+- "agent": The agent type (e.g., "Research Analyst", "Technical Writer")
+- "role": A detailed role description for how the agent should approach this research
+"""
+```
+
+### Research Planning Prompt
+
+```python
+@staticmethod
+def generate_search_queries_prompt(
+    query: str,
+    parent_query: str = "",
+    report_type: str = "",
+    max_iterations: int = 3,
+    context: str = "",
+) -> str:
+    return f"""Generate {max_iterations} focused search queries to research: "{query}"
+
+Context from initial search:
+{context}
+
+Requirements:
+- Each query should explore a different aspect
+- Queries should be specific and searchable
+- Consider the report type: {report_type}
+
+Return a JSON array of query strings.
+"""
+```
+
+### Report Generation Prompt (with images)
+
+```python
+@staticmethod
+def generate_report_prompt(
+    question: str,
+    context: str,
+    report_source: str,
+    report_format="apa",
+    total_words=1000,
+    tone=None,
+    language="english",
+    available_images: list = [],
+) -> str:
+    # Build image embedding instruction if images available
+    image_instruction = ""
+    if available_images:
+        image_list = "\n".join([
+            f"- Title: {img.get('title')}\n  URL: {img['url']}"
+            for img in available_images
+        ])
+        image_instruction = f"""
+AVAILABLE IMAGES (embed where relevant):
+{image_list}
+
+Use markdown format: ![Title](URL)
+"""
+
+    return f"""Information: "{context}"
+---
+Using the above information, answer: "{question}" in a detailed report.
+
+- Format: {report_format}
+- Length: ~{total_words} words
+- Tone: {tone.value if tone else "Objective"}
+- Language: {language}
+- Include citations for all factual claims
+{image_instruction}
+"""
+```
+
+### MCP Tool Selection Prompt
+
+```python
+@staticmethod
+def generate_mcp_tool_selection_prompt(query: str, tools_info: list, max_tools: int = 3) -> str:
+    return f"""Select the most relevant tools for researching: "{query}"
+
+AVAILABLE TOOLS:
+{json.dumps(tools_info, indent=2)}
+
+Select exactly {max_tools} tools ranked by relevance.
+
+Return JSON:
+{{
+  "selected_tools": [
+    {{"index": 0, "name": "tool_name", "relevance_score": 9, "reason": "..."}}
+  ]
+}}
+"""
+```
diff --git a/skills/.experimental/gpt-researcher/references/retrievers.md b/skills/.experimental/gpt-researcher/references/retrievers.md
new file mode 100644
index 00000000..fd3939d0
--- /dev/null
+++ b/skills/.experimental/gpt-researcher/references/retrievers.md
@@ -0,0 +1,122 @@
+# Retriever System Reference
+
+## Table of Contents
+- [Available Retrievers](#available-retrievers)
+- [Retriever Selection](#retriever-selection)
+- [Adding a New Retriever](#adding-a-new-retriever)
+
+---
+
+## Available Retrievers
+
+**Directory:** `gpt_researcher/retrievers/`
+
+| Retriever | Class | API Key Env Var |
+|-----------|-------|-----------------|
+| Tavily | `TavilySearch` | `TAVILY_API_KEY` |
+| Google | `GoogleSearch` | `GOOGLE_API_KEY`, `GOOGLE_CX_KEY` |
+| DuckDuckGo | `Duckduckgo` | None |
+| Bing | `BingSearch` | `BING_API_KEY` |
+| Serper | `SerperSearch` | `SERPER_API_KEY` |
+| SerpAPI | `SerpApiSearch` | `SERPAPI_API_KEY` |
+| SearchAPI | `SearchApiSearch` | `SEARCHAPI_API_KEY` |
+| Exa | `ExaSearch` | `EXA_API_KEY` |
+| arXiv | `ArxivSearch` | None |
+| Semantic Scholar | `SemanticScholarSearch` | None |
+| PubMed Central | `PubMedCentralSearch` | None |
+| MCP | `MCPRetriever` | Per-server |
+| Custom | `CustomRetriever` | User-defined |
+
+---
+
+## Retriever Selection
+
+**File:** `gpt_researcher/actions/retriever.py`
+
+```python
+def get_retriever(retriever: str):
+    """Get a retriever class by name."""
+    match retriever:
+        case "tavily":
+            from gpt_researcher.retrievers import TavilySearch
+            return TavilySearch
+        case "google":
+            from gpt_researcher.retrievers import GoogleSearch
+            return GoogleSearch
+        case "mcp":
+            from gpt_researcher.retrievers import MCPRetriever
+            return MCPRetriever
+        # ... etc
+
+def get_retrievers(retriever_names: str, headers: dict = None) -> list:
+    """
+    Get multiple retrievers from comma-separated string.
+    
+    Usage: RETRIEVER=tavily,google,mcp
+    """
+    retrievers = []
+    for name in retriever_names.split(","):
+        retriever_class = get_retriever(name.strip())
+        if retriever_class:
+            retrievers.append(retriever_class)
+    return retrievers
+```
+
+---
+
+## Adding a New Retriever
+
+### Step 1: Create Retriever File
+
+**File:** `gpt_researcher/retrievers/my_retriever/my_retriever.py`
+
+```python
+class MyRetriever:
+    def __init__(self, query: str, headers: dict = None):
+        self.query = query
+        self.headers = headers
+    
+    async def search(self, max_results: int = 10) -> list[dict]:
+        """
+        Returns list of:
+        {
+            "title": str,
+            "href": str,
+            "body": str
+        }
+        """
+        # Implementation
+        pass
+```
+
+### Step 2: Register in retriever.py
+
+**File:** `gpt_researcher/actions/retriever.py`
+
+```python
+case "my_retriever":
+    from gpt_researcher.retrievers.my_retriever import MyRetriever
+    return MyRetriever
+```
+
+### Step 3: Export in __init__.py
+
+**File:** `gpt_researcher/retrievers/__init__.py`
+
+```python
+from .my_retriever import MyRetriever
+__all__ = [..., "MyRetriever"]
+```
+
+### Step 4: Usage
+
+```bash
+RETRIEVER=tavily,my_retriever
+```
+
+```python
+researcher = GPTResearcher(
+    query="...",
+    # Will use both Tavily and your custom retriever
+)
+```
diff --git a/skills/.experimental/research-summarizer/LICENSE.txt b/skills/.experimental/research-summarizer/LICENSE.txt
new file mode 100644
index 00000000..c3e30bcc
--- /dev/null
+++ b/skills/.experimental/research-summarizer/LICENSE.txt
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alireza Rezvani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/skills/.experimental/research-summarizer/SKILL.md b/skills/.experimental/research-summarizer/SKILL.md
new file mode 100644
index 00000000..4a8b979d
--- /dev/null
+++ b/skills/.experimental/research-summarizer/SKILL.md
@@ -0,0 +1,278 @@
+---
+name: "research-summarizer"
+description: "Structured summarization skill for source material already in hand. Handles papers, articles, reports, and documentation; extracts key findings, compares sources, and formats citations. Use this for synthesis and citation work after documents have been collected. Do not use it as an autonomous research-orchestration skill."
+license: MIT
+metadata:
+  version: 1.0.0
+  author: Alireza Rezvani
+  category: product
+  updated: 2026-03-16
+---
+
+# Research Summarizer
+
+> Read less. Understand more. Cite correctly.
+
+Structured research summarization workflow that turns dense source material into actionable briefs. Built for product managers, analysts, founders, and anyone who reads more than they should have to.
+
+Not a generic "summarize this" — a repeatable framework that extracts what matters, compares across sources, and formats citations properly.
+
+---
+
+## Scope
+
+- Input: one or more documents, articles, reports, PDFs, or notes that the user already has
+- Output: structured briefs, comparison matrices, extracted citations, and summary templates
+- Use when: the material is already available and the job is to synthesize, compare, or cite it
+- Do not use when: the main task is to search broadly, gather new sources autonomously, or orchestrate a multi-step research crawl
+
+## Slash Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/research:summarize` | Summarize a single source into a structured brief |
+| `/research:compare` | Compare 2-5 sources side-by-side with synthesis |
+| `/research:cite` | Extract and format all citations from a document |
+
+---
+
+## When This Skill Activates
+
+Recognize these patterns from the user:
+
+- "Summarize this paper / article / report"
+- "What are the key findings in this document?"
+- "Compare these sources"
+- "Extract citations from this PDF"
+- "Give me a research brief on [topic]"
+- "Break down this whitepaper"
+- Any request involving: summarize, research brief, literature review, citation, source comparison
+
+If the user has a document and wants structured understanding → this skill applies.
+
+---
+
+## Workflow
+
+### `/research:summarize` — Single Source Summary
+
+1. **Identify source type**
+   - Academic paper → use IMRAD structure (Introduction, Methods, Results, Analysis, Discussion)
+   - Web article → use claim-evidence-implication structure
+   - Technical report → use executive summary structure
+   - Documentation → use reference summary structure
+
+2. **Extract structured brief**
+   ```
+   Title: [exact title]
+   Author(s): [names]
+   Date: [publication date]
+   Source Type: [paper | article | report | documentation]
+
+   ## Key Thesis
+   [1-2 sentences: the central argument or finding]
+
+   ## Key Findings
+   1. [Finding with supporting evidence]
+   2. [Finding with supporting evidence]
+   3. [Finding with supporting evidence]
+
+   ## Methodology
+   [How they arrived at these findings — data sources, sample size, approach]
+
+   ## Limitations
+   - [What the source doesn't cover or gets wrong]
+
+   ## Actionable Takeaways
+   - [What to do with this information]
+
+   ## Notable Quotes
+   > "[Direct quote]" (p. X)
+   ```
+
+3. **Assess quality**
+   - Source credibility (peer-reviewed, reputable outlet, primary vs secondary)
+   - Evidence strength (data-backed, anecdotal, theoretical)
+   - Recency (when published, still relevant?)
+   - Bias indicators (funding source, author affiliation, methodology gaps)
+
+### `/research:compare` — Multi-Source Comparison
+
+1. **Collect sources** (2-5 documents)
+2. **Summarize each** using the single-source workflow above
+3. **Build comparison matrix**
+
+   ```
+   | Dimension        | Source A        | Source B        | Source C        |
+   |------------------|-----------------|-----------------|-----------------|
+   | Central Thesis   | ...             | ...             | ...             |
+   | Methodology      | ...             | ...             | ...             |
+   | Key Finding      | ...             | ...             | ...             |
+   | Sample/Scope     | ...             | ...             | ...             |
+   | Credibility      | High/Med/Low    | High/Med/Low    | High/Med/Low    |
+   ```
+
+4. **Synthesize**
+   - Where do sources agree? (convergent findings = stronger signal)
+   - Where do they disagree? (divergent findings = needs investigation)
+   - What gaps exist across all sources?
+   - What's the weight of evidence for each position?
+
+5. **Produce synthesis brief**
+   ```
+   ## Consensus Findings
+   [What most sources agree on]
+
+   ## Contested Points
+   [Where sources disagree, with strongest evidence for each side]
+
+   ## Gaps
+   [What none of the sources address]
+
+   ## Recommendation
+   [Based on weight of evidence, what should the reader believe/do?]
+   ```
+
+### `/research:cite` — Citation Extraction
+
+1. **Scan document** for all references, footnotes, in-text citations
+2. **Extract and format** using the requested style (APA 7 default)
+3. **Classify citations** by type:
+   - Primary sources (original research, data)
+   - Secondary sources (reviews, meta-analyses, commentary)
+   - Tertiary sources (textbooks, encyclopedias)
+4. **Output** sorted bibliography with classification tags
+
+Supported citation formats:
+- **APA 7** (default) — social sciences, business
+- **IEEE** — engineering, computer science
+- **Chicago** — humanities, history
+- **Harvard** — general academic
+- **MLA 9** — arts, humanities
+
+---
+
+## Tooling
+
+### `scripts/extract_citations.py`
+
+CLI utility for extracting and formatting citations from text.
+
+**Features:**
+- Regex-based citation detection (DOI, URL, author-year, numbered references)
+- Multiple output formats (APA, IEEE, Chicago, Harvard, MLA)
+- JSON export for integration with reference managers
+- Deduplication of repeated citations
+
+**Usage:**
+```bash
+# Extract citations from a file (APA format, default)
+python3 scripts/extract_citations.py document.txt
+
+# Specify format
+python3 scripts/extract_citations.py document.txt --format ieee
+
+# JSON output
+python3 scripts/extract_citations.py document.txt --format apa --output json
+
+# From stdin
+cat paper.txt | python3 scripts/extract_citations.py --stdin
+```
+
+### `scripts/format_summary.py`
+
+CLI utility for generating structured research summaries.
+
+**Features:**
+- Multiple summary templates (academic, article, report, executive)
+- Configurable output length (brief, standard, detailed)
+- Markdown and plain text output
+- Key findings extraction with evidence tagging
+
+**Usage:**
+```bash
+# Generate structured summary template
+python3 scripts/format_summary.py --template academic
+
+# Brief executive summary format
+python3 scripts/format_summary.py --template executive --length brief
+
+# All templates listed
+python3 scripts/format_summary.py --list-templates
+
+# JSON output
+python3 scripts/format_summary.py --template article --output json
+```
+
+---
+
+## Quality Assessment Framework
+
+Rate every source on four dimensions:
+
+| Dimension | High | Medium | Low |
+|-----------|------|--------|-----|
+| **Credibility** | Peer-reviewed, established author | Reputable outlet, known author | Blog, unknown author, no review |
+| **Evidence** | Large sample, rigorous method | Moderate data, sound approach | Anecdotal, no data, opinion |
+| **Recency** | Published within 2 years | 2-5 years old | 5+ years, may be outdated |
+| **Objectivity** | No conflicts, balanced view | Minor affiliations disclosed | Funded by interested party, one-sided |
+
+**Overall Rating:**
+- 4 Highs = Strong source — cite with confidence
+- 2+ Mediums = Adequate source — cite with caveats
+- 2+ Lows = Weak source — verify independently before citing
+
+---
+
+## Summary Templates
+
+See `references/summary-templates.md` for:
+- Academic paper summary template (IMRAD)
+- Web article summary template (claim-evidence-implication)
+- Technical report template (executive summary)
+- Comparative analysis template (matrix + synthesis)
+- Literature review template (thematic organization)
+
+See `references/citation-formats.md` for:
+- APA 7 formatting rules and examples
+- IEEE formatting rules and examples
+- Chicago, Harvard, MLA quick reference
+
+---
+
+## Proactive Triggers
+
+Flag these without being asked:
+
+- **Source has no date** → Note it. Undated sources lose credibility points.
+- **Source contradicts other sources** → Highlight the contradiction explicitly. Don't paper over disagreements.
+- **Source is behind a paywall** → Note limited access. Suggest alternatives if known.
+- **User provides only one source for a compare** → Ask for at least one more. Comparison needs 2+.
+- **Citations are incomplete** → Flag missing fields (year, author, title). Don't invent metadata.
+- **Source is 5+ years old in a fast-moving field** → Warn about potential obsolescence.
+
+---
+
+## Installation
+
+### Install from `openai/skills`
+```bash
+$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/research-summarizer
+```
+
+### Local install
+```bash
+cp -r skills/.experimental/research-summarizer ~/.codex/skills/
+```
+
+### Source
+Adapted from `alirezarezvani/claude-skills/product-team/research-summarizer`.
+
+---
+
+## Related Skills
+
+- **product-analytics** — Quantitative analysis. Complementary — use research-summarizer for qualitative sources, product-analytics for metrics.
+- **competitive-teardown** — Competitive research. Complementary — use research-summarizer for individual source analysis, competitive-teardown for market landscape.
+- **content-production** — Content writing. Research-summarizer feeds content-production — summarize sources first, then write.
+- **product-discovery** — Discovery frameworks. Complementary — research-summarizer for desk research, product-discovery for user research.
diff --git a/skills/.experimental/research-summarizer/references/citation-formats.md b/skills/.experimental/research-summarizer/references/citation-formats.md
new file mode 100644
index 00000000..2f07b773
--- /dev/null
+++ b/skills/.experimental/research-summarizer/references/citation-formats.md
@@ -0,0 +1,105 @@
+# Citation Formats Quick Reference
+
+## APA 7 (American Psychological Association)
+
+Default format for social sciences, business, and product research.
+
+### Journal Article
+Author, A. A., & Author, B. B. (Year). Title of article. *Title of Periodical*, *volume*(issue), page–page. https://doi.org/xxxxx
+
+**Example:**
+Smith, J., & Jones, K. (2023). Agile adoption in enterprise organizations. *Journal of Product Management*, *15*(2), 45–62. https://doi.org/10.1234/jpm.2023.001
+
+### Book
+Author, A. A. (Year). *Title of work: Capital letter also for subtitle*. Publisher.
+
+**Example:**
+Cagan, M. (2018). *Inspired: How to create tech products customers love*. Wiley.
+
+### Web Page
+Author, A. A. (Year, Month Day). *Title of page*. Site Name. URL
+
+**Example:**
+Torres, T. (2024, January 15). *Continuous discovery in practice*. Product Talk. https://www.producttalk.org/discovery
+
+### In-Text Citation
+- Parenthetical: (Smith & Jones, 2023)
+- Narrative: Smith and Jones (2023) found that...
+- 3+ authors: (Patel et al., 2022)
+
+---
+
+## IEEE (Institute of Electrical and Electronics Engineers)
+
+Standard for engineering, computer science, and technical research.
+
+### Format
+[N] A. Author, "Title of article," *Journal*, vol. X, no. Y, pp. Z–Z, Month Year, doi: 10.xxxx.
+
+### Journal Article
+[1] J. Smith and K. Jones, "Agile adoption in enterprise organizations," *J. Prod. Mgmt.*, vol. 15, no. 2, pp. 45–62, Mar. 2023, doi: 10.1234/jpm.2023.001.
+
+### Conference Paper
+[2] A. Patel, B. Chen, and C. Kumar, "Cross-functional team performance metrics," in *Proc. Int. Conf. Software Eng.*, 2022, pp. 112–119.
+
+### Book
+[3] M. Cagan, *Inspired: How to Create Tech Products Customers Love*. Hoboken, NJ, USA: Wiley, 2018.
+
+### In-Text Citation
+As shown in [1], agile adoption has increased...
+Multiple: [1], [3], [5]–[7]
+
+---
+
+## Chicago (Notes-Bibliography)
+
+Standard for humanities, history, and some business writing.
+
+### Footnote Format
+1. First Name Last Name, *Title of Book* (Place: Publisher, Year), page.
+2. First Name Last Name, "Title of Article," *Journal* Volume, no. Issue (Year): pages.
+
+### Bibliography Entry
+Last Name, First Name. *Title of Book*. Place: Publisher, Year.
+Last Name, First Name. "Title of Article." *Journal* Volume, no. Issue (Year): pages.
+
+---
+
+## Harvard
+
+Common in UK and Australian academic writing.
+
+### Format
+Author, A.A. (Year) *Title of book*. Edition. Place: Publisher.
+Author, A.A. (Year) 'Title of article', *Journal*, Volume(Issue), pp. X–Y.
+
+### In-Text Citation
+(Smith and Jones, 2023)
+Smith and Jones (2023) argue that...
+
+---
+
+## MLA 9 (Modern Language Association)
+
+Standard for arts and humanities.
+
+### Format
+Last, First. *Title of Book*. Publisher, Year.
+Last, First. "Title of Article." *Journal*, vol. X, no. Y, Year, pp. Z–Z.
+
+### In-Text Citation
+(Smith and Jones 45)
+Smith and Jones argue that "direct quote" (45).
+
+---
+
+## Quick Decision Guide
+
+| Field / Context | Recommended Format |
+|----------------|-------------------|
+| Social sciences, business, psychology | APA 7 |
+| Engineering, computer science, technical | IEEE |
+| Humanities, history, arts | Chicago or MLA |
+| UK/Australian academic | Harvard |
+| Internal business reports | APA 7 (most widely recognized) |
+| Product research briefs | APA 7 |
diff --git a/skills/.experimental/research-summarizer/references/summary-templates.md b/skills/.experimental/research-summarizer/references/summary-templates.md
new file mode 100644
index 00000000..e2205dba
--- /dev/null
+++ b/skills/.experimental/research-summarizer/references/summary-templates.md
@@ -0,0 +1,120 @@
+# Summary Templates Reference
+
+## Academic Paper (IMRAD)
+
+Use for peer-reviewed journal articles, conference papers, and research studies.
+
+### Structure
+1. **Introduction** — What problem does the paper address? Why does it matter?
+2. **Methods** — How was the study conducted? What data, what approach?
+3. **Results** — What did they find? Key numbers, key patterns.
+4. **Analysis** — What do the results mean? How do they compare to prior work?
+5. **Discussion** — What are the implications? Limitations? Future work?
+
+### Quality Signals
+- Published in a peer-reviewed venue
+- Clear methodology section with reproducible steps
+- Statistical significance reported (p-values, confidence intervals)
+- Limitations acknowledged openly
+- Conflicts of interest disclosed
+
+### Red Flags
+- No methodology section
+- Claims without supporting data
+- Funded by an entity that benefits from specific results
+- Published in a predatory journal (check Beall's List)
+
+---
+
+## Web Article (Claim-Evidence-Implication)
+
+Use for blog posts, news articles, opinion pieces, and online publications.
+
+### Structure
+1. **Claim** — What is the author arguing or reporting?
+2. **Evidence** — What data, examples, or sources support the claim?
+3. **Implication** — So what? What should the reader do or think differently?
+
+### Quality Signals
+- Author has relevant expertise or credentials
+- Sources are linked and verifiable
+- Multiple perspectives acknowledged
+- Published on a reputable platform
+- Date of publication is clear
+
+### Red Flags
+- No author attribution
+- No sources or citations
+- Sensationalist headline vs. measured content
+- Affiliate links or sponsored content without disclosure
+
+---
+
+## Technical Report (Executive Summary)
+
+Use for industry reports, whitepapers, market research, and internal documents.
+
+### Structure
+1. **Executive Summary** — Bottom line in 2-3 sentences
+2. **Scope** — What does this report cover?
+3. **Key Data** — Most important numbers and findings
+4. **Methodology** — How was the data gathered?
+5. **Recommendations** — What should be done based on findings?
+6. **Relevance** — Why does this matter for our specific context?
+
+### Quality Signals
+- Clear methodology for data collection
+- Sample size and composition disclosed
+- Published by a recognized research firm or organization
+- Methodology section available (even if separate document)
+
+### Red Flags
+- "Report" is actually a marketing piece for a product
+- Data from a single, small, unrepresentative sample
+- No methodology disclosure
+- Conclusions far exceed what the data supports
+
+---
+
+## Comparative Analysis (Matrix + Synthesis)
+
+Use when evaluating 2-5 sources on the same topic.
+
+### Comparison Dimensions
+- **Central thesis** — What is each source's main argument?
+- **Methodology** — How did each source arrive at its conclusions?
+- **Key finding** — What is the headline result?
+- **Sample/scope** — How broad or narrow is the evidence?
+- **Credibility** — How trustworthy is the source?
+- **Recency** — When was it published?
+
+### Synthesis Framework
+1. **Convergent findings** — Where sources agree (stronger signal)
+2. **Divergent findings** — Where sources disagree (investigate further)
+3. **Gaps** — What no source addresses
+4. **Weight of evidence** — Which position has stronger support?
+
+---
+
+## Literature Review (Thematic)
+
+Use when synthesizing 5+ sources into a research overview.
+
+### Organization Approaches
+- **Thematic** — Group by topic (preferred for most use cases)
+- **Chronological** — Group by time period (good for showing evolution)
+- **Methodological** — Group by research approach (good for methods papers)
+
+### Per-Theme Structure
+1. Theme name and scope
+2. Key sources that address this theme
+3. What the sources say (points of agreement)
+4. What the sources disagree on
+5. Strength of evidence for each position
+
+### Synthesis Checklist
+- [ ] All sources categorized into themes
+- [ ] Gaps in literature identified
+- [ ] Contradictions highlighted (not hidden)
+- [ ] Overall state of knowledge summarized
+- [ ] Future research directions suggested
diff --git a/skills/.experimental/research-summarizer/scripts/extract_citations.py b/skills/.experimental/research-summarizer/scripts/extract_citations.py
new file mode 100644
index 00000000..ee4de0dd
--- /dev/null
+++ b/skills/.experimental/research-summarizer/scripts/extract_citations.py
@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+"""
+research-summarizer: Citation Extractor
+
+Extract and format citations from text documents. Detects DOIs, URLs,
+author-year patterns, and numbered references. Outputs in APA, IEEE,
+Chicago, Harvard, or MLA format.
+
+Usage:
+    python scripts/extract_citations.py document.txt
+    python scripts/extract_citations.py document.txt --format ieee
+    python scripts/extract_citations.py document.txt --format apa --output json
+    python scripts/extract_citations.py --stdin < document.txt
+"""
+
+import argparse
+import json
+import re
+import sys
+from collections import OrderedDict
+
+
+# --- Citation Detection Patterns ---
+
+PATTERNS = {
+    "doi": re.compile(
+        r"(?:https?://doi\.org/|doi:\s*)(10\.\d{4,}/[^\s,;}\]]+)", re.IGNORECASE
+    ),
+    "url": re.compile(
+        r"https?://[^\s,;}\])\"'>]+", re.IGNORECASE
+    ),
+    "author_year": re.compile(
+        r"(?:^|\(|\s)([A-Z][a-z]+(?:\s(?:&|and)\s[A-Z][a-z]+)?(?:\set\sal\.?)?)\s*\((\d{4})\)",
+    ),
+    "numbered_ref": re.compile(
+        r"^\[(\d+)\]\s+(.+)$", re.MULTILINE
+    ),
+    "footnote": re.compile(
+        r"^\d+\.\s+([A-Z].+?(?:\d{4}).+)$", re.MULTILINE
+    ),
+}
+
+
+def extract_dois(text):
+    """Extract DOI references."""
+    citations = []
+    for match in PATTERNS["doi"].finditer(text):
+        doi = match.group(1).rstrip(".")
+        citations.append({
+            "type": "doi",
+            "doi": doi,
+            "raw": match.group(0).strip(),
+            "url": f"https://doi.org/{doi}",
+        })
+    return citations
+
+
+def extract_urls(text):
+    """Extract URL references (excluding DOI URLs already captured)."""
+    citations = []
+    for match in PATTERNS["url"].finditer(text):
+        url = match.group(0).rstrip(".,;)")
+        if "doi.org" in url:
+            continue
+        citations.append({
+            "type": "url",
+            "url": url,
+            "raw": url,
+        })
+    return citations
+
+
+def extract_author_year(text):
+    """Extract author-year citations like (Smith, 2023) or Smith & Jones (2021)."""
+    citations = []
+    for match in PATTERNS["author_year"].finditer(text):
+        author = match.group(1).strip()
+        year = match.group(2)
+        citations.append({
+            "type": "author_year",
+            "author": author,
+            "year": year,
+            "raw": f"{author} ({year})",
+        })
+    return citations
+
+
+def extract_numbered_refs(text):
+    """Extract numbered reference list entries like [1] Author. Title..."""
+    citations = []
+    for match in PATTERNS["numbered_ref"].finditer(text):
+        num = match.group(1)
+        content = match.group(2).strip()
+        citations.append({
+            "type": "numbered",
+            "number": int(num),
+            "content": content,
+            "raw": f"[{num}] {content}",
+        })
+    return citations
+
+
+def deduplicate(citations):
+    """Remove duplicate citations based on raw text."""
+    seen = OrderedDict()
+    for c in citations:
+        key = c.get("doi") or c.get("url") or c.get("raw", "")
+        key = key.lower().strip()
+        if key and key not in seen:
+            seen[key] = c
+    return list(seen.values())
+
+
+def classify_source(citation):
+    """Classify citation as primary, secondary, or tertiary."""
+    raw = citation.get("content", citation.get("raw", "")).lower()
+    if any(kw in raw for kw in ["meta-analysis", "systematic review", "literature review", "survey of"]):
+        return "secondary"
+    if any(kw in raw for kw in ["textbook", "encyclopedia", "handbook", "dictionary"]):
+        return "tertiary"
+    return "primary"
+
+
+# --- Formatting ---
+
+def format_apa(citation):
+    """Format citation in APA 7 style."""
+    if citation["type"] == "doi":
+        return f"https://doi.org/{citation['doi']}"
+    if citation["type"] == "url":
+        return f"Retrieved from {citation['url']}"
+    if citation["type"] == "author_year":
+        return f"{citation['author']} ({citation['year']})."
+    if citation["type"] == "numbered":
+        return citation["content"]
+    return citation.get("raw", "")
+
+
+def format_ieee(citation):
+    """Format citation in IEEE style."""
+    if citation["type"] == "doi":
+        return f"doi: {citation['doi']}"
+    if citation["type"] == "url":
+        return f"[Online]. Available: {citation['url']}"
+    if citation["type"] == "author_year":
+        return f"{citation['author']}, {citation['year']}."
+    if citation["type"] == "numbered":
+        return f"[{citation['number']}] {citation['content']}"
+    return citation.get("raw", "")
+
+
+def format_chicago(citation):
+    """Format citation in Chicago style."""
+    if citation["type"] == "doi":
+        return f"https://doi.org/{citation['doi']}."
+    if citation["type"] == "url":
+        return f"{citation['url']}."
+    if citation["type"] == "author_year":
+        return f"{citation['author']}. {citation['year']}."
+    if citation["type"] == "numbered":
+        return citation["content"]
+    return citation.get("raw", "")
+
+
+def format_harvard(citation):
+    """Format citation in Harvard style."""
+    if citation["type"] == "doi":
+        return f"doi:{citation['doi']}"
+    if citation["type"] == "url":
+        return f"Available at: {citation['url']}"
+    if citation["type"] == "author_year":
+        return f"{citation['author']} ({citation['year']})"
+    if citation["type"] == "numbered":
+        return citation["content"]
+    return citation.get("raw", "")
+
+
+def format_mla(citation):
+    """Format citation in MLA 9 style."""
+    if citation["type"] == "doi":
+        return f"doi:{citation['doi']}."
+    if citation["type"] == "url":
+        return f"{citation['url']}."
+    if citation["type"] == "author_year":
+        return f"{citation['author']}. {citation['year']}."
+    if citation["type"] == "numbered":
+        return citation["content"]
+    return citation.get("raw", "")
+
+
+FORMATTERS = {
+    "apa": format_apa,
+    "ieee": format_ieee,
+    "chicago": format_chicago,
+    "harvard": format_harvard,
+    "mla": format_mla,
+}
+
+
+# --- Demo Data ---
+
+DEMO_TEXT = """
+Recent studies in product management have shown significant shifts in methodology.
+According to Smith & Jones (2023), agile adoption has increased by 47% since 2020.
+Patel et al. (2022) found that cross-functional teams deliver 2.3x faster.
+
+Several frameworks have been proposed:
+[1] Cagan, M. Inspired: How to Create Tech Products Customers Love. Wiley, 2018.
+[2] Torres, T. Continuous Discovery Habits. Product Talk LLC, 2021.
+[3] Gothelf, J. & Seiden, J. Lean UX. O'Reilly Media, 2021. doi: 10.1234/leanux.2021
+
+For further reading, see https://www.svpg.com/articles/ and the meta-analysis
+by Chen (2024) on product discovery effectiveness.
+
+Related work: doi: 10.1145/3544548.3581388
+"""
+
+
+def run_extraction(text, fmt, output_mode):
+    """Run full extraction pipeline."""
+    all_citations = []
+    all_citations.extend(extract_dois(text))
+    all_citations.extend(extract_author_year(text))
+    all_citations.extend(extract_numbered_refs(text))
+    all_citations.extend(extract_urls(text))
+
+    citations = deduplicate(all_citations)
+
+    for c in citations:
+        c["classification"] = classify_source(c)
+
+    formatter = FORMATTERS.get(fmt, format_apa)
+
+    if output_mode == "json":
+        result = {
+            "format": fmt,
+            "total": len(citations),
+            "citations": [],
+        }
+        for i, c in enumerate(citations, 1):
+            result["citations"].append({
+                "index": i,
+                "type": c["type"],
+                "classification": c["classification"],
+                "formatted": formatter(c),
+                "raw": c.get("raw", ""),
+            })
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Citations ({fmt.upper()}) — {len(citations)} found\n")
+        primary = [c for c in citations if c["classification"] == "primary"]
+        secondary = [c for c in citations if c["classification"] == "secondary"]
+        tertiary = [c for c in citations if c["classification"] == "tertiary"]
+
+        for label, group in [("Primary Sources", primary), ("Secondary Sources", secondary), ("Tertiary Sources", tertiary)]:
+            if group:
+                print(f"### {label}")
+                for i, c in enumerate(group, 1):
+                    print(f"  {i}. {formatter(c)}")
+                print()
+
+    return citations
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="research-summarizer: Extract and format citations from text"
+    )
+    parser.add_argument("file", nargs="?", help="Input text file (omit for demo)")
+    parser.add_argument(
+        "--format", "-f",
+        choices=["apa", "ieee", "chicago", "harvard", "mla"],
+        default="apa",
+        help="Citation format (default: apa)",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        choices=["text", "json"],
+        default="text",
+        help="Output mode (default: text)",
+    )
+    parser.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read from stdin instead of file",
+    )
+    args = parser.parse_args()
+
+    if args.stdin:
+        text = sys.stdin.read()
+    elif args.file:
+        try:
+            with open(args.file, "r", encoding="utf-8") as f:
+                text = f.read()
+        except FileNotFoundError:
+            print(f"Error: File not found: {args.file}", file=sys.stderr)
+            sys.exit(1)
+        except IOError as e:
+            print(f"Error reading file: {e}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        print("No input file provided. Running demo...\n")
+        text = DEMO_TEXT
+
+    run_extraction(text, args.format, args.output)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/skills/.experimental/research-summarizer/scripts/format_summary.py b/skills/.experimental/research-summarizer/scripts/format_summary.py
new file mode 100644
index 00000000..8640a93c
--- /dev/null
+++ b/skills/.experimental/research-summarizer/scripts/format_summary.py
@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""
+research-summarizer: Summary Formatter
+
+Generate structured research summary templates for different source types.
+Produces fill-in-the-blank frameworks for academic papers, web articles,
+technical reports, and executive briefs.
+
+Usage:
+    python scripts/format_summary.py --template academic
+    python scripts/format_summary.py --template executive --length brief
+    python scripts/format_summary.py --list-templates
+    python scripts/format_summary.py --template article --output json
+"""
+
+import argparse
+import json
+import sys
+import textwrap
+from datetime import datetime
+
+
+# --- Templates ---
+
+TEMPLATES = {
+    "academic": {
+        "name": "Academic Paper Summary",
+        "description": "IMRAD structure for peer-reviewed papers and research studies",
+        "sections": [
+            ("Title", "[Full paper title]"),
+            ("Author(s)", "[Author names, affiliations]"),
+            ("Publication", "[Journal/Conference, Year, DOI]"),
+            ("Source Type", "Academic Paper"),
+            ("Key Thesis", "[1-2 sentences: the central research question and answer]"),
+            ("Methodology", "[Study design, sample size, data sources, analytical approach]"),
+            ("Key Findings", "1. [Finding 1 with supporting data]\n2. [Finding 2 with supporting data]\n3. [Finding 3 with supporting data]"),
+            ("Statistical Significance", "[Key p-values, effect sizes, confidence intervals]"),
+            ("Limitations", "- [Limitation 1: scope, sample, methodology gap]\n- [Limitation 2]"),
+            ("Implications", "- [What this means for practice]\n- [What this means for future research]"),
+            ("Notable Quotes", '> "[Direct quote]" (p. X)'),
+            ("Quality Assessment", "Credibility: [High/Med/Low] | Evidence: [High/Med/Low] | Recency: [High/Med/Low] | Objectivity: [High/Med/Low]"),
+        ],
+    },
+    "article": {
+        "name": "Web Article Summary",
+        "description": "Claim-evidence-implication structure for online articles and blog posts",
+        "sections": [
+            ("Title", "[Article title]"),
+            ("Author", "[Author name]"),
+            ("Source", "[Publication/Website, Date, URL]"),
+            ("Source Type", "Web Article"),
+            ("Central Claim", "[1-2 sentences: main argument or thesis]"),
+            ("Supporting Evidence", "1. [Evidence point 1]\n2. [Evidence point 2]\n3. [Evidence point 3]"),
+            ("Counterarguments Addressed", "- [Counterargument and author's response]"),
+            ("Implications", "- [What this means for the reader]"),
+            ("Bias Check", "Author affiliation: [?] | Funding: [?] | Balanced perspective: [Yes/No]"),
+            ("Actionable Takeaways", "- [What to do with this information]\n- [Next step]"),
+            ("Quality Assessment", "Credibility: [High/Med/Low] | Evidence: [High/Med/Low] | Recency: [High/Med/Low] | Objectivity: [High/Med/Low]"),
+        ],
+    },
+    "report": {
+        "name": "Technical Report Summary",
+        "description": "Structured summary for industry reports, whitepapers, and technical documentation",
+        "sections": [
+            ("Title", "[Report title]"),
+            ("Organization", "[Publishing organization]"),
+            ("Date", "[Publication date]"),
+            ("Source Type", "Technical Report"),
+            ("Executive Summary", "[2-3 sentences: scope, key conclusion, recommendation]"),
+            ("Scope", "[What the report covers and what it excludes]"),
+            ("Key Data Points", "1. [Statistic or data point with context]\n2. [Statistic or data point with context]\n3. [Statistic or data point with context]"),
+            ("Methodology", "[How data was collected — survey, analysis, case study]"),
+            ("Recommendations", "1. [Recommendation with supporting rationale]\n2. [Recommendation with supporting rationale]"),
+            ("Limitations", "- [Sample bias, geographic scope, time period]"),
+            ("Relevance", "[Why this matters for our context — specific applicability]"),
+            ("Quality Assessment", "Credibility: [High/Med/Low] | Evidence: [High/Med/Low] | Recency: [High/Med/Low] | Objectivity: [High/Med/Low]"),
+        ],
+    },
+    "executive": {
+        "name": "Executive Brief",
+        "description": "Condensed decision-focused summary for leadership consumption",
+        "sections": [
+            ("Source", "[Title, Author, Date]"),
+            ("Bottom Line", "[1 sentence: the single most important takeaway]"),
+            ("Key Facts", "1. [Fact]\n2. [Fact]\n3. [Fact]"),
+            ("So What?", "[Why this matters for our business/product/strategy]"),
+            ("Action Required", "- [Specific next step with owner and timeline]"),
+            ("Confidence", "[High/Medium/Low] — based on source quality and evidence strength"),
+        ],
+    },
+    "comparison": {
+        "name": "Comparative Analysis",
+        "description": "Side-by-side comparison matrix for 2-5 sources on the same topic",
+        "sections": [
+            ("Topic", "[Research topic or question being compared]"),
+            ("Sources Compared", "1. [Source A — Author, Year]\n2. [Source B — Author, Year]\n3. [Source C — Author, Year]"),
+            ("Comparison Matrix", "| Dimension | Source A | Source B | Source C |\n|-----------|---------|---------|---------|"
+             "\n| Central Thesis | ... | ... | ... |"
+             "\n| Methodology | ... | ... | ... |"
+             "\n| Key Finding | ... | ... | ... |"
+             "\n| Sample/Scope | ... | ... | ... |"
+             "\n| Credibility | High/Med/Low | High/Med/Low | High/Med/Low |"),
+            ("Consensus Findings", "[What most sources agree on]"),
+            ("Contested Points", "[Where sources disagree — with strongest evidence for each side]"),
+            ("Gaps", "[What none of the sources address]"),
+            ("Synthesis", "[Weight-of-evidence recommendation: what to believe and do]"),
+        ],
+    },
+    "literature": {
+        "name": "Literature Review",
+        "description": "Thematic organization of multiple sources for research synthesis",
+        "sections": [
+            ("Research Question", "[The question this review addresses]"),
+            ("Search Scope", "[Databases, keywords, date range, inclusion/exclusion criteria]"),
+            ("Sources Reviewed", "[Total count, breakdown by type]"),
+            ("Theme 1: [Name]", "Summary: [Theme overview]\nKey Sources: [Author (Year), Author (Year)]\nFindings: [What sources say about this theme]"),
+            ("Theme 2: [Name]", "Summary: [Theme overview]\nKey Sources: [Author (Year), Author (Year)]\nFindings: [What sources say about this theme]"),
+            ("Theme 3: [Name]", "Summary: [Theme overview]\nKey Sources: [Author (Year), Author (Year)]\nFindings: [What sources say about this theme]"),
+            ("Gaps in Literature", "- [Under-researched area 1]\n- [Under-researched area 2]"),
+            ("Synthesis", "[Overall state of knowledge — what we know, what we don't, where to go next]"),
+        ],
+    },
+}
+
+LENGTH_CONFIGS = {
+    "brief": {"max_sections": 4, "label": "Brief (key points only)"},
+    "standard": {"max_sections": 99, "label": "Standard (full template)"},
+    "detailed": {"max_sections": 99, "label": "Detailed (full template with extended guidance)"},
+}
+
+
+def render_template(template_key, length="standard", output_format="text"):
+    """Render a summary template."""
+    template = TEMPLATES[template_key]
+    sections = template["sections"]
+
+    if length == "brief":
+        # Keep only first 4 sections for brief output
+        sections = sections[:4]
+
+    if output_format == "json":
+        result = {
+            "template": template_key,
+            "name": template["name"],
+            "description": template["description"],
+            "length": length,
+            "generated": datetime.now().strftime("%Y-%m-%d"),
+            "sections": [],
+        }
+        for title, content in sections:
+            result["sections"].append({
+                "heading": title,
+                "placeholder": content,
+            })
+        return json.dumps(result, indent=2)
+
+    # Text/Markdown output
+    lines = []
+    lines.append(f"# {template['name']}")
+    lines.append(f"_{template['description']}_\n")
+    lines.append(f"Length: {LENGTH_CONFIGS[length]['label']}")
+    lines.append(f"Generated: {datetime.now().strftime('%Y-%m-%d')}\n")
+    lines.append("---\n")
+
+    for title, content in sections:
+        lines.append(f"## {title}\n")
+        # Indent content for readability
+        for line in content.split("\n"):
+            lines.append(line)
+        lines.append("")
+
+    lines.append("---")
+    lines.append("_Template from research-summarizer skill_")
+
+    return "\n".join(lines)
+
+
+def list_templates(output_format="text"):
+    """List all available templates."""
+    if output_format == "json":
+        result = []
+        for key, tmpl in TEMPLATES.items():
+            result.append({
+                "key": key,
+                "name": tmpl["name"],
+                "description": tmpl["description"],
+                "sections": len(tmpl["sections"]),
+            })
+        return json.dumps(result, indent=2)
+
+    lines = []
+    lines.append("Available Summary Templates\n")
+    lines.append(f"{'KEY':<15} {'NAME':<30} {'SECTIONS':>8}  DESCRIPTION")
+    lines.append(f"{'─' * 90}")
+    for key, tmpl in TEMPLATES.items():
+        lines.append(
+            f"{key:<15} {tmpl['name']:<30} {len(tmpl['sections']):>8}  {tmpl['description'][:40]}"
+        )
+    return "\n".join(lines)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="research-summarizer: Generate structured summary templates"
+    )
+    parser.add_argument(
+        "--template", "-t",
+        choices=list(TEMPLATES.keys()),
+        help="Template type to generate",
+    )
+    parser.add_argument(
+        "--length", "-l",
+        choices=["brief", "standard", "detailed"],
+        default="standard",
+        help="Output length (default: standard)",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)",
+    )
+    parser.add_argument(
+        "--list-templates",
+        action="store_true",
+        help="List all available templates",
+    )
+    args = parser.parse_args()
+
+    if args.list_templates:
+        print(list_templates(args.output))
+        return
+
+    if not args.template:
+        print("No template specified. Available templates:\n")
+        print(list_templates(args.output))
+        print("\nUsage: python scripts/format_summary.py --template academic")
+        return
+
+    print(render_template(args.template, args.length, args.output))
+
+
+if __name__ == "__main__":
+    main()