[pull] main from 5L-Labs:main

.Jules/palette.md

@@ -45,3 +45,26 @@
 ## 2026-03-01 - External Links and Interactive Icons
 **Learning:** Setting `aria-hidden="true"` on custom external link icons prevents screen readers from announcing that the link opens in a new tab. Additionally, using only `hover` classes on interactive icons within a link omits keyboard users from seeing the same visual interactions.
 **Action:** Always assign `role="img"` and `aria-label="(opens in new tab)"` to SVG icons indicating external links. Furthermore, apply equivalent `focus-visible` classes to any hover interactions inside interactive elements to ensure visual feedback parity for keyboard users.
+
+## 2026-03-02 - Dynamic Link Attributes
+
+**Learning:** When dynamically rendering `<Link>` components, simply inserting attributes like `target="_blank"` or `aria-label` inside a loop can accidentally pollute internal links with external behaviors or unnecessary labels.
+**Action:** Use an object spread with a conditional (e.g., `{...(isExternal ? { target: "_blank", rel: "noopener noreferrer", "aria-label": \`\${title} (opens in a new tab)\`, title: title } : {})}`) to apply specific accessibility and behavioral attributes only when appropriate, keeping the DOM clean and accessible.
+
+## 2026-04-26 - Hardcoded Heading Levels in Reusable Components
+**Learning:** Hardcoding specific heading levels (like `<h3>`) inside reusable UI components (like cards) often breaks semantic document structure when the component is placed in different contexts on a page, causing screen readers to skip levels or announce confusing hierarchies.
+**Action:** Always ensure nested headings (like card titles) properly increment relative to their parent container's heading level, or consider passing the appropriate heading level as a prop to the component to maintain strict HTML semantics.
+## 2024-05-03 - Redundant Link Icons Announcement
+**Learning:** Decorative icons indicating external or internal links (like `↗`) that are appended to already readable links cause frustrating redundant screen reader announcements (e.g., reading "North East Arrow" immediately after reading the link text) and create confusing double tab-stops if wrapped in separate interactive elements.
+**Action:** Always add `aria-hidden="true"` to decorative link icons or elements. If an icon must be inside its own link but points to the same destination as a preceding adjacent text link, also add `tabIndex="-1"` to prevent it from receiving keyboard focus, streamlining navigation.
+
+## 2026-05-10 - Expanding Hit Areas for Block Elements
+**Learning:** Having only text as the clickable area within a larger logical block (like a project listing or card) violates Fitts's Law and frustrates mobile users who try to tap the area around the text.
+**Action:** Always wrap the entire logical block in a `<Link>` (or `<a>` tag) and apply `display: block` to expand the interactive hit area. Pair this with hover and `:focus-visible` styles on the entire block, and use transforms on trailing icons (e.g., `↗`) to provide clear visual affordance.
+
+## 2026-05-18 - Expanding Hit Areas for Table Rows
+**Learning:** Having only text as the clickable area within a table row violates Fitts's Law. Wrapping an entire `<tr>` in an `<a>` or `<Link>` tag is invalid HTML and breaks semantic document structure.
+**Action:** Use relative positioned rows (`position: relative` on `tr`) and absolute positioned `::after` pseudo-elements (`inset: 0; position: absolute; z-index: 1`) on the primary link to safely expand the interactive hit area. Pair this with `:focus-within` styles on the entire row and `z-index: 2` on secondary interactive elements within the row.
+## 2026-05-31 - Hiding Redundant Directional Arrows
+**Learning:** Text-based directional arrows (like `→` and `↗`) used inline for visual affordance are read out loud by screen readers, creating annoying auditory clutter (e.g., reading "Start an inquiry rightwards arrow").
+**Action:** Always wrap text-based decorative arrows in `<span aria-hidden="true">` or `<tspan aria-hidden="true">` (if inside an SVG `<text>` block) to hide them from screen readers while preserving the visual UX.

.gitignore

@@ -28,3 +28,10 @@ embedding_generation.log
 __pycache__/
 server.log
 \n# OpenSpec Agent Configs\n.agent/\n.claude/\n.gemini/\n.kilocode/\n
+
+# Generated at build time — do not commit
+src/generated/all-posts.json
+src/generated/latest-post.json
+
+# Local Claude Code settings (contain machine-specific absolute paths)
+openspec/tooling/claude/settings.local.json

.jules/bolt.md

@@ -9,3 +9,27 @@ This journal documents critical performance learnings for the 5L Labs project.
 ## 2026-02-22 - Static Image Formats
 **Learning:** The Docusaurus React setup efficiently handles direct WebP imports in `src/pages/index.js`, dropping the hero banner LCP image payload by ~85% (233KB -> 35KB) without needing additional Webpack loader configurations.
 **Action:** Default to `.webp` formats for large static UI elements (like logos or hero images) rather than `.png`.
+
+## 2025-05-24 - Client-side Markdown Rendering for Static Previews
+**Learning:** Using client-side markdown parsers (like react-markdown) for static content previews significantly increases bundle size unnecessarily. Processing markdown to plain text or HTML at build time is a much more efficient strategy for static site generators.
+**Action:** Always check if content transformation can be moved to the build step before importing heavy runtime libraries.
+
+## 2025-10-26 - Implicit Dependency Upgrades with Bun
+**Learning:** `bun install` may implicitly upgrade major versions of dependencies (e.g., React 18 to 19) if `package.json` ranges allow it and the lockfile isn't respected or is regenerated. This can cause massive, out-of-scope diffs.
+**Action:** Always verify `bun.lock` diffs after installation. Revert lockfile changes if they are not intended.
+
+## 2025-05-24 - Hero Image Optimization & CLS
+**Learning:** Large unoptimized images in the hero section are a primary cause of slow LCP and CLS. Providing explicit `width` and `height` attributes to the `img` tag, even if overridden by CSS, allows the browser to reserve the correct aspect ratio space immediately.
+**Action:** Always optimize hero images (compress/resize) and define explicit dimensions to prevent layout shifts.
+
+## 2026-02-23 - Python HTTP Connection Pooling
+**Learning:** Using standalone `requests.get()` and `requests.post()` in a loop to fetch multiple URLs or hit an API causes a new TCP/TLS handshake per request, leading to massive latency overhead for large jobs.
+**Action:** Always refactor iterative network operations to use a shared `requests.Session()` passed down via arguments to implement Keep-Alive connection pooling.
+
+## 2023-10-27 - Caching Network I/O
+**Learning:** For batch processing scripts that perform slow network I/O or downstream API calls, not checking if the work has already been done on previous runs leads to redundant requests and N times the API cost.
+**Action:** Always check local file system state (e.g., using `.exists()` on the target output path) and skip operations like fetching remote content if the result is already available locally.
+
+## 2026-02-23 - Memoizing React Render Computations
+**Learning:** In Docusaurus React pages, synchronous list filtering (like iterating through large `allPosts` arrays) on every render is an unnecessary bottleneck when routing causes unrelated state/location changes.
+**Action:** Always wrap derived list computations in `useMemo` when the source array is static or infrequently changing, ensuring filtering only fires when the specific dependency (like a filter category) updates.

.jules/sentinel.md

@@ -2,3 +2,13 @@
 **Vulnerability:** Python `requests` (and similar libraries) will happily stream any content type, allowing attackers to force a crawler to download and process unexpected binary files or large data streams.
 **Learning:** Scripts that fetch content (like for embeddings or metadata) often check size limits but neglect `Content-Type`. This can waste resources or trigger errors in parsers.
 **Prevention:** Always validate `Content-Type` headers against a strict allowlist (e.g., `text/html`, `application/xml`) *before* iterating over the response content.
+
+## 2025-02-21 - Connection Leak DoS in requests.get with stream=True
+**Vulnerability:** When using `requests.get(..., stream=True)`, if the response is not fully consumed and `.close()` is not manually called on all early return paths (like redirect checks or content-type validations), the underlying connection remains open. Over many requests, this leads to connection pool exhaustion and a Denial of Service (DoS).
+**Learning:** Manual resource management (`response.close()`) in python is error-prone, especially when multiple early exit conditions exist in the code.
+**Prevention:** Always wrap `requests.get` (or equivalent network calls) in a `with` statement (context manager) to guarantee the connection is closed when the block exits, regardless of how it exits.
+
+## 2025-05-31 - Stale Embeddings Data Leak
+**Vulnerability:** Skipping embedding regeneration based purely on file existence causes embeddings to become stale. If sensitive data was present in an older version of a page and later removed, the stale embedding retains the sensitive data, leading to a data leak.
+**Learning:** Caching mechanisms for derived data (like embeddings) must validate the source material hasn't changed.
+**Prevention:** Always validate content changes (e.g., via ETag or file hash like SHA-256) before using a cached derived artifact.