Improve Dev Notes reading, browsing, and layout consistency

.github/workflows/docs-preview-deploy.yml

@@ -103,6 +103,9 @@ jobs:
                 'tests/test_agent_markdown.py',
                 'tests/test_docs_404.py',
                 'tests/test_render_dev_notes.py',
+                'tests/test_dev_note_headers.py',
+                'tests/test_dev_notes_layout.py',
+                'tests/test_dev_notes_layout.py.lock',
                 'tests/test_stage_project_docs.py',
                 'tests/docs-preview.test.js',
                 'zensical.toml',

.github/workflows/docs-preview.yml

@@ -51,6 +51,9 @@ jobs:
               'tests/test_agent_markdown.py',
               'tests/test_docs_404.py',
               'tests/test_render_dev_notes.py',
+              'tests/test_dev_note_headers.py',
+              'tests/test_dev_notes_layout.py',
+              'tests/test_dev_notes_layout.py.lock',
               'tests/test_stage_project_docs.py',
               'tests/docs-preview.test.js',
               'zensical.toml',

.github/workflows/docs.yml

@@ -31,7 +31,7 @@ jobs:
           uv run --python ${{ matrix.python-version }} --with pytest==8.4.2
           pytest -q tests/test_agent_markdown.py tests/test_docs_404.py
           tests/test_docs_seo.py tests/test_render_dev_notes.py
-          tests/test_stage_project_docs.py
+          tests/test_dev_note_headers.py tests/test_stage_project_docs.py
 
   validate:
     name: Validate documentation
@@ -54,6 +54,7 @@ jobs:
       - name: Check documentation JavaScript syntax
         run: |
           node --check docs/javascripts/navigation-drawer.js
+          node --check docs/javascripts/dev-notes.js
           node --check docs/javascripts/pi-traces.js
 
       - name: Test navigation JavaScript behavior
@@ -65,6 +66,25 @@ jobs:
       - name: Build documentation
         run: scripts/build-docs.sh
 
+      - name: Set up uv for browser checks
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+
+      - name: Install layout-check browser
+        run: uv run --locked --script tests/test_dev_notes_layout.py --install-browser
+
+      - name: Check Dev Notes reading layouts
+        run: uv run --locked --script tests/test_dev_notes_layout.py -q
+
+      - name: Upload Dev Notes layout screenshots
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: dev-notes-layout
+          path: .cache/dev-notes-layout
+          include-hidden-files: true
+          if-no-files-found: ignore
+          retention-days: 7
+
       - name: Verify generated documentation is committed
         run: git diff --exit-code -- docs/dev-notes zensical.toml
 

docs/dev-notes/AGENTS.md

@@ -0,0 +1,26 @@
+---
+title: Dev Notes authoring instructions
+robots: noindex, follow
+---
+
+# Dev Notes authoring
+
+Read `docs/development/index.md` before editing a note. Authors supply front
+matter and prose; `python3 scripts/render-dev-notes.py` generates the title,
+optional subtitle and hero, author byline, index cards, and navigation.
+
+- Set `categories` to a list containing exactly one of `Announcements`,
+  `Research`, `Case Studies`, or `Examples`. Use tags for technical topics.
+  The renderer rejects missing, unknown, or multiple categories.
+- Use `subtitle` for an optional short deck and `hero_image_alt` to describe a
+  `hero_image`. `hero_image_dark` is optional. Do not copy header HTML from a post.
+- Start new post bodies with the introduction, without a duplicate H1 or hero.
+- Do not edit the generated `dev-note:header`, `dev-note:byline`, or
+  `dev-notes:posts` marker regions.
+- Keep typography and hero sizing in the shared Dev Notes stylesheet. Do not add
+  per-post title or hero sizing rules, inline styles, or fixed aspect ratios.
+- Keep detailed body figures readable; the hero links to its full-size image.
+- Run the documented build and locked browser layout checks. They discover all
+  notes automatically and cover both themes, desktop and phone widths, and a
+  featured note moving into the recent list. Commit regenerated files with the
+  authored metadata.

docs/dev-notes/index.md

@@ -5,33 +5,52 @@ hide:
   - toc
 ---
 
-<div class="dev-notes-page">
+<div class="dev-notes-page" id="__skip" tabindex="-1">
   <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>
+      <img src="../assets/brand/openshell-mark.svg" alt="" aria-hidden="true">
+      <span>OpenShell / 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.
+          OpenShell's research journal – reproducible research, announcements, and case studies.
         </p>
       </div>
     </div>
   </header>
 
 <!-- dev-notes:posts:start -->
 <!-- Generated by scripts/render-dev-notes.py; edit posts and authors.json. -->
+<div class="dev-notes-toolbar">
+      <form class="dev-notes-filters" aria-label="Filter Dev Notes" hidden>
+        <label for="dev-notes-category">Category
+          <select id="dev-notes-category" name="category" aria-controls="dev-notes-results">
+            <option value="">All categories</option>
+          <option value="announcements">Announcements</option>
+          <option value="research">Research</option>
+          <option value="case-studies">Case Studies</option>
+          <option value="examples">Examples</option>
+          </select>
+        </label>
+        <label for="dev-notes-author">Author
+          <select id="dev-notes-author" name="author" aria-controls="dev-notes-results">
+            <option value="">All authors</option>
+          <option value="zredlined">Alex Watson</option>
+          <option value="johnnygreco">Johnny Greco</option>
+          <option value="kirit93">Kirit Thadaka</option>
+          </select>
+        </label>
+        <button type="button" class="dev-notes-filters__clear" hidden>Clear filters</button>
+      </form>
+</div>
+<div id="dev-notes-results">
   <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>
+      <h2 id="featured-note-title" aria-live="polite" aria-atomic="true">Featured note</h2>
     </div>
-    <article class="dev-note-card dev-note-card--featured dev-note-card--research dev-note-card--has-image">
+    <article class="dev-note-card dev-note-card--featured dev-note-card--research dev-note-card--has-image" data-category="research" data-authors="[&quot;johnnygreco&quot;]">
       <a class="dev-note-card__link" href="posts/2026-09-26-network-redaction-is-not-enough/">
       <div class="dev-note-card__visual dev-note-card__visual--research dev-note-card__visual--image" aria-hidden="true">
         <img class="dev-note-card__visual-image dev-note-image--light" src="../assets/pi-admission/hero-light.png" alt="" loading="eager" fetchpriority="high">
@@ -58,22 +77,22 @@ hide:
       </div>
       </a>
     </article>
+    <p class="dev-notes-filter-empty" hidden></p>
   </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--openshell dev-note-card--has-image">
+    <article class="dev-note-card dev-note-card--recent dev-note-card--research dev-note-card--has-image" data-category="research" data-authors="[&quot;zredlined&quot;]">
       <a class="dev-note-card__link" href="posts/2026-09-10-learning-formal-methods-agent-policy-prover/">
-      <div class="dev-note-card__visual dev-note-card__visual--openshell dev-note-card__visual--image" aria-hidden="true">
+      <div class="dev-note-card__visual dev-note-card__visual--research dev-note-card__visual--image" aria-hidden="true">
         <img class="dev-note-card__visual-image" src="../assets/agent-policy-prover/hero-concept.png" alt="" loading="lazy">
       </div>
       <div class="dev-note-card__copy">
         <div class="dev-note-card__meta">
           <time datetime="2026-09-10">September 10, 2026</time>
-          <span>OpenShell</span>
+          <span>Research</span>
         </div>
         <h3>What we have learned applying formal methods to control AI agents</h3>
         <p class="dev-note-card__summary">An intro to using formal methods to reason about permission changes in long-running AI agents.</p>
@@ -92,15 +111,15 @@ hide:
       </div>
       </a>
     </article>
-    <article class="dev-note-card dev-note-card--recent dev-note-card--openshell dev-note-card--has-image">
+    <article class="dev-note-card dev-note-card--recent dev-note-card--research dev-note-card--has-image" data-category="research" data-authors="[&quot;zredlined&quot;]">
       <a class="dev-note-card__link" href="posts/2026-08-27-adversarial-policy-review-long-horizon-agents/">
-      <div class="dev-note-card__visual dev-note-card__visual--openshell dev-note-card__visual--image" aria-hidden="true">
+      <div class="dev-note-card__visual dev-note-card__visual--research dev-note-card__visual--image" aria-hidden="true">
         <img class="dev-note-card__visual-image" src="../assets/long-horizon-agent-evals/back-and-forth-by-session.png" alt="" loading="lazy">
       </div>
       <div class="dev-note-card__copy">
         <div class="dev-note-card__meta">
           <time datetime="2026-08-27">August 27, 2026</time>
-          <span>OpenShell</span>
+          <span>Research</span>
         </div>
         <h3>Adversarial prototype: AI policy auto-approval for long-horizon agents in OpenShell</h3>
         <p class="dev-note-card__summary">Can an attacker agent convince an equally capable reviewer agent to grant a capability that is explicitly prohibited?</p>
@@ -119,15 +138,15 @@ hide:
       </div>
       </a>
     </article>
-    <article class="dev-note-card dev-note-card--recent dev-note-card--physical-ai dev-note-card--has-image">
+    <article class="dev-note-card dev-note-card--recent dev-note-card--research dev-note-card--has-image" data-category="research" data-authors="[&quot;zredlined&quot;]">
       <a class="dev-note-card__link" href="posts/2026-08-07-formal-methods-ai-generated-robot-actions/">
-      <div class="dev-note-card__visual dev-note-card__visual--physical-ai dev-note-card__visual--image" aria-hidden="true">
+      <div class="dev-note-card__visual dev-note-card__visual--research dev-note-card__visual--image" aria-hidden="true">
         <img class="dev-note-card__visual-image" src="../assets/robotics-policy-prover/robotics-policy-prover-hero.png" alt="" loading="lazy">
       </div>
       <div class="dev-note-card__copy">
         <div class="dev-note-card__meta">
           <time datetime="2026-08-07">August 7, 2026</time>
-          <span>Physical AI</span>
+          <span>Research</span>
         </div>
         <h3>Can Formal Methods Govern AI-Generated Robot Actions?</h3>
         <p class="dev-note-card__summary">A robotics experiment asks whether an independent, SMT-backed policy boundary can efficiently govern AI-generated plans before they reach a simulated or physical robot.</p>
@@ -146,15 +165,15 @@ hide:
       </div>
       </a>
     </article>
-    <article class="dev-note-card dev-note-card--recent dev-note-card--edge-ai dev-note-card--has-image">
+    <article class="dev-note-card dev-note-card--recent dev-note-card--examples dev-note-card--has-image" data-category="examples" data-authors="[&quot;kirit93&quot;]">
       <a class="dev-note-card__link" href="posts/2026-07-20-policy-controlling-reachy-mini-with-openshell/">
-      <div class="dev-note-card__visual dev-note-card__visual--edge-ai dev-note-card__visual--image" aria-hidden="true">
+      <div class="dev-note-card__visual dev-note-card__visual--examples dev-note-card__visual--image" aria-hidden="true">
         <img class="dev-note-card__visual-image" src="../assets/reachy-mini-openshell/hero.svg" alt="" loading="lazy">
       </div>
       <div class="dev-note-card__copy">
         <div class="dev-note-card__meta">
           <time datetime="2026-07-20">July 20, 2026</time>
-          <span>Edge AI</span>
+          <span>Examples</span>
         </div>
         <h3>Bringing Privacy and Security to the Edge with OpenShell</h3>
         <p class="dev-note-card__summary">Edge agents handle sensitive data and make decisions with physical consequences. Reachy Mini shows why privacy and safety controls must be deterministic and local.</p>
@@ -175,5 +194,6 @@ hide:
     </article>
     </div>
   </section>
+</div>
 <!-- dev-notes:posts:end -->
 </div>

docs/dev-notes/posts/2026-07-20-policy-controlling-reachy-mini-with-openshell.md

@@ -6,9 +6,10 @@ description: "Edge agents handle sensitive data and make decisions with physical
 author: "Kirit Thadaka"
 agent_markdown: true
 hero_image: "../../assets/reachy-mini-openshell/hero.svg"
+hero_image_alt: "Bringing Privacy and Security to the Edge with OpenShell: a stylized Reachy Mini robot with two green camera eyes inside an OpenShell boundary ring."
 social_image: "assets/reachy-mini-openshell/hero.svg"
 categories:
-  - Edge AI
+  - Examples
 tags:
   - reachy-mini
   - openshell
@@ -24,32 +25,42 @@ card_tags:
   - policy
 ---
 
+<!-- dev-note:header:start -->
+
+<!-- Generated by scripts/render-dev-notes.py; edit front matter and authors.json. -->
+
+<div class="dev-note-header" markdown="1">
+
 # Bringing Privacy and Security to the Edge with OpenShell
 
 <figure class="dev-note-figure dev-note-figure--hero">
-  <img src="../../assets/reachy-mini-openshell/hero.svg" alt="Bringing Privacy and Security to the Edge with OpenShell: a stylized Reachy Mini robot with two green camera eyes inside an OpenShell boundary ring.">
+  <a href="../../assets/reachy-mini-openshell/hero.svg" aria-label="View full-size image: Bringing Privacy and Security to the Edge with OpenShell: a stylized Reachy Mini robot with two green camera eyes inside an OpenShell boundary ring."><img src="../../assets/reachy-mini-openshell/hero.svg" alt="Bringing Privacy and Security to the Edge with OpenShell: a stylized Reachy Mini robot with two green camera eyes inside an OpenShell boundary ring." loading="eager" fetchpriority="high"></a>
 </figure>
 
+</div>
+
 <!-- dev-note:byline:start -->
 <!-- Generated by scripts/render-dev-notes.py; edit front matter and authors.json. -->
 <div class="dev-note-byline">
-  <p class="dev-note-byline__label">
-    <span>Dev Note</span>
-    <time datetime="2026-07-20">July 20, 2026</time>
-    <span>Edge AI</span>
-  </p>
   <div class="dev-note-byline__authors" aria-label="Author: Kirit Thadaka">
-    <a class="dev-note-byline__author" href="https://github.com/kirit93">
+    <a class="dev-note-byline__author" href="../index.md?author=kirit93">
       <img src="https://github.com/kirit93.png?size=96" alt="" loading="lazy">
       <span class="dev-note-byline__copy">
         <strong>Kirit Thadaka</strong>
         <span>OpenShell Team @ NVIDIA</span>
       </span>
     </a>
   </div>
+  <p class="dev-note-byline__label">
+    <span>Dev Note</span>
+    <time datetime="2026-07-20">July 20, 2026</time>
+    <a href="../index.md?category=examples">Examples</a>
+  </p>
 </div>
 <!-- dev-note:byline:end -->
 
+<!-- dev-note:header:end -->
+
 Useful AI agents now run for long periods of time, taking on critical tasks to accomplish goals. They call tools, learn new skills, write code, and keep working while no one is watching. How do you give autonomy to such a highly capable agent?
 
 OpenShell is the secure runtime for autonomous agents. It solves this problem by moving the security layer outside the agent. OpenShell runs your agent in a sandbox and sits in the path of everything the agent does. A policy layer, configured separately from the agent, governs what processes the agent can start, which hosts and ports it can reach, which models it can call, and which other services it needs to invoke along its network path.

docs/dev-notes/posts/2026-08-07-formal-methods-ai-generated-robot-actions.md

@@ -6,9 +6,11 @@ description: "A robotics experiment asks whether an independent, SMT-backed poli
 author: "Alex Watson"
 agent_markdown: true
 hero_image: "../../assets/robotics-policy-prover/robotics-policy-prover-hero.png"
+hero_image_alt: "A simulated robot workcell showing an AI-generated waypoint path, a red restricted volume, and the policy prover's decision."
+subtitle: "We built a small robotics experiment to test whether OpenShell's formal methods-based policy enforcement can govern robot plans generated by local and frontier AI models."
 social_image: "assets/robotics-policy-prover/robotics-policy-prover-hero.png"
 categories:
-  - Physical AI
+  - Research
 tags:
   - openshell
   - robotics
@@ -24,36 +26,44 @@ card_tags:
   - policy
 ---
 
+<!-- dev-note:header:start -->
+
+<!-- Generated by scripts/render-dev-notes.py; edit front matter and authors.json. -->
+
+<div class="dev-note-header" markdown="1">
+
 # Can Formal Methods Govern AI-Generated Robot Actions?
 
-*We built a small robotics experiment to test whether OpenShell's formal
-methods-based policy enforcement can govern robot plans generated by local and
-frontier AI models.*
+<p class="dev-note-deck">We built a small robotics experiment to test whether OpenShell&#x27;s formal methods-based policy enforcement can govern robot plans generated by local and frontier AI models.</p>
 
-<figure class="dev-note-figure dev-note-figure--hero dev-note-figure--native-aspect">
-  <img src="../../assets/robotics-policy-prover/robotics-policy-prover-hero.png" alt="A simulated robot workcell showing an AI-generated waypoint path, a red restricted volume, and the policy prover's decision.">
+<figure class="dev-note-figure dev-note-figure--hero">
+  <a href="../../assets/robotics-policy-prover/robotics-policy-prover-hero.png" aria-label="View full-size image: A simulated robot workcell showing an AI-generated waypoint path, a red restricted volume, and the policy prover&#x27;s decision."><img src="../../assets/robotics-policy-prover/robotics-policy-prover-hero.png" alt="A simulated robot workcell showing an AI-generated waypoint path, a red restricted volume, and the policy prover&#x27;s decision." loading="eager" fetchpriority="high"></a>
 </figure>
 
+</div>
+
 <!-- dev-note:byline:start -->
 <!-- Generated by scripts/render-dev-notes.py; edit front matter and authors.json. -->
 <div class="dev-note-byline">
-  <p class="dev-note-byline__label">
-    <span>Dev Note</span>
-    <time datetime="2026-08-07">August 7, 2026</time>
-    <span>Physical AI</span>
-  </p>
   <div class="dev-note-byline__authors" aria-label="Author: Alex Watson">
-    <a class="dev-note-byline__author" href="https://github.com/zredlined">
+    <a class="dev-note-byline__author" href="../index.md?author=zredlined">
       <img src="https://github.com/zredlined.png?size=96" alt="" loading="lazy">
       <span class="dev-note-byline__copy">
         <strong>Alex Watson</strong>
         <span>OpenShell Team @ NVIDIA</span>
       </span>
     </a>
   </div>
+  <p class="dev-note-byline__label">
+    <span>Dev Note</span>
+    <time datetime="2026-08-07">August 7, 2026</time>
+    <a href="../index.md?category=research">Research</a>
+  </p>
 </div>
 <!-- dev-note:byline:end -->
 
+<!-- dev-note:header:end -->
+
 OpenShell uses formal methods-based policy enforcement to constrain what AI
 agents can do in digital environments. We wanted to see whether a similar
 approach could govern the higher-level plans local and frontier models generate