waitsec 0.4.5 → 0.5.2

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

@@ -0,0 +1,161 @@
+# 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.
+
+---
+
+## SEO, GEO & Structured Data (About & Portfolio)
+
+- Title: full name plus role, for example "Ilyas Mukhlisin, Backend Engineer", about 50 to 60 characters.
+- Meta description: who you are, what you build, and how to reach you, about 140 to 160 characters.
+- One `<h1>` with your name.
+- Server-render the bio, project list, and contact email.
+- Add `sameAs` links to GitHub, LinkedIn, and X so engines can confirm the identity.
+- Describe each project with a concrete outcome, not a vague claim, so answer engines have something to quote.
+
+### JSON-LD for an About or Portfolio Page
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "ProfilePage",
+  "url": "https://example.com/about",
+  "mainEntity": {
+    "@type": "Person",
+    "name": "Your Name",
+    "jobTitle": "Backend Engineer",
+    "url": "https://example.com",
+    "image": "https://example.com/images/avatar.jpg",
+    "worksFor": { "@type": "Organization", "name": "Fastro" },
+    "knowsAbout": ["Laravel", "PostgreSQL", "API design"],
+    "sameAs": [
+      "https://github.com/username",
+      "https://www.linkedin.com/in/username"
+    ]
+  }
+}
+</script>
+```
+
+When the about page is part of a company site, add an `Organization` node and connect it with `worksFor` or `memberOf`.
+
+---
+
+## 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?
+- [ ] Is there a valid ProfilePage with Person data, including sameAs links to real profiles?

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

@@ -0,0 +1,168 @@
+# 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.
+
+---
+
+## SEO, GEO & Structured Data (Article Page)
+
+- Title: the article headline, optionally with the site name, about 50 to 60 characters.
+- Meta description: an honest summary of the article, about 140 to 160 characters.
+- One `<h1>` that matches the headline.
+- State the article's main answer in the first paragraph, before background detail.
+- Use question-shaped `<h2>` and `<h3>` headings, each followed by a direct answer.
+- Show `datePublished` and `dateModified` visibly near the top, and keep both in the schema.
+- Give the cover image descriptive alt text and an absolute URL.
+- Keep the article body server-rendered.
+
+### JSON-LD for an Article Page
+
+The `Article` type is safe, while `BlogPosting` is more specific for blog posts. Use the one that matches the page. Add `BreadcrumbList` so search engines can show the path.
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@graph": [
+    {
+      "@type": "BlogPosting",
+      "headline": "Why Errors Appear as Codes and How to Read Them",
+      "description": "A short, honest summary of what the article explains.",
+      "image": "https://example.com/storage/blog-thumbnails/cover.webp",
+      "datePublished": "2026-09-04T09:56:00+07:00",
+      "dateModified": "2026-09-04T09:56:00+07:00",
+      "author": {
+        "@type": "Person",
+        "name": "Ilyas Mukhlisin",
+        "url": "https://example.com/about"
+      },
+      "publisher": {
+        "@type": "Organization",
+        "name": "Fikselink",
+        "logo": {
+          "@type": "ImageObject",
+          "url": "https://example.com/images/logo.png"
+        }
+      },
+      "mainEntityOfPage": {
+        "@type": "WebPage",
+        "@id": "https://example.com/blog/post/why-errors-appear-as-codes"
+      },
+      "articleSection": "Technology",
+      "keywords": "error code, HTTP status code, how to read errors"
+    },
+    {
+      "@type": "BreadcrumbList",
+      "itemListElement": [
+        { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com" },
+        { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://example.com/blog" },
+        { "@type": "ListItem", "position": 3, "name": "Why Errors Appear as Codes", "item": "https://example.com/blog/post/why-errors-appear-as-codes" }
+      ]
+    }
+  ]
+}
+</script>
+```
+
+---
+
+## 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?
+- [ ] Does the first paragraph answer the main question directly?
+- [ ] Is there a valid BlogPosting or Article block with author, publisher, and ISO 8601 dates?

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

@@ -0,0 +1,167 @@
+# 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.
+
+---
+
+## SEO, GEO & Structured Data (Blog Index)
+
+- Title: blog name plus its topic focus, about 50 to 60 characters.
+- Meta description: what the blog covers and who it helps, about 140 to 160 characters.
+- One `<h1>` for the index title, and `<h2>` for each article title.
+- Server-render article titles, excerpts, and dates so crawlers read them without JavaScript.
+- Link each card with the article title as anchor text, not "read more".
+- Point a canonical tag at the canonical page of the listing, and keep paginated pages self-canonical.
+- Keep the publish date and reading time visible, because freshness matters to both search and answer engines.
+
+### JSON-LD for a Blog Index
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "CollectionPage",
+  "name": "Engineering Journal",
+  "url": "https://example.com/blog",
+  "description": "Articles about software architecture, security, and frontend engineering.",
+  "isPartOf": { "@type": "WebSite", "url": "https://example.com" },
+  "mainEntity": {
+    "@type": "ItemList",
+    "itemListElement": [
+      {
+        "@type": "ListItem",
+        "position": 1,
+        "url": "https://example.com/blog/scaling-sqlite"
+      },
+      {
+        "@type": "ListItem",
+        "position": 2,
+        "url": "https://example.com/blog/reading-stack-traces"
+      }
+    ]
+  }
+}
+</script>
+```
+
+Use `Blog` instead of `CollectionPage` when the listing is a true blog. Include one `ListItem` per visible article, in the same order shown on the page.
+
+---
+
+## 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?
+- [ ] Does the page expose a valid CollectionPage or Blog ItemList schema?
+- [ ] Do article cards use the article title as anchor text instead of "read more"?

package/skills/waitsec-pagemaker/references/contact-page.md

@@ -0,0 +1,162 @@
+# Contact Page Blueprint (waitsec-pagemaker)
+
+Use this guide when creating a contact page, support inquiry form, or feedback screen. It ensures users can reach out smoothly on mobile and desktop without friction or broken form states.
+
+---
+
+## Complete Page Anatomy & Responsive Flow
+
+### 1. Header & Clear Expectations
+* **Desktop & Mobile:** Clear heading ("Get in Touch" or "Contact Us"), followed by an honest response estimate (e.g. "We typically respond within 24 business hours"). Setting expectations prevents users from sending repeat tickets.
+
+### 2. Form Layout & Alternative Channels (The Split)
+* **Desktop (1024px+):** 2-column layout (`grid grid-cols-1 lg:grid-cols-12 gap-12`).
+  - Left Side (7 cols): Clean form card with minimal inputs.
+  - Right Side (5 cols): Direct contact box with direct email, office address, timezone, and live status badge.
+* **Mobile (<768px):** Single vertical stack. The form appears first at the top. The direct contact details and social links appear below the form.
+
+### 3. Minimal Field Discipline
+Strictly limit input fields to what is necessary:
+1. Full Name (`<input type="text" required>`)
+2. Email Address (`<input type="email" required>`)
+3. Topic / Category (clean `<select>` dropdown or horizontal radio pills)
+4. Message (`<textarea rows="4" required>`)
+Never demand phone numbers, fax numbers, company size, or physical mailing address for a general contact form.
+
+### 4. Interactive States (Feedback Loop)
+* **Default State:** Clean borders with high contrast labels.
+* **Typing / Focus State:** High-contrast focus ring around active input (`focus-visible:ring-2 focus-visible:ring-neutral-900`).
+* **Submitting State:** The submit button disables immediately and shows a clean spinner with "Sending...".
+* **Success State:** The form disappears and displays an inline confirmation message: "Thank you! We received your message and will reply soon."
+* **Error State:** Specific field outlines turn red (`border-red-500`) with a clear error explanation directly below the field.
+
+---
+
+## Detailed Pitfalls & The 5-Point Rule
+
+### 1. The 10-Field Interrogation Form
+
+* **The Bad Habit:** Demanding full name, company name, company URL, job title, phone number, budget dropdown, industry, country, and message.
+* **The Problem:** The contact form looks like a government tax audit. On a phone, the user has to scroll through 4 screens just to find the submit button.
+* **Why It Fails:** Conversion drops by over 50% for every 2 extra fields added to a form. Mobile users will not type their corporate biography on a phone keyboard.
+* **Clean Fix:** Cut the form down to 3 essential fields: Name, Email, and Message. You can always ask follow-up questions in your reply email:
+  ```html
+  <form class="space-y-4 max-w-lg">
+    <div>
+      <label for="name" class="block text-sm font-medium text-neutral-700">Full Name</label>
+      <input type="text" id="name" required class="w-full mt-1 px-4 py-2.5 border border-neutral-300 rounded-lg focus:ring-2 focus:ring-neutral-900 outline-none">
+    </div>
+    <div>
+      <label for="email" class="block text-sm font-medium text-neutral-700">Email Address</label>
+      <input type="email" id="email" required class="w-full mt-1 px-4 py-2.5 border border-neutral-300 rounded-lg focus:ring-2 focus:ring-neutral-900 outline-none">
+    </div>
+    <div>
+      <label for="message" class="block text-sm font-medium text-neutral-700">Message</label>
+      <textarea id="message" rows="4" required class="w-full mt-1 px-4 py-2.5 border border-neutral-300 rounded-lg focus:ring-2 focus:ring-neutral-900 outline-none"></textarea>
+    </div>
+    <button type="submit" class="w-full py-3 bg-neutral-900 text-white font-medium rounded-lg hover:bg-neutral-800 transition">
+      Send Message
+    </button>
+  </form>
+  ```
+* **The Waitsec Way:** Respect user time. Ask only for what you need to start the conversation.
+
+### 2. Stripping Input Focus Outlines
+
+* **The Bad Habit:** Setting `outline: none` on inputs without replacing it with a custom focus ring.
+* **The Problem:** When a user taps or tabs into an input box, the border looks completely unchanged.
+* **Why It Fails:** The user cannot tell which field is currently active. On mobile devices with virtual keyboards, it leads to typing into the wrong box.
+* **Clean Fix:** Always provide an unmistakable focus ring:
+  ```css
+  /* Tailwind standard focus */
+  input:focus {
+    outline: none;
+    border-color: #171717;
+    box-shadow: 0 0 0 2px #171717;
+  }
+  ```
+* **The Waitsec Way:** Focus indicators guide the user's attention. Never disable them without providing a better one.
+
+### 3. The Silent Ghost Submission
+
+* **The Bad Habit:** When the user clicks "Send Message", nothing happens for 4 seconds, then the page reloads back to an empty form with no message.
+* **The Problem:** The user has no idea whether the message went through or crashed. They click the button 5 more times in frustration.
+* **Why It Fails:** Software must always confirm state changes. Silent forms destroy confidence and generate duplicate tickets.
+* **Clean Fix:** Disable the submit button immediately on click, show a loading state, and render an unmistakable success card:
+  ```html
+  <!-- Button Loading State: the spinner icon comes from the icon library, never inline SVG -->
+  <button disabled class="w-full py-3 bg-neutral-700 text-white font-medium rounded-lg cursor-not-allowed flex items-center justify-center gap-2">
+    <i data-lucide="loader-2" class="w-4 h-4 animate-spin"></i>
+    <span>Sending...</span>
+  </button>
+
+  <!-- Inline Success State -->
+  <div class="p-6 bg-green-50 border border-green-200 rounded-xl text-green-900">
+    <h3 class="font-bold">Message sent successfully!</h3>
+    <p class="text-sm mt-1 text-green-800">We received your note and will reply to your email within 24 hours.</p>
+  </div>
+  ```
+* **The Waitsec Way:** Never leave users guessing. Give immediate visual feedback for every user submission.
+
+### 4. The Trapped Mobile Keyboard Viewport Shift
+
+* **The Bad Habit:** Setting the contact container to fixed pixel height (`height: 600px`) or centering the form inside a strict `h-screen flex items-center`.
+* **The Problem:** When the virtual on-screen keyboard pops up on a phone, the viewport height shrinks by 50%. The input field gets pushed behind the keyboard, and the user cannot see what they are typing.
+* **Why It Fails:** Users cannot see their words, cannot review typos, and cannot reach the submit button.
+* **Clean Fix:** Allow the page to scroll naturally. Use `min-h-screen` instead of `h-screen`, and give the form bottom padding (`pb-24`) so the submit button easily clears the virtual keyboard:
+  ```html
+  <main class="min-h-screen py-12 px-4 sm:px-6 pb-32">
+    <div class="max-w-xl mx-auto">...</div>
+  </main>
+  ```
+* **The Waitsec Way:** Always account for virtual mobile keyboards. Content must scroll freely above the keyboard plane.
+
+---
+
+## SEO, GEO & Structured Data (Contact Page)
+
+- Title: "Contact" plus the brand name, about 50 to 60 characters.
+- Meta description: how to reach the team and the expected response time, about 140 to 160 characters.
+- One `<h1>` such as "Get in touch".
+- Print the email and address as visible text, not only inside the form, so they can be extracted.
+- Server-render the contact details, the email link, and the response-time note.
+- Keep the page focused on contact, and avoid unrelated marketing sections.
+
+### JSON-LD for a Contact Page
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "ContactPage",
+  "name": "Contact Us",
+  "url": "https://example.com/contact",
+  "mainEntity": {
+    "@type": "Organization",
+    "name": "Example Inc",
+    "url": "https://example.com",
+    "contactPoint": {
+      "@type": "ContactPoint",
+      "contactType": "customer support",
+      "email": "hello@example.com",
+      "availableLanguage": ["English", "Indonesian"]
+    }
+  }
+}
+</script>
+```
+
+Add the organization `logo` and a `PostalAddress` when a physical address is shown. Only include channels that are actually displayed on the page.
+
+---
+
+## Pre-Flight Checklist for Contact Pages
+
+- [ ] Is the form limited to 3 or 4 essential fields (Name, Email, Message)?
+- [ ] Does every input field have a visible label and high-contrast focus ring?
+- [ ] Is there an immediate loading spinner on the submit button to prevent double-submits?
+- [ ] Does the page display an unmistakable success banner after submission?
+- [ ] Is there a direct, visible email address (`mailto:`) provided as an alternative contact method?
+- [ ] Does the form have enough bottom padding to clear mobile virtual keyboards?
+- [ ] Is there a valid ContactPage with Organization and ContactPoint schema?
+- [ ] Are the email and address visible as text, not only inside the form?