# Directory Showcase

Turns any directory into a single, good-looking, browsable web page. The skill looks at what's actually in the folder, asks the user a couple of framing questions so the result is tailored rather than generic, and then builds a self-contained HTML page where every item has a visual, a title, and a short description.

The same skill should produce a noticeably different page for a legal folder, a photo folder, and a research folder — because it adapts to both the contents and the user's stated interest. That adaptiveness is the point; do not produce a one-size-fits-all template.

## Step 1 — Survey the directory

Determine the target directory (the connected folder by default, or a path the user names).

1. List the files and subfolders. Note count, types, and rough sizes.
2. Sample contents to understand what the collection actually is. Read readable files (`.md`, `.txt`, `.csv`, code, `.html`) directly; extract text from `.pdf`/`.docx`; for images, note them as images (you'll thumbnail them later). **Cap reading** at roughly the first 1–2 pages or ~1,500 characters per file — enough to summarize, not so much that it burns the session. If there are more than ~25 items, sample the most substantial ones and group the rest.
3. Form a quick internal picture: What is this collection? What themes run across it? What's the natural way someone would want to browse it (by topic, by type, by date, by project)?

Do not narrate the raw file listing back to the user. Move to the questions.

## Step 2 — Ask two or three framing questions

Based on what you actually found (not generic boilerplate), ask **two or three** short questions that will shape the page. Make them specific to this directory. Cover:

- **Purpose / audience** — "Who's this overview for, and what are they trying to do with it?"
- **Emphasis** — surface the 2–4 real themes you detected and ask which matter most, e.g. "I'm seeing contracts, research notes, and meeting recaps — which should lead?"
- **Browse logic** (optional third) — "Group by topic, by type, or by date?"

Keep it to one round. The answers steer how descriptions are written, what leads, how items are grouped/sorted, and the one-line synthesis at the top.

## Step 3 — Generate the showcase page

Build a **single, self-contained HTML file** (inline CSS and minimal inline JS; no build step; web fonts/icons from a CDN are fine but the page must work offline-ish). Save it in the target directory as `showcase.html` and tell the user the path so they can open it.

### Page structure

- **Header** — the collection's name, item count, and a one-line synthesis of what this directory is, written through the lens of the user's answers.
- **Controls** — a search box (filters cards by title/description live) and filter/sort controls matching the chosen browse logic (by topic / type / date).
- **Card grid** — one card per item (or per group), responsive, that reads as a gallery, not a file listing.

### Each card has

- **A visual.** For image files, embed an actual thumbnail (reference the file by relative path, or inline as base64 if small). For everything else, render a tasteful tile: a type glyph or emoji (📄 doc, 📊 sheet, 📑 PDF, 🖼️ image, 🗂️ folder, etc.) on a color keyed to the item's type or theme. The visual should make the item recognizable at a glance.
- **A title.** Human-readable — clean up the filename, or use the document's real title if you extracted one. Not `final_v3_FINAL.docx`.
- **A description.** One to two sentences, written to emphasize what the user said they care about. This is summary, not metadata.
- **Light meta.** Type, size, modified date; optional topic tag.
- **Expand on click.** Clicking a card reveals a longer summary / key points without leaving the page.

### Styling

Make it genuinely attractive — something you'd be happy to present. Use a small, coherent palette and a CSS variable block at the top of the `<style>` so the whole look can be re-themed by changing a few values. Generous spacing, clear type hierarchy, subtle hover states, responsive grid. Avoid default-browser styling and avoid clutter.

### Technical constraints

- One file, self-contained. No server, no external data files required to view it.
- Never invent file contents. Every title and description must come from what you actually read. If a file couldn't be read (binary, encrypted), say so plainly on its card rather than guessing.
- Don't expose absolute system paths in the visible page.

## What good looks like

A non-technical person opens `showcase.html`, immediately understands what's in the folder, can search and filter it, and can click into anything for more — and it looks like a designed page, not a directory dump. If you handed the same folder to this skill twice with different answers to Step 2, the two pages would lead with different things.