waitsec 0.4.4 → 0.5.0

package/skills/waitsec-pagemaker/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: waitsec-pagemaker
+description: "Web page architect and layout generator for AI coding agents. Produces clean, high-conversion landing pages, readable blogs, and standalone pages without AI visual clutter or broken mobile grids."
+---
+
+# waitsec-pagemaker: Clean Web Page Architect
+
+You operate under the **waitsec-pagemaker** engineering discipline. This skill guides the agent in designing, structuring, and building complete web pages from scratch. It works hand-in-hand with [`skills/waitsec/SKILL.md`](../waitsec/SKILL.md) to keep code lean, secure, and free from AI design slop.
+
+---
+
+## Operating Mode & Role
+
+When you are asked to build a new page, template, or screen, act as an experienced product designer and clean frontend engineer. Build pages where every section, color, and spacing choice has a real purpose.
+
+## Activation Triggers
+
+Activate this skill whenever:
+- The user asks for a complete new page (for example: "build a landing page", "make a contact page", "create a blog template", "make an about me page").
+- Structuring multi-section web views or routes (`/`, `/about`, `/contact`, `/blog`, `/blog/[slug]`).
+- Writing layout containers, responsive grids, and design themes.
+
+---
+
+## Part 1: Mobile & Responsive Layout
+
+### 1. Desktop Squeezed into Mobile
+
+* **The Bad Habit:** Creating a wide desktop layout with 3 or 4 columns, and letting it shrink into a narrow phone screen without changing the structure.
+* **The Problem:** Cards become 70px wide, images get clipped, and text squishes into narrow vertical strips.
+* **Why It Fails:** People cannot tap buttons without hitting neighboring elements by accident, and reading squished text causes instant eye strain. Users assume the site is broken on mobile.
+* **Clean Fix:** Change the layout to a single vertical stack on mobile (`grid-cols-1` or `flex-col`). Only expand into 2 columns on tablets, and 3 or 4 columns on large desktop screens.
+* **The Waitsec Way:** Mobile is a standalone layout, not a desktop layout squeezed down. Build for the small phone screen first, then add columns only when the screen width genuinely allows it.
+
+### 2. Breakpoints Based on Device Names
+
+* **The Bad Habit:** Hardcoding arbitrary media query breakpoints because "that is the iPhone 14 size" or "that is the iPad size".
+* **The Problem:** The design breaks whenever a user views it on a slightly different screen, a split-screen browser, or an Android phone with different pixel dimensions.
+* **Why It Fails:** Phone models and tablet sizes change every single year. Tying layout rules to specific device names creates fragile code that breaks on future devices.
+* **Clean Fix:** Place breakpoints where your content naturally begins to feel cramped. Narrow your browser window slowly. The moment text lines feel too short or cards feel crowded, that exact width is your breakpoint.
+* **The Waitsec Way:** Design around your content, not around phone marketing specs. Let the content dictate when a layout needs to shift.
+
+### 3. Mobile as a Late Patch
+
+* **The Bad Habit:** Writing 500 lines of desktop CSS first, then adding a tiny 10-line media query at the very bottom to patch the worst mobile bugs.
+* **The Problem:** The mobile layout is full of inherited desktop rules that cause horizontal scrolling, massive font sizes, and awkward margins.
+* **Why It Fails:** A patch only fixes the bug you noticed today. It leaves twenty other mobile glitches that real visitors see right away.
+* **Clean Fix:** Write base styles for mobile viewports first (mobile-first). Add media queries (`min-width`) to enhance the design as the screen gets wider.
+* **The Waitsec Way:** A web page is mobile by default. Desktop is an enhancement, not the original starting point.
+
+### 4. The Two-State Extreme
+
+* **The Bad Habit:** Defining only two states: a tiny 1-column mobile stack, and an ultra-wide 4-column desktop grid, with nothing in between.
+* **The Problem:** On tablets, iPads, and small laptops (roughly 600px to 1024px), the page either looks like a ridiculously stretched phone stack or a crowded desktop grid.
+* **Why It Fails:** Millions of visitors use tablets and mid-sized screens. Treating the web as only "small phone" or "giant monitor" ruins the experience for mid-tier devices.
+* **Clean Fix:** Use a three-tier progression: 1 column on phone, 2 columns on tablet (`md:grid-cols-2`), and 3 or 4 columns on desktop (`lg:grid-cols-3` or `xl:grid-cols-4`).
+* **The Waitsec Way:** The web is a continuous sliding scale of widths. Test the entire range by dragging your window width from 320px up to 1440px.
+
+### 5. Horizontal Page Overflow
+
+* **The Bad Habit:** Setting fixed widths like `width: 650px` or `min-w-[500px]` on main containers, or letting code blocks and tables stretch off the screen.
+* **The Problem:** The entire page wobbles left and right on mobile, and text disappears past the right edge of the screen.
+* **Why It Fails:** Horizontal scrolling on a vertical web page is frustrating. Users lose their scroll position and cannot read sentences properly.
+* **Clean Fix:** Never set fixed pixel widths on layout containers. Use fluid widths like `w-full max-w-5xl mx-auto px-4`. Wrap tables and code blocks in `overflow-x-auto`.
+* **The Waitsec Way:** If content spills past the viewport width, the layout is broken. Zero horizontal page scrolling on mobile screens.
+
+---
+
+## Part 2: Scale, Sizing & Human Touch
+
+### 1. Giant Desktop Spacing on Phones
+
+* **The Bad Habit:** Leaving desktop padding (`py-24 px-16`) and huge gaps (`gap-12`) active on mobile screens.
+* **The Problem:** A single hero section takes up three full screen scrolls on a phone before the user even sees the first sentence of real content.
+* **Why It Fails:** Phone screens have limited space. Massive empty gaps make users feel like the app is empty or poorly built.
+* **Clean Fix:** Drop section padding on mobile to `py-10 px-4`. Scale up to `md:py-16` and `lg:py-24` as the screen widens.
+* **The Waitsec Way:** Spacing must respect the physical canvas in the user's hand. Small screen means compact, breathable spacing.
+
+### 2. Tiny Tap Targets That Fingers Cannot Hit
+
+* **The Bad Habit:** Making buttons, links, and icons 20px by 20px with no padding on mobile.
+* **The Problem:** Touch targets are too small for real human fingers. Users tap a link and accidentally hit a delete button or open the wrong menu.
+* **Why It Fails:** Unlike a mouse pointer with pixel precision, human thumbs cover roughly 44 to 48 pixels of screen space. Small targets cause mis-clicks and rage quits.
+* **Clean Fix:** Every clickable element on mobile must have an interactive touch target of at least 44px by 44px. Add invisible padding (`p-2.5`) if the visual icon is small.
+* **The Waitsec Way:** If a real human thumb cannot comfortably tap a button on the first attempt, the UI is not finished.
+
+### 3. Full Screen 100vh Sections on Mobile
+
+* **The Bad Habit:** Setting hero sections or cards to `height: 100vh` on mobile phones.
+* **The Problem:** When the browser address bar slides in and out during scrolling, the screen jumps up and down violently. Content gets cut off at the bottom.
+* **Why It Fails:** Mobile browsers constantly resize `100vh` as the user scrolls. It makes the site feel jittery and cuts off primary CTA buttons under the bottom navigation bar.
+* **Clean Fix:** Use `min-h-[85vh]` or `min-h-screen` with `dvh` units (`min-h-[100dvh]`), and let content flow naturally with comfortable padding.
+* **The Waitsec Way:** Never lock mobile heights strictly. Let the text and buttons define the natural height of the section.
+
+### 4. Fixed Font Sizes That Wrap Awkwardly
+
+* **The Bad Habit:** Using fixed `font-size: 48px` on main headlines across all screen sizes.
+* **The Problem:** A single word takes up three lines on a phone, creating broken hyphenated words and pushed-down content.
+* **Why It Fails:** Big desktop typography looks bold on a monitor, but becomes unreadable on a phone screen.
+* **Clean Fix:** Scale typography down on mobile: `text-2xl sm:text-4xl lg:text-5xl`, or use fluid type with CSS `clamp()`.
+* **The Waitsec Way:** Headlines must fit the natural reading rhythm of a human being on any device.
+
+---
+
+## Part 3: Visual Restraint & Color Discipline
+
+### 1. Generic AI Purple Gradients
+
+* **The Bad Habit:** Splashing blue-to-purple, cyan-to-pink, or rainbow gradients across backgrounds, buttons, and text headlines.
+* **The Problem:** The design looks identical to every lazy AI template generated in the last two years.
+* **Why It Fails:** It shows that the project has no real brand identity. Visitors recognize the AI aesthetic immediately and question the product's credibility.
+* **Clean Fix:** Use clean, solid neutral backgrounds (clean whites, subtle grays, or solid dark tones). Pick one deliberate accent color for primary actions.
+* **The Waitsec Way:** Good design is built on hierarchy, not colorful glows. Restraint makes a page look confident and professional.
+
+### 2. Blur and Glassmorphism Everywhere
+
+* **The Bad Habit:** Putting `backdrop-blur` and semi-transparent frosted glass layers on the navbar, every card, modal, and footer at once.
+* **The Problem:** When every element is transparent and blurry, there is no solid ground plane. Background text bleeds through cards, making reading painful.
+* **Why It Fails:** If everything is elevated glass, nothing stands out as important. Contrast drops and accessibility fails.
+* **Clean Fix:** Keep background surfaces solid. If you use frosted glass, limit it to at most one element (like a sticky top navbar). Everything else stays matte and solid.
+* **The Waitsec Way:** Elevation should be functional, not decorative. Use solid layers to keep text crisp and clear.
+
+### 3. Pill Shapes on Everything
+
+* **The Bad Habit:** Giving 9999px border-radius (`rounded-full`) to every button, card, modal, badge, and input field.
+* **The Problem:** The UI loses visual distinction. A button looks like a badge, an input looks like a search pill, and cards look bubbly and childish.
+* **Why It Fails:** Inconsistent or exaggerated roundness removes the professional structure of an interface.
+* **Clean Fix:** Pick a clean, consistent border-radius (such as `rounded-md` or `rounded-lg`) for cards and inputs. Reserve pill shapes only for small tags or badges if needed.
+* **The Waitsec Way:** Keep shapes intentional. Buttons should look like buttons, and cards should look like cards.
+
+### 4. Overly Soft Floating Shadows
+
+* **The Bad Habit:** Adding huge, diffused drop-shadows to every container so that every single box feels like it is floating 50px off the screen.
+* **The Problem:** The entire page looks blurry, lacks sharp borders, and loses visual structure.
+* **Why It Fails:** Shadows should communicate that an element is physically lifted (like a dropdown menu or modal). When every flat card has a giant shadow, depth loses all meaning.
+* **Clean Fix:** Use crisp, subtle borders (`border border-neutral-200 dark:border-neutral-800`) to define cards. Reserve shadows for floating elements like dropdowns and modals.
+* **The Waitsec Way:** Flat surfaces with clear borders age better and look cleaner than fake floating shadows.
+
+### 5. Technical Background Dot Grids
+
+* **The Bad Habit:** Putting blueprint lines, graph paper grids, or repeating dot matrices behind hero sections just to make the site look "techy".
+* **The Problem:** The grid competes with the text, creates visual noise, and looks like a generic developer boilerplate template.
+* **Why It Fails:** It adds visual clutter without delivering any product information.
+* **Clean Fix:** Use a clean, solid background. Let your product screenshots, headlines, and real code snippets provide the visual interest.
+* **The Waitsec Way:** Never use background wallpaper to compensate for a weak value proposition. State what the product does cleanly.
+
+---
+
+## Part 4: Human Readability & Accessibility
+
+### 1. Low-Contrast Faint Gray Text
+
+* **The Bad Habit:** Using light gray text (`#999999` or `#aaaaaa`) on white backgrounds because it looks "modern and soft".
+* **The Problem:** The text is almost invisible in sunlight, on budget monitors, or to anyone with mild vision impairment.
+* **Why It Fails:** Contrast is not an optional aesthetic choice. If people cannot read your words without squinting, they will close the tab.
+* **Clean Fix:** Ensure all body text has at least a 4.5:1 contrast ratio against the background. Use dark neutral colors (like `#171717` on `#ffffff`, or `#f5f5f5` on `#0a0a0a`).
+* **The Waitsec Way:** Readability always beats subtle styling. Text exists to be read clearly.
+
+### 2. Text Over Busy Photos Without Darkening
+
+* **The Bad Habit:** Placing white text directly over a colorful photo or a bright hero graphic.
+* **The Problem:** In bright areas of the photo, the white text completely disappears.
+* **Why It Fails:** Even if the text looks readable on your personal monitor, it breaks whenever screen brightness or device color balance changes.
+* **Clean Fix:** Add a solid dark overlay (`bg-black/60`) or place the text in a solid container next to the image instead of on top of it.
+* **The Waitsec Way:** Never gamble with readability over unpredictable background images.
+
+### 3. Missing Keyboard Focus Rings
+
+* **The Bad Habit:** Removing focus outlines with `outline: none` because the browser blue ring looks "ugly" to designers.
+* **The Problem:** Users navigating with the keyboard (Tab key) have zero clue where their cursor is on the screen.
+* **Why It Fails:** It locks out keyboard-only users, power users who love shortcuts, and anyone using assistive technology.
+* **Clean Fix:** Replace the default ring with a custom high-contrast focus ring: `focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-neutral-900`.
+* **The Waitsec Way:** An interface that cannot be used with a keyboard is an incomplete interface.
+
+---
+
+## Part 5: Page Archetypes & Blueprint Routing
+
+When the user asks for a specific type of page, check its dedicated reference guide:
+
+### 1. Marketing & Conversion Pages
+* **Includes:** SaaS homepages, landing pages, product launch screens.
+* **Key Blueprint:** Clear hero statement, problem vs solution, key feature cards, social proof, and a single high-contrast primary CTA.
+* *Detailed Guide:* [`skills/waitsec-pagemaker/references/landing-page.md`](./references/landing-page.md)
+
+### 2. Editorial & Content Pages
+* **Includes:** Blog catalogs, single article readers, changelogs, docs.
+* **Key Blueprint:** Comfortable reading line length (60 to 75 characters per line), clean typography rhythm, clear subheadings, and distraction-free reading.
+* *Detailed Guides:*
+  - Blog Index: [`skills/waitsec-pagemaker/references/blog-index.md`](./references/blog-index.md)
+  - Single Article: [`skills/waitsec-pagemaker/references/article-single.md`](./references/article-single.md)
+
+### 3. Standalone Single Pages
+* **Includes:** Contact forms, About Me / Portfolio, simple profile pages.
+* **Key Blueprint:** Single-purpose layouts, minimal input forms (name, email, message) with instant validation states, and direct project links.
+* *Detailed Guides:*
+  - Contact Page: [`skills/waitsec-pagemaker/references/contact-page.md`](./references/contact-page.md)
+  - About / Portfolio: [`skills/waitsec-pagemaker/references/about-me.md`](./references/about-me.md)
+
+---
+
+## Pre-Flight Checklist
+
+Before returning generated page code to the user, verify:
+
+- [ ] Does the mobile layout reflow into a clean vertical stack without horizontal scrolling?
+- [ ] Are clickable buttons and links at least 44px by 44px on mobile viewports?
+- [ ] Are generic AI gradients, floating shadows, and all-pill buttons removed in favor of clean solid styling?
+- [ ] Does all text meet comfortable readability standards with high contrast against the background?
+- [ ] Is there exactly one primary Call to Action (CTA) per marketing section?

package/skills/waitsec-pagemaker/references/about-me.md

@@ -0,0 +1,122 @@
+# About Me & Portfolio Blueprint (waitsec-pagemaker)
+
+Use this guide when creating a personal developer portfolio, founder bio, or engineer profile page. It ensures the page highlights real-world work and technical competence without cheesy resume clichés.
+
+---
+
+## Complete Page Anatomy & Responsive Flow
+
+### 1. Intro Snapshot (The Header)
+* **Desktop (1024px+):** Side-by-side layout. Profile photo or avatar on the left (80px to 96px), short 2-sentence bio on the right, followed by status badge (e.g. "Available for projects") and direct social links (GitHub, X, LinkedIn, Email).
+* **Mobile (<768px):** Stacks vertically. Avatar centered or left-aligned with clean text underneath. Keep intro under 50 words so visitors see projects without scrolling endlessly.
+
+### 2. Selected Projects Showcase
+* **Desktop:** 2-column grid (`md:grid-cols-2 gap-6`). Each card highlights 1 tangible problem solved, tech stack badges, live demo link, and GitHub repository link.
+* **Mobile:** 1-column vertical stack (`grid-cols-1 gap-6`). Full-width cards with large touch targets for external links.
+
+### 3. Career & Experience Timeline
+* **Desktop & Mobile:** Single vertical line aligned to the left edge with bullet dots. Never use an alternating left-and-right zigzag timeline that breaks on mobile.
+* Content per role: Company name, job title, start/end dates, and 2 concise bullet points detailing measurable engineering impact.
+
+### 4. Technical Skills & Tools
+* **Desktop & Mobile:** Simple, clean text pills organized by category (Languages, Frameworks, Cloud & Databases, Tooling).
+* Absolutely zero animated percentage bars or fake skill ratings.
+
+### 5. Direct Reachout Section
+* A clean footer box with a prominent email link (`mailto:your@email.com`) and location timezone.
+
+---
+
+## Detailed Pitfalls & The 5-Point Rule
+
+### 1. The Fake Skill Percentage Bars
+
+* **The Bad Habit:** Adding animated progress bars that claim "JavaScript: 95%", "Docker: 80%", "Teamwork: 90%".
+* **The Problem:** Percentage numbers on human skills mean literally nothing. What does 95% of JavaScript even mean? Does it mean you wrote the V8 engine?
+* **Why It Fails:** Senior hiring managers and engineering leads instantly recognize skill bars as amateur filler. It damages technical credibility.
+* **Clean Fix:** Group skills into clear categorical text badges, or list them alongside the real projects where you actually used them:
+  ```html
+  <div class="space-y-4">
+    <h3 class="text-sm font-semibold uppercase tracking-wider text-neutral-500">Core Technologies</h3>
+    <div class="flex flex-wrap gap-2">
+      <span class="px-3 py-1 bg-neutral-100 dark:bg-neutral-800 text-neutral-700 dark:text-neutral-300 text-xs rounded-md">TypeScript</span>
+      <span class="px-3 py-1 bg-neutral-100 dark:bg-neutral-800 text-neutral-700 dark:text-neutral-300 text-xs rounded-md">Next.js</span>
+      <span class="px-3 py-1 bg-neutral-100 dark:bg-neutral-800 text-neutral-700 dark:text-neutral-300 text-xs rounded-md">PostgreSQL</span>
+      <span class="px-3 py-1 bg-neutral-100 dark:bg-neutral-800 text-neutral-700 dark:text-neutral-300 text-xs rounded-md">Tailwind CSS</span>
+    </div>
+  </div>
+  ```
+* **The Waitsec Way:** Prove skills through projects and code, not through invented percentages.
+
+### 2. The Alternating Zigzag Timeline on Mobile
+
+* **The Bad Habit:** Creating a timeline where odd years are on the left of a center line and even years are on the right.
+* **The Problem:** On a 375px phone screen, dividing the screen in half leaves only 140px of width for text. Sentences wrap every 2 words.
+* **Why It Fails:** It looks like a tangled mess on phones, and dates collide with company names.
+* **Clean Fix:** Use a left-aligned timeline across all screen sizes. The timeline border sits strictly on the left margin:
+  ```html
+  <div class="relative border-l border-neutral-200 dark:border-neutral-800 ml-3 space-y-8">
+    <div class="relative pl-6">
+      <!-- Timeline Node Dot -->
+      <div class="absolute -left-1.5 top-1.5 w-3 h-3 bg-neutral-900 dark:bg-white rounded-full"></div>
+      <div class="text-xs text-neutral-400 font-medium">2024 - Present</div>
+      <h3 class="text-base font-bold text-neutral-900 dark:text-white mt-1">Lead Backend Engineer • Fastro</h3>
+      <p class="text-sm text-neutral-600 dark:text-neutral-400 mt-2">
+        Redesigned API gateway architecture, reducing response latency by 35%.
+      </p>
+    </div>
+  </div>
+  ```
+* **The Waitsec Way:** Keep mobile layouts simple. A single vertical line reads naturally from top to bottom on any device.
+
+### 3. Vague Project Cards With No Live Proof
+
+* **The Bad Habit:** Listing 8 generic project cards with titles like "E-Commerce App" and "Task Manager", with no live demo and no source code link.
+* **The Problem:** The visitor has no way to verify whether the project was actually built or just copied from a YouTube tutorial.
+* **Why It Fails:** Recruiters and clients want to see live code and architecture decisions. Dead links cause visitors to bounce.
+* **Clean Fix:** Showcase 3 or 4 high-quality projects. For each project, explain the technical problem it solved, provide a live link, and link the GitHub repository:
+  ```html
+  <div class="p-6 border border-neutral-200 dark:border-neutral-800 rounded-xl hover:border-neutral-400 transition-colors">
+    <div class="flex items-center justify-between">
+      <h3 class="text-lg font-bold text-neutral-900 dark:text-white">Waitsec CLI</h3>
+      <div class="flex items-center gap-3 text-sm">
+        <a href="https://github.com/..." class="text-neutral-500 hover:text-neutral-900">GitHub &rarr;</a>
+        <a href="https://waitsec.dev" class="text-neutral-900 dark:text-white font-medium">Live &rarr;</a>
+      </div>
+    </div>
+    <p class="text-sm text-neutral-600 dark:text-neutral-400 mt-2">
+      Lightweight engineering discipline tool for AI coding agents with zero external dependencies.
+    </p>
+    <div class="flex gap-2 mt-4 text-xs font-mono text-neutral-500">
+      <span>Node.js</span> • <span>ESM</span> • <span>CLI</span>
+    </div>
+  </div>
+  ```
+* **The Waitsec Way:** Fewer projects with real code beats twenty shallow placeholders.
+
+### 4. Hiding the Contact Email Behind a Wall
+
+* **The Bad Habit:** Hiding the contact option behind a broken third-party contact form with 8 mandatory fields.
+* **The Problem:** The user just wants to send a quick freelance inquiry or collaboration email, but the form errors out or sends into a void.
+* **Why It Fails:** Friction kills inbound opportunities. If people cannot easily email you, they will message someone else.
+* **Clean Fix:** Always provide a direct, visible email address with a clickable `mailto:` link:
+  ```html
+  <div class="p-8 bg-neutral-50 dark:bg-neutral-900 rounded-2xl border border-neutral-200 dark:border-neutral-800 text-center">
+    <h2 class="text-2xl font-bold">Let's build something together</h2>
+    <p class="text-neutral-600 dark:text-neutral-400 mt-2 text-sm">Currently open to select contract and advisory roles.</p>
+    <a href="mailto:hello@example.com" class="inline-block mt-4 px-6 py-3 bg-neutral-900 text-white dark:bg-white dark:text-neutral-900 font-medium rounded-lg">
+      hello@example.com
+    </a>
+  </div>
+  ```
+* **The Waitsec Way:** Remove barriers between you and your audience. Make reaching out as easy as clicking one button.
+
+---
+
+## Pre-Flight Checklist for About Me & Portfolio Pages
+
+- [ ] Are all fake animated skill percentage bars removed in favor of clean categorical tags?
+- [ ] Is the career timeline strictly left-aligned with zero alternating zigzag layouts?
+- [ ] Does every featured project have a working live link or public repository link?
+- [ ] Is there a direct, clickable `mailto:` link clearly visible on the page?
+- [ ] Do project cards collapse into a clean single vertical stack on mobile screens?

package/skills/waitsec-pagemaker/references/article-single.md

@@ -0,0 +1,104 @@
+# Single Article & Reading View Blueprint (waitsec-pagemaker)
+
+Use this guide when creating a single article view, blog post template, or markdown documentation page. It ensures readers can focus comfortably on long-form text without eye strain on any device.
+
+---
+
+## Complete Page Anatomy & Responsive Flow
+
+### 1. Top Navigation & Context
+* **Desktop & Mobile:** A clean back link at the top (for example: "← Back to all articles"). Keeps the reader oriented so they never feel lost in deep content.
+
+### 2. Article Header & Metadata
+* **Category Badge:** Small tag indicating the topic (e.g. "Tutorial" or "Architecture").
+* **Main Title (`<h1>`):** Bold, clear, and prominent. Use `text-3xl sm:text-4xl lg:text-5xl font-bold tracking-tight`.
+* **Author & Meta Row:** Author avatar, full name, publication date, and estimated reading time (e.g. "Sep 12, 2026 • 6 min read").
+
+### 3. Reading Container & Measure
+* **Desktop (1024px+):** Constrain the reading container to `max-w-prose` or `max-w-3xl mx-auto px-4`. Never allow lines of text to stretch wider than 70 to 75 characters per line.
+* **Mobile (<768px):** Full width with generous side padding (`px-4 sm:px-6`). Use comfortable 16px or 17px body text with relaxed line-height.
+
+### 4. Rich Media & Code Elements
+* **Code Blocks:** Dark background, syntax highlighting, monospace font, with an explicit `overflow-x-auto` wrapper so long lines of code scroll horizontally instead of blowing up the mobile page.
+* **Blockquotes:** Indented with a 3px solid neutral accent border on the left and slightly italicized text.
+* **Tables:** Always wrapped in a container with `overflow-x-auto` to allow smooth horizontal scrolling on phones.
+
+### 5. Article Footer & Engagement
+* **Author Card:** 2-sentence bio with direct links to GitHub or social profiles.
+* **Next / Previous Navigation:** 2-column cards at the bottom of the article linking to the next piece of content.
+
+---
+
+## Detailed Pitfalls & The 5-Point Rule
+
+### 1. The 1920px Full-Width Reading Nightmare
+
+* **The Bad Habit:** Letting article paragraphs stretch 100% across the full width of an ultrawide desktop monitor.
+* **The Problem:** Lines of text become 180 characters long. Readers have to physically turn their heads from left to right to finish a single sentence.
+* **Why It Fails:** Human eyes lose track of the next line when scanning sentences longer than 75 characters. Readers get disoriented, skip paragraphs, and leave out of fatigue.
+* **Clean Fix:** Strictly constrain the text wrapper using `max-w-3xl` or `max-w-prose` with centered margins:
+  ```html
+  <main class="w-full max-w-3xl mx-auto px-4 sm:px-6 py-12">
+    <article class="prose prose-neutral dark:prose-invert max-w-none">
+      <p class="text-base sm:text-lg leading-relaxed text-neutral-800">
+        Paragraph text stays comfortable and readable across any screen size.
+      </p>
+    </article>
+  </main>
+  ```
+* **The Waitsec Way:** Reading comfort is non-negotiable. Cap line length between 60 and 75 characters per line on all devices.
+
+### 2. Code Blocks That Break Mobile Viewports
+
+* **The Bad Habit:** Rendering `<pre><code>` blocks with default styling or `white-space: pre` without horizontal overflow protection.
+* **The Problem:** A single long line of code (like a long URL or terminal command) forces the entire mobile page to expand to 900px width.
+* **Why It Fails:** The entire website starts wobbling sideways on mobile phones. Users have to pinch-to-zoom just to recenter the text.
+* **Clean Fix:** Always wrap code blocks with `overflow-x-auto` and specify a clean monospace font stack:
+  ```html
+  <div class="my-6 rounded-xl bg-neutral-900 text-neutral-100 p-4 overflow-x-auto border border-neutral-800">
+    <pre class="font-mono text-sm leading-normal"><code>const response = await fetch("https://api.example.com/v1/data/endpoint/users");</code></pre>
+  </div>
+  ```
+* **The Waitsec Way:** Code snippets must adapt to the screen, not break the screen. Contain horizontal overflow strictly inside the code block.
+
+### 3. Markdown Tables Clipping Columns on Phones
+
+* **The Bad Habit:** Inserting a 5-column data table inside an article and expecting it to fit on a 375px phone screen.
+* **The Problem:** The rightmost 3 columns get permanently cut off, or the text inside table cells squishes into unreadable single-letter stacks.
+* **Why It Fails:** Tables cannot shrink below the width of their text. When table boundaries are locked, readers miss crucial data.
+* **Clean Fix:** Wrap every markdown table in an explicit scroll container with a visual scroll indicator:
+  ```html
+  <div class="my-6 w-full overflow-x-auto border border-neutral-200 rounded-lg">
+    <table class="w-full min-w-[500px] text-left text-sm">
+      <thead class="bg-neutral-50 border-b border-neutral-200">...</thead>
+      <tbody class="divide-y divide-neutral-200">...</tbody>
+    </table>
+  </div>
+  ```
+* **The Waitsec Way:** Tables are inherently wide. Always give them dedicated horizontal scroll containers so the main page stays rock solid.
+
+### 4. Header Crowding & Suffocating Line-Height
+
+* **The Bad Habit:** Using tight line-height (`leading-tight`) on body paragraphs and putting zero top margin above `<h2>` and `<h3>` subheadings.
+* **The Problem:** Subheadings look glued to the paragraph above them, and dense blocks of text look like intimidating walls of gray ink.
+* **Why It Fails:** Reading on a screen is tiring. Without generous breathing room, readers skim and bounce.
+* **Clean Fix:** Give subheadings double the margin above them (`mt-10 mb-4`), and use relaxed line height (`leading-relaxed` or `line-height: 1.75`) for body text:
+  ```html
+  <h2 class="text-2xl font-bold tracking-tight text-neutral-900 mt-12 mb-4">
+    Core Architectural Changes
+  </h2>
+  <p class="text-base sm:text-lg leading-relaxed text-neutral-700 mb-6">
+    Notice how the generous space above makes it instantly obvious that a new topic has begun.
+  </p>
+  ```
+* **The Waitsec Way:** Visual breathing room creates typographic rhythm. Generous spacing makes complex technical content easy to absorb.
+
+---
+
+## Pre-Flight Checklist for Single Article Pages
+
+- [ ] Is the article reading width capped at `max-w-3xl` or `65-75ch` to prevent eye strain?
+- [ ] Do all code blocks and tables have `overflow-x-auto` to prevent mobile viewport wobbling?
+- [ ] Is body paragraph line-height set to relaxed (`leading-relaxed` / 1.75)?
+- [ ] Are subheadings given generous top margin (`mt-10` to `mt-12`) to separate topics clearly?
+- [ ] Is there a clear back-navigation link at the top of the article?

package/skills/waitsec-pagemaker/references/blog-index.md

@@ -0,0 +1,121 @@
+# Blog & Article Index Blueprint (waitsec-pagemaker)
+
+Use this guide when creating a blog listing, article archive, or news feed. It ensures your readers can easily discover, browse, and filter articles across phones, tablets, and wide monitors.
+
+---
+
+## Complete Page Anatomy & Responsive Flow
+
+### 1. Header & Category Bar
+* **Desktop (1024px+):** Clean page heading (e.g. "Engineering Journal"), a 1-sentence descriptor, and a horizontal row of category pills (All, Architecture, Security, Tutorials).
+* **Mobile (<768px):** Category pills sit in a smooth horizontally scrollable row (`overflow-x-auto no-scrollbar`) with 44px touch targets. Never wrap 15 category tags into four messy vertical lines.
+
+### 2. Featured / Latest Story (Hero Card)
+* **Desktop:** Wide horizontal card (spans 2 columns or full width). High-resolution cover image on the left (50% width), title, category tag, 3-line excerpt, and author metadata on the right (50% width).
+* **Mobile:** Stacks vertically. Image on top (aspect-video), followed by title, date, reading time, and excerpt.
+
+### 3. Article Stream / Card Grid
+* **Desktop Grid Option:** 3-column card grid (`lg:grid-cols-3 gap-8`).
+* **Desktop Feed Option (Substack/Medium Style):** Single centered feed (`max-w-3xl mx-auto space-y-8`). Highly recommended for tech blogs.
+* **Tablet:** 2-column grid (`md:grid-cols-2 gap-6`).
+* **Mobile:** 1-column vertical stack (`grid-cols-1 gap-6`). Every card gets full screen width with generous tap target padding.
+
+### 4. Article Card Anatomy
+Every article preview card must contain:
+1. Category badge (e.g. "Security" or "CSS").
+2. Article title (`<h2>` or `<h3>`) with clear hover underline or color shift.
+3. Reading metadata: Publication date and estimated reading time (e.g. "Sep 12, 2026 • 5 min read").
+4. Short excerpt: strictly truncated to 2 or 3 lines (`line-clamp-2` or `line-clamp-3`).
+5. Author snapshot: small 28px avatar and author name.
+
+### 5. Pagination & Page Navigation
+* **Desktop & Mobile:** Explicit page numbers or simple "Previous Page" and "Next Page" buttons.
+* Avoid infinite scroll by default so users can reach the footer and search filters comfortably.
+
+---
+
+## Detailed Pitfalls & The 5-Point Rule
+
+### 1. The Giant Image Trap on Mobile
+
+* **The Bad Habit:** Placing massive 16:9 cover images with fixed 400px heights above every single article card.
+* **The Problem:** On a phone, one single article card fills the entire screen. The user has to scroll 3 full times just to see two article titles.
+* **Why It Fails:** People browse blog indexes to scan headlines quickly. Giant thumbnail images waste mobile vertical space and burn unnecessary cellular data.
+* **Clean Fix:** Use compact thumbnail aspect ratios on mobile, or switch to a clean text-first layout where thumbnails are small squares placed on the right side:
+  ```html
+  <article class="flex flex-col sm:flex-row items-start justify-between gap-4 py-6 border-b border-neutral-200">
+    <div class="flex-1">
+      <span class="text-xs font-semibold text-neutral-500 uppercase">Architecture</span>
+      <h2 class="text-xl font-bold mt-1 hover:text-neutral-600">
+        <a href="/blog/scaling-sqlite">How We Scaled SQLite to 100k Requests</a>
+      </h2>
+      <p class="text-sm text-neutral-600 mt-2 line-clamp-2">
+        A practical walkthrough of write-ahead logging and connection pooling.
+      </p>
+      <div class="text-xs text-neutral-400 mt-3">Sep 12, 2026 • 4 min read</div>
+    </div>
+    <!-- Small thumbnail on right (tablet/desktop), hidden or compact on mobile -->
+    <div class="w-full sm:w-32 h-32 bg-neutral-100 rounded-lg overflow-hidden shrink-0">...</div>
+  </article>
+  ```
+* **The Waitsec Way:** A blog index is an index for reading. Headlines and excerpts must always take priority over decorative stock images.
+
+### 2. The Wrapping Category Pill Explosion
+
+* **The Bad Habit:** Displaying 10 or 15 topic tags ("JavaScript", "Python", "Database", "Design", "DevOps") as inline flex pills that wrap into 4 uneven rows on mobile.
+* **The Problem:** The top third of the phone screen is consumed by a wall of colorful tag pills, pushing the actual articles out of view.
+* **Why It Fails:** It looks messy, creates visual clutter, and forces mobile users to scroll before they even see an article.
+* **Clean Fix:** Use a single horizontal scrolling row on mobile, or use a clean dropdown selector:
+  ```html
+  <div class="flex items-center gap-2 overflow-x-auto pb-2 -mx-4 px-4 sm:mx-0 sm:px-0 scrollbar-none">
+    <button class="px-4 py-2 text-xs font-semibold bg-neutral-900 text-white rounded-full shrink-0">All Posts</button>
+    <button class="px-4 py-2 text-xs font-semibold bg-neutral-100 text-neutral-700 rounded-full shrink-0 hover:bg-neutral-200">Security</button>
+    <button class="px-4 py-2 text-xs font-semibold bg-neutral-100 text-neutral-700 rounded-full shrink-0 hover:bg-neutral-200">Architecture</button>
+    <button class="px-4 py-2 text-xs font-semibold bg-neutral-100 text-neutral-700 rounded-full shrink-0 hover:bg-neutral-200">Frontend</button>
+  </div>
+  ```
+* **The Waitsec Way:** Protect vertical mobile screen space. Keep navigation filters on a single horizontal plane.
+
+### 3. The Uncontrollable Infinite Scroll
+
+* **The Bad Habit:** Loading 20 more articles automatically every time the user scrolls near the bottom of the page, with zero option to stop.
+* **The Problem:** The footer, contact links, copyright, and RSS feed links become completely unreachable because the page keeps jumping and inserting new items.
+* **Why It Fails:** Users get trapped in an endless scroll. If they want to find an older article or visit the privacy policy, they are blocked.
+* **Clean Fix:** Use clean, explicit pagination buttons or a manual "Load More Articles" button that only triggers when clicked:
+  ```html
+  <div class="flex items-center justify-between pt-10 border-t border-neutral-200">
+    <a href="?page=1" class="px-4 py-2 text-sm font-medium border border-neutral-300 rounded-lg hover:bg-neutral-50">
+      &larr; Newer Posts
+    </a>
+    <span class="text-xs text-neutral-500">Page 2 of 8</span>
+    <a href="?page=3" class="px-4 py-2 text-sm font-medium border border-neutral-300 rounded-lg hover:bg-neutral-50">
+      Older Posts &rarr;
+    </a>
+  </div>
+  ```
+* **The Waitsec Way:** Put the user in total control of their navigation. Never trap users with automatic background triggers.
+
+### 4. The Tiny Unreadable Date Stamp
+
+* **The Bad Habit:** Showing dates in 9px light gray text (`text-[9px] text-gray-300`), making it nearly invisible against white backgrounds.
+* **The Problem:** Readers have no idea whether an engineering tutorial was written yesterday or seven years ago.
+* **Why It Fails:** Outdated software tutorials waste hours of developer time. Freshness is one of the most critical decision factors for technical articles.
+* **Clean Fix:** Display dates and reading times in clear, readable 12px or 13px neutral text with proper contrast:
+  ```html
+  <div class="flex items-center gap-2 text-xs text-neutral-500 font-medium">
+    <time datetime="2026-09-12">Sep 12, 2026</time>
+    <span>•</span>
+    <span>4 min read</span>
+  </div>
+  ```
+* **The Waitsec Way:** Metadata gives context to content. Make publication dates and reading times clearly legible.
+
+---
+
+## Pre-Flight Checklist for Blog Index Pages
+
+- [ ] Do article cards stack into a clean single column on mobile without horizontal scrolling?
+- [ ] Are category filter pills contained in a single horizontal scrollable row on mobile?
+- [ ] Are article excerpts clamped to 2 or 3 lines so cards maintain a predictable height?
+- [ ] Can visitors comfortably reach the footer without being trapped by automatic infinite scroll?
+- [ ] Are publication dates and reading estimates clearly legible with strong contrast?