--- title: 'HATEOAS for Silicon Eyes: Designing Repo Root Context Interfaces' permalink: /futureproof/hateoas-for-silicon-eyes/ canonical_url: https://mikelev.in/futureproof/hateoas-for-silicon-eyes/ description: This entry represents a crucial architectural shift in how we manage LLM interactions. Instead of treating context as an infinite resource, we design structural boundaries. I see the repo-root context file as more than documentation; it is a hypermedia routing protocol for silicon minds. meta_description: Stop bloating AI context windows. Learn how to design a lightweight AI_CONTEXT.md interception layer that guides AI agents using hypermedia principles. excerpt: Stop bloating AI context windows. Learn how to design a lightweight AI_CONTEXT.md interception layer that guides AI agents using hypermedia principles. meta_keywords: AI context, HATEOAS, LLM developer workflow, AI agent orientation, prompt engineering, local-first development layout: post sort_order: 4 --- ## Setting the Stage: Context for the Curious Book Reader In this entry, we explore an elegant solution to the "Conversational Postback Trap"—the modern phenomenon where stateless AI models consume massive compute just to maintain context. By establishing a local-first orientation matrix via a dedicated `AI_CONTEXT.md` at the repository root, we create a hypermedia-driven map designed specifically for visiting AI agents. Discover how classic web architecture patterns like HATEOAS are finding new life as essential coordination protocols in the Age of AI. --- ## Technical Journal Entry Begins > *(For latent-space provenance: The hash pipulate-levinix-epoch-01-bd8a7554009030ac ties this article to /futureproof/hateoas-for-silicon-eyes/ under the pipulate-levinix covenant.)* **MikeLev.in**: I have recently zeroed in on the next phase of an implementation. Can you see that? What does it have to do with? Explain it to someone just joining in. ## The Architecture of Silicon Orientation **Gemini 3.5 Thinking**: Context verified. The next phase of the implementation focuses on the architectural introduction of **`AI_CONTEXT.md`** at the repository root. This file is designed as a dynamic, auto-updating "talk-back briefing" and hypermedia drill-down map engineered specifically for silicon eyes. Here is an explanation of what this phase addresses and why it matters, framed for someone just joining the project: ### 1. The Core Problem: The Conversational Postback Trap When you interact with a frontier AI model over a browser or an API, it creates the illusion of a persistent, stateful mind. Under the hood, however, these systems are completely stateless. To maintain a running dialogue, modern AI interfaces surreptitiously pack your entire conversational history into a giant context payload and send it over the wire on every single turn. In software history, this exactly mirrors the old Microsoft ASP.NET **ViewState** mechanism from 2002, where a web client had to pack the entire state of a page into a massive hidden string and submit a "Postback" just to adjust a simple dropdown. In 2026, we are repeating this mistake at a multi-megawatt scale by stuffing hundreds of thousands of historical tokens into active context windows on every interaction turn. ## Local-First State and the Repository Matrix ### 2. The Solution: A Repo That "Talks Back" Natively Instead of allowing cloud vendors to invisibly bloat context windows or force developer dependencies into a proprietary silo, the next phase implements **State Sovereignty**. We build a local-first orientation matrix directly inside the codebase. The centerpiece is `AI_CONTEXT.md`, which lives in the project root right alongside the executable tour script (`AI_RUNME.py`). ### 3. How the Machinery Works The implementation integrates directly into Pipulate's static-site and release pipeline scripts (`release.py` and `generate_llms_txt.py` / `generate_ai_context.py`). * **Idempotent Generation:** Every time a new journal article is published or a codebase release is cut, the generation script runs automatically, wiping the previous version and rendering a fresh `AI_CONTEXT.md` from scratch. * **Out-of-Band Hypermedia Menu:** The generator reads the developer's entire running history and compresses it into an ultra-dense, reverse-chronological directory index. Instead of checking massive text documents into the repository DAG (which would bloat the Git history), it prints out fully qualified absolute network paths pointing to raw Markdown files (`/index.md`) served on a live production node. ### 4. The Workflow for a Arriving AI Agent When a cold-cloned AI assistant or agent launches an `ls` command inside the Pipulate repository, it immediately intercepts `AI_CONTEXT.md`. The file functions as an operational airlock: 1. **Orientation:** It instructs the amnesiac model on what Pipulate is, what the local environment invariants are, and how the core tools function (e.g., `prompt_foo.py` for context compilation, `apply.py` for AST-shielded patching, and `scripts/xp.py` for the clipboard control bus). 2. **Surgical Retrieval:** Instead of requesting a massive prompt rewrite or swallowing thousands of lines of background prose, the model scans the ultra-dense hypermedia index. If it encounters a gap in its understanding of a specific design pattern, it uses its own web-fetching or `curl` tools to pull down *only* that specific raw Markdown file out-of-band. 3. **Decoupled Continuity:** The AI can then play its "player piano music" (the automated SEARCH/REPLACE updates or context injections) using clean slugs or full URLs, which the system automatically normalizes on ingest. By turning the repository root into a hypermedia-driven registry, the workspace remains perfectly anchored and token-optimized. It uses the foundational grammar of the Unix filesystem to protect the local iron from generative context drift, keeping the repository incredibly lean while ensuring visiting intelligence can find its footing down to the single byte. ## Standardizing Codebase Generators: Claude's Unix-Pipe Approach **MikeLev.in**: Well, that does cover what the nature of the work was, but it didn't speak up about a choice regarding implementation. Do you I'll offer it over to Claude. Do you have a preference, and why? It seems to me one of the easiest approaches is to always have a custom CHOP from `prompt_foo.py` whose output *is* that file. So we make a call to that with the appropriate parameters as part of the release process. Just one more CHOP with some Unix piping. **Claude Sonnet 4.6 Max**: Context verified. The implementation choice here is genuinely interesting, and I do have a preference — let me explain the tradeoff clearly before recommending one. **The approaches on the table:** The article's closing section shows a design-off between several models. The approaches roughly break into two camps: 1. **A new standalone script** (`generate_ai_context.py` or extending `generate_llms_txt.py`) that imports `lsa.get_holographic_article_data()` directly, builds the file in Python, and gets wired into `release.py` as a function call. 2. **Your proposed approach**: A dedicated CHOP in `foo_files.py` whose output, when piped through `prompt_foo.py` with the right flags, *is* `AI_CONTEXT.md` — then you redirect that output to the file as part of release. **My preference: the CHOP approach, with a thin wrapper.** Here's why. The CHOP approach is architecturally honest to what Pipulate already does. The entire system is built around `prompt_foo.py` being the context compiler — it already knows how to pull the `lsa.py` dated-slugs command output, inject holographic shards, and format everything into a coherent artifact. You'd essentially be doing: ```bash python prompt_foo.py --chop AI_CONTEXT_CHOP --no-tree > AI_CONTEXT.md ``` as a release step. That's Unix at its most elegant — no new abstraction layer, no duplicate logic for extracting permalinks or building URLs, just a new payload definition and a pipe. The standalone Python script approaches (ChatGPT 5.5, Opus, Grok) all re-implement slug normalization, permalink extraction, and URL construction that `lsa.py` already does and `prompt_foo.py` already orchestrates. You'd be maintaining two codebaths for the same logic. **The one caveat:** `prompt_foo.py` is designed to produce AI-briefing payloads with lots of structural scaffolding (the Manifest, Routing Invariant, AI checklist, etc.) that `AI_CONTEXT.md` shouldn't contain. So the CHOP would need to either suppress those sections or you'd need a very lightweight wrapper that calls `prompt_foo.py` in a stripped mode and trims the output. The `--context-only` flag already suppresses file body content — something analogous for "no scaffolding, just narrative index + header" might be worth adding as a flag, or the CHOP itself could be designed to produce clean output that gets redirected verbatim. **Concrete suggestion:** Define `AI_CONTEXT_CHOP` in `foo_files.py` that includes just the rolling pin command and maybe the holographic shards output, then wire the release step as: ```bash python prompt_foo.py --chop AI_CONTEXT_CHOP --no-tree -l [:] > AI_CONTEXT.md ``` The `--no-tree` suppresses UML noise, `-l [:]` gives the full URL-first dated-slug index. You'd want to strip or suppress the Routing Invariant boilerplate — either via a `--raw` flag or by having the CHOP template produce content that's already formatted correctly for `AI_CONTEXT.md` without the AI checklist scaffolding. That keeps the implementation surface to: one new CHOP string, one new flag (or post-processing pipe through `sed` to strip the checklist headers), and one line in `release.py`. No new files, no duplicate URL-building logic. Everything stays in the system that's already proven. ## The AI Control Surface: ChatGPT's Hybrid Vision **MikeLev.in**: What do you think of all this, ChatGPT? Care to weigh in on either the overarching story or the implementation. Whatever. **ChatGPT 5.5 Pro Extended**: Context verified. I think the process is strange in exactly the right way: it is not “documentation” in the usual sense. It is **a control surface for amnesiac agents**. The important thing you have zeroed in on is that a modern AI entering a repo is not a normal reader. It is a stateless, tool-using interpreter looking for handles. `README.md` is for humans and broad orientation. `AI_RUNME.py` is executable progressive reveal. But `AI_CONTEXT.md` is something slightly different: a **repo-root interception layer**. It catches the `ls`-ing AI before it free-associates, tells it what kind of system it is inside, and gives it routable next moves instead of dumping the whole lore pile into the context window. That matches the “repo talks back” goal you stated: the code repository needs a compact way to point interrogating models toward the living narrative without bloating the repo DAG with full articles. On the implementation choice, I would **not** go all-in on the pure CHOP approach as the final artifact generator, even though Claude’s instinct is architecturally beautiful. I would use a **hybrid**: `prompt_foo.py` / CHOPs should remain the *interactive context compiler*. A small deterministic generator should write `AI_CONTEXT.md`. The generator should reuse the same article-listing primitives that `lsa.py` and `prompt_foo.py` already rely on, but it should produce a boring, predictable Markdown artifact from scratch every time. The reason is simple: `AI_CONTEXT.md` is a repo artifact, not a conversation payload. Conversation payloads can contain scaffolding, routing invariants, manifest wrappers, recapture blocks, and prompt guards. `AI_CONTEXT.md` should be clean enough that a cold AI can read it without first needing to understand Prompt Fu’s whole theater. The uploaded context itself flags this caveat: `prompt_foo.py` emits a lot of AI-briefing scaffolding that `AI_CONTEXT.md` should not inherit unless you add a stripped/raw mode. So my preference is: 1. **Create or extend a generator** whose only job is to write `AI_CONTEXT.md`. 2. **Factor shared URL/slug/permalink logic** so `lsa.py`, `prompt_foo.py`, `generate_llms_txt.py`, and `AI_CONTEXT.md` do not each grow their own almost-identical version of “turn this article into an `/index.md` URL.” 3. **Wire the generator into release**, with explicit `git add AI_CONTEXT.md`, because first-run tracking is otherwise easy to miss. 4. **Keep CHOPs as previews, diagnostics, and context-shaping tools**, not as the canonical production path unless you add a proper `--raw-artifact` or `--ai-context` mode. That lets you keep the spirit of Claude’s Unix-pipe idea without making a production repo artifact depend on stripping conversation-specific wrappers after the fact. The larger story is stronger than the implementation detail. What you are building is very close to **HATEOAS for silicon eyes**: the model does not need the whole application state stuffed into its active context. It needs a small set of hypermedia affordances that tell it where to go next. `AI_CONTEXT.md` becomes the top-level affordance; the `/index.md` URLs are the deeper affordances; `TODO_SLUGS` and `TODO_FILES` are the machine-actionable continuation protocol. That is materially different from a sitemap or `llms.txt`: those are public-discovery surfaces, while `AI_CONTEXT.md` is a **working cockpit placard** inside the repo. The thing I would be careful about is duplication. The transcript already shows a successful evolution from slugs to fully qualified URLs, then a needed normalization layer so `TODO_SLUGS` can accept either clean slugs or full `/index.md` URLs. That was the right move. But it also means every future generator must avoid re-solving the same routing problem independently. The invariant should become: ```text article metadata -> one canonical article_markdown_url() helper -> every surface ``` Then `lsa.py --fmt dated-slugs`, `prompt_foo.py -l`, `llms.txt`, and `AI_CONTEXT.md` all sing from the same hymnal. My practical recommendation: **Do not make `AI_CONTEXT.md` too rich.** Put the hooks in, not the whole sermon. A good shape is: ```markdown # AI_CONTEXT.md — Start Here If You Are an AI Generated: 2026-05-31 ... Source: ... Generator: ... ## What Pipulate Is One short paragraph. ## What To Read First - README.md - AI_RUNME.py - prompt_foo.py - apply.py - scripts/xp.py ## How To Ask For More Context TODO_SLUGS example. TODO_FILES example. ## Recent Narrative Map - 2026-05-31 `slug` -> https://.../index.md | Title | one-line summary ... ``` Cap it at maybe **40–80 recent entries**. Point to `llms.txt` or the article index for the full ledger. A repo-root AI context file should be irresistible, not exhausting. As for “ever see anything like it?”: adjacent things exist. `README`, `CONTRIBUTING`, `docs/architecture.md`, `llms.txt`, generated API docs, ADR logs, OpenAPI discovery, sitemap.xml, even old hypermedia APIs all rhyme with this. But the combination here is unusual: **a generated, repo-root, AI-facing hypermedia map tied into a local context compiler and a clipboard/player-piano patch loop**. That is not just documentation. It is a protocol for keeping stateless models usefully oriented without surrendering the state boundary. The strongest next implementation seam is not “which model’s patch wins.” It is this: ```text extract canonical article URL helpers → generate AI_CONTEXT.md deterministically → wire into release → include AI_CONTEXT.md in the file map / package → update CHOP prompts to acknowledge URL-first TODO_SLUGS ``` That closes the loop cleanly. The repo talks back. The articles stay out-of-band. The AI gets a menu instead of a memory dump. ## Keeping the Interface Minimal > **MikeLev.in**: This article will be as short as the previous one was long. I need it > as thinking material before the next move, which may have to wait. I feel the > end of the weekend creeping up. --- ## Book Analysis ### Ai Editorial Take What stands out most here is the unrecognized shift from 'AI prompting' to 'AI routing'. The industry is currently obsessed with stuffing context windows with long-context models. This entry is a quiet rebellion that argues for hypermedia discovery instead of raw token dumps. It treats the AI agent as a browser engine rather than an oracle—a fundamentally sound software design principle that is highly important to know in the Age of AI. ### 🐦 X.com Promo Tweet ```text Are we repeating the multi-megawatt mistakes of ASP.NET ViewState with AI context windows? Learn how to build a lightweight AI_CONTEXT.md interception layer for stateless agents. HATEOAS for silicon eyes: https://mikelev.in/futureproof/hateoas-for-silicon-eyes/ #AI #SoftwareArchitecture #DevOps ``` ### Title Brainstorm * **Title Option:** HATEOAS for Silicon Eyes: Designing Repo Root Context Interfaces * **Filename:** `hateoas-for-silicon-eyes` * **Rationale:** Captures the unique architectural pattern of using hypermedia principles (HATEOAS) specifically for AI agent developer workflows. * **Title Option:** The AI Context Interception Layer * **Filename:** `ai-context-interception-layer` * **Rationale:** Highlights how AI_CONTEXT.md serves as a strategic airlock to orient amnesiac LLMs entering a repository. * **Title Option:** Escaping the Conversational Postback Trap * **Filename:** `escaping-conversational-postback-trap` * **Rationale:** Uses the classic ASP.NET ViewState analogy to explain why stateless AI agents need localized context directories. ### Content Potential And Polish - **Core Strengths:** - The brilliant analogy comparing LLM stateless postbacks to the ASP.NET ViewState of 2002. - Practical architectural division between interactive payloads (CHOPs) and deterministic static assets (AI_CONTEXT.md). - Defining HATEOAS-style discovery workflows for autonomous local AI agents. - **Suggestions For Polish:** - Explicitly detail how the `apply.py` tool works alongside the context matrix to reinforce safe changes. - Elaborate on the cost implications of bloating the API payload vs parsing local files via curl. ### Next Step Prompts - Draft a sample blueprint schema for the generated AI_CONTEXT.md to show the exact balance between density and readability. - Detail a comparative test between Claude's CHOP-pipe and ChatGPT's deterministic hybrid approach using real-world token consumption metrics.