Redesign the OpenShell research journal

.github/workflows/docs.yml

@@ -11,8 +11,27 @@ permissions:
   contents: read
 
 jobs:
+  renderer-tests:
+    name: Test Dev Notes renderer (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run renderer tests
+        run: python -m unittest discover -s tests
+
   validate:
     name: Validate documentation
+    needs: renderer-tests
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -28,9 +47,15 @@ jobs:
       - name: Check Dev Notes renderer syntax
         run: python -m py_compile scripts/render-dev-notes.py
 
+      - name: Check navigation JavaScript syntax
+        run: node --check docs/javascripts/navigation-drawer.js
+
       - name: Build documentation
         run: scripts/build-docs.sh
 
+      - name: Verify generated documentation is committed
+        run: git diff --exit-code -- docs/dev-notes zensical.toml
+
   deploy:
     name: Deploy documentation
     if: >-

AGENTS.md

@@ -46,8 +46,10 @@ explicit `url` or `avatar` fields when needed.
 Each Dev Note post needs `title`, `date`, `description`, and at least one
 author. The landing card uses `description` as its summary, `categories[0]` as
 the topic after `Dev Note`, and `card_tags` when present; otherwise it falls
-back to `tags`. `card_variant` is optional and maps to a CSS modifier such as
-`.dev-note-card--launch`.
+back to `tags`. Dates must use the exact `YYYY-MM-DD` form. `card_variant` is
+optional and maps to both the card and artwork CSS modifiers, such as
+`.dev-note-card--launch` and `.dev-note-card__visual--launch`; add the
+corresponding styles when introducing a new visual variant.
 
 Posts are sorted newest first by ISO `date`, then title. Use dated filenames
 such as `YYYY-MM-DD-short-title.md` so file paths stay stable and readable, but

README.md

@@ -12,6 +12,8 @@ OpenShell as the runtime.
 - `docs/dev-notes/` contains research engineering updates, release notes, and
   build logs worth sharing.
 - `docs/dev-notes/authors.json` contains reusable Dev Notes author metadata.
+- `docs/documentation/` contains durable guides and references for packages,
+  libraries, benchmarks, and examples introduced in Dev Notes.
 - `projects/` contains self-contained research projects and a reusable Python
   project template.
 - `scripts/render-dev-notes.py` renders Dev Notes cards, post bylines, and
@@ -31,6 +33,7 @@ To preview the documentation locally:
 python3 -m venv .venv
 source .venv/bin/activate
 python -m pip install -r requirements-docs.txt
+python scripts/render-dev-notes.py
 zensical serve
 ```
 
@@ -55,14 +58,22 @@ after validation passes.
 Add new posts under `docs/dev-notes/posts/` with a dated filename such as
 `YYYY-MM-DD-short-title.md`. Set `authors` to IDs from
 `docs/dev-notes/authors.json`; add new authors there once, including their
-GitHub handle and description. Run `python scripts/render-dev-notes.py` after
-editing posts or authors so the landing-page cards, visible post bylines, and
-Dev Notes navigation stay in sync.
+GitHub handle and description. Dates must use the exact `YYYY-MM-DD` form.
+`card_tags` controls the landing-page taxonomy (falling back to `tags`), and an
+optional `card_variant` selects a matching visual modifier such as `launch`.
+Run `python scripts/render-dev-notes.py` after editing posts or authors so the
+landing-page cards, visible post bylines, and Dev Notes navigation stay in
+sync; CI verifies that generated changes are committed.
+
+### Documentation
+
+Add durable software documentation under `docs/documentation/` when a Dev Note
+introduces a package, library, benchmark, or reusable example. Link the
+documentation back to its originating Dev Note and cover installation, usage,
+reproducibility requirements, and known limitations. Add the new page beneath
+the `Documentation` entry in `zensical.toml`.
 
 ## Content model
 
-Use the documentation for durable project knowledge: architecture notes,
-application guides, runtime integration details, and reproducible research
-engineering workflows. Use Dev Notes for dated updates: experiments, milestones,
-benchmarks, release notes, and lessons learned while turning research into OpenShell
-applications.
+Use Documentation for durable software knowledge. Use Dev Notes for dated
+experiments, benchmarks, releases, use case examples, and engineering updates.

docs/dev-notes/index.md

@@ -1,57 +1,108 @@
 ---
 title: Dev Notes
-description: Dated engineering notes, experiments, milestones, and lessons from building OpenShell research applications.
+description: Research field notes, experiments, milestones, and lessons from building OpenShell research applications.
 hide:
   - toc
 ---
 
-# Dev Notes
-
-<section class="dev-notes-hero" aria-labelledby="dev-notes-title">
-  <div class="openshell-brand-lockup dev-notes-hero__brand">
-    <img src="../assets/brand/openshell-mark.svg" alt="" aria-hidden="true">
-    <span>Open<strong>Shell</strong> Research</span>
-  </div>
-  <div class="dev-notes-hero__body">
-    <p class="dev-notes-kicker">Research-to-runtime field notes</p>
-    <h2 id="dev-notes-title">
-      <span>What changed,</span>
-      <span>what worked,</span>
-      <span>and what we learned.</span>
-    </h2>
-    <p>
-      Dev Notes are the dated engineering record for OpenShell Research: build
-      logs, experiment results, runtime discoveries, release notes, and the
-      useful mistakes that should not have to be rediscovered.
-    </p>
-  </div>
-</section>
+<div class="dev-notes-page">
+  <header class="research-masthead" aria-labelledby="dev-notes-title">
+    <div class="research-masthead__topline">
+      <span class="research-masthead__identity">
+        <img src="../assets/brand/openshell-mark.svg" alt="" aria-hidden="true">
+        OpenShell Research / Dev Notes
+      </span>
+    </div>
+    <div class="research-masthead__layout">
+      <div class="research-masthead__copy">
+        <h1 id="dev-notes-title">Dev Notes</h1>
+        <p class="research-masthead__dek">
+          Technical notes from the OpenShell team – reproducible research,
+          benchmarks, and use case examples.
+        </p>
+      </div>
+    </div>
+  </header>
 
 <!-- dev-notes:posts:start -->
 <!-- Generated by scripts/render-dev-notes.py; edit posts and authors.json. -->
-<section class="dev-notes-grid" aria-label="Dev Notes posts">
-  <article class="dev-note-card">
-    <a class="dev-note-card__link" href="posts/2026-06-05-making-dev-notes-repeatable/">
-      <span class="dev-note-card__meta">June 5, 2026 / Dev Note / Documentation</span>
-      <h2>Making Dev Notes Repeatable</h2>
-      <p>A repeatable author and post workflow keeps Dev Notes easy to extend as the research log grows.</p>
-      <span class="dev-note-card__authors" aria-label="Author: Kirit Thadaka">
-        <img src="https://github.com/kirit93.png?size=64" alt="" loading="lazy">
-      </span>
-      <span class="dev-note-card__tags">dev-notes / authors / workflow</span>
-    </a>
-  </article>
-  <article class="dev-note-card dev-note-card--launch">
-    <a class="dev-note-card__link" href="posts/2026-06-04-bootstrapping-openshell-research/">
-      <span class="dev-note-card__meta">June 4, 2026 / Dev Note / Runtime</span>
-      <h2>Bootstrapping OpenShell Research</h2>
-      <p>Initial setup for OpenShell Research documentation and Dev Notes.</p>
-      <span class="dev-note-card__authors" aria-label="Authors: Johnny Greco and Alex Watson">
-        <img src="https://github.com/johnnygreco.png?size=64" alt="" loading="lazy">
-        <img src="https://github.com/zredlined.png?size=64" alt="" loading="lazy">
-      </span>
-      <span class="dev-note-card__tags">openshell / docs / ci</span>
-    </a>
-  </article>
-</section>
+  <section class="journal-section dev-notes-featured" aria-labelledby="featured-note-title">
+    <div class="journal-section__head">
+      <h2 id="featured-note-title">Featured note</h2>
+      <span>Latest from the team</span>
+    </div>
+    <article class="dev-note-card dev-note-card--featured dev-note-card--process">
+      <a class="dev-note-card__link" href="posts/2026-06-05-making-dev-notes-repeatable/">
+      <div class="dev-note-card__visual dev-note-card__visual--process" aria-hidden="true">
+        <span class="dev-note-card__visual-label">Field note / Process</span>
+        <span class="dev-note-card__visual-index">2026.06.05</span>
+        <span class="dev-note-card__visual-mark">&gt;_</span>
+      </div>
+      <div class="dev-note-card__copy">
+        <div class="dev-note-card__meta">
+          <time datetime="2026-06-05">June 5, 2026</time>
+          <span>Process</span>
+        </div>
+        <h3>Making Dev Notes Repeatable</h3>
+        <p class="dev-note-card__summary">A repeatable author and post workflow keeps Dev Notes easy to extend as the research log grows.</p>
+        <div class="dev-note-card__tags" aria-label="Tags">
+          <span>dev-notes</span>
+          <span>authors</span>
+          <span>workflow</span>
+        </div>
+        <div class="dev-note-card__footer">
+        <span class="dev-note-card__authors" aria-label="Author: Kirit Thadaka">
+          <img src="https://github.com/kirit93.png?size=64" alt="" loading="lazy">
+          <span class="dev-note-card__author-names">Kirit Thadaka</span>
+        </span>
+          <span class="dev-note-card__read">Read note</span>
+        </div>
+      </div>
+      </a>
+    </article>
+  </section>
+  <section class="journal-section dev-notes-recent" aria-labelledby="recent-notes-title">
+    <div class="journal-section__head">
+      <h2 id="recent-notes-title">Recent notes</h2>
+      <span>The working archive</span>
+    </div>
+    <div class="dev-notes-recent-list">
+    <article class="dev-note-card dev-note-card--recent dev-note-card--launch">
+      <a class="dev-note-card__link" href="posts/2026-06-04-bootstrapping-openshell-research/">
+      <div class="dev-note-card__visual dev-note-card__visual--launch" aria-hidden="true">
+        <span class="dev-note-card__visual-label">Field note / Runtime</span>
+        <span class="dev-note-card__visual-index">2026.06.04</span>
+        <span class="dev-note-card__visual-mark">&gt;_</span>
+      </div>
+      <div class="dev-note-card__copy">
+        <div class="dev-note-card__meta">
+          <time datetime="2026-06-04">June 4, 2026</time>
+          <span>Runtime</span>
+        </div>
+        <h3>Bootstrapping OpenShell Research</h3>
+        <p class="dev-note-card__summary">Initial setup for OpenShell Research documentation and Dev Notes.</p>
+        <div class="dev-note-card__tags" aria-label="Tags">
+          <span>openshell</span>
+          <span>docs</span>
+          <span>ci</span>
+        </div>
+        <div class="dev-note-card__footer">
+        <span class="dev-note-card__authors" aria-label="Authors: Johnny Greco and Alex Watson">
+          <img src="https://github.com/johnnygreco.png?size=64" alt="" loading="lazy">
+          <img src="https://github.com/zredlined.png?size=64" alt="" loading="lazy">
+          <span class="dev-note-card__author-names">Johnny Greco and Alex Watson</span>
+        </span>
+          <span class="dev-note-card__read">Read note</span>
+        </div>
+      </div>
+      </a>
+    </article>
+    </div>
+  </section>
 <!-- dev-notes:posts:end -->
+
+  <footer class="journal-colophon">
+    <p><span>&gt;_</span> OpenShell Research Engineering Journal</p>
+    <p>2026</p>
+  </footer>
+</div>

docs/dev-notes/posts/2026-06-04-bootstrapping-openshell-research.md

@@ -24,9 +24,13 @@ card_tags:
 
 <!-- dev-note:byline:start -->
 <!-- Generated by scripts/render-dev-notes.py; edit front matter and authors.json. -->
-<div class="dev-note-byline" aria-labelledby="dev-note-authors">
-  <p class="dev-note-byline__label" id="dev-note-authors">Authors</p>
-  <div class="dev-note-byline__authors">
+<div class="dev-note-byline">
+  <p class="dev-note-byline__label">
+    <span>Field note</span>
+    <time datetime="2026-06-04">June 4, 2026</time>
+    <span>Runtime</span>
+  </p>
+  <div class="dev-note-byline__authors" aria-label="Authors: Johnny Greco and Alex Watson">
     <a class="dev-note-byline__author" href="https://github.com/johnnygreco">
       <img src="https://github.com/johnnygreco.png?size=96" alt="" loading="lazy">
       <span class="dev-note-byline__copy">

docs/dev-notes/posts/2026-06-05-making-dev-notes-repeatable.md

@@ -4,7 +4,7 @@ date: 2026-06-05
 updated: 2026-06-05
 description: A repeatable author and post workflow keeps Dev Notes easy to extend as the research log grows.
 categories:
-  - Documentation
+  - Process
 tags:
   - dev-notes
   - authors
@@ -21,9 +21,13 @@ card_tags:
 
 <!-- dev-note:byline:start -->
 <!-- Generated by scripts/render-dev-notes.py; edit front matter and authors.json. -->
-<div class="dev-note-byline" aria-labelledby="dev-note-authors">
-  <p class="dev-note-byline__label" id="dev-note-authors">Author</p>
-  <div class="dev-note-byline__authors">
+<div class="dev-note-byline">
+  <p class="dev-note-byline__label">
+    <span>Field note</span>
+    <time datetime="2026-06-05">June 5, 2026</time>
+    <span>Process</span>
+  </p>
+  <div class="dev-note-byline__authors" aria-label="Author: Kirit Thadaka">
     <a class="dev-note-byline__author" href="https://github.com/kirit93">
       <img src="https://github.com/kirit93.png?size=96" alt="" loading="lazy">
       <span class="dev-note-byline__copy">

docs/documentation/index.md

@@ -0,0 +1,12 @@
+---
+title: Documentation
+description: Guides and reference material for software introduced in OpenShell Dev Notes.
+---
+
+# Documentation
+
+Guides and reference material for packages, libraries, benchmarks, and examples
+introduced in OpenShell Dev Notes will be published here.
+
+Each documentation page will link to the Dev Note that introduced the work and
+cover installation, usage, reproducibility requirements, and known limitations.

docs/index.md

@@ -1,30 +1,32 @@
-# OpenShell Research
+---
+title: OpenShell Research
+description: Dev Notes and software documentation from the OpenShell team.
+hide:
+  - toc
+---
 
-<section class="openshell-home-hero" aria-label="OpenShell Research overview">
-  <div class="openshell-brand-lockup openshell-home-hero__brand">
-    <img src="assets/brand/openshell-mark.svg" alt="" aria-hidden="true">
-    <span>Open<strong>Shell</strong> Research</span>
-  </div>
-  <p class="openshell-kicker">Research engineering documentation</p>
-  <p>
-    OpenShell Research turns new research into usable applications that run on
-    the OpenShell runtime. This site collects the engineering record: what we
-    are building, how the runtime is used, and what we learn from each
-    experiment.
-  </p>
-</section>
+<div class="openshell-home-page">
+  <section class="openshell-home-hero" aria-labelledby="openshell-home-title">
+    <div>
+      <h1 id="openshell-home-title">
+        <img src="assets/brand/openshell-mark.svg" alt="" aria-hidden="true">
+        <span>OpenShell Research</span>
+      </h1>
+    </div>
+  </section>
 
-## Starting points
-
-- [Research engineering](research/index.md)
-- [Runtime notes](research/runtime.md)
-- [Application skeletons](research/applications.md)
-- [Dev Notes](dev-notes/index.md)
-
-## What belongs here
-
-- OpenShell runtime integration notes
-- Experimental application designs
-- Research-to-product build logs
-- Benchmarks, evaluations, and reproducibility notes
-- Deployment and sharing patterns for research applications
+  <nav class="openshell-home-links" aria-label="Explore OpenShell Research">
+    <a class="openshell-home-link" href="dev-notes/">
+      <span class="openshell-home-link__copy">
+        <strong>Dev Notes</strong>
+        <span>Research engineering notes from the OpenShell team covering experimental findings, benchmarks, example use cases, and implementation lessons.</span>
+      </span>
+    </a>
+    <a class="openshell-home-link" href="documentation/">
+      <span class="openshell-home-link__copy">
+        <strong>Documentation</strong>
+        <span>Guides and reference material for packages, libraries, benchmarks, and examples introduced in Dev Notes.</span>
+      </span>
+    </a>
+  </nav>
+</div>