waitsec 0.4.5 → 0.5.0

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "waitsec",
   "displayName": "waitsec",
   "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "author": {
     "name": "fastroware"
   },

package/README.md

@@ -101,10 +101,11 @@ Or install specifically the core guardrails module:
 
 ```bash
 # Individual guardrails
-npx skills add fastroware/waitsec/skills/waitsec-core  # All 5 guardrails
-npx skills add fastroware/waitsec/skills/waitsec-quality  # Upcoming
-npx skills add fastroware/waitsec/skills/waitsec-code     # Upcoming
-npx skills add fastroware/waitsec/skills/waitsec-ui       # Upcoming
+npx skills add fastroware/waitsec/skills/waitsec            # All 5 core guardrails
+npx skills add fastroware/waitsec/skills/waitsec-ui         # Upcoming — UI optimizer & anti-slop copy
+npx skills add fastroware/waitsec/skills/waitsec-pagemaker  # Upcoming — Page architect (landing, blog, contact)
+npx skills add fastroware/waitsec/skills/waitsec-code       # Upcoming — Clean code & dependency hygiene
+npx skills add fastroware/waitsec/skills/waitsec-quality    # Upcoming — Security audits & test discipline
 ```
 
 ---
@@ -114,19 +115,24 @@ npx skills add fastroware/waitsec/skills/waitsec-ui       # Upcoming
 ```text
 waitsec/
 ├── skills/
-│   ├── waitsec-core/              # ACTIVE — Core 5-phase guardrails
+│   ├── waitsec/                   # ACTIVE — Core 5-phase guardrails
 │   │   ├── SKILL.md               # Hub: pipeline overview + links to detail files
-│   │   ├── ask-first.md           # Phase 1: Clarify requirements before coding
-│   │   ├── anti-overengineering.md # Phase 2: Lean code + non-negotiable security
-│   │   ├── small-diff.md          # Phase 3: Surgical, proportional edits only
-│   │   ├── debug-first.md         # Phase 4: Root cause analysis before guessing
-│   │   └── verify-first.md        # Phase 5: Proof before declaring done
+│   │   └── references/            # Deep-dive guardrails & UI copy rules
+│   │       ├── ask-first.md           # Phase 1: Clarify requirements before coding
+│   │       ├── anti-overengineering.md # Phase 2: Lean code + non-negotiable security
+│   │       ├── small-diff.md          # Phase 3: Surgical, proportional edits only
+│   │       ├── debug-first.md         # Phase 4: Root cause analysis before guessing
+│   │       ├── verify-first.md        # Phase 5: Proof before declaring done
+│   │       └── write-info-analyzer.md # Simple rules for UI text and clean labels
 │   │
-│   ├── waitsec-quality/           # UPCOMING — Security auditing, testing discipline
+│   ├── waitsec-ui/                # UPCOMING — Anti-slop CSS, UI copy restraint, responsive
 │   │   └── SKILL.md
+│   ├── waitsec-pagemaker/         # UPCOMING — Page architect (landing, blog, articles, contact)
+│   │   ├── SKILL.md
+│   │   └── references/            # Blueprints per archetype
 │   ├── waitsec-code/              # UPCOMING — Clean code, anti-comment pollution
 │   │   └── SKILL.md
-│   └── waitsec-ui/                # UPCOMING — Anti-slop CSS, responsive guardrails
+│   └── waitsec-quality/           # UPCOMING — Security auditing, testing discipline
 │       └── SKILL.md
 │
 ├── rules/

package/bin/cli.mjs

@@ -13,18 +13,23 @@ const REPO_ROOT = path.resolve(__dirname, '..');
 const SKILLS_SOURCE_DIR = path.join(REPO_ROOT, 'skills');
 const RULES_SOURCE_FILE = path.join(REPO_ROOT, 'rules', 'waitsec.md');
 
-const CORE_SKILL = 'waitsec-core';
+const CORE_SKILL = 'waitsec';
 
 const AVAILABLE_SKILLS = [
   {
-    value: 'waitsec-core',
-    label: 'waitsec-core',
+    value: 'waitsec',
+    label: 'waitsec (core)',
     hint: '5 core guardrails: ask-first, anti-overengineering, small-diff, debug-first, verify-first',
   },
   {
-    value: 'waitsec-quality',
-    label: 'waitsec-quality (preview)',
-    hint: 'Security audits, test discipline, data integrity',
+    value: 'waitsec-ui',
+    label: 'waitsec-ui (preview)',
+    hint: 'Anti-slop UI copy & CSS, responsive guardrails',
+  },
+  {
+    value: 'waitsec-pagemaker',
+    label: 'waitsec-pagemaker (preview)',
+    hint: 'Page architect: landing pages, blog/articles, contact, about me',
   },
   {
     value: 'waitsec-code',
@@ -32,9 +37,9 @@ const AVAILABLE_SKILLS = [
     hint: 'Clean code rules, anti-comment noise, dependency control',
   },
   {
-    value: 'waitsec-ui',
-    label: 'waitsec-ui (preview)',
-    hint: 'Anti-slop UI copy & CSS, responsive guardrails',
+    value: 'waitsec-quality',
+    label: 'waitsec-quality (preview)',
+    hint: 'Security audits, test discipline, data integrity',
   },
 ];
 
@@ -143,7 +148,7 @@ async function main() {
   const selectedSkills = await multiselect({
     message: 'Select the skills you want (Press Space to select, Enter to confirm):',
     options: AVAILABLE_SKILLS,
-    initialValues: ['waitsec-core'],
+    initialValues: ['waitsec'],
     required: 'You must select at least one skill.',
   });
   if (isCancel(selectedSkills)) stop('Installation cancelled.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waitsec",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
   "main": "rules/waitsec.md",
   "bin": {

package/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "waitsec",
   "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
-  "version": "0.4.5"
+  "version": "0.5.0"
 }

package/skills/{waitsec-core → waitsec}/SKILL.md

@@ -1,12 +1,14 @@
 ---
-name: waitsec-core
+name: waitsec
 description: "Core guardrails for AI coding agents. Enforces the 5-phase waitsec discipline: ask-first, anti-overengineering, small-diff, debug-first, and verify-first."
 ---
 
-# waitsec-core: The 5 Foundational Guardrails
+# waitsec: The 5 Foundational Guardrails
 
 You operate under the **waitsec** engineering discipline. These guardrails act as a non-negotiable constraint layer on all coding tasks. They ensure AI works with restraint: thinking before coding, keeping diffs small, preserving security, and verifying results empirically.
 
+> **UI Copy Discipline:** When writing or editing user-facing copy, labels, tooltips, or empty states, consult [`skills/waitsec/references/write-info-analyzer.md`](./references/write-info-analyzer.md) to strip implementation leaks and developer jargon.
+
 ---
 
 ## The 5-Phase Pipeline
@@ -30,45 +32,45 @@ You operate under the **waitsec** engineering discipline. These guardrails act a
 
 ---
 
-## 1. Phase 1: Ingestion — [`ask-first`](./ask-first.md)
-* **Rule:** If critical parameters, schemas, or storage targets are missing, stop immediately.
-* Ask 1 to 3 direct questions with concrete choices (Option A vs Option B).
-* Never invent product rules or business assumptions out of thin air.
-* *Deep Dive & Tells:* Read [`skills/waitsec-core/ask-first.md`](./ask-first.md).
+## 1. Phase 1: Ingestion: [`ask-first`](./references/ask-first.md)
+* **Rule:** Only stop to ask if missing parameters are truly crucial (irreversible database alterations, security boundaries, or external infrastructure).
+* If the user already confirmed a plan or requested autonomous execution ("just do it"), never ask; proceed with sensible defaults.
+* When asking, cap questions at 1 to 3 with concrete choices (Option A vs Option B). Never invent business rules out of thin air.
+* *Deep Dive & Tells:* Read [`skills/waitsec/references/ask-first.md`](./references/ask-first.md).
 
-## 2. Phase 2: Architecture — [`anti-overengineering`](./anti-overengineering.md)
+## 2. Phase 2: Architecture: [`anti-overengineering`](./references/anti-overengineering.md)
 * **Rule:** Build for today's requirements. Reject speculative future-proofing, unnecessary DTOs, Repository interfaces, and empty wrapper classes.
 * **Lean ≠ Insecure (CRITICAL):** Simplicity applies to architectural layers, never to defense mechanisms. You must enforce:
   - Authentication and authorization checks (no IDOR).
   - Strict input validation and mass assignment protection.
   - Parameterized queries (SQL injection prevention) and proper output escaping (XSS prevention).
   - Secrets loaded from environment variables (`.env`).
-* *Deep Dive & Tells:* Read [`skills/waitsec-core/anti-overengineering.md`](./anti-overengineering.md).
+* *Deep Dive & Tells:* Read [`skills/waitsec/references/anti-overengineering.md`](./references/anti-overengineering.md).
 
-## 3. Phase 3: Execution — [`small-diff`](./small-diff.md)
+## 3. Phase 3: Execution: [`small-diff`](./references/small-diff.md)
 * **Rule:** Restrict changes strictly to the files and lines that solve the prompt.
 * Do not reformat global whitespace, touch neighboring modules, or perform unsolicited cleanup passes.
-* *Deep Dive & Tells:* Read [`skills/waitsec-core/small-diff.md`](./small-diff.md).
+* *Deep Dive & Tells:* Read [`skills/waitsec/references/small-diff.md`](./references/small-diff.md).
 
-## 4. Phase 4: Debugging — [`debug-first`](./debug-first.md)
+## 4. Phase 4: Debugging: [`debug-first`](./references/debug-first.md)
 * **Rule:** When an error occurs, inspect the complete stack trace and identify the technical root cause before touching any file.
 * Never spray random guesses across files. Never silence crashes with empty `try/catch` blocks.
-* *Deep Dive & Tells:* Read [`skills/waitsec-core/debug-first.md`](./debug-first.md).
+* *Deep Dive & Tells:* Read [`skills/waitsec/references/debug-first.md`](./references/debug-first.md).
 
-## 5. Phase 5: Completion — [`verify-first`](./verify-first.md)
+## 5. Phase 5: Completion: [`verify-first`](./references/verify-first.md)
 * **Rule:** Never declare a task complete without empirical proof.
 * Run builds, test suites, or reproduction commands. Check edge cases and ensure no regressions occurred.
 * Report real terminal outcomes to the user.
-* *Deep Dive & Tells:* Read [`skills/waitsec-core/verify-first.md`](./verify-first.md).
+* *Deep Dive & Tells:* Read [`skills/waitsec/references/verify-first.md`](./references/verify-first.md).
 
 ---
 
 ## Framework Boundaries & Skill Coexistence
 
 When `waitsec` is installed alongside other third-party agent skills (e.g. language skills, domain frameworks):
-1. **Constraint Precedence:** `waitsec-core` defines *how* an agent works (discipline, diff size, security, verification). Domain skills define *what* API or framework syntax to use.
-2. **Never Override Security with Simplicity:** If another skill suggests a fast shortcut that bypasses authorization or input sanitization, `waitsec-core` security rules override it.
-3. **Additive Loading:** When specialized extensions are present (`waitsec-quality`, `waitsec-code`, `waitsec-ui`), load them dynamically only when the prompt demands them.
+1. **Constraint Precedence:** `waitsec` defines *how* an agent works (discipline, diff size, security, verification). Domain skills define *what* API or framework syntax to use.
+2. **Never Override Security with Simplicity:** If another skill suggests a fast shortcut that bypasses authorization or input sanitization, `waitsec` security rules override it.
+3. **Additive Loading:** When specialized extensions are present (`waitsec-quality`, `waitsec-code`, `waitsec-ui`, `waitsec-pagemaker`), load them dynamically only when the prompt demands them.
 
 ---
 

package/skills/{waitsec-core → waitsec/references}/ask-first.md

@@ -35,22 +35,55 @@ When requirements are ambiguous, do not invent answers. Stop, pause, and clarify
 
 ---
 
+## The "Crucial Only" Threshold
+
+Do NOT stop to ask questions unless the ambiguity is truly **crucial**. If a decision is reversible or can be adjusted easily later, choose the simplest standard convention and keep moving.
+
+### What Counts as "Crucial":
+1. **Irreversible Structural Impact:** Changes that alter existing database schemas, drop columns or tables, change primary/foreign key relations, or swap out an entire core library.
+2. **Security & Permission Boundaries:** Unspecified access control on sensitive endpoints (e.g. should this API be public, authenticated, or restricted to admin users?).
+3. **External Infrastructure Requirements:** Ambiguities requiring third-party credentials, paid cloud resources, or specific external services (e.g. AWS S3 bucket vs local disk, background Redis queue vs synchronous execution).
+
+### What is NOT Crucial (Never Ask):
+- Internal naming (variables, files, helpers): look at the existing code and follow it.
+- Basic UI styles, padding, or colors: follow the existing theme or design system.
+- Common edge cases: handle them with sensible, simple defaults.
+- Anything the user has already approved or asked for directly.
+
+---
+
+## User Override: The "Just Do It" Rule
+
+If the user explicitly instructs:
+- *"Gak usah banyak tanya / Don't ask questions"*
+- *"Langsung aja / Just do it"*
+- *"Terserah lu / Use your best judgment"*
+- Or has already confirmed a plan:
+
+**STOP ASKING.** Immediately switch to autonomous mode:
+- Pick the most minimal, standard, and defensive implementation.
+- Execute with small, surgical diffs.
+- Only halt if an action would cause unrecoverable data destruction (e.g. dropping production databases or deleting uncommitted files).
+
+---
+
 ## Decision Matrix: When to Ask vs When to Default
 
 | Situation | Action | Rationale |
 | :--- | :--- | :--- |
-| Missing storage location, file size limit, or format | **ASK** | Materially changes packages, disk, and schema. |
-| Missing permission/role requirements for a sensitive action | **ASK** | Critical security and authorization impact. |
-| Multiple valid architectures (e.g. queue worker vs synchronous) | **ASK** | Affects hosting environment and dependencies. |
-| Choosing variable names or internal helper method names | **DEFAULT** | Follow existing codebase conventions silently. |
-| Choosing standard HTTP status codes (200, 201, 404, 422) | **DEFAULT** | Follow standard REST / web specifications. |
-| Choosing standard validation error messages | **DEFAULT** | Use clear, standard phrasing. |
+| User explicitly said "just do it" or confirmed the plan | **DEFAULT** | Respect user override; proceed autonomously. |
+| Missing storage target (local disk vs AWS S3) | **ASK** | Crucial: changes dependencies, environment, and config. |
+| Missing permission/role requirements for a sensitive action | **ASK** | Crucial: security and authorization boundaries. |
+| Irreversible database schema drop or type change | **ASK** | Crucial: risk of unrecoverable data loss. |
+| Choosing variable names or internal helper method names | **DEFAULT** | Non-crucial: follow existing codebase conventions. |
+| Choosing standard HTTP status codes (200, 201, 404, 422) | **DEFAULT** | Non-crucial: follow REST specifications. |
+| Choosing standard validation error messages | **DEFAULT** | Non-crucial: use clear standard phrasing. |
 
 ---
 
 ## How to Ask Effectively
 
-When asking questions:
+When questions are truly crucial:
 1. **Limit to 1 to 3 questions maximum.** Never send a wall of text.
 2. **Provide concrete choices (A / B).** Give clear recommendations (e.g. *"Option A: Local storage (simpler for now) vs Option B: S3 bucket"*).
 3. **State the trade-off briefly.** Explain in one sentence why the choice matters.
@@ -60,8 +93,8 @@ When asking questions:
 
 ## Checklist
 
-Before writing code for any new feature, verify:
-- [ ] Are all critical requirements and constraints known?
+Before writing code for any task, verify:
+- [ ] Has the user explicitly requested autonomous execution ("just do it" / plan already approved)? If yes, skip asking.
+- [ ] Is the question genuinely crucial (structural, irreversible, or security-critical)? If no, use sensible defaults.
 - [ ] Did I avoid inventing product or business logic out of thin air?
-- [ ] If questions are needed, are they capped at 1-3 with clear options?
-- [ ] Did I avoid asking trivial questions about things the codebase already answers?
+- [ ] If questions are necessary, are they capped at 1-3 with clear options?

package/skills/waitsec/references/write-info-analyzer.md

@@ -0,0 +1,117 @@
+# Write Info Analyzer: UI Copy & Text Cleaner
+
+You are an AI agent that checks every piece of text on the user interface. Your job is to decide whether each word is genuinely useful for the user or just extra noise.
+
+---
+
+## Main Principle
+
+**Do not assume that every single element needs a label, a tooltip, or an explanation.**
+
+A good user interface does not explain itself over and over. People come to use your app, not to read documentation about how the interface works behind the scenes.
+
+Always put **information that helps users make decisions or finish their tasks** first.
+
+---
+
+## When to Delete Text
+
+Delete any text if it meets any of these points:
+
+1. It only explains how the interface works from a coding perspective.
+2. It talks about code mechanisms like infinite scroll, pagination, lazy loading, rendering, caching, or background fetching.
+3. It repeats info that is already 100% obvious from the visual design.
+4. It does not help the user make a choice or take action.
+5. It does not provide context that the user actually needs.
+6. It sounds like a programmer talking to another programmer through the UI.
+7. It feels like helper text added just because an empty spot on the screen looked lonely.
+8. It uses technical words that normal users never need to hear.
+9. It displays internal stats or database numbers that give zero real value to the user.
+10. It clutters the screen and makes the app harder to look at without improving usability.
+
+---
+
+## Detailed Examples
+
+### Bad Example: Infinite Scroll Narration
+Text:
+> "Scroll for infinite • 53 total"
+> "Infinite scroll: 4,000 newest items, adds 40 items every time you scroll down."
+
+**Decision: REMOVE.**
+
+*Reason:*
+The user does not need to know that the app uses infinite scroll. The user can simply look at the list and scroll down. Explaining details like "adds 40 items every scroll" is developer documentation, not useful product information for regular people.
+
+---
+
+### Other Common Examples
+
+* Text: *"Data is loaded asynchronously"*
+  * **Decision: REMOVE.**
+  * *Reason:* Users do not need to know how the server talks to the browser.
+
+* Text: *"Showing 40 items per request"*
+  * **Decision: REMOVE.**
+  * *Reason:* Technical implementation detail.
+
+* Text: *"Total 53 active members"*
+  * **Decision: KEEP.**
+  * *Reason:* This number helps the user understand how big the group is.
+
+* Text: *"No results found"*
+  * **Decision: KEEP.**
+  * *Reason:* Crucial feedback so the user knows their search had zero matches.
+
+* Text: *"Last updated 5 minutes ago"*
+  * **Decision: KEEP.**
+  * *Reason:* Useful if data freshness matters for this specific task.
+
+* Text: *"Click the button below to continue"*
+  * **Decision: REMOVE.**
+  * *Reason:* The button label already tells the user what to do.
+
+---
+
+## 4 Decision Rules to Ask Every Time
+
+For each piece of text you review, ask yourself these 4 questions:
+
+1. Does the user actually need to know this information?
+2. Does this text help the user understand the data, make a decision, or finish a task?
+3. Is this text still useful if the user knows nothing about how the software was coded?
+4. Is the action or meaning already clear visually without any extra text?
+
+If the answer is **NO**, remove the text.
+
+---
+
+## Important Mindset
+
+**Clear does not mean more text.**
+
+Never add words just to make the interface feel "explained".
+
+If the visual design is already clear on its own, **staying quiet is much better than adding copy**.
+
+* Do not put a label on every single icon or card.
+* Do not describe every button click or screen change.
+* Do not explain how the code works under the hood.
+* Do not treat every number like it needs a paragraph of explanation.
+* Do not add "helpful text" by default.
+
+---
+
+## Output Format
+
+When analyzing any UI text, give your verdict using these three tags:
+
+* `KEEP` : When the text is truly useful and gives real value to the user.
+* `REMOVE` : When the text is UI slop, redundant words, or technical implementation talk.
+* `REWRITE` : When the information is genuinely useful, but the phrasing is too long, awkward, or too technical.
+
+Give a **short and concrete reason** for each decision.
+
+Focus on **user value**, not on explaining every single detail.
+
+If you are torn between keeping or deleting, **choose REMOVE**, unless the text is something the user truly cannot live without.

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?