waitsec 0.5.0 → 0.5.2

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

@@ -112,6 +112,50 @@ Every article preview card must contain:
 
 ---
 
+## 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?
@@ -119,3 +163,5 @@ Every article preview card must contain:
 - [ ] 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

@@ -84,9 +84,9 @@ Never demand phone numbers, fax numbers, company size, or physical mailing addre
 * **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 -->
+  <!-- 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">
-    <svg class="animate-spin h-4 w-4 text-white" viewBox="0 0 24 24">...</svg>
+    <i data-lucide="loader-2" class="w-4 h-4 animate-spin"></i>
     <span>Sending...</span>
   </button>
 
@@ -113,6 +113,43 @@ Never demand phone numbers, fax numbers, company size, or physical mailing addre
 
 ---
 
+## 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)?
@@ -121,3 +158,5 @@ Never demand phone numbers, fax numbers, company size, or physical mailing addre
 - [ ] 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?

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

@@ -143,6 +143,72 @@ Use this guide when creating a marketing page, product launch screen, or SaaS ho
 
 ---
 
+## SEO, GEO & Structured Data (Landing Page)
+
+State what the product is and who it is for within the first two sentences of the hero. Answer engines quote those lines, so make them complete and direct.
+
+- Title: product name plus one clear benefit, about 50 to 60 characters.
+- Meta description: what the product does and who it is for, about 140 to 160 characters.
+- One `<h1>` that carries the core value proposition in plain words.
+- Server-render the hero headline, subheadline, and primary CTA.
+- Add an FAQ block with question-shaped `<h3>` headings. Start each answer with a direct one-sentence response.
+- Keep the Open Graph image at 1200x630 and use an absolute URL.
+
+### JSON-LD for a Landing Page
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@graph": [
+    {
+      "@type": "Organization",
+      "@id": "https://example.com/#organization",
+      "name": "Example Inc",
+      "url": "https://example.com",
+      "logo": "https://example.com/images/logo.png"
+    },
+    {
+      "@type": "WebSite",
+      "@id": "https://example.com/#website",
+      "url": "https://example.com",
+      "name": "Example",
+      "publisher": { "@id": "https://example.com/#organization" }
+    },
+    {
+      "@type": "SoftwareApplication",
+      "name": "Example App",
+      "applicationCategory": "BusinessApplication",
+      "operatingSystem": "Web",
+      "url": "https://example.com",
+      "offers": {
+        "@type": "Offer",
+        "price": "0",
+        "priceCurrency": "USD"
+      }
+    },
+    {
+      "@type": "FAQPage",
+      "mainEntity": [
+        {
+          "@type": "Question",
+          "name": "Is there a free plan?",
+          "acceptedAnswer": {
+            "@type": "Answer",
+            "text": "Yes. The free plan covers one project with no time limit."
+          }
+        }
+      ]
+    }
+  ]
+}
+</script>
+```
+
+Include the `FAQPage` block only when the FAQ is actually visible on the page. Use `Product` instead of `SoftwareApplication` for a physical or ecommerce product.
+
+---
+
 ## Pre-Flight Checklist for Landing Pages
 
 - [ ] Does the hero section have exactly 1 high-contrast primary CTA button?
@@ -150,3 +216,5 @@ Use this guide when creating a marketing page, product launch screen, or SaaS ho
 - [ ] Are feature cards structured with varied visual weight (bento style) rather than copy-paste clones?
 - [ ] Is there zero horizontal page wobble when testing at 320px width?
 - [ ] Are all headlines scaled down comfortably on mobile to avoid breaking words into multiple lines?
+- [ ] Is there one H1, a unique title, a meta description, and an absolute Open Graph image?
+- [ ] Is the JSON-LD valid, type-appropriate, and free of validator errors?

package/skills/waitsec-quality/SKILL.md

@@ -21,22 +21,101 @@ Activate this skill whenever:
 
 ---
 
-## Core Guardrails
-
-### 1. Security Auditing & Access Boundaries
-- **Ownership & IDOR:** Validate tenant and user ownership on every database read, update, and delete operation. Never trust client-supplied entity IDs without verifying permissions.
-- **Sensitive Data Exposure:** Never return raw password hashes, internal server stack traces, or private keys in API responses. Use explicit serialization filters.
-- **Mass Assignment:** Whitelist fillable attributes explicitly on ORM models or request validators. Reject raw wildcard inserts.
-
-### 2. Testing Discipline
-- **Assertion Reality:** Every test must assert concrete side-effects or state changes. Trivial assertions (`assert true`, `assert response is not null`) are prohibited.
-- **Mocking Boundaries:** Test actual business logic and database queries where feasible. Never mock the system under test to force an artificial passing run.
-- **Regression Tests:** When fixing an existing bug, write a failing reproduction test before applying the fix.
-
-### 3. Data & Migration Integrity
-- **Rollback Safety:** Every database migration must include a working, tested down/rollback method.
-- **Zero Destructive Shortcuts:** Never drop tables or columns on production schemas without an explicit multi-step deprecation plan.
-- **Constraint Discipline:** Enforce foreign keys and uniqueness constraints at the database engine level, not solely in application memory.
+## Part 1: Security & Access Boundaries
+
+### 1. Trusting Client-Supplied IDs (IDOR)
+
+* **The Bad Habit:** Fetching a record straight from a request ID, like `Order::find($id)`, without checking who owns it.
+* **The Problem:** Any logged-in user can change the ID in the URL and read or edit someone else's record.
+* **Why It Fails:** This is a direct data breach. One guessed number exposes private orders, messages, or invoices.
+* **Clean Fix:** Scope every read, update, and delete to the authenticated user or tenant:
+  ```php
+  // Bad
+  $order = Order::find($id);
+
+  // Good
+  $order = auth()->user()->orders()->findOrFail($id);
+  ```
+* **The Waitsec Way:** Never trust an ID that came from the client. Verify ownership on every data access.
+
+### 2. Leaking Sensitive Data in Responses
+
+* **The Bad Habit:** Returning the whole model, including password hashes, internal flags, or stack traces.
+* **The Problem:** The API response exposes fields the user should never see.
+* **Why It Fails:** Leaked hashes and internal details hand attackers the first step of a break-in.
+* **Clean Fix:** Return explicit, whitelisted fields only. Use serialization filters or resource classes.
+* **The Waitsec Way:** Send the minimum the client needs. Everything else stays server-side.
+
+### 3. Mass Assignment
+
+* **The Bad Habit:** Passing the whole request payload into `create()` or `update()`.
+* **The Problem:** A crafted request can set fields the form never exposed, such as `isAdmin` or `price`.
+* **Why It Fails:** Attackers change roles and prices with a single extra parameter, and the database accepts it.
+* **Clean Fix:** Whitelist fillable attributes and pass only validated data:
+  ```php
+  // Forbidden
+  User::create($request->all());
+
+  // Required
+  User::create($request->validated());
+  ```
+* **The Waitsec Way:** Accept only the fields you meant to accept. Never forward raw input to the database.
+
+---
+
+## Part 2: Testing Discipline
+
+### 4. Trivial Assertions
+
+* **The Bad Habit:** Writing tests that assert `true`, assert the response is not null, or call an endpoint without checking the result.
+* **The Problem:** The suite is green while the feature is broken.
+* **Why It Fails:** A passing test that proves nothing gives false confidence. Bugs reach production behind a fake safety net.
+* **Clean Fix:** Assert a concrete outcome: the row was created, the balance changed, the status code is 403, or the field equals the expected value.
+* **The Waitsec Way:** A test must prove a behavior. If it cannot fail, it is not a test.
+
+### 5. Mocking the System Under Test
+
+* **The Bad Habit:** Mocking the very class or query the test is supposed to verify.
+* **The Problem:** The test only confirms that the mock returned what the mock was told to return.
+* **Why It Fails:** Real bugs live in the code that got mocked away. The suite passes and the feature still fails.
+* **Clean Fix:** Test real business logic and database behavior where feasible. Mock only true external boundaries.
+* **The Waitsec Way:** Test the real thing. Put mocks at the edges, never over the subject.
+
+### 6. Fixing Without a Reproduction Test
+
+* **The Bad Habit:** Fixing a reported bug immediately and moving on, with no test that captures the failure.
+* **The Problem:** Nothing stops the same bug from returning in the next refactor.
+* **Why It Fails:** Without a failing reproduction first, you cannot even prove the fix addresses the reported case.
+* **Clean Fix:** Write a failing test that reproduces the bug, then fix until it passes, then keep the test.
+* **The Waitsec Way:** A bug fix ships with proof. The reproduction test is that proof.
+
+---
+
+## Part 3: Data & Migration Integrity
+
+### 7. One-Way Migrations
+
+* **The Bad Habit:** Writing an `up()` migration with no working `down()` rollback.
+* **The Problem:** A bad deploy cannot be reversed cleanly.
+* **Why It Fails:** When the migration corrupts or blocks data, the team is stuck with a manual, risky recovery under pressure.
+* **Clean Fix:** Every migration gets a tested rollback that restores the previous schema state.
+* **The Waitsec Way:** A migration is a two-way door. If you cannot safely go back, you cannot safely go forward.
+
+### 8. Destructive Schema Shortcuts
+
+* **The Bad Habit:** Dropping a column or table in one migration to "clean up".
+* **The Problem:** Live data disappears the moment the migration runs, with no recovery path.
+* **Why It Fails:** Production data loss is permanent and often unrecoverable. One migration erases history.
+* **Clean Fix:** Deprecate in steps: stop writing, keep reading, back up, wait, then drop in a later release.
+* **The Waitsec Way:** Remove data only when you are certain nothing needs it. Prefer deprecation over destruction.
+
+### 9. Application-Only Constraints
+
+* **The Bad Habit:** Enforcing uniqueness or relationships only in application code.
+* **The Problem:** Race conditions and direct database writes slip past the checks.
+* **Why It Fails:** Duplicate or orphaned rows appear even though the app "always checks". Data integrity decays over time.
+* **Clean Fix:** Enforce foreign keys, unique indexes, and not-null rules at the database engine level.
+* **The Waitsec Way:** The database is the last line of defense. Let it enforce the invariants.
 
 ---
 

package/skills/waitsec-ui/SKILL.md

@@ -20,23 +20,80 @@ Activate this skill whenever:
 
 ---
 
-## Core Guardrails
-
-### 1. Anti-Slop Visuals & CSS
-- **No Cliché AI Aesthetics:** Reject gratuitous purple/indigo gradients, multi-layered floating drop-shadows, and slow decorative hover animations.
-- **Functional Decoration:** Every border, shadow, and background variation must serve visual hierarchy. If removing an effect does not hurt usability, remove it.
-- **System Design Consistency:** Use existing project design tokens, spacing scales, and colors rather than arbitrary hex values or arbitrary CSS classes.
-
-### 2. Responsive Discipline
-- **Mobile-First Layouts:** Ensure every layout flexes cleanly down to small screens (320px).
-- **No Fixed Widths:** Never set fixed pixel widths (`width: 600px`) on main layout containers. Use fluid widths, `max-width`, and relative units (`rem`, `%`).
-- **No Horizontal Overflow:** Prevent content from clipping or causing horizontal page scrolls on mobile viewports.
-
-### 3. Anti-Slop UI Copy (Implementation Silence)
-- **User Value Over Mechanism:** Never explain technical implementations to the user (e.g. "Data loaded via asynchronous API", "Infinite scroll - 40 items per request"). Users need product information, not architecture docs.
-- **Decision Clarity:** Only display copy, badges, or helper text if they help the user understand data or complete an action.
-- **Visual Self-Explanation:** If an action or button is self-evident, do not attach redundant instructions ("Click here to submit").
-- *Deep Dive & Triage:* Read [`skills/waitsec/references/write-info-analyzer.md`](../waitsec/references/write-info-analyzer.md).
+## Part 1: Visual Restraint
+
+### 1. Generic AI Aesthetics
+
+* **The Bad Habit:** Reaching for purple-to-indigo gradients, layered drop shadows, and slow hover animations on every surface.
+* **The Problem:** The interface looks like every other generated template, and depth cues appear on elements that have no reason to float or move.
+* **Why It Fails:** Users recognize the generic look instantly and trust the product less. Decorative motion also distracts from the actual task.
+* **Clean Fix:** Use solid neutral surfaces and pick one deliberate accent color for the primary action. Add shadow or motion only when it signals real elevation or state.
+* **The Waitsec Way:** Restraint reads as confidence. If an effect does not help the user, remove it.
+
+### 2. Decoration That Does Not Earn Its Place
+
+* **The Bad Habit:** Adding borders, shadows, glows, and background patterns to fill empty space.
+* **The Problem:** The page is visually busy and the important element no longer stands out.
+* **Why It Fails:** When everything is decorated, nothing has hierarchy. Users do not know where to look first.
+* **Clean Fix:** Remove an effect and check whether usability drops. If it does not, leave it removed.
+* **The Waitsec Way:** Every visual choice must carry meaning. Decoration is not a substitute for hierarchy.
+
+### 3. Arbitrary Values Instead of Design Tokens
+
+* **The Bad Habit:** Typing random hex colors, odd spacing numbers, and one-off font sizes into components.
+* **The Problem:** The same "gray" appears in five slightly different shades, and spacing drifts from screen to screen.
+* **Why It Fails:** The interface feels inconsistent, and future changes require hunting every stray value.
+* **Clean Fix:** Use the existing design tokens, spacing scale, and theme colors. Add a token only when the system genuinely lacks one.
+* **The Waitsec Way:** Follow the system in place. Consistency comes from reuse, not from fresh choices.
+
+---
+
+## Part 2: Responsive Discipline
+
+### 4. Fixed Widths and Horizontal Overflow
+
+* **The Bad Habit:** Setting fixed pixel widths on main containers, tables, or code blocks.
+* **The Problem:** On a narrow phone the page wobbles sideways and content disappears past the edge of the screen.
+* **Why It Fails:** Horizontal scrolling on a vertical page breaks reading and navigation. Users lose their place and leave.
+* **Clean Fix:** Use fluid widths with a max width (`w-full max-w-5xl mx-auto px-4`) and wrap tables or code blocks in `overflow-x-auto`.
+* **The Waitsec Way:** The layout must fit the screen it is on. Zero horizontal page scrolling on mobile.
+
+### 5. Desktop Assumed as the Default
+
+* **The Bad Habit:** Building the wide desktop layout first and patching mobile with a media query at the very end.
+* **The Problem:** The mobile view inherits desktop rules and glitches: oversized type, cramped cards, and broken spacing.
+* **Why It Fails:** A last-minute patch fixes only the bug you happened to notice. Real visitors hit all the rest.
+* **Clean Fix:** Start with the mobile layout, then add widths and columns as the screen grows.
+* **The Waitsec Way:** Mobile is the base, not an afterthought. Design from the small screen up.
+
+---
+
+## Part 3: Anti-Slop UI Copy (Implementation Silence)
+
+### 6. Implementation Leaks in Copy
+
+* **The Bad Habit:** Writing user-facing text about the code, such as "Data loaded via asynchronous API" or "Infinite scroll, 40 items per request".
+* **The Problem:** The interface explains its own technical internals to the user.
+* **Why It Fails:** Users want to finish a task, not read architecture notes. The text adds noise and reveals nothing useful.
+* **Clean Fix:** Delete implementation talk. Keep only what helps the user understand the data or complete an action.
+* **The Waitsec Way:** The UI serves the user, not the developer. Hide the mechanism, show the meaning.
+* *Deep Dive & Triage:* Read [`skills/waitsec/references/write-info-analyzer.md`](../waitsec/references/write-info-analyzer.md).
+
+### 7. Redundant Instructional Copy
+
+* **The Bad Habit:** Adding "Click here to submit" under a clear "Submit" button.
+* **The Problem:** The screen repeats what the control already says.
+* **Why It Fails:** Extra text slows scanning without adding information. It makes a clean interface feel cluttered and unsure.
+* **Clean Fix:** Let the label and visual design carry the instruction. Delete the helper sentence.
+* **The Waitsec Way:** If the interface is already clear, stay quiet. Clear does not mean more text.
+
+### 8. Labels That Do Not Help a Decision
+
+* **The Bad Habit:** Labeling every icon, card, and number with explanatory text "so the screen does not look empty".
+* **The Problem:** The page fills with words that do not help the user choose or act.
+* **Why It Fails:** Visual noise makes the real information harder to find, and users skim past everything.
+* **Clean Fix:** Keep text only when it changes a decision or explains the data. Remove labels that merely restate what is already visible.
+* **The Waitsec Way:** Show information that helps. Delete decoration made of words.
 
 ---