opencastle 0.32.5 → 0.32.6

package/src/orchestrator/skills/security-hardening/SKILL.md

@@ -3,118 +3,74 @@ name: security-hardening
 description: "Security architecture including authentication, authorization, RLS policies, security headers, CSP, input validation, API security, and OAuth patterns. Use when implementing auth flows, writing RLS policies, configuring security headers, validating inputs, or auditing security."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Security Hardening
 
-## Security Architecture
-
-```
-Edge Network (WAF, DDoS)
-  → Security Headers (framework config: HSTS, CSP, X-Frame-Options)
-    → Middleware (session refresh)
-      → Server Actions (Auth: CSRF protection)
-        → RLS Policies (row-level authorization)
-```
+## Architecture
 
-| Layer | Role | Protection |
+| Layer | Tool | Protection |
 |-------|------|------------|
 | Edge | WAF / CDN | DDoS, bot detection |
-| Headers | Framework config | HSTS, CSP, XSS protection |
-| Middleware | Proxy / middleware layer | Session management |
+| Headers | Framework config | HSTS, CSP, X-Frame-Options |
+| Middleware | Proxy layer | Session refresh, protected routes |
 | Server Actions | Auth provider | Authentication, CSRF |
 | Database | RLS Policies | Row-level authorization |
-| API Routes | CRON_SECRET | Cron job authorization |
+| API Routes | `CRON_SECRET` | Cron job authorization |
 | Input | Zod | Schema validation |
 | Rate Limiting | Proxy layer | IP-based throttling |
 
 ## Authentication
 
-**Platform:** Auth provider with Server Actions pattern. Resolve specific auth library and configuration via the **database** capability slot in the skill matrix.
-
-- **Server Actions** for sign in/up/out, session management.
-- **Middleware** for session refresh, protected routes.
-- **RLS Policies** in the database.
-- **OAuth providers:** Configured in the auth provider's dashboard.
-- **User roles:** Stored in the user profiles table (e.g., `profiles.roles TEXT[]`).
-- **Key auth files:** Resolve via project-specific customization files.
-- **Cron authorization:** `CRON_SECRET` env var, `Bearer` token in `authorization` header
-
-### Server Actions Pattern Benefits
-
-- Automatic CSRF protection (POST-only Server Actions).
-- No exposed API endpoints for auth.
-- Server-side session management.
+Auth provider with Server Actions pattern. Resolve library via **database** capability slot in skill matrix.
 
-### Session Management
+| Concern | Approach |
+|---------|----------|
+| Sign in/up/out | Server Actions (POST-only → automatic CSRF protection) |
+| Session refresh | Middleware `updateSession()`, HTTP-only cookies |
+| Protected routes | Middleware check |
+| OAuth | Configured in auth provider dashboard |
+| User roles | `profiles.roles TEXT[]` |
+| Cron auth | `CRON_SECRET` env var, `Bearer` token in `authorization` header |
 
-- HTTP-only cookies (auth client managed).
-- Automatic refresh via middleware (`updateSession()`).
-- Sign out clears cookie and invalidates session.
+## CSP
 
-## Content Security Policy
+Principle of least privilege. External domains are project-specific (see deployment customization).
 
-### Allowed External Domains (framework config)
+- `default-src 'self'` — deny by default
+- `object-src 'none'` — block plugins
+- `frame-ancestors 'self'` — prevent clickjacking
+- `upgrade-insecure-requests` — enforce HTTPS
+- Whitelist only required external domains per directive
 
-| Purpose | Domains |
-|---------|--------|
-| Scripts | Project-specific — see deployment customization |
-| Styles | Project-specific — see deployment customization |
-| Fonts | Project-specific — see deployment customization |
-| Frames | Project-specific — see deployment customization |
+**Note:** `'unsafe-inline'`/`'unsafe-eval'` may be required in dev mode — use nonces/hashes in production.
 
-### Directives
+## RLS
 
-General CSP directives follow the principle of least privilege:
-- `default-src 'self'` — deny by default.
-- Whitelist only required external domains per directive.
-- `object-src 'none'` — block plugins.
-- `frame-ancestors 'self'` — prevent clickjacking.
-- `upgrade-insecure-requests` — enforce HTTPS.
+> **SQL examples and role system:** See the **database** skill (authoritative source for RLS).
 
-**Known weaknesses:** `'unsafe-inline'` and `'unsafe-eval'` in script-src (may be required for framework dev mode). Consider nonces/hashes for production inline scripts.
-
-## RLS Policy Patterns
-
-> **Detailed RLS patterns and SQL examples:** See the **database** skill (resolved via skill matrix), which is the authoritative source for RLS policies, role systems, and migration rules.
-
-### Best Practices
-
-- Enable RLS on all tables: `ALTER TABLE x ENABLE ROW LEVEL SECURITY;`
-- Test policies with different user roles.
-- Use `auth.uid()` for authentication checks.
-- EXISTS subqueries for role checks.
-- Never rely solely on client-side authorization.
-- Never disable RLS in production.
+- `ALTER TABLE x ENABLE ROW LEVEL SECURITY;` on all tables
+- Use `auth.uid()` for auth checks; EXISTS subqueries for role checks
+- Never rely solely on client-side authorization; never disable RLS in production
 
 ## API Security
 
-### Cron Job Authorization
-
 ```typescript
-export async function GET(request: NextRequest) {
-  const authHeader = request.headers.get('authorization');
-  if (!authHeader || authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-  }
+// Cron authorization pattern
+const authHeader = request.headers.get('authorization');
+if (!authHeader || authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
+  return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
 }
 ```
 
-- Strong random CRON_SECRET: `openssl rand -hex 32`
-- Rotate quarterly.
-
-### Input Validation
+Generate secret: `openssl rand -hex 32`. Rotate quarterly.
 
-- Zod schemas for all request validation.
-- React Hook Form for client-side validation.
-- Server-side validation in all Server Actions and route handlers.
+Input: Zod schemas in all Server Actions and route handlers; React Hook Form client-side.
 
 ## Critical Rules
 
-1. Never commit secrets — use deployment platform environment variables.
-2. Always use Server Actions for auth operations.
-3. Enable RLS on all tables — default-deny, explicit-allow.
-4. Validate all inputs with Zod before database operations.
-5. Sanitize user content — escape HTML in reviews/descriptions.
-6. Parameterized queries (database client handles automatically).
-7. Rotate secrets regularly (quarterly).
+1. Never commit secrets — use env vars.
+2. Server Actions for all auth operations.
+3. RLS on all tables — default-deny, explicit-allow.
+4. Validate all inputs with Zod before DB operations.
+5. Sanitize user content (escape HTML).
+6. Parameterized queries (DB client handles automatically).
+7. Rotate secrets quarterly.

package/src/orchestrator/skills/self-improvement/SKILL.md

@@ -3,96 +3,62 @@ name: self-improvement
 description: "Protocol for reading and updating the lessons-learned knowledge base. MUST be followed by ALL agents — read lessons before work, write lessons after retries. This makes the agent team self-improving across sessions."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # Self-Improvement Protocol
 
-This skill defines how agents learn from mistakes and share knowledge so the same pitfalls are never repeated.
-
-## Core Principle
-
-**If you retry something with a different approach and it works, document the lesson immediately.** The cost of writing a lesson (2 minutes) is always less than the cost of someone else hitting the same pitfall (5-30 minutes).
-
-## The Lessons File
-
-Location: `.opencastle/LESSONS-LEARNED.md`
-
-This is the team's collective memory — a structured log of tool/command pitfalls, workarounds, and correct approaches discovered through execution.
+## Core Rule
 
-## Protocol for All Agents
+**Retry with a different approach and it works → document the lesson immediately.** File: `.opencastle/LESSONS-LEARNED.md`
 
-The core protocol (read lessons → write on retry → log session) is referenced from `general.instructions.md` via the **Workflow & Governance** table. This skill provides the detailed reference material for writing lessons.
+## Writing a Lesson
 
-## How to Write a Lesson
-
-> **⛔ HARD GATE — Use the CLI to write lessons. Do NOT edit LESSONS-LEARNED.md directly.**
-
-Use the `opencastle lesson` CLI command. It auto-increments the lesson ID, formats the entry, and updates the category index.
+> **⛔ HARD GATE — Use the CLI. Do NOT edit LESSONS-LEARNED.md directly.**
 
 ```sh
 opencastle lesson --title "Short descriptive title" --category general --severity high \
-  --problem "What went wrong and what error/behavior was observed" \
-  --wrong "The obvious/intuitive approach that fails" \
-  --correct "The working solution" \
-  --why "Root cause explanation"
+  --problem "What was observed" --wrong "Failing approach" --correct "Working solution" \
+  --why "Root cause"
 ```
 
-Required flags: `--title`, `--category`, `--severity`, `--problem`
-Optional flags: `--wrong`, `--correct`, `--why`
-
-Run `opencastle lesson --help` for full usage and valid category/severity values.
-
-### After writing the lesson
-
-If the lesson reveals a gap in existing instruction/skill files, **also update those files** to include the correct approach. This prevents the pitfall at the source level, not just as a retroactive note.
+Required: `--title`, `--category`, `--severity`, `--problem` · Optional: `--wrong`, `--correct`, `--why`
 
-Examples:
-- Lesson about task tracker tools → update the skill mapped by the `task-management` slot in the skill matrix
-- Lesson about codebase-tool commands → update the skill mapped by the `codebase-tool` slot in the skill matrix
-- Lesson about CMS queries → update the skill mapped by the `cms` slot in the skill matrix
-- Lesson about browser testing → update the skill mapped by the `e2e-testing` slot in the skill matrix
+After writing: if the lesson reveals a gap in a skill/instruction file, update that file too (prevents the pitfall at source).
 
 ## Categories
 
 | Category | Covers |
 |----------|--------|
 | `task-management` | Task tracker tools, issue management, workflow states |
-| `jira` | Jira MCP tools (Atlassian Rovo), issue management, workflows |
-| `mcp-tools` | Any MCP server tool quirks (deferred loading, parameters) |
+| `jira` | Jira MCP tools (Atlassian Rovo) |
+| `mcp-tools` | MCP server tool quirks (deferred loading, parameters) |
 | `codebase-tool` | Task runner CLI commands, caching, build tools |
-| `terminal` | Shell commands, port management, process management |
+| `terminal` | Shell commands, port/process management |
 | `framework` | App framework, build, dev server, SSR |
 | `cms` | CMS content queries, schema deployment |
 | `database` | Database auth, migrations, RLS, SQL |
 | `git` | Git operations, branching, merge conflicts |
 | `deployment` | Deployment, environment variables, edge config |
 | `browser-testing` | E2E testing, screenshots, browser automation |
-| `general` | Anything that doesn't fit above |
+| `general` | Anything else |
 
-## Severity Guide
+## Severity
 
-| Level | Meaning | Impact |
-|-------|---------|--------|
-| `high` | Blocks work entirely | Agent cannot proceed without the workaround |
-| `medium` | Wastes 5+ minutes | Agent will eventually figure it out but wastes time |
-| `low` | Minor friction | Slight annoyance, easy to work around |
+| Level | Impact |
+|-------|--------|
+| `high` | Blocks work — agent cannot proceed without the workaround |
+| `medium` | Wastes 5+ minutes |
+| `low` | Minor friction |
 
-## Quality Standards
+## Quality Rules
 
-- **Be specific** — include exact error messages, exact commands, exact tool parameters
-- **Show both wrong and right** — the contrast is what makes lessons actionable
-- **Explain why** — root cause helps agents reason about similar situations
-- **Keep it concise** — one lesson per entry, no essays
-- **Code blocks are mandatory** — for commands, tool calls, and configurations
+- Include exact error messages, commands, and tool parameters
+- Show wrong **and** correct approaches — the contrast is actionable
+- Explain why (root cause)
+- One lesson per entry; code blocks mandatory for commands
 
 ## Anti-Patterns
 
-- **Never skip reading lessons** before starting work — this is the #1 cause of repeated mistakes
-- **Never "fix it and move on"** without documenting — your fix dies with your session
-- **Never write vague lessons** like "the tracker is tricky" — be specific about what fails and what works
-- **Never duplicate existing lessons** — check the index first
-- **Never wait until the end of a session** to write lessons — write them immediately when the retry succeeds
+Never skip reading lessons · Never fix without documenting · Never write vague entries · Never duplicate · Never defer to end of session
 
-## Agent Memory Protocol
+## Agent Memory
 
-For agent expertise tracking and cross-session knowledge graphs, load the **agent-memory** skill. It covers memory templates, update triggers, retrieval protocols, and the knowledge graph format.
+For expertise tracking and cross-session knowledge graphs, load the **agent-memory** skill.

package/src/orchestrator/skills/seo-patterns/SKILL.md

@@ -3,8 +3,6 @@ name: seo-patterns
 description: "Technical SEO patterns for meta tags, structured data, sitemaps, URL strategy, and rendering. Use when optimizing pages for search engines or implementing SEO features."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # SEO Patterns
 
 ## Core Principles
@@ -16,10 +14,7 @@ description: "Technical SEO patterns for meta tags, structured data, sitemaps, U
 
 ## Meta Tags & Open Graph
 
-Every page template must include the full set of meta tags:
-
 ```tsx
-// Next.js App Router — layout or page metadata
 export const metadata: Metadata = {
   title: 'Product Name — Short Descriptor',
   description: 'Concise 150-160 char description with primary keyword.',
@@ -31,35 +26,24 @@ export const metadata: Metadata = {
     type: 'website',
     images: [{ url: 'https://example.com/og-image.jpg', width: 1200, height: 630 }],
   },
-  twitter: {
-    card: 'summary_large_image',
-    title: 'Product Name — Short Descriptor',
-    images: ['https://example.com/og-image.jpg'],
-  },
+  twitter: { card: 'summary_large_image', title: 'Product Name — Short Descriptor', images: ['https://example.com/og-image.jpg'] },
   robots: { index: true, follow: true },
 };
 ```
 
-### Meta Tag Checklist
-
-- [ ] `<title>` is unique, 50-60 chars, includes primary keyword
-- [ ] `<meta name="description">` is unique, 150-160 chars, includes CTA
-- [ ] `<link rel="canonical">` points to the single authoritative URL
-- [ ] `og:title`, `og:description`, `og:image` (1200×630 px min), `og:type` are set
-- [ ] `twitter:card`, `twitter:title`, `twitter:image` are set
-- [ ] `robots` directives are correct (`noindex` on admin/draft pages only)
+**Checklist:** unique title (50-60 chars) · unique description (150-160 chars) · canonical URL · `og:title/description/image` (1200×630 px) · `og:type` · `twitter:card/title/image` · `noindex` only on admin/draft pages.
 
 ## Structured Data (JSON-LD)
 
-Use JSON-LD `<script>` blocks — never microdata or RDFa. Choose schema types based on page purpose:
+Use JSON-LD `<script>` blocks — never microdata or RDFa.
 
 | Page Type | Schema Type(s) | Required Properties |
 |-----------|----------------|---------------------|
 | Homepage | `WebSite`, `Organization` | `name`, `url`, `searchAction`, `logo` |
-| Detail page | `Product`, `Article`, or domain-specific type | `name`, `description`, `image` |
-| Listing / category page | `ItemList` + `ListItem` | `itemListElement`, `position`, `url` |
-| Breadcrumb navigation | `BreadcrumbList` | `itemListElement`, `position`, `name` |
-| Blog post | `Article` or `BlogPosting` | `headline`, `datePublished`, `author` |
+| Detail page | `Product`, `Article`, or domain type | `name`, `description`, `image` |
+| Listing page | `ItemList` + `ListItem` | `itemListElement`, `position`, `url` |
+| Breadcrumbs | `BreadcrumbList` | `itemListElement`, `position`, `name` |
+| Blog post | `Article` / `BlogPosting` | `headline`, `datePublished`, `author` |
 | FAQ page | `FAQPage` | `mainEntity` with `Question` + `Answer` |
 
 ### Example: Breadcrumb + Article
@@ -67,27 +51,15 @@ Use JSON-LD `<script>` blocks — never microdata or RDFa. Choose schema types b
 ```tsx
 function StructuredData({ breadcrumbs, article }: Props) {
   const breadcrumbLd = {
-    '@context': 'https://schema.org',
-    '@type': 'BreadcrumbList',
-    itemListElement: breadcrumbs.map((crumb, i) => ({
-      '@type': 'ListItem',
-      position: i + 1,
-      name: crumb.label,
-      item: crumb.url,
-    })),
+    '@context': 'https://schema.org', '@type': 'BreadcrumbList',
+    itemListElement: breadcrumbs.map((crumb, i) => ({ '@type': 'ListItem', position: i + 1, name: crumb.label, item: crumb.url })),
   };
-
   const articleLd = {
-    '@context': 'https://schema.org',
-    '@type': 'Article',
-    headline: article.title,
-    description: article.summary,
-    image: article.imageUrl,
-    datePublished: article.publishedAt,
-    dateModified: article.updatedAt,
-    author: { '@type': 'Person', name: article.author },
+    '@context': 'https://schema.org', '@type': 'Article',
+    headline: article.title, description: article.summary,
+    image: article.imageUrl, datePublished: article.publishedAt,
+    dateModified: article.updatedAt, author: { '@type': 'Person', name: article.author },
   };
-
   return (
     <>
       <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(breadcrumbLd) }} />
@@ -97,20 +69,13 @@ function StructuredData({ breadcrumbs, article }: Props) {
 }
 ```
 
-### Validation
-
-- Run every JSON-LD block through [Google's Rich Results Test](https://search.google.com/test/rich-results) before merging.
-- Validate against [schema.org](https://schema.org) definitions for required/recommended properties.
-- Check the Search Console **Enhancements** report after deployment.
+Validate every block via [Google's Rich Results Test](https://search.google.com/test/rich-results) before merging. Check Search Console **Enhancements** after deployment.
 
 ## Sitemap & Crawlability
 
-- Generate an XML sitemap dynamically from your data source (CMS, database, filesystem).
-- Use a **sitemap index** when page count exceeds 50,000 URLs or file size exceeds 50 MB.
-- Include `<lastmod>` timestamps — omit if you can't guarantee accuracy.
-- Submit sitemaps via Google Search Console and reference them in `robots.txt`.
-
-### Example: robots.txt
+- Generate XML sitemap dynamically from your data source (CMS, DB, filesystem).
+- Use a **sitemap index** when >50,000 URLs or >50 MB.
+- Include `<lastmod>` only if accurate; submit via Google Search Console and reference in `robots.txt`.
 
 ```txt
 User-agent: *
@@ -118,26 +83,13 @@ Allow: /
 Disallow: /admin/
 Disallow: /api/
 Disallow: /preview/
-
 Sitemap: https://example.com/sitemap.xml
 ```
 
-### Crawlability Checklist
-
-- [ ] `robots.txt` allows crawling of all public pages
-- [ ] `robots.txt` blocks admin, API, and preview routes
-- [ ] XML sitemap is auto-generated and up to date
-- [ ] Sitemap is referenced in `robots.txt`
-- [ ] Internal links connect all public pages (no orphan pages)
-- [ ] Page load time < 3s (crawl budget efficiency)
+**Checklist:** robots.txt allows all public pages · blocks admin/API/preview · XML sitemap auto-generated and current · referenced in robots.txt · no orphan pages · page load < 3s.
 
 ## URL Strategy
 
-- Use lowercase, hyphen-separated slugs: `/blog/my-post-title`
-- Keep URLs short, keyword-relevant, and human-readable.
-- Enforce trailing-slash consistency (pick one, redirect the other).
-- Implement 301 redirects for any renamed or moved pages.
-
 | Pattern | Good | Bad |
 |---------|------|-----|
 | Slug format | `/products/blue-widget` | `/products/Blue_Widget` |
@@ -145,56 +97,39 @@ Sitemap: https://example.com/sitemap.xml
 | Consistency | Always `/path/` or `/path` | Mixed trailing slashes |
 | Parameters | `/products?sort=price` | `/products/sort/price/asc` |
 
-### Redirect Example (Next.js)
-
 ```ts
 // next.config.ts
-const nextConfig = {
-  async redirects() {
-    return [
-      { source: '/old-page', destination: '/new-page', permanent: true },
-      { source: '/blog/:slug/amp', destination: '/blog/:slug', permanent: true },
-    ];
-  },
-};
+const redirects = [
+  { source: '/old-page', destination: '/new-page', permanent: true },
+  { source: '/blog/:slug/amp', destination: '/blog/:slug', permanent: true },
+];
 ```
 
 ## Rendering & Indexability
 
-- **Server-render** all content that must be indexed — titles, descriptions, body text, structured data.
-- **Client-hydrated** interactive elements (filters, modals) are fine, but content behind JS-only rendering will not be indexed reliably.
-- Use semantic HTML (`<h1>`–`<h6>`, `<article>`, `<nav>`, `<main>`) for crawlers to understand page structure.
+Server-render all indexed content. Use semantic HTML (`<h1>`–`<h6>`, `<article>`, `<nav>`, `<main>`) for crawler structure.
 
-### Image SEO
-
-| Attribute | Purpose | Example |
-|-----------|---------|---------|
-| `alt` | Describes image for screen readers + crawlers | `alt="Blue widget on white background"` |
-| `loading` | Lazy-load below-fold images | `loading="lazy"` |
-| `width` / `height` | Prevents layout shift (CLS) | `width={800} height={600}` |
+| Image Attribute | Purpose | Example |
+|-----------------|---------|---------|
+| `alt` | Describes for crawlers + screen readers | `alt="Blue widget on white background"` |
+| `loading` | Lazy-load below-fold | `loading="lazy"` |
+| `width` / `height` | Prevents CLS | `width={800} height={600}` |
 | File name | Keyword signal | `blue-widget-front.webp` |
-| Format | Performance + quality | Use WebP/AVIF with JPEG fallback |
-
-### Indexability Checklist
+| Format | Performance + quality | WebP/AVIF with JPEG fallback |
 
-- [ ] Primary content renders in initial HTML (view source, not inspect)
-- [ ] `<h1>` is unique per page and contains the primary keyword
-- [ ] Structured data is present in the server-rendered HTML
-- [ ] Images have descriptive `alt` text
-- [ ] No `noindex` on pages that should be indexed
-- [ ] Hydration does not remove or rewrite structured data scripts
+**Checklist:** primary content in initial HTML · unique `<h1>` with primary keyword · structured data in SSR HTML · descriptive `alt` on all images · no stray `noindex` · hydration preserves structured data scripts.
 
 ## Anti-Patterns
 
 | Anti-Pattern | Why It's Bad | Correct Approach |
 |---|---|---|
-| Duplicate `<title>` across pages | Dilutes ranking signals; confuses crawlers | Unique, keyword-specific title per page |
-| Missing canonical URL | Causes duplicate content penalties | Add `<link rel="canonical">` to every page |
-| Client-only rendered content | Googlebot may not execute JS reliably | Server-render all indexable content |
-| Hardcoded sitemap file | Goes stale as pages are added/removed | Generate sitemap dynamically from data source |
-| Using `noindex` as a "temporary" fix | Often forgotten; pages stay de-indexed | Fix the underlying issue instead |
-| Stuffing keywords in meta tags | Penalized by search engines | Write natural, user-focused descriptions |
-| Missing `alt` text on images | Lost image search traffic + accessibility failure | Descriptive alt text on every meaningful image |
-| Structured data without validation | Silent errors cause rich result loss | Validate with Google Rich Results Test before merge |
-| Blocking CSS/JS in `robots.txt` | Prevents Googlebot from rendering the page | Only block admin/API routes |
-| Mixed trailing slash URLs | Splits link equity between two URLs | Pick one convention, 301-redirect the other |
+| Duplicate `<title>` | Dilutes ranking signals | Unique, keyword-specific title per page |
+| Missing canonical URL | Duplicate content penalties | Add `<link rel="canonical">` to every page |
+| Client-only rendered content | Googlebot may miss JS | Server-render all indexable content |
+| Hardcoded sitemap | Goes stale | Generate sitemap dynamically |
+| `noindex` as "temporary" fix | Often forgotten | Fix the underlying issue |
+| Keyword stuffing in meta tags | Penalized by search engines | Natural, user-focused descriptions |
+| Missing `alt` on images | Lost image traffic + a11y failure | Descriptive alt on every meaningful image |
+| Unvalidated structured data | Silent errors = rich result loss | Validate with Rich Results Test before merge |
+| Blocking CSS/JS in robots.txt | Prevents page rendering | Only block admin/API routes |
+| Mixed trailing slash URLs | Splits link equity | Pick one convention, 301-redirect other |