wal.sh is a personal research archive. It collects technical notes, conference observations, and extended investigations in the areas of programming languages, distributed systems, AI agent architectures, and formal methods. The audience is technical and self-selecting. There is no marketing copy and no onboarding flow. Readers arrive already knowing what they are looking for.

The site does not have a product to sell. Its purpose is to make research thinking legible across time and across sessions.

The writing voice is direct and claim-forward. Notes open with an assertion or a concrete fact, not a description of what the note will cover. Abstractions are introduced after the concrete example that motivates them, not before.

Sentences are complete. Lists are used for enumeration, not as a substitute for prose. Code blocks contain code; prose describes what the code does and why it matters.

The visual language is quiet and scholarly. The page presents text with a minimum of decoration. Color appears in diagrams, not in navigation or prose layout. The chrome (header, footer, links) is subdued — greys and a single blue accent. Diagrams are the visual centerpiece of each research page; they carry structure and color while the surrounding page recedes.

The design deliberately avoids:

• Pull quotes, callout boxes, or highlight panels on prose sections
• Colored backgrounds behind text
• Decorative icons in navigation
• Heavy border treatments on content elements

The one exception is the .ai block, which uses a pale blue left-border treatment to mark content that originated from an AI assistant.

This palette governs all Graphviz diagrams. Each color family encodes a fixed semantic role across all diagrams on the site. The mapping must not be broken for aesthetic reasons — it is a protocol, not a preference.

The 100-weight fills are the pastel node backgrounds. The 700-weight values serve triple duty: node border, node text color, and cluster label. The 50-weight is for cluster backgrounds only, lighter than the node fill so the cluster recedes behind its contents.

All hex values are full 6-digit. Shorthand hex (#d63) is prohibited. Named HTML colors (lightblue, yellow) are prohibited. They are not reproducible across Graphviz renderers.

These values come from the style.css :root block and are used for page chrome, text, and UI elements.

Additional grey values appear in component-specific contexts:

The same blue accent (#0066cc) serves as the link color in prose, the blockquote border, and the .ai block border. This creates a consistent "interactive or generated" signal: anything with that blue treatment is either a link to follow or content that came from an AI source.

Diagram colors are intentionally distinct from the CSS neutral palette. The pastel diagram fills (#dbeafe, #dcfce7, etc.) do not appear in the site CSS. This separation prevents visual bleed between page chrome and diagram semantics.

All headings use font-weight: 700 and letter-spacing: -0.02em. Color is #1a1a1a, same as body text.

The page h1.title from org-publish is hidden via #content > h1 { display: none }. The visible page title is emitted by the preamble as a <header class"page-header"><h1>= on non-index pages. Index pages use the org-mode h1 directly.

Links use color: var(--accent) (#0066cc) with text-decoration: underline and text-underline-offset: 2px. On hover, the background becomes var(--accent-light) (#e6f2ff). Nav links in the site header suppress the underline and use var(--text-secondary) at 0.9rem.

Two distinct code block treatments coexist:

All diagram text uses fontname"Helvetica"=. Three sizes, applied consistently across all diagrams:

Navigation links, author lines, dates, and footer text use var(--text-secondary) (#666) at reduced sizes (0.85rem–0.95rem).

Every published page follows this vertical structure:

<header class="site-header">          preamble: sitewide nav + logo
<div class="breadcrumbs">             preamble: path from home to current page
<header class="page-header">          preamble: page h1 (non-index pages only)

  [org-mode content body]

    banner image (728x90 greyscale)
    prose sections
    diagrams
    tables
    code blocks

#postamble                             postamble: author, date, build info
                                       postamble: adtech includes (conditional)
                                       postamble: web-vitals (conditional)
.webring                               postamble: webring navigation

The content body is the org-mode HTML export. The page title h1 is suppressed from the org export (display: none) and re-emitted by the preamble so it appears before breadcrumbs do not interrupt the title.

The site header is a flex row with justify-content: space-between, separated from content by a 1px #eaeaea border-bottom and 3rem margin-bottom.

Left: navigation list with four items (Home, Current, Research, Events) in var(--text-secondary) at 0.9rem.

Right: logo image (48x48px) linking to /, wrapped in .site-logo.

Generated programmatically from the file path relative to the site root. The root index page emits no breadcrumbs. All other pages show a path: home > section > subsection > page (YYYY-MM-DD). Breadcrumb links use var(--text-secondary) at 0.85rem, with last-modified date in parentheses on the leaf entry.

Each research page opens with a 728x90 greyscale leaderboard banner image. Banners sit between the page-header and the first body section. Images are centered via display: block; margin: 2rem auto.

Org reference form:

#+ATTR_HTML: :alt <description> :class banner-leaderboard :width 728 :height 90
[[file:banner.png]]

Banner images are produced from a source graphic using:

magick input.png -resize 728x90^ -gravity center -extent 728x90 -colorspace Gray output.png

The greyscale constraint is intentional: diagrams carry the color on the page. A color banner would compete with the diagrams for attention.

Diagrams are PNG images exported from Graphviz .dot files by org-babel during publish. They are placed via standard org image links:

#+CAPTION: <description of what the diagram shows>
#+NAME: fig:<identifier>
#+ATTR_HTML: :alt <alt text describing content for screen readers>
[[file:<diagram-name>.png]]

Images are max-width: 100%, height: auto, centered with 2rem margins. No explicit width or height is set in HTML for diagram images; they scale to content width.

The postamble is generated by wal-sh/org-html-postamble. It contains:

1. <p class"author">= — Author name
2. <p class"email">= — Email in angle brackets (via CSS ::before / ::after)
3. <p class"date">= — Last modified timestamp from file system
4. <p class"build-info"><code>= — build timestamp and git SHA

Followed by conditional adtech performance-art includes, web-vitals measurement, and the webring navigation element.

The #postamble element uses font-size: 0.85em, color: var(--text-secondary), centered, with a 1px #eaeaea border-top and 3rem top margin.

728x90 pixels, greyscale, leaderboard format. One per research page, placed immediately after the page title / first section heading. Alt text is required and should describe the visual content meaningfully for screen readers. The :class banner-leaderboard attribute is always set.

Graphviz dot diagrams, compiled to PNG via org-babel #+begin_src dot blocks during publish. Every diagram follows the palette and node conventions described in section 6. Each diagram image requires:

• #+CAPTION — prose description of the claim the diagram makes
• #+NAME — a fig: prefixed identifier for internal linking
• #+ATTR_HTML with :alt — screen-reader description

The site had 53+ dot files as of 2026-05-19, all following the canonical palette. Mermaid diagrams in older pages have been converted to dot.

Org source blocks with language tags export with the dark Catppuccin Mocha theme. Plain #+begin_example blocks export as plain grey <pre> elements. The language label is rendered via CSS ::before.

The :eval no :tangle no header args appear on code blocks that are documentation examples not intended for execution.

Org tables export as HTML tables with width: 100%, border-collapse: collapse, and margin: 1.5rem 0. Cell padding is 0.75rem 1rem. Rows are separated by a 1px #eaeaea border-bottom. Headers use font-weight: 600. No zebra striping. Tables scroll horizontally on narrow viewports.

Left border: 3px solid #0066cc (var(--accent)). Italic text in var(--text-secondary). No background fill.

<div class"ai">= is used to mark content that originated from an AI assistant. It uses var(--accent-light) background and a 3px var(--accent) left border, matching the blockquote treatment. A copy button (.copy-javascript) is positioned absolutely in the top-right corner.

Org TODO/DONE keywords export as inline badges:

0.7em, uppercase, padded, border-radius: 3px.

Exported as .property-drawer in var(--text-secondary) at 0.8em, using font-family: monospace and white-space: pre.

Both internal [[file:...]] links and external [[https://...]] links render identically: #0066cc with underline, pale blue hover background. The distinction between internal and external is not visually signaled beyond what the URL itself communicates.

The webring element appears at the very bottom of every page, outside the main postamble block. It is a <nav class"webring">= with prev and next links populated by /static/js/webring.js at runtime.

Styling: centered, padding: 0.75rem 0, border-top: 1px solid var(--border), font-size: 0.85rem, opacity: 0.7 (rising to 1 on hover). The .ring-label element uses font-style: italic and color: var(--muted, #888).

1. Color encodes semantics, not decoration. Each of the six color families carries a fixed meaning across all diagrams. Blue is input and primary flow. Green is output and success. Red is error and critical path. A reader can identify state semantics from color before reading labels.
2. Diagrams carry the color; banners stay quiet. Research page banners are greyscale. The pastel diagrams are the visual centerpiece of the page. A color banner would compete with the diagram for the reader's attention.
3. The palette is a protocol, not a preference. The Tailwind 100/700 pairs were chosen because they are widely known, machine-readable, and have accessible contrast ratios. The cost of replacing them would require updating every diagram simultaneously.

Every node uses shape=box with style"rounded,filled"=. Three color attributes are mandatory and must come from the same family:

• fillcolor — 100-weight pastel fill
• color — 700-weight border
• fontcolor — 700-weight text (black text on a pastel node means this attribute is missing)

Special shapes:

• shape=note — annotation nodes and legend entries; still uses the palette
• shape=diamond — decision points in pipelines; typically amber
• shape=plain — invisible structural nodes (start/end markers in state machines); no fill, no border

Default cluster style is border-only: a colored border with a white interior. The cluster border and label both use the 700-weight of the dominant color family of its contents.

subgraph cluster_name {
    label="Cluster Title";
    style="rounded";
    color="#1d4ed8";      // border: 700-weight
    fontcolor="#1d4ed8";  // label: 700-weight
    fontname="Helvetica";
    fontsize=11;
}

Use style"rounded,filled"= with a 50-weight fillcolor only when the cluster background needs to visually separate regions — layer stacks or side-by-side comparisons. Prefer border-only for all other cases. Never use #fafafa for clusters; it has no semantic meaning.

The feedback edge in a process loop is always dashed and uses the default grey, signaling that the loop is structural rather than representing an error or degraded path.

ASCII arrow diagrams in #+begin_example blocks that represent data flows, state machines, or architectures should be converted to Graphviz dot diagrams. ASCII directory trees (├── .config/) and inline prose arrows stay as text.

• Shorthand hex (#369, #d63)
• Named HTML colors (lightblue, yellow)
• Dark backgrounds with light text (inverts the site's light theme)
• Hard saturated fills (always use the 100-weight pastel)
• Non-Helvetica fonts
• Neutral grey clusters (#444 / #fafafa)
• Missing fontcolor (produces black text on pastel background)

Every published page requires these five headers:

Optional but common:

• #+URL — canonical URL for the page
• #+KEYWORDS — comma-separated, lowercase, hyphen-separated
• #+OPTIONS: toc:2 num:t — table of contents depth and section numbering
• #+SUBTITLE — appears under the title in some contexts

New research notes are scaffolded from site/templates/research-note-dir/index.org for directory-form notes, or site/templates/research-note.org for flat files. The template provides the correct header set and a placeholder body. The slug must be kebab-case (^[a-z0-9][a-z0-9-]*[a-z0-9]$).

Research pages live in site/research/ (flat .org files) or site/research/<slug>/index.org (directory form). Directory form is preferred for notes that include multiple images, diagrams, or supplementary files.

Event pages live in site/events/<conference>/<year>/index.org. They record observations from attended conferences and follow the same header requirements.

The * current focus section in site/index.org lists recent research in reverse chronological order, newest first. Each entry follows this format:

- YYYY-MM [[file:research/<slug>/index.org][display title]] --- one-line abstract

Older items are moved to the * 2025, * past, or ** 20XX sections below current focus. The current focus section should contain only the most recent entries (roughly the last six to twelve months).

External links (GitHub repos, external sites) use [[https://...][title]] in the same list.

Internal links to published pages use [[file:research/<slug>/index.org]] or [[file:research/<slug>.org]]. The Emacs export filter wal-sh/clean-url-filter rewrites foo/index.html to foo/ and foo.html to foo in the published HTML, producing clean extensionless URLs.

The following are excluded from org-publish:

• README.org, SECURITY.org, CLAUDE.md, HEALTH_CHECKS.org
• site/includes/ — HTML fragments assembled at publish time
• site/_drafts/ — work in progress not ready for publication
• site/templates/ — scaffolding files
• site/research/ai_model_outputs/ — raw data files
• Files matching *-YYYY.org — year-template placeholders

The postamble includes a build timestamp and git SHA in the form build: YYYY-MM-DD HH:MM | sha: <short-sha>. This appears in a <code> element inside a .build-info paragraph.

Half-formed notes belong in site/_drafts/. That directory is excluded from org-publish, so drafts can be committed without appearing on the live site. When ready, the file is moved into the appropriate site/research/ or site/events/ path.