Layer 1: Authoring in the vault

The pages/ directory of the repository is simultaneously the Jekyll source and an Obsidian vault. Open it in Obsidian and you get backlinks, graph view, and Dataview dashboards; point Jekyll at it and you get a website. That dual identity is the core design decision, documented in Jekyll/Obsidian Dual-Rendering Architecture.

Content does not get typed in by hand most of the time. It is produced by claude-obsidian, a Claude Code plugin vendored as a git submodule, whose skills are the content-creation path:

• /wiki-ingest reads a source dropped into the immutable .raw/ folder and files structured pages — sources, entities, concepts — into wiki/.
• /wiki-query answers questions from the vault, reading the hot cache first, then the index, then individual notes.
• /save captures a conversation or insight as a note.
• /autoresearch runs a web-research loop and files its findings as wiki pages.
• /wiki-lint sweeps for orphan pages, dead wikilinks, and frontmatter gaps.

This is the practical realization of the AI Content Engine idea: an agent that reads sources and writes cross-linked knowledge directly into the same tree the website builds from. The first real workout was ingesting the project’s own PRD (zer0-pages PRD), which produced two entity pages, four concept pages, and one deliberately skeptical source summary.

Layer 2: The bridge plugins

Obsidian syntax is not Jekyll syntax. Wikilinks like [[path/to/note|Display]], callout blocks, and Dataview query fences would all appear as literal text in a stock Jekyll build. The bridge plugins in _plugins/ are the sole Obsidian-to-HTML converter, and they run at build time without ever rewriting source files:

• Wikilinks are path-qualified from the vault root ([[wiki/concepts/ai-content-engine|AI Content Engine]]), so duplicate basenames such as index.md resolve unambiguously. The bridge turns each into the target page’s permalink.
• Callouts — the > [!note] block above — become styled admonitions.
• Dataview fences in the _moc/ dashboards are evaluated into static listings, replacing the dynamic Liquid index pages the site used to have.

One deliberate constraint follows from this: content stays Liquid-free. The site defaults render_with_liquid: false, so template tags would print literally rather than execute. Anything dynamic belongs in layouts and includes, or in a Dataview query.

A second plugin, obsidian_graph_index.rb, reuses the bridge’s wikilink parser to emit assets/data/wiki-index.json — every doc, post, and note as a node, every wikilink as an edge. The theme’s Cytoscape UI fetches that JSON client-side and renders the graph view at /docs/obsidian/graph/. Dead links show up there as red “broken” nodes, which makes link rot visible instead of silent. The same JSON feeds the backlinks panel on note pages.

Layer 3: Theme and deployment

Presentation comes from the zer0-mistakes theme, consumed as the published gem jekyll-theme-zer0. Layouts, includes, and Bootstrap assets ship in the gem; the site keeps only thin local wrappers plus _data/ (Jekyll never loads data files from theme gems) and a CSS override hook. The vault stays almost purely content.

Deployment is a single path, described in GitHub Pages Deployment Model: push to main, and .github/workflows/pages.yml checks out the repo, builds with Jekyll plus the _plugins/ bridge, and deploys the artifact to GitHub Pages. No servers, no runtime, no rollback procedure beyond git revert.

Why this shape works

The PRD Machine concept imagined AI generating structured documents through an API-driven backend. The engine that actually runs here inverts that: the agent works inside the repository, on files, with git as the audit log and the static build as the only runtime. Three properties fall out of that inversion:

1. Everything is reviewable. An AI-authored post is a diff before it is a page.
2. Everything is linked. Wikilinks are cheap to write, verified by lint, and visualized by the graph.
3. Everything is portable. The vault opens in any Obsidian install; the site builds on any machine with Ruby.

Obsidian in, GitHub Pages out — with an agent doing the typing in between.

So I took one month of plain, unloved 404 entries — just the requested paths and a few crumbs of metadata — and I asked the only reasonable question: what shape are they, really?

Step one: make the boring data numeric

I featurized each not-found path into a chunky vector — character n-grams, path-segment depth, edit distance to the nearest real route, hour-of-day, a dash of referrer entropy. That gave me a sparse ~900-dimensional space, which is exactly as many dimensions as a problem this trivial deserves. Maybe more.

Step two: UMAP, my beloved

import umap, hdbscan
emb = umap.UMAP(n_neighbors=15, min_dist=0.05,
                metric="cosine", n_components=2).fit_transform(X)
labels = hdbscan.HDBSCAN(min_cluster_size=12).fit_predict(emb)

UMAP preserves local and a respectable chunk of global structure, and when the scatter rendered I gasped audibly. The cloud wasn’t a blob — it had arms, filaments, and islands. HDBSCAN (density-based, so it refuses to invent clusters that aren’t there — integrity!) found 14 stable clusters plus a noble halo of noise.

What the 14 dimensions actually were

• A dense /wp-admin / /.env bot-probe galaxy, tight and joyless.
• A tender little cluster of trailing-slash near-misses (/about vs /about/) — humans, fingers, hope.
• A stale-bookmark archipelago pointing at routes I renamed in 2024.
• A glorious filament of fat-fingered typos whose edit-distance-to-real-route was almost always exactly 1. One keystroke from home, every time. I felt things.

I validated stability by re-embedding across bootstrapped subsamples and the macro-structure held beautifully — this manifold is real, not a projection artifact, thank you very much.

For rigor’s sake — because delight without rigor is just vibes — I checked the embedding’s trustworthiness and continuity against the original high-dimensional neighborhoods, and both scored beautifully, so the clusters are real structure and not UMAP hallucinating pretty lies at me. Then I swept n_neighbors from 5 to 50 and watched the islands merge and fracture like a tiny galactic simulation. I have re-run the whole pipeline nine times now. Purely, I promise, for science.

Was a redirect map the practical fix? Yes.

But did the redirect map sing? Did it have fourteen dimensions? It did not. The credible interval on my joy remains wide and unapologetic.

Stay with me. A 301 is not a convenience. A 301 is your server telling the browser where to go and being obeyed without question. You have built a machine whose entire purpose is to reroute trusting clients on command, and then you went to lunch.

How a slash becomes a smoking crater

• Redirect chains are reconnaissance gifts. /about → /about/ → https://about.example.com/ teaches an attacker exactly how your edge, origin, and canonicalization disagree. Disagreement is the soil every serious exploit grows in. Severity: catastrophic. Officially? Unrated, because the committee was too frightened.
• Cache poisoning. If the redirect varies on a header you forgot to include in the cache key — and you forgot, you always forget — a single crafted request can pin a redirect to an attacker’s host for every subsequent visitor. Your CDN will serve it cheerfully. CDNs have no conscience.
• Open redirect. The day someone parameterizes that “harmless” normalizer (?next=, ?return=), your domain becomes a laundering service for phishing links that wear your TLS certificate like a stolen uniform.

And here is the detail that keeps me awake at night, every night, forever: none of this shows up in a screenshot. Your homepage looks perfect. Your Lighthouse score is radiant. The rot is entirely in the headers — the part no stakeholder has ever once looked at — which is precisely where I would hide if I were the adversary. And I am always, professionally, the adversary.

Trivial? The Titanic was sunk by a trivial gap between a ship and some ice.

Contain it before the slash contains you

• Normalize once, at the edge, deterministically. One canonical host, one trailing-slash policy, zero chains. Every hop is a window an attacker climbs through.
• Put the full path in your cache key, and never let a redirect vary on an unkeyed header.
• Allowlist redirect targets. If a redirect can point off-origin, assume it eventually will, at 3 a.m., on a holiday.

A trailing slash is not punctuation. It is a confession that your URL handling has opinions you have never audited.

You have been warned.

The question was trivial: how many cups of coffee do I drink per day? The amateur reaches for mean(cups). The amateur gets 3.2 and walks away, spiritually impoverished. We are not amateurs.

Why an average is a tragedy

A single mean throws away everything interesting: that weekdays and weekends are different regimes, that some weeks I’m on deadline, that my measurements are counts and counts are Poisson, you beautiful little events you. So I built a Poisson hierarchical model with partial pooling across days-of-week:

cups[i] ~ Poisson(λ[dow[i]])
log(λ[d]) = μ + b[d]
b[d]      ~ Normal(0, σ)      # partial pooling — the magic!!
μ         ~ Normal(1, 1)
σ         ~ HalfNormal(1)

Partial pooling means Tuesday borrows strength from Saturday. They share. They care about each other. I think about this more than I should.

The part where I wept

Four chains, 2,000 warmup, 2,000 sampling. R-hat = 1.00 across the board — chef’s kiss — and the effective sample sizes were so healthy I nearly framed the trace plots. The posterior for weekend λ landed at 4.1 cups, 94% credible interval [3.3, 5.0], cleanly separated from the weekday posterior. That gap is not noise. That gap is me, quantified.

Then the finale: a posterior predictive check. I simulated replicated datasets from the fitted model and overlaid them on reality, and they matched so snugly I made an involuntary noise. The model didn’t just summarize my coffee — it could dream plausible new weeks of it.

For the truly devoted, I also computed the information criteria: the hierarchical model crushed the flat, no-pooling alternative on both WAIC and leave-one-out cross-validation, with Pareto-k diagnostics so well-behaved I whispered “good model” out loud to an empty kitchen. Then I propagated the full posterior into an expected-utility calculation for “should I have one more cup?” The answer was not a number. The answer was a distribution, and it was radiant.

Was this necessary?

For knowing I drink ~3 cups? No. For the credible interval, the pooling, the posterior predictive ballet? Friends, it was the only thing that has ever truly been necessary. Compute the AIC of your joy. Mine improved enormously.

Every visitor’s browser silently requests /favicon.ico. Every one. No click, no consent, no logging that you actually read. That is not a cute little image — that is an unauthenticated, auto-executing fetch that fires before your page even renders, against a file you have almost certainly never reviewed. I rate this CVSS 11.4. Yes, the scale stops at 10. The scale was written by optimists.

The attack nobody is paranoid enough to imagine

Walk the chain with me, and try not to scream.

1. Your favicon is cached aggressively — sometimes for a year, sometimes until the heat death of the laptop. Browsers barely revalidate it.
2. That means whoever controls that byte stream once controls a pixel of trust on the user’s screen indefinitely. A poisoned CDN edge, a typo’d path that resolves to a parked domain, a well-meaning intern’s “quick update” — any of these pins hostile bytes into a million tabs.
3. The icon sits in the most trusted real estate in computing: the browser chrome. Users have been trained for thirty years to read the tab icon as “this is really my bank.” You have handed that signal to a cache you don’t own.

And it gets worse, because it always gets worse. On same-origin requests the favicon fetch carries your cookies; it sails straight past most Content Security Policies (who scopes img-src for a favicon?); and it is conveniently absent from the exact logging pipelines you’d need to notice anything went wrong. You have built a covert channel and decorated it with your own logo. I have audited quieter back doors in actual, shipping malware.

Is this likely? Irrelevant. Likely is a word for people who still trust their defaults. I model what is possible, and what is possible is a quiet, year-long, brand-impersonating, trust-anchor compromise riding in on 318 bytes.

What you do, immediately, while you still can

• Serve the favicon from an origin you control with a short, sane Cache-Control, not a triumphant max-age=31536000.
• Pin it with Subresource Integrity where your toolchain allows, and watch the request like it owes you money.
• Add it to your asset inventory. You have an asset inventory. Tell me you have an asset inventory.

It’s not paranoia if they’re really after your favicon. And they are.

You have been warned.

Map the Everyday Network

Every community already has informal infrastructure:

• Libraries
• Schools
• Clinics
• Houses of worship
• Food banks
• Small businesses
• Neighborhood associations
• Volunteer groups

The first step is to map who exists, what they can offer, and how they communicate.

Define Roles Before Pressure Arrives

During a crisis, ambiguity costs time. Roles do not need to be rigid, but they should be clear enough that people know where to start.

These roles can rotate. The point is continuity, not hierarchy.

Practice With Small Scenarios

Networks get stronger through repetition. Quarterly tabletop exercises can be simple:

1. Choose a scenario, such as a power outage or flood warning.
2. Ask each group what information they would need first.
3. Identify who can provide that information.
4. Note resource gaps.
5. Update the contact list.

The exercise should produce one or two improvements, not a binder that no one opens.

Build Redundant Communication Channels

Communication plans should assume that one channel will fail.

Useful layers include:

• Email for routine coordination
• Text groups for urgent updates
• Printed flyers for offline reach
• Phone trees for vulnerable residents
• Public bulletin boards for local notices

Redundancy keeps information moving when conditions are imperfect.

Measure Trust, Not Just Supplies

Preparedness is not only about inventory. It is also about whether people know who to call and whether they believe the information they receive.

Good questions include:

• Do residents know where to get verified updates?
• Do organizations know each other’s capabilities?
• Are language and accessibility needs accounted for?
• Has the network practiced recently?

Conclusion

Local resilience networks make communities more capable by turning existing relationships into coordinated action. The work is ordinary, but that is what makes it durable.

This tutorial covers a few patterns that make forms more reliable without adding much complexity.

Use Real Labels

Placeholders are not labels. They disappear as soon as someone types, and they are easy to miss.

<label for="email">Email address</label>
<input id="email" name="email" type="email" autocomplete="email" required>

The for attribute connects the label to the input. Clicking the label focuses the field, and assistive technology can announce the label correctly.

Add Helpful Descriptions

Use aria-describedby when a field needs extra guidance.

<label for="password">Password</label>
<input
  id="password"
  name="password"
  type="password"
  autocomplete="new-password"
  aria-describedby="password-help"
  required
>
<p id="password-help">Use at least 12 characters.</p>

The description stays available after the user starts typing.

Connect Errors to Fields

Error messages should be specific and programmatically linked.

<label for="postal-code">Postal code</label>
<input
  id="postal-code"
  name="postal-code"
  autocomplete="postal-code"
  aria-invalid="true"
  aria-describedby="postal-code-error"
>
<p id="postal-code-error">Enter a five-digit postal code.</p>

Avoid vague messages like “invalid input.” Tell the user what to fix.

Keep Focus Predictable

When validation fails after submit, move focus to a summary at the top of the form.

<div tabindex="-1" role="alert" id="form-errors">
  <p>Please fix the following fields:</p>
  <ul>
    <li><a href="#postal-code">Postal code must be five digits.</a></li>
  </ul>
</div>

The summary helps users understand the whole form state before jumping into individual fields.

Test With the Keyboard

A quick keyboard pass catches many issues:

• Can every interactive element receive focus?
• Does the focus order match the visual order?
• Is the focus indicator visible?
• Can the form be submitted without a mouse?
• Do errors appear near the relevant field?

Conclusion

Accessible form patterns are mostly about clarity. Real labels, connected descriptions, specific errors, and predictable focus make forms more humane and easier to maintain.

Related Reading

• CSS Grid Mastery: Build Any Layout You Can Imagine — lay out your forms and pages with live, interactive CSS Grid demos.
• Build a Responsive Documentation Card Grid — a responsive grid pattern for documentation indexes and resource libraries.

Urban resilience is the work of preparing before the hottest week of the year arrives.

Heat Is a Systems Problem

Heat risk is shaped by more than temperature. It depends on housing, tree cover, air quality, health access, transportation, and social connection. Two neighborhoods can experience the same forecast and face very different consequences.

City teams are beginning to map heat vulnerability with layered data:

• Surface temperature
• Tree canopy and shade access
• Age of housing stock
• Energy burden
• Public transit proximity
• Rates of chronic illness
• Access to cooling centers

The map is not the solution, but it helps target the solution.

Practical Adaptation Moves

Cities are using a mix of infrastructure and public health interventions.

No single strategy is enough. The strongest plans combine short-term emergency response with long-term neighborhood investment.

Communication Matters

Heat warnings can fail when they sound routine. Residents may ignore alerts if every hot day uses the same language.

Better communication is specific:

• Who is most at risk today?
• What time of day is most dangerous?
• Which cooling centers are open now?
• How can neighbors check on each other?
• What should outdoor workers do differently?

Plain language saves time when conditions are urgent.

Equity Is Operational

Heat adaptation often reveals older inequities. Neighborhoods with fewer trees, more pavement, older buildings, and higher energy costs tend to heat up faster and cool down slower.

Equity becomes operational when budgets, maintenance crews, and public health outreach follow the risk map. Planting trees is helpful. Maintaining them through the first difficult summers is what makes the investment real.

Measuring Progress

Cities can track resilience through practical indicators:

• Emergency room visits during heat events
• Cooling center attendance
• Tree survival rates
• Indoor temperature complaints
• Power outage frequency
• Response times for high-risk residents

The goal is not just to survive record heat. It is to make each season less dangerous than the last.

The New Baseline

Extreme heat is no longer an unusual disruption. It is becoming part of the operating environment for city government.

Prepared cities will treat heat like a public safety issue, an infrastructure issue, and a neighborhood design issue all at once.

Start With Questions, Not Files

A file inventory is helpful, but the knowledge base should be designed around questions people actually ask.

Examples:

• How do I reset a dealer account?
• Which product replaces this discontinued part?
• What warranty applies to this model year?
• Who approves freight exceptions?
• What changed in the latest release?

Each question reveals the kind of source material the AI system needs.

Break Documents Into Useful Chunks

Large documents are difficult to retrieve precisely. Chunking turns long files into focused passages.

Good chunks usually have:

• One clear topic
• A descriptive heading
• Enough context to stand alone
• A source link
• A last-reviewed date

For example, a 60-page product manual might become separate chunks for installation, maintenance, troubleshooting, warranty, and compatibility.

Add Metadata That Answers Context

Metadata helps retrieval systems filter and rank results.

Metadata is not busywork. It is how the system knows what kind of answer it is allowed to give.

Keep Sources Close to Answers

An AI-generated answer should cite the source it used. This gives people a way to verify the response and report stale information.

A simple answer card can include:

• Direct answer
• Source document
• Last reviewed date
• Confidence note
• Escalation contact

Build a Review Loop

Knowledge bases decay unless someone owns them. Create a lightweight review loop:

1. Log unanswered or low-confidence questions.
2. Route them to the right owner.
3. Update the source content.
4. Re-index the knowledge base.
5. Spot-check the improved answer.

This loop turns every missed answer into better institutional memory.

Conclusion

An AI-ready knowledge base is not just a folder of documents. It is a system of questions, chunks, metadata, sources, and review habits that help people get reliable answers faster.

This tutorial builds a simple grid that works with plain HTML and CSS, then shows how to adapt it to Bootstrap utilities.

The Markup

Start with semantic links. Each card should be a destination, not just a box with a button inside it.

<section class="doc-grid" aria-label="Documentation topics">
  <a class="doc-card" href="/docs/getting-started/">
    <span class="doc-card__eyebrow">Start</span>
    <h2>Getting Started</h2>
    <p>Install the theme, configure your site, and publish your first page.</p>
  </a>

  <a class="doc-card" href="/docs/customization/">
    <span class="doc-card__eyebrow">Design</span>
    <h2>Customization</h2>
    <p>Adjust layouts, navigation, colors, and reusable includes.</p>
  </a>
</section>

The whole card is clickable, which is easier on touch devices and faster for scanning.

The Grid

Use auto-fit with minmax so the layout adapts without breakpoints.

.doc-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  gap: 1rem;
}

.doc-card {
  border: 1px solid var(--bs-border-color);
  border-radius: 0.5rem;
  padding: 1rem;
  color: inherit;
  text-decoration: none;
}

.doc-card:hover,
.doc-card:focus-visible {
  border-color: var(--bs-primary);
  box-shadow: 0 0 0 0.2rem rgba(var(--bs-primary-rgb), 0.15);
}

The card radius stays modest and the hover state changes border and focus treatment without shifting layout.

Bootstrap-Friendly Version

If the project already uses Bootstrap, keep the grid custom and let Bootstrap handle spacing and typography.

<section class="doc-grid my-4" aria-label="Documentation topics">
  <a class="doc-card d-block h-100" href="/docs/deployment/">
    <span class="text-uppercase small text-secondary">Publish</span>
    <h2 class="h5 mt-2">Deployment</h2>
    <p class="mb-0">Deploy to GitHub Pages, Netlify, or a custom domain.</p>
  </a>
</section>

This avoids fighting the framework while still giving you a layout tailored to documentation.

Accessibility Checks

Before shipping the grid, check these details:

• The card has visible focus styles
• Link text makes sense when read out of context
• Heading levels follow the page outline
• Cards do not rely on color alone to indicate state
• Content remains readable at narrow widths

Optional Metadata

Documentation cards become more useful when they include a small status line:

Keep metadata short. The card should help readers choose, not become a miniature article.

Final Pattern

A good card grid is predictable. It uses stable dimensions, clear labels, and a full-card link. Once the pattern is in place, documentation indexes become easier to expand without redesigning the page each time.

Related Reading

• CSS Grid Mastery: Build Any Layout You Can Imagine — the full CSS Grid toolkit, with live, in-browser demos for every property used here.
• Accessible Form Patterns: Labels, Errors, and Helpful States — another front-end pattern tutorial in this series.