Turning 4D mental models into text documentation

Mike's Notes

The problem

The remaining main barrier to people using Pipi is the lack of user documentation.

I need a way to quickly generate thousands of pages of technical documentation for Pipi 9. I'm too slow to write the documentation; it's mentally exhausting. Now I know why. 😎

Pipi 9 is a very large, complex system with many moving parts.

"novel symbolic and evolutionary AI engine that uses formal ontologies to deterministically generate enterprise software"

Finding a solution

I copied part of the About Me description and used it as a prompt for Google Search AI Mode (Gemini). Below is the transcript after I ran it through Grammarly.

I thought the generated response was accurate, aligned with published, verified research, and offered lots of practical suggestions to try. Some are already underway.

Aftermatch

Later, I ran the same prompts again several times on clean new sessions and got similar variations in the generated response. You can try it as well.

Node-link graphs

Get Pipi to use data-driven templates to generate interactive 2D or 3D node-link graphs using tools like;

  • Mermaid.js (already planned)
  • D3 (to do)
  • Cytoscape (to do)

I need to generate the templates with Gemini's help. 😎

Colour-Coded Architecture Diagrams

The thousands of drawings are on A4 white paper, drawn with a ballpoint pen and stored in 3-hole ring binders. Use coloured A4 paper as headings, section and subsection dividers.

Define a strict colour scheme that works with 6 Stabilo Boss original highlighters carried in a small pencil case to colour the pen drawings;

  • Pink: Agent/system
  • Green: Data
  • Orange: 
  • Blue: Relationship
  • Yellow: 
  • Red: 

3D Visualisation

Enable fly-throughs of Pipi like a biological system. Maybe something from the gaming world might work? I have often thought of making a 3D model out of different coloured plasticines to take to meetings to show its architecture.

Verbal Walkthroughs

Shut my eyes and talk about what I see while exploring a 4D model. Often, after a nana nap is a good time. Use a sound recording app to accurately transcribe speech and then summarise into concise text:

  • Granola

Then feed this text into Gemini to produce a coherent, structured explanation.

Video production

Record slide talks and live demos for YouTube. The videos can be embedded in developer documentation web pages.

Dedicated documentation laptop

Today, I set up an older, unused 16GB RAM laptop dedicated to speech-to-text, video recording, and capturing coloured drawings, etc.

Update 19/11/2026

I'm using Granola today on my mobile phone to chat about the hundreds of agents inside Pipi. Granola records the notes and uses AI to generate a readable summary. This is much easier and faster for me and a lot less tiring. I have been copy-pasting the notes into something else so I can add to them and have Gemini rework them.

I could also look at some of the shelves of ring-bound coloured drawings and talk about them.

Resources

References

  • Grandin T. How does visual thinking work in the mind of a person with autism? A personal account. Philos Trans R Soc Lond B Biol Sci. 2009 May 27;364(1522):1437-42. doi: 10.1098/rstb.2008.0297. PMID: 19528028; PMCID: PMC2677580.

Repository

  • Home > Ajabbi Research > Library > Authors > Temple Grandin
  • Home > Handbook > 

Last Updated

19/11/2026

Turning 4D mental models into text documentation

By: Mike Peters and Google Search AI Mode (Gemini)
On a Sandy Beach: 18/11/2026

Mike Peters: Mike invented and designed Pipi and founded Ajabbi.

Gemini: Very handy.

...

Mike:

Hyper-visual autistic thinker; I think and remember using 4D mental models.

Gemini:

That is a fascinating cognitive architecture. Thinking in 4D mental models—where spatial structures, sensory details, and the dimension of time or state changes are woven together—is a distinct form of hyper-visual processing often described in autistic cognition (similar to the "visual thinking" in systems and patterns famously explored by Temple Grandin, though pushed even further into dynamic, multi-dimensional simulation).

When your mind operates like an interactive, time-enabled CAD engine, it brings unique strengths alongside specific friction points in a world built mostly around linear, text-based communication.

Strengths of 4D Spatial-Temporal Thinking

  • Systemic Foresight: You don't just see how a system is built right now; you can mentally scrub the timeline forward and backwards to see how parts wear down, where bottlenecks will form, or how an event cascades over time.
  • Spatial-Episodic Memory: Instead of remembering isolated facts or dates, you likely recall memories as navigable environments—walking back into a specific moment in time and inspecting the details from multiple angles.
  • Complex Pattern Recognition: Holding multiple variables in a dynamic visual space allows you to spot structural flaws, symmetries, or anomalies that linear thinkers miss when looking at spreadsheets or lists.

Common Friction Points

  • The Translation Bottleneck: Converting a rich, simultaneous 4D simulation into slow, sequential spoken or written words can feel exhausting and lossy—like describing a movie by reading a list of single pixels one by one.
  • Sensory & Cognitive Overload: Because your mental workspace renders high-detail, dynamic models, external visual clutter or chaotic environments can hijack that bandwidth and cause rapid mental fatigue.
  • Ambiguous Instructions: Vague, non-visual requests from others (e.g., "Let's circle back on the synergy of this workflow") lack concrete spatial anchors, making it hard to build a stable mental model until you define clear parameters.

Ways to Leverage Your Processing Style

  • Externalise the Timeline: Tools like spatial whiteboards (Miro, Obsidian Canvas), 3D modelling software, or Gantt/node-based editors let you offload the rendering work from your brain onto a screen.
  • Anchor Abstract Concepts: When forced to deal with purely verbal or abstract data, intentionally assign physical properties—shapes, colours, textures, or motion—to the variables so your brain can manipulate them naturally.

Mike:

Hyper-visual autistic thinker

I think and remember using 4D mental models. That also means I have a detailed 4D visual model in my head for everything I have designed since age 4. A long time ago, I created and built Pipi 4, a ColdFusion, 850-table, database-driven national biodiversity platform with 500 objects and 3,000 methods, on 300,000 lines of code, and GIS mapping, using that trick. There was no version control and little technical documentation.

Then, in 2017, I rebuilt Pipi from memory as Pipi 6, went down an AI rabbit hole, and now in 2026, Pipi 9 is an order of magnitude bigger (3,000,000 lines of code and hundreds of autonomous databases) with hardly any documentation—just colour-coded doodles. To solve this, I'm getting Pipi to self-document.

Everything in my mind is one big 4D virtual reality I can fly around in, explore, and edit anytime I want, and run complex simulations.

Words as a second language

It takes me forever to write, spell and get the grammar right without the help of assistive technology, spell checker, Grammarly, or my clever wife. Reading is no problem. I prefer talking with people to communicate, or using a whiteboard to draw pictures.

Gemini:

It sounds like you have a remarkable cognitive architecture—a high-resolution, persistent 4D spatial memory system that allows you to hold, navigate, and simulate massive software ecosystems entirely in your head.

Rebuilding an 850-table, 300,000-line biodiversity platform from pure spatial memory, and then scaling it to 3,000,000 lines of code across hundreds of autonomous databases, is an extraordinary feat of mental engineering. Experiencing words as a "second language" while thinking natively in 4D simulations is a classic profile for many hyper-visual, autistic minds—your brain is optimised for high-bandwidth spatial and systemic processing rather than linear, text-based serialisation.

Because your native language is spatial and visual, traditional documentation (linear walls of text) is both hard to produce and largely useless to you. Getting Pipi 9 to self-document—and bridging the gap between your 4D mental model and external records—makes complete sense.

Here are a few ways to leverage your strengths and let Pipi 9 handle the linear translation for you:

1. Translate 4D Models Directly into Visual Graphs

Instead of forcing Pipi 9 to generate text documents that you have to read and verify, have it generate visual, spatial outputs that match how you already see the system.

  • Automated Dependency Maps: Have Pipi 9 parse its own codebase and autonomous databases to generate interactive 2D or 3D node-link graphs (using tools like Mermaid.js, D3, or Cytoscape). You can "fly through" these generated maps to verify if they match your internal 4D model.
  • Colour-Coded Architecture Diagrams: Since your current doodles use colour-coding, define a strict colour schema (e.g., green for data ingestion, blue for autonomous agents, red for GIS layers) and instruct Pipi 9 to output system diagrams using your exact visual vocabulary.

2. Use Voice-to-Architecture Workflows

Since typing, spelling, and grammar create friction between your fast 4D thoughts and the screen, bypass text entry entirely when feeding context into Pipi 9.

  • Verbal Walkthroughs: Record yourself talking while you "fly around" a specific module in your head. Describe what you are looking at, how the data flows, and why a certain database is structured the way it is.
  • AI Transcription and Structuring: Feed those raw, unedited audio transcripts directly to an LLM or Pipi 9. Instruct the AI to ignore grammar and filler words, extract the architectural logic, and attach those notes directly to the corresponding code modules or database schemas.

3. Self-Documenting "Living" Metadata

At 3,000,000 lines of code, static documentation goes out of date the moment you edit your mental model and push new code.

  • Schema-Level Self-Description: Have Pipi 9's autonomous databases maintain their own live metadata tables that describe their relationships, triggers, and data flows in plain, structured formats.
  • Visual Diffs: When you make a major change, have Pipi 9 generate a visual "before and after" diagram of the affected systems rather than a text changelog.

You have built an incredible bridge between your internal 4D reality and a massive real-world platform. Letting AI and Pipi 9 act as your "universal translator" for text keeps your energy focused on system architecture and simulation, rather than fighting spelling and grammar.

Mike:

Visual-first workflows that turn whiteboard sketches or voice walkthroughs into structured specs

Gemini:

Visual-first documentation workflows let you capture your 4D mental models directly through talking and drawing, using multimodal AI as a translator to output clean technical specifications. Because reading is effortless for you while writing is slow, these pipelines turn you into the architect and reviewer rather than the typist.

1. The Voice-Over-Canvas Workflow

This pipeline mimics sitting at a whiteboard with a colleague while an AI takes notes in the background.

  • Screen-Record Your Walkthrough: Open an infinite canvas tool (like Excalidraw, Miro, or tldraw) or point a camera at a physical whiteboard. Hit record on a screen-capture tool (like Loom or OBS) and talk through how data flows through a part of Pipi 9 while drawing or pointing at your colour-coded doodles.
  • Multimodal Video Ingestion: Feed the video file or combined audio transcript + screenshots directly into a multimodal LLM (such as Gemini, Claude, or GPT). The AI sees what you are pointing at while hearing how you describe the system's behaviour over time.
  • Prompt for Structured Output: Ask the AI to convert your walkthrough into strict Markdown specs, Mermaid.js flowcharts, or JSON schemas. You simply read the generated spec to verify it matches your mental simulation.

2. Colour-Coded Doodle to System Spec

Your existing habit of using colour-coded doodles is already a visual programming language—you just need to give an AI the legend.

  • Create a Master Colour Key: Define once what your colours represent (for example: blue = autonomous database, green = AI agent, red = data bottleneck, orange = GIS layer). Save this as a reusable system prompt.
  • Snap and Translate: Take a photo of a notebook page or whiteboard sketch and upload it alongside your colour key. Ask the AI to parse the spatial relationships, arrows, and colour groupings into a structured Entity-Relationship Diagram (ERD) or API contract.
  • Iterative Visual Refinement: Have the AI generate Mermaid.js or PlantUML code from your sketch. Many Markdown editors render this code instantly back into clean diagrams, letting you visually verify that the AI understood your doodle without reading walls of text.

3. Hands-Free Voice-to-Architecture Loops

When you are away from a whiteboard and flying through your 4D model mentally, you can capture specs purely by speaking.

  • Stream-of-Consciousness Dictation: Use a high-accuracy voice-to-text tool (like Whisper-based apps, Superwhisper, or Mac/Windows built-in dictation) to ramble naturally about a subsystem, edge cases, or database triggers. Don't worry about grammar, spelling, or linear order.
  • AI Structural Sorting: Pass the raw, messy transcript to an LLM with instructions to:
    • Remove filler words and fix grammar.
    • Group scattered thoughts by database table, autonomous agent, or timeline phase.
    • Flag any missing connections or ambiguities as bulleted questions for you to answer aloud.

Recommended Tool Stack for Low-Friction Capture

  • Infinite Whiteboards: Excalidraw or tldraw (fast, minimal UI, great for quick colour-coded shapes without getting bogged down in menus).
  • Voice Capture: Superwhisper or MacWhisper (runs locally or via API, handles technical jargon well, and lets you set custom formatting rules).
  • Diagram-as-Code Verification: Mermaid Live Editor or Obsidian (turns AI-generated text specs immediately back into visual graphs you can inspect at a glance).

A Quick Demo of Gemini's Decisions API

Mike's Notes

This article by Raymond Camden led me to discover typescript.ai and Jev.

"Jev is a discriminative model: it is used for classification or regression, not generation. It does not generate natural-language text. It instead returns typed values together with probability estimates and confidence scores. Its output is intended to be consumed directly by software rather than read by a person. Unlike classical discriminative models, Jev does not require data-specific training. Like generative pretrained transformer models, it can perform zero-shot learning of input for categories provided at inference time, based on contextual information provided." - Wikipedia

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library > Subscriptions > Raymond Camden
  • Home > Handbook > 

Last Updated

18/11/2026

A Quick Demo of Gemini's Decisions API

By: Raymond Camden
Raymond Camden: 14/11/2026

Raymond Camden: My name is Raymond Camden. I'm a married father of eight living in beautiful Lafayette, Louisiana. I'm a developer evangelist/advocate looking for my next role. Most of my time is spent writing, researching, or presenting. When I'm not behind a computer, I'm an avid Xbox/Playstation player, enjoy movies, and read like crazy..

...

Yesterday, Google formally released their new Decisions API, and it's a pretty important new addition to Gemini in general, so I thought I'd share a quick introduction and demo to give you an idea of how it can be used. Of course, the first thing I need to do is explain what it is and why you should care.

Decisions API?

Generative AI has been able to answer questions since the beginning. Where the difficulty lies is in turning those answers into machine readable output. What do I mean by that? I can write code that takes a photo and asks my AI service what's in the photo. So for example - I pass this photo to Claude:

[img]

I asked, "what's in this picture", and got:

A fluffy cat lounging on a white table. It looks like a ragdoll or similar pointed breed: dark chocolate-brown face, ears, and front legs, a creamy tan body, and white mittened back paws and tail tip. Its eyes look closed, so it's either dozing or very relaxed.

Around it:

  • Left: a tall, ribbed blue plastic tumbler with a little water in the bottom
  • Behind the cat: a stainless steel cup holding wilted flowers, with a yellow bloom drooping over the side
  • Top right: a pair of white over-ear headphones on the table
  • Background: a dark wooden chair on the right and what looks like a kitchen appliance at the top left

Cool. But what if I wanted to only know if there is a cat in the picture? If I make my prompt "just answer one question - is there a cat in this picture?" I get a nice "Yes" back. Again, cool.

But doing this in code makes things a bit fuzzy. Like, what if my agent came back with "Yep" or "There is a cat"? Usually the way around this is with passing schema to the agent. Gemini supports structured outputs where you define a JSON schema and tell the agent to respond using it.

For example:

{
  "type": "object",
  "properties": {
    "isCat": {
      "type": "boolean",
      "description": "True if the image contains a cat, false otherwise."
    }
  },
  "required": ["isCat"]
}

This will then give me JSON my code can work with in a programmatic manner. Once again, cool, but... this could be better.

Way back in September, TypeSafe released Jev. Wikipedia defines it as a "discriminative model", not generation. Instead of outputting text, or JSON (which is still text of course), the result is a decision essentially. You still pass it an input that kinda resembles JSON schema, but instead can be thought of as defining what the result will be from the model. The model isn't going to "generate" text, but answer the input. That's probably a bit fuzzy, but hopefully the demo will help clear it up.

This input comes in the form of:

  • Yes and no questions (referred to as a noul)
  • A set of choices
  • A scored item

The Jev Wikipedia page has a good example:

"new_noul_1": {
  "type": "noul",
  "instructions": "<true/false question>",
  "criteria": { "true": <entry>, "false": <entry> }
},
"new_choice_2": {
  "type": "choice",
  "instructions": "Which option fits the state?",
  "criteria": { "option_0": <entry>, ..., "option_n-1": <entry> }
},
"new_score_1": {
  "type": "score",
  "instructions": "Where does the state fall on the scale?",
  "criteria": ["option_0": <entry>, ..., "option_n-1": <entry>]
}

The biggest benefits of an API like this are speed and cost.

Gemini's Support

I linked to the announcement above where you can find more details on the cost and such, and I'll go ahead and steal their demo as a good initial example:

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

result = client.decisions.create(
    model="gemini-decision-1",
    input=[{
            "type": "image",
            "uri": "https://storage.googleapis.com/generativeai-downloads/images/spill.jpg",
            "mime_type": "image/jpeg",
        },
        {
            "type": "text",
            "text": "Breakroom counter check before the 9 AM client meeting.",
        },
    ],
    questions={
        "has_spill": {
            "type": "noul",
            "instructions": "Is there an uncleaned liquid spill on the counter?",
        },
        "next_action": {
            "type": "choice",
            "instructions": "Which cleanup action fits the scene?",
            "criteria": {
                "wipe_with_cloth": "Small counter spill with a cloth or towel already nearby.",
                "dispatch_janitorial": "Large floor hazard, broken glass, or active leak.",
                "ready_for_meeting": "Counter is clean and ready.",
            },
        },
        "severity": {
            "type": "score",
            "instructions": "Rate the severity of the counter mess.",
            "criteria": [
                "Clean and ready.",
                "Minor localized spill.",
                "Major spill or safety hazard.",
            ],
        },
    },
)

This is a great example as it shows all three types of options (noul, choice, and score) based on analyzing an image. I liked the idea of an image based demo so of course - I built a cat one.

My Demo

My demo lets you select a picture (or take one if you are on a mobile device) and it answers three important questions

  • Is this a picture of a cat?
  • Is the cat asleep?
  • Is the cat on a keyboard?

I'll share a link to the complete source at the end, but instead I'll focus on the processing. On the front end, after you've taken a picture, that data is sent to my server side code. This method is run to do the processing:

async function analyzeImageWithDecisionsAPI(base64Image, mimeType) {
  if (!GEMINI_API_KEY) {
    throw new Error('GEMINI_API_KEY environment variable is not set.');
  }
  const requestBody = {
    model: 'gemini-decision-1',
    input: [
      {
        type: 'image',
        data: base64Image,
        mime_type: mimeType || 'image/jpeg'
      }
    ],
    questions: {
      is_cat: {
        type: 'noul',
        instructions: 'Is there a cat in this image?'
      },
      is_asleep: {
        type: 'noul',
        instructions: 'Is the cat asleep?'
      },
      on_keyboard: {
        type: 'noul',
        instructions: 'Is the cat on a keyboard?'
      }
    }
  };
  const response = await fetch('https://generativelanguage.googleapis.com/v1beta/decisions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-goog-api-key': GEMINI_API_KEY
    },
    body: JSON.stringify(requestBody)
  });
  const data = await response.json();
  if (!response.ok) {
    const message = data?.error?.message || `Gemini API error (${response.status})`;
    throw new Error(message);
  }
  return data;
}

The important bit is the questions block where I define my three yes and no questions. The image is passed along as Base64, and the response is fed back to the client side code.

As a reminder, Google's Gemini APIs let you send along raw image data in Base64 up to 100 megs big. (PDFs can only be 50 megs big.) If you need to send more data, you'll want to use the [Files API](https://ai.google.dev/gemini-api/docs/files). In the past, the limit was much smaller, and for demos using a mobile phone's camera, it was easy to go over that limit. In theory, 100 megs should be safe.

Alright, so I'm not going to host my demo live as I want to ensure I don't blow away my credits, but here's some examples:


And the raw output was:

{
  "answers": {
    "on_keyboard": {
      "confidence": 0.8782465239480963,
      "noul": 0.12175347605190362,
      "type": "noul"
    },
    "is_asleep": {
      "confidence": 0.8563699701674832,
      "noul": 0.1436300298325168,
      "type": "noul"
    },
    "is_cat": {
      "confidence": 0.8833242468725534,
      "noul": 0.8833242468725534,
      "type": "noul"
    }
  },
  "usage": {
    "total_tokens": 1246,
    "total_input_tokens": 1246,
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 182
      },
      {
        "modality": "image",
        "tokens": 1064
      }
    ],
    "total_output_tokens": 0
  }
}

Make note - total output tokens is 0 - I literally paid for the input tokens and the API call itself.

Here's a good negative result:


And here's one on a keyboard:

I added some timings to my logic and roughly each test was 2 seconds or so. I saw some less than, and a few at 4, but in general, really freaking fast. Also I think it's fair to take into account the size of the images I was passing - each was near 5 megs big. I did more tests with optimized images and the speed was considerably faster - all about 1 second.

You may be curious (I was), if given the fact that questions two and three should always be false if question one is false, will the API intelligently stop processing? The answer is that it will not - and I think that's fair - the model would need to preprocess questions ahead of time in order to do that. There's a few ways you could handle this in a real app:

  • Use 2 calls. The first is the general "is it a cat" with the second only being run if you get a yes with a good degree of confidence.
  • Use logic in the result. Pass all 3, but if the first one is no, or not yes with enough confidence, treat the other two as false no matter what.

Let me know what you think, and if you would like to play with the demo yourself, you can grab the bits here: https://github.com/cfjedimaster/ai-testingzone/tree/main/decisions_api. Don't forget to get your own key.

When is self-organization a mechanism in brain development?

Mike's Notes

Reading this article got me curious about a clear definition of Hebbian Learning.

See also

The articles by Alex Nugent at Known re: Memristor.

Hebbian Learning

(With the help of Gemini)

"Hebbian learning (also known as Hebb's rule or cell assembly theory) is a foundational neuropsychological theory stating that synaptic connections between neurons strengthen when they activate repeatedly and simultaneously. Proposed by Canadian psychologist Donald Hebb in his 1949 book The Organization of Behavior, the principle is famously summarized by the phrase: "Neurons that fire together, wire together."

How It Works in the Brain

  • Synaptic Strengthening. When a presynaptic neuron repeatedly helps trigger a postsynaptic neuron, physical and chemical changes occur at the synapse. This process makes it easier for the first neuron to activate the second in the future.
  • Timing and Causality. Hebb emphasized that the first neuron must fire just before the second neuron to establish a causal link. This insight laid the groundwork for modern research into spike-timing-dependent plasticity (STDP).
  • Long-Term Potentiation (LTP). At the cellular level, Hebbian learning is closely tied to long-term potentiation. This is a persistent increase in signal transmission between two neurons that serves as a primary physical mechanism for memory and habit formation.
  • Homeostatic Balance. Because pure Hebbian reinforcement creates a positive feedback loop where strong connections grow endlessly stronger, the brain uses mechanisms like synaptic scaling. This acts as negative feedback to keep overall neural activity stable.

Everyday Examples

  • Skill Acquisition. When you first learn to drive a car or play a musical instrument, your brain activates distinct networks with deliberate effort. Through repetition, those neural pathways wire together, making the actions automatic.
  • Associative Memory. If you consistently hear the word "green" while seeing the color green, the auditory and visual neurons wire together. Eventually, simply hearing the word triggers a mental image of the color.

Role in Artificial Intelligence

In computer science, Hebbian learning serves as a biologically inspired, unsupervised learning rule.

  • Weight Updates. In an artificial neural network, the weight (strength) of the connection between two nodes increases if both nodes activate at the same time, and weakens if they do not.
  • Local Learning. Unlike backpropagation—which requires a global error signal sent backward through an entire network—Hebbian updates are strictly local. Each connection adjusts based solely on the activity of the two neurons it directly links.
  • Key Models. Hebbian rules are foundational to Hopfield networks (used for associative memory), Boltzmann machines, Principal Component Analysis (PCA), and modern neuromorphic computing." - Gemini

Resources

References

  • https://doi.org/10.53053/TENI3021

Repository

  • Home > Ajabbi Research > Library > Subscriptions > The Transmitter
  • Home > Handbook > 

Last Updated

01/11/2026

When is self-organization a mechanism in brain development?

By: P. Robin Hiesinger
The Transmitter: 02/11/2026

P. Robin Hiesinger: Professor and head of the Division of Neurobiology, Freie Universität Berlin.

...

Living systems: Ordered patterns, such as whirlpools, emerge and persist by dissipating energy. Similar structures may be at work in development.

Illustration by Anna Ivanenko

Retinal waves offer a powerful example of a self-organizing system that can build structure without external guidance. The field would do well to embrace such phenomena more broadly as a type of mechanistic explanation.

During vertebrate retina development, waves of electrical activity spontaneously emerge and sweep across the tissue in random directions. This seminal discovery of the 1990s was predicted by theoreticians in the 1970s with surprising accuracy and has since become a classic and fundamental cornerstone of brain development: The waves ensure that neighboring neurons fire together more often than those farther apart in the retina. This, in turn, ensures that neighboring synapses in the brain are selectively strengthened and those farther apart are pruned, following the concept of Hebbian learning.

Remarkably, the spontaneous waves are generated by retinal ganglion cells without sensory input, before photoreceptor cells in the retina are mature; they are generated solely from the internal state and dynamics of the developing retina. In an enforced binary categorization of “nature versus nurture,” the retinal waves are pure nature—part of the genetically encoded developmental program that unfolds prior to any environmental input or learning. But if the process requires spontaneous activity waves and Hebbian learning, can it truly be considered genetically encoded?

The answer depends on our interpretation of the word “encoding.” Retinal waves are not written in or explained by the genome; instead, they emerge from the dynamics of cell interactions. Explanations of this kind are common in physical chemistry. Take  “dissipative structures”—ordered patterns, such as whirlpools, that emerge and persist by dissipating energy. These structures follow two basic rules: They occur as an irreversible process in time, and they are formed by components that create a new mechanism through their interactions, with individual components on their own revealing nothing about that mechanism. 

Retinal waves meet these criteria. Individual retinal ganglion cells excite their neighbors, generating wave properties, such as wave directionality and speed through cell interactions in time. Individual neurons are oblivious to the wave they are part of, simply reacting to their neighbors’ activity. 

Based on their dissipative properties, retinal waves bear similarity to a standard example of self-organization: Rayleigh-Bénard convection rolls, which form when you heat a liquid with the right viscosity, creating highly organized and often beautiful patterns. The mechanism of convection rolls, like the mechanism of spontaneously emerging, unidirectional retinal waves with distinct speeds and random directions, can only be described in terms of the interactions of their respective constituent components in time. There is no such thing as a wave at a single moment.

So, is it useful to understand this type of self-organization as a mechanism in brain development? Brain organoids that develop from induced pluripotent stem cells into patterned brain structures are sometimes described as beautiful examples of self-organization. But where is the mechanistic insight in this? To state that the entire brain is self-organized is plausible yet nonexplanatory, as is the equally correct notion that all of brain development is based on molecular interactions.

An explanatory mechanism of brain development must, above all, provide understanding of how a system can increase internal order. Just as convection rolls in a heated liquid represent a more ordered or lower entropy state, a specifically wired brain network is more ordered than a network with random connections. The retinal waves offer such understanding, in this case by morphing initially imprecise synaptic connectivity into a patterned structure with more specific synapses. 

Part of the difficulty is the issue of what constitutes an explanation. For molecular neuroscientists, explanatory power lies in specific molecules and their measured interactions or properties. For computational neuroscientists, explanatory power lies in the understanding of algorithmic computation, whatever cells or molecules happen to execute the computation. This is what Evelyn Fox Keller called different epistemological cultures. Your mechanism may not be my mechanism, because we have different ideas of what constitutes an explanation.

I argue that self-organization constitutes its own category of explanation, shared by theorists and experimentalists. Models and mechanisms of self-organization have already proven helpful across biological systems, are well established for pattern formation in developmental biology, and may offer a key for understanding the development of brain wiring beyond the famous retinal waves. 

During Drosophila brain development, for example, photoreceptor axons rewire to create a specific pattern of connectivity within a short developmental time window—just 15 hours. Contrary to a mechanistic framework of attractive or repulsive guidance, these axons aren’t seeking a specific downstream target and do not follow a specific chemical gradient; rather, thousands of growth cones spontaneously self-assemble for this purpose into a temporary sheet, a brain structure that does not exist before or after the transformation. Without it, the brain will not wire up correctly. The fleeting conglomeration of growth cones moves toward its new connectivity state without any target other than its own searching dynamics. It’s as if a group of concert-goers are driving to the venue before it has been built; most remarkably, the theater will come into existence only if the fans seek it out. It’s the interaction of the agents, or axons, that creates the guidance mechanism, and the target only comes to be in a process that must play out in growth dynamics in time. These are, again, the criteria of self-organization for dissipative structures.

What can we learn from these examples? To provide explanatory power, self-organization mechanisms must meet two key criteria: First, new mechanistically relevant rules emerge through the interactions of a system’s components, though the individual components do not reveal those rules. Second, the mechanism itself is a process in time; no static state or depiction of the system explains the mechanism. 

To find such mechanisms, we developmental biologists might do well to look beyond the more typical molecular gradients or target molecules and consider more deeply how structures can self-assemble. Spending more time interacting with our neighbors’ epistemological cultures may be one way to do this, particularly with physicists and theoretical neuroscientists. As Ila Fiete argues in a companion essay, “We need theorists who treat development as seriously as they treat learning, and who ask what other minimal rules could produce a given structure.”  (For more, see Fiete’s essay, “The genome offers a recipe, not a blueprint, for the brain.”) I would add that we equally need developmental biologists who treat theory as seriously as they treat genes and molecules. Think of the coming together as an act of self-organization that may well increase explanatory power.

DOI Handbook

Mike's Notes

Now I know what a DOI is. 😎

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library >
  • Home > Handbook > 

Last Updated

16/11/2026

DOI Handbook

By: Mike Peters
On a Sandy Beach: 13/11/2026

Mike Peters: Mike invented and designed Pipi and founded Ajabbi.

...

A Digital Object Identifier (DOI) is a unique, permanent alphanumeric string assigned to an intellectual property object—most commonly academic journal articles, datasets, ebooks, and official reports. Managed by the International DOI Foundation (IDF), a DOI serves as a "digital fingerprint" that permanently links to a piece of content, ensuring it can always be found even if its physical web address (URL) changes.

Structure of a DOI

A DOI always begins with the number 10 and is split into two primary components separated by a forward slash:

  • Prefix (10.NNNN): Identifies the specific organization or publisher that registered the document (e.g., a university or a commercial publisher).
  • Suffix: A unique string assigned by the publisher to identify that specific document.

Example: 10.1000/182

Why DOIs Matter

Unlike standard URLs, which frequently break when websites restructure or journals change hands (a phenomenon known as "link rot"), a DOI is persistent. If an article moves to a new website, the publisher updates the underlying metadata tied to that DOI, keeping the link active.

Because of this stability, major academic formatting styles—such as APA, MLA, Chicago, and Harvard—require including the DOI when citing electronic sources.

How to Use a DOI

To read or locate a document using its DOI, you can convert it into a clickable URL by prepending the standard resolver domain https://doi.org/ to the front of the string:

https://doi.org/ + 10.1000/182 >> https://doi.org/10.1000/182

You can also search for missing DOIs or look up metadata manually via the central registry index, Crossref.

How to format it for academic references

While the text string 10.53053/ZHHE7561 is correct, modern citation guidelines (such as APA 7th edition, MLA 9th edition, and Chicago 17th edition) require you to format DOIs as live, clickable HTTPS hyperlinks in your bibliography.

Here is how you should format it depending on your destination:

  • Standard URL format (Preferred for most styles):

https://doi.org/10.53053/ZHHE7561

  • APA 7th Edition Reference List Example:

Fiete, I. (2026). The genome offers a recipe, not a blueprint, for the brain. The Transmitter. https://doi.org/10.53053/ZHHE7561

Note: Never place a full stop at the very end of a DOI hyperlink in your reference list, as this can break the link functionality for readers.

Stop Treating CSS Container Queries Like Traditional Media Queries

Mike's Notes

The original Smashing Magazine article has all the CodePen examples.

And for fun, visit Set Studio to confirm that the ideal viewport doesn’t exist.

"Here at Set Studio, we conducted a little casual experiment to answer “how fragmented are viewport sizes?”. We gathered over 120,000 datapoints with over 2,300 unique viewport sizes. The data mainly came from users in the USA and Europe, therefore it is not necessarily representative of a global audience, but still useful for this article." - Set Studio

Resources

References

  • Reference

Repository

  • Home > Ajabbi Research > Library > Subscriptions > Smashing Magazine
  • Home > Handbook > 

Last Updated

15/11/2026

Stop Treating CSS Container Queries Like Traditional Media Queries

By: Victor Ayomipo
Smashing Magazine: 16/09/2026

Victor Ayomipo: I Code. I Write. Meme Rules. Ok, but seriously, I’m a web and mobile developer who writes a lot. In my spare time, I like to build products that would make my life easier. Because what’s more fun than making a computer do what you want it to do?

...

Quick Summary

Despite broad browser support, container queries remain surprisingly underused and frequently misunderstood. Let’s look at how they differ from media queries, when to reach for each, and how container queries help reusable components respond naturally to the contexts in which they appear.

...

To be completely honest with you, I missed the news when CSS Container Queries first shipped. And when I finally heard about it, my very first thought was, “Why exactly do I need this when media queries already exist?”

I’m not proud of that reaction, knowing what I know now, but it was comforting to know that I wasn’t alone. In fact, there are legions of us out there.

What baffles me is that container queries aren’t a new feature, as it currently sits at around 94% browser support. And yet, very few people are actually using it. According to the State of CSS survey, 86% of developers are aware of container queries, but only 41.4% actually use them. Surveys can be biased and not completely representative of our entire field, but this one is certainly the best indicator we’ve got.

Kevin Powell also talked about this at SmashingConf Amsterdam 2026: Container Queries adoption has been terrible. And that is so strange to me, knowing that the ability for components to adapt to the size of their outer container has been at the top of so many CSS wishlists over the years.

I’m not particularly interested in how many people are using container queries as much as in how they are using them. I can’t account for everyone, but from what I’ve seen — including in my own early attempts — many of us are using them wrong.

The bottom line is that incorrect use comes down to the same impression I had when learning about them: they absolutely look just like media queries at first glance. And since they look similar, it’s easy to assume they serve similar purposes and work the same way.

They don’t.

Note: I should state up front that what I’m focusing on in this article is using container size queries, i.e., a responsive design technique for responding to the size of a particular container. There are also container style queries that respond to a container’s computed styles (and are experimental at the time of this writing). You can catch up on those in Juan Diego’s piece here on Smashing Magazine where he examines their possible use cases.

Media Queries Look Outward

The viewport is a proxy. It always has been. Media queries are what gave us the illusion that screen width alone is responsible for how responsive apps adapt to their environment.

Ask yourself this: When you write @media, what are you asking the browser?

@media (min-width: 1024px) {
  .card {
    display: flex;
  }

I, like most developers, am asking the browser: How wide is the screen right now? That’s it.

Media queries answer that beautifully, but what happens when this .card component is placed in a grid cell that’s 300px wide on a 1920px desktop screen?

The media query doesn’t care; it does its job. The viewport is still 1920px, so min-width: 1024px fires and the matched query styles are applied, even though the card only has 300px of space to work with. Eventually, everything in the card deforms, overflows, or cramps up.

“Media queries are dumb. Not dumb in terms of the concept, but dumb in that they don’t know very much. In fact, most people assume that they know more than they do.” - Kevin Powell

It’s common to think of responsive design purely as a system for updating complete page layouts, like going from two columns on a large screen to a single column on a small screen.

Container Queries Look Inward

Container queries are smarter than that. They make responsive layouts more reliant on what’s happening inside a component rather than on the outer context that has no insight into a component’s contents. It is more like: “How much space is available for me in this specific spot, right now?”

Here is the same card code example we looked at in the last section, but with a container query:

.card-wrapper {
  container-name: card;
  container-type: inline-size;
}
@container card (min-width: 450px) {
  .card {
    display: flex;
    flex-direction: row;
  }
}

This changes everything. The card isn’t influenced by the viewport; its only concern is whether the .card component’s parent wrapper has at least 450px of inline (i.e., horizontal in a left-to-right writing mode) space. If that condition is true, the component goes horizontal; if not, it goes to its default block display.

See the Pen Viewport vs Container [forked] by Vayo.

“Macro” Layout Vs. “Micro” Layouts

A very interesting way to distinguish @media and @container queries is the layout type.

Media queries are for the “macro” layout; they look outward. Stuff like page structure, the header that spans the window, footers, main grid layout, system preferences (prefers-color-scheme), device capabilities (touch screens). You know, anything that is majorly true to the entire page structure.

Container queries, I’d say, are for “micro” layouts, i.e., most things that live inside the “macro” layout. We use them when any content needs to responsively fit whatever space it is allocated. Components that come to mind are things like cards, widgets, forms, navigation, and so on.

In other words, think “page layout” vs. “component layout”.

An element shouldn’t magically become “tablet-sized” just because the width exceeds an abstract width threshold like 768px. Instead, it should switch layout when it has enough space to do so, whether that happens on a mobile viewport or inside a desktop sidebar.

In case you’re still not convinced, did you know there are over 2,300 unique viewport sizes on the modern web? Do you think it is possible to account for all of them?

"I’m not hating on media queries. It’s that in this era of responsiveness and component re-use, layout logic is closer to the container than the viewport. When we think in terms of containers and components, we’re effectively relying on the content to determine layout, not the viewport.“

This is how it should be.

Example: Fluid Typography Inside A Component

Responsive typography is a good example of something many of us have relied on media queries for. The fact that media queries come with their own CSS units — e.g., vw, vh, and so on — that are relative to the viewport size makes media queries look really good for adjusting font size based on the user’s screen size.

.card-title {
  font-size: clamp(100%, 1rem + 2vw, 24px);
}

This works until that same component is moved into a different context, like a sidebar, where the viewport is completely irrelevant. Now, because we tied the responsiveness to the wrong reference point, the scaled typography can get too big or too small.

Container queries come with their very own units — cqi, cqw, cqb, among others — and we can take responsive components further by coupling those units with the CSS clamp() function, using it for fluid typography that scales with the component rather than the viewport:

.card-title {
  font-size: clamp(1rem, .5rem + 3cqi, 2rem);
}


See the Pen Fluid Typography [forked] by Vayo.

With this in place, the entire code is self-contained to that element’s specific container.

Example: Flexbox Wrap Detection

Interestingly, container queries can, in a way, detect the state of a component’s internal layout. It’s not bulletproof, but it is also something media queries simply cannot do because they only observe the external browser window and are structurally blind to internal layout events like when, for example, flex items wrap onto a new line. Let’s poke at that.

Flexbox is superb at wrapping content (flex-wrap: wrap), allowing flex items to automatically wrap to new lines when the flex container runs out of space to fit them in a single row. But CSS by itself can’t tell when that wrap happens. There isn’t something like a :wrapped pseudo-class or a media query like @media (flex-wrapped: true) that would get us there.

Media queries only observe the browser window, as they can’t see internal changes. That is pretty much what flex wrapping is: a width state change on the item itself.

For example, if you have a horizontal menu that is lined up with flexbox and you want the items to restyle themselves only when wrapped, you’d be in JavaScript territory, using ResizeObserver to get that information. However, when we nest container queries inside flex items, we can come up with a workaround to get what we need without JavaScript, thanks to this technique I learned from Kevin Powell. The core idea is to allow a flex item to flex-grow: 1 when we query the container’s inline size.

See the Pen Fluid Typography [forked] by Vayo.

The logic works like this:

  1. When there’s enough room, both items (.flex-item) sit side-by-side, each exactly half the parent container’s width.
  2. When there is limited space, the second item wraps to the next line.
  3. Because flex-grow is active on each item, the wrapped items stretch to fill most of the parent’s width.
  4. If the item is a container itself, it detects the sudden width expansion and fires.

/* The flex parent */
.flex-layout {
  display: flex;
  flex-wrap: wrap;
}
/* Register a flex item as a container */
.flex-item {
  container-type: inline-size;
  flex: 1 1 390px; /* Grow to fill space, wrap at 390px */
}
/* Default Card Styles (narrow / side-by-side) */
.card {
  display: flex;
  flex-direction: column;
  background: #f4f4f4;
}
/* Once there's enough room for a full row */
@container (min-width: 600px) {
  .card {
    flex-direction: row;
    align-items: center;
    background: #e2f0d9;
  }
}

This works. As the parent size shrinks and the cards wrap to two lines, the card item expands, the container query fires, and applies the necessary styles.

See the Pen Flex Wrap Detection Using Container Queries [forked] by Vayo.

Container Queries Do Have Side Effects

Container queries, like all things, come with some side effects or caveats you will want to watch for before reaching for them.

1. A Container Requires An Extra Wrapper

Container queries need something similar to a parent-child relationship to function as expected. Let’s say we have this markup:

<div class="card">
  <div class="card-content">...</div>
</div>

We can’t actually query the .card component to adjust the .card-content, like this:

/* DOES NOT WORK */
.card {
  container-name: card;
  container-type: inline-size;
}
@container card (min-width: 400px) {
  .card {
    display: flex;
  }
}

This doesn’t work because a container cannot query itself. In that last example, we’re querying a card container and then attempting to adjust that container’s display based on its size. It’s an infinite loop.

Instead, we need an additional wrapper that makes the .card a descendant of the container:

<div class="cards">
  <div class="card">
    <div class="card-content">...</div>
  </div>
</div>

From there, we can query the .cards container and adjust the .card layout accordingly:

.cards {
  container-name: cards;
  container-type: inline-size;
}
@container cards (min-width: 400px) {
  .card {
    display: flex;
  }
}

In media queries, this doesn’t matter as @media does not care which element you style inside the block; its only concern is the viewport, which is always available. So you can just slap a condition on any element and call it a day.

2. Querying A Container’s size Could Collapse Your Layout

This happens when querying the container’s size (i.e., its block, or vertical, size) instead of its inline-size:

/* Collapses to 0px even if it has content inside */
.hero-banner {
  container-type: size;
}

Why? Because the browser calculates the container’s dimensions without looking at its children. If we don’t give the .hero-banner an explicit height (or min-height or aspect-ratio), the browser sets a height of 0px.

For that reason, it’s often better to query a container by its inline-size instead. That is, unless you genuinely need to query the container’s block size.

Media queries aren’t affected by this, as they treat height the same way they treat @media (min-height: ...) does, i.e., ask the viewport and move on.

3. Queries Cannot Accept Custom Properties

Another container query limitation: we can’t query against a custom property value:

:root {
  --breakpoint-lg: 1600px;
}
/* DOES NOT WORK */
@container (min-width: var(--breakpoint-lg)) {
  /* ... */
}

This is because custom properties depend on values that cascade down the DOM tree. There’s the possibility that a container query that relies on a custom property can change that same custom property. And it can quickly get complicated:

:root {
  --breakpoint-lg: 1600px;
}
/* DOES NOT WORK */
@container cards (min-width: var(--breakpoint-lg)) {
  .card {
    --breakpoint-lg: 1000px;
  }
}

When To Reach For Media And Container Querie

I don’t think any project should wholesale use @container instead of @media. Media queries still play an important role in responsive layouts. It’s about understanding the separation of concerns.

I tend to reach for container queries when a component is used in more than one layout context. For example, a .card element could live in a full-width grid or a narrower sidebar. If that’s the case, then we’ll want the component’s content to determine when it adjusts rather than a media query that looks at the outer viewport.

Similarly, I reach for media queries when a component solely exists at the page level. This would be something like a main navigation that always sits at the top of the page. It is directly influenced by the viewport’s size, meaning that the viewport is a reliable reference for when the navigation needs to adjust. Again, it’s all about “macro” layout versus “micro” layouts.

Here’s a diagram for how I reason about which type of query to use:

Flowchart for choosing between media and container queries

Conclusion

At the end of the day, the core reason why container queries look incredibly similar to media queries is simply familiarity. They’re not exactly “new”, but they are way less understood and adopted than media queries. But media queries have plenty of their own limitations; otherwise, we wouldn’t need container queries to fill those gaps.

What we have is a more effective feature for detecting when a specific component’s context changes and a means for adjusting styles based on its content, as it should be when that component can exist in multiple contexts.