docs: header logo, hero centering, pattern icons, lead line breaks, fence fix

- Header logo: stop clipping to a circle — show the full wordmark at its natural
  aspect ratio (remove border-radius/object-fit:cover; height 1.8rem, width auto).
- Home: center "Built by 🚜 Query.Farm"; add the SVG cardinality glyphs as a
  "Shape" column in the Function patterns table.
- Lead lines: put "What this is" and "Who it's for" on separate lines (trailing
  <br>) across every tutorial/how-to/concept page; update the contributing-docs
  standard + template to match.
- Fix broken filter-pushdown/http-auth rendering: pymdownx.superfences mishandles
  the `test="skip"` info string and leaked the fence delimiters into the page.
  Switch illustrative blocks to plain ```python with a render-safe `# illustrative`
  sentinel; the doc-example harness skips on that marker instead. Documented the
  gotcha in contributing-docs.

Strict build green; fence leaks 0 across pages; 67 doc/e2e assertions pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rustyconover

docs/concepts/index.md

@@ -5,7 +5,8 @@ description: "How VGI works: the worker process model, transports, the Apache Ar
 # Concepts
 
 **What this is:** the mental model behind VGI — enough to design workers correctly and debug them
-confidently. **Who it's for:** developers who want the "why," not just the "how." None of this is
+confidently.<br>
+**Who it's for:** developers who want the "why," not just the "how." None of this is
 required to ship your first worker; do the [tutorial](../tutorial/index.md) for that.
 
 ## The worker process model

docs/contributing-docs.md

@@ -4,9 +4,9 @@ description: "Conventions for writing vgi-python documentation: the per-page ori
 
 # Writing docs
 
-**What this is:** the conventions every vgi-python documentation page follows. **Who it's for:**
-anyone adding or editing docs. Following these keeps the site easy to orient in and keeps examples
-from rotting.
+**What this is:** the conventions every vgi-python documentation page follows.<br>
+**Who it's for:** anyone adding or editing docs. Following these keeps the site easy to orient in
+and keeps examples from rotting.
 
 ## Diátaxis: pick the right mode
 
@@ -23,8 +23,9 @@ Every page belongs to exactly one of four modes. If a page is doing two jobs, sp
 
 Every tutorial, how-to, and concept page **must** contain, in order:
 
-1. **A lead "what + who" line** — one sentence stating what the page is and who it's for, so a
-   reader self-orients in under 10 seconds. (See the top of this page.)
+1. **A lead "what + who" block** — one sentence on what the page is, then **on its own line**
+   (use a trailing `<br>`) one phrase on who it's for, so a reader self-orients in under 10 seconds.
+   (See the top of this page.)
 2. **Prerequisites** — assumed knowledge, prior steps, and required extras (e.g.
    `pip install vgi-python[http]`), with links. Use a list or an admonition.
 3. **At least one complete, runnable example** — no `...` elisions in the primary example. It must
@@ -52,7 +53,9 @@ Every tutorial, how-to, and concept page **must** contain, in order:
   broken example fails the build.
 - **Mark illustrative-only blocks.** If a block genuinely can't run standalone (SQL, shell, a
   partial snippet), use a non-`python` fence or the ` ```python test="lint" ` / ` test="skip" `
-  setting so the harness lints but doesn't execute it.
+  setting so the harness lints but doesn't execute it. **Do not put blank lines inside a
+  `test="skip"` block** — the renderer doesn't own that info string, so a blank line splits the
+  fence and leaks the delimiters into the page. Keep skip snippets blank-line-free.
 - **Progressive disclosure for newcomers.** Put background that experts can skip inside a
   collapsible admonition (`??? info "New to X?"`).
 
@@ -67,7 +70,8 @@ description: "One-line summary used for SEO and search."
 
 # Page title
 
-**What this is:** one sentence. **Who it's for:** one phrase.
+**What this is:** one sentence.<br>
+**Who it's for:** one phrase.
 
 ## Prerequisites
 

docs/how-to/catalogs.md

@@ -5,9 +5,9 @@ description: "How to expose a VGI worker as a DuckDB catalog: schemas, function
 # Expose a catalog
 
 **What this is:** how a worker presents itself to DuckDB as a catalog — a named namespace of
-schemas, functions, tables, and views you reach with `ATTACH`. **Who it's for:** developers who've
-finished the [tutorial](../tutorial/index.md) and want to understand how their functions get
-qualified names, or who want to expose data (not just functions).
+schemas, functions, tables, and views you reach with `ATTACH`.<br>
+**Who it's for:** developers who've finished the [tutorial](../tutorial/index.md) and want to
+understand how their functions get qualified names, or who want to expose data (not just functions).
 
 ## Prerequisites
 

docs/how-to/function-patterns.md

@@ -5,7 +5,8 @@ description: "How to write each of the four VGI function patterns: scalar, table
 # Function patterns
 
 **What this is:** a recipe showing each of the five VGI function patterns, with a complete,
-runnable worker for each. **Who it's for:** developers who've finished the
+runnable worker for each.<br>
+**Who it's for:** developers who've finished the
 [tutorial](../tutorial/index.md) and want to know which pattern fits their problem.
 
 ## Prerequisites

docs/how-to/http-auth.md

@@ -5,8 +5,9 @@ description: "How to serve a VGI worker over HTTP and authenticate callers with
 # Serve over HTTP with authentication
 
 **What this is:** how to run a worker over **HTTP** instead of a subprocess, and gate it with
-authentication. **Who it's for:** developers deploying a worker as a network service. **Requires:**
-`pip install vgi-python[http]` (and `[oauth]` for JWT).
+authentication.<br>
+**Who it's for:** developers deploying a worker as a network service.<br>
+**Requires:** `pip install vgi-python[http]` (and `[oauth]` for JWT).
 
 ## Prerequisites
 
@@ -26,7 +27,8 @@ DuckDB still attaches the worker over HTTP the usual way (`ATTACH ... (TYPE vgi,
 rather than from SQL — for tests, scripts, or another service. It connects with `transport="http"`
 instead of spawning a subprocess, and exposes the same call methods:
 
-```python test="skip"
+```python
+# illustrative — calling the worker from Python over HTTP
 from vgi.client import Client
 
 with Client(transport="http", base_url="http://localhost:8080", bearer_token="token1") as client:
@@ -47,7 +49,8 @@ Unauthenticated requests get HTTP 401. Authenticated requests carry the principa
 signature and the framework injects a per-call `CallContext` (auth, logging, transport info) — you
 don't pass it from SQL.
 
-```python test="skip"
+```python
+# illustrative — reading the injected ctx in a function
 class Secret(ScalarFunction):
     @classmethod
     def compute(cls, value, *, ctx) -> ...:

docs/how-to/index.md

@@ -4,9 +4,9 @@ description: "Task-oriented recipes for building VGI workers: function patterns,
 
 # How-to guides
 
-**What this is:** focused, task-oriented recipes for getting a specific thing done. **Who it's
-for:** developers who've finished the [tutorial](../tutorial/index.md) and want to build something
-real. Each guide assumes you can already write and run a basic worker.
+**What this is:** focused, task-oriented recipes for getting a specific thing done.<br>
+**Who it's for:** developers who've finished the [tutorial](../tutorial/index.md) and want to build
+something real. Each guide assumes you can already write and run a basic worker.
 
 ## Recipes
 

docs/how-to/pushdown-and-statistics.md

@@ -5,7 +5,7 @@ description: "How to integrate VGI table functions with DuckDB's optimizer: acce
 # Integrate with the optimizer
 
 **What this is:** how to make table functions cooperate with DuckDB's query optimizer — receiving
-pushed-down `WHERE` predicates and reporting column statistics so the planner can skip work.
+pushed-down `WHERE` predicates and reporting column statistics so the planner can skip work.<br>
 **Who it's for:** developers whose table functions back real data sources and want less data moved.
 
 ## Prerequisites
@@ -21,15 +21,16 @@ framework deserializes the predicates for you and exposes them on `params.curren
 as a `PushdownFilters` tree (or `None` when no filter applies), refreshed before each `process`
 call:
 
-```python test="skip"
+```python
+# illustrative — sketch using your own types
 class Events(TableFunctionGenerator[EventsArgs]):
     class Meta:
         filter_pushdown = True      # opt in to receiving WHERE predicates
 
     @classmethod
     def process(cls, params, state, out):
         filters = params.current_pushdown_filters   # PushdownFilters tree, or None
-        # apply `filters` while generating rows, then out.emit(...) / out.finish()
+        # apply the filters while generating rows, then out.emit(...) / out.finish()
 ```
 
 `PushdownFilters` is already decoded — you don't call `deserialize_filters` yourself (that helper is
@@ -43,7 +44,8 @@ When a table reports per-column min/max, null, and distinct-count statistics, Du
 can eliminate scans and order joins better. The declarative path is a `statistics` entry on the
 `Table` descriptor:
 
-```python test="skip"
+```python
+# illustrative — `schema` and the table stand in for your own catalog
 from vgi.catalog import Table
 from vgi.catalog.descriptors import ColumnStatisticsInput
 

docs/how-to/state-storage.md

@@ -5,7 +5,8 @@ description: "How to give VGI functions shared, persistent state across worker p
 # Persist state across workers
 
 **What this is:** how functions that span **multiple worker processes** (notably distributed
-aggregates) share and persist state. **Who it's for:** developers building aggregates or any
+aggregates) share and persist state.<br>
+**Who it's for:** developers building aggregates or any
 function that coordinates partial results across workers.
 
 ## Prerequisites

docs/index.md

@@ -14,7 +14,9 @@ Write a function, `uv run` the script, query it from SQL. Other languages work t
   <img src="assets/logo.png" alt="VGI logo" width="360">
 </p>
 
+<p align="center" markdown>
 Built by [🚜 Query.Farm](https://query.farm).
+</p>
 
 ## See it in action
 
@@ -85,13 +87,13 @@ custom ETL transforms, expose external data sources as queryable tables and view
 
 ## Function patterns
 
-| Type | Base class | SQL pattern | Use case |
+| Shape | Type | Base class | Use case |
 |---|---|---|---|
-| **Scalar** | `ScalarFunction` | `SELECT func(col) FROM t` | Per-row transforms (1:1) |
-| **Table** | `TableFunctionGenerator` | `SELECT * FROM func(args)` | Generate data |
-| **Table-in-out** | `TableInOutFunction` | `SELECT * FROM func((SELECT ...))` | Streaming transforms, filtering |
-| **Aggregate** | `AggregateFunction` | `SELECT func(col) ... GROUP BY` | Grouped accumulation |
-| **Buffering** | `TableBufferingFunction` | `SELECT * FROM func((SELECT ...))` | Sees every row first (sort, top-k) |
+| ![scalar shape](assets/kinds/scalar.svg){ height="32" } | **Scalar** | `ScalarFunction` | Per-row transforms (1:1) |
+| ![table shape](assets/kinds/table.svg){ height="32" } | **Table** | `TableFunctionGenerator` | Generate data |
+| ![table-in-out shape](assets/kinds/table-in-out.svg){ height="32" } | **Table-in-out** | `TableInOutFunction` | Streaming transforms, filtering |
+| ![aggregate shape](assets/kinds/aggregate.svg){ height="32" } | **Aggregate** | `AggregateFunction` | Grouped accumulation |
+| ![buffering shape](assets/kinds/buffering.svg){ height="32" } | **Buffering** | `TableBufferingFunction` | Sees every row first (sort, top-k) |
 
 See the [API Reference](api/index.md) for the full surface, or jump into the guides below.
 

docs/stylesheets/extra.css

@@ -234,13 +234,11 @@
   transform: scale(1.05);
 }
 
-/* Header logo — bigger than default, clipped to circle */
+/* Header logo — slightly bigger than default, full logo at its natural aspect ratio */
 .md-header__button.md-logo img,
 .md-nav__button.md-logo img {
-  height: 3rem;
-  width: 3rem;
-  border-radius: 50%;
-  object-fit: cover;
+  height: 1.8rem;
+  width: auto;
 }
 
 /* ── D2 diagrams — constrain size and center ── */