FE-1322: Migrate the architecture prose into the docs bundle

[kube]

🌟 What is the purpose of this PR?

Moves the hand-written architecture documentation from petrinaut-core/docs/architecture/ into the docs bundle, so it appears alongside the generated pages instead of beside them.

The old location held 3,100 lines of HTML and a stylesheet. Nothing served it, and it could only be read by opening the files off disk. Its content is what a generated page cannot produce: why a boundary is where it is, which alternatives were rejected, and which mistakes are easy to make.

Second of three PRs, on top of #9204. #9206 renders the result.

🔍 What does this change?

A page names the layer it explains, and is written out below that layer's generated page:

---
title: Memory model
attachTo: core.simulation
---

flowchart LR
  S["content/simulation/<br/>memory-model.mdx"] --> A{"attachTo:<br/>core.simulation"}
  A --> P["pages/architecture/core/<br/>simulation/memory-model.mdx"]
  A --> G["Guides link on<br/>the layer page"]

Loading

The layer's page gains a Guides section linking to it. Because a page's depth depends on attachTo, links are written by name (layer:core.simulation.engine, doc:simulation/memory-model) and the path is worked out when the page is written. A target that does not resolve fails the build.

Five simulation deep-dives carry detail the generated pages do not: the memory model and frame format, the fixed stage order of a step, the HIR pipeline and the limits of the sandbox, the worker protocol and its ack contract, and why only aggregates reach the UI from a Monte Carlo run.

Four diagram components cover the parts that are visual: byte layouts, lane diagrams, pipelines, and message sequences. They are the only reason the bundle asks a host for a React-capable MDX pipeline.

Migrating the pages turned up two claims that were no longer true: UUID support described as unimplemented when it is complete, and a sandbox description narrower than what the code does.

🔗 Related links

• FE-1322
• FE-1139, the ticket that produced the HTML pages migrated here.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

• does not modify any publishable blocks or libraries, or modifications do not need publishing

Deletes documentation from petrinaut-core. No runtime code, types or exports change.

📜 Does this require a change to the docs?

• require changes to docs which are made as part of this PR

This PR is a documentation change. The user-facing guide (libs/@hashintel/petrinaut/docs/) is untouched. AGENTS.md gains a paragraph on attachTo and the link schemes.

🕸️ Does this require a change to the Turbo Graph?

• does not affect the execution graph

⚠️ Known issues

• These pages are written by hand and can stop matching the code. They avoid repeating facts the generated pages already carry, which limits the damage but does not prevent it. The generated half is checked against the source; this half is not, and the index page says so.
• content/ is not checked against the code. A guide describing a layer that later changes shape will not fail the build. Only its attachTo and its links are checked.

🐾 Next steps

• FE-1322: Add a Starlight site that renders the docs bundle #9206 renders these pages.

🛡 What tests cover this?

No new tests, since this is content. The code that consumes it is covered by emit/mdx.test.ts (link resolution at different depths, fragments, unresolved targets) and by lint:arch-docs, which fails on an attachTo naming a layer that does not exist, a layer: or doc: target that does not resolve, and an @diagrams/ import naming a component that does not exist.

❓ How to test this?

turbo run doc:architecture --filter @local/petrinaut-arch-docs

Expect 38 generated pages · 8 authored pages, with the deep-dives under bundle/pages/architecture/core/simulation/.

To see the link checking fire: point a layer: target at layer:core.nonexistent, or set an attachTo to a layer that does not exist. Each fails lint:arch-docs and names the file.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 13, 2026 10:12am
petrinaut	Ready	Preview	Aug 13, 2026 10:12am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 13, 2026 10:12am

[cursor]

PR Summary

^{Cursor Bugbot is generating a summary for commit 1e53e0d. Configure here.}

[Copilot]

Pull request overview

Moves Petrinaut’s hand-written architecture documentation into the generated docs bundle alongside layer reference pages.

Changes:

• Adds eight authored MDX architecture guides with layer-aware links.
• Adds reusable React diagram components and styling.
• Removes the obsolete standalone HTML documentation and updates contributor guidance.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
libs/@local/petrinaut-arch-docs/content/working-on-the-architecture.mdx	Adds contributor guidance.
libs/@local/petrinaut-arch-docs/content/two-execution-paths.mdx	Explains simulation execution paths.
libs/@local/petrinaut-arch-docs/content/simulation/user-code.mdx	Documents user-code compilation.
libs/@local/petrinaut-arch-docs/content/simulation/stepping.mdx	Documents simulation stepping.
libs/@local/petrinaut-arch-docs/content/simulation/protocol.mdx	Documents worker messaging and backpressure.
libs/@local/petrinaut-arch-docs/content/simulation/memory-model.mdx	Documents frame storage and layout.
libs/@local/petrinaut-arch-docs/content/simulation/experiments.mdx	Documents Monte Carlo execution.
libs/@local/petrinaut-arch-docs/content/index.mdx	Adds the authored documentation index.
libs/@local/petrinaut-arch-docs/content/components/sequence.tsx	Adds sequence diagrams.
libs/@local/petrinaut-arch-docs/content/components/pipeline.tsx	Adds pipeline diagrams.
libs/@local/petrinaut-arch-docs/content/components/lanes.tsx	Adds lane diagrams.
libs/@local/petrinaut-arch-docs/content/components/inline.tsx	Adds inline code formatting.
libs/@local/petrinaut-arch-docs/content/components/diagram.css	Styles diagram components.
libs/@local/petrinaut-arch-docs/content/components/byte-map.tsx	Adds byte-layout diagrams.
libs/@hashintel/petrinaut-core/docs/architecture/worker.html	Removes legacy worker documentation.
libs/@hashintel/petrinaut-core/docs/architecture/monte-carlo.html	Removes legacy experiment documentation.
libs/@hashintel/petrinaut-core/docs/architecture/index.html	Removes the legacy architecture index.
libs/@hashintel/petrinaut-core/docs/architecture/engine.html	Removes legacy engine documentation.
libs/@hashintel/petrinaut-core/docs/architecture/authoring.html	Removes legacy authoring documentation.
libs/@hashintel/petrinaut-core/docs/architecture/architecture.css	Removes legacy documentation styling.
AGENTS.md	Documents authored-page attachment and links.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.

Suppressed comments (6)

libs/@local/petrinaut-arch-docs/content/simulation/stepping.mdx:17

• computeNextFrame does not mutate its input: it constructs and returns updatedSimulation with a new frames array (libs/@hashintel/petrinaut-core/src/simulation/engine/compute-next-frame.ts:160-167). This wording can make callers assume the original instance advanced. Describe the returned instance as new while retaining the concurrency warning for the shared transition scratch buffers (engine/types.ts:63-87).

Neither is pure. Stepping mutates the instance it is given, and the transition
path reuses kernel staging buffers between calls, so a `SimulationInstance` must
not be stepped concurrently or reused across runs.

libs/@local/petrinaut-arch-docs/content/simulation/protocol.mdx:50

• The worker does not compile user TypeScript. SimulationConfig explicitly requires artifacts produced by compileHirArtifacts and says the engine has no compiler (libs/@hashintel/petrinaut-core/src/simulation/api.ts:78-84); a net containing a lambda, kernel, or dynamics fails initialization when those artifacts are omitted. Change this note to “validate and instantiate precompiled HIR artifacts,” add hirArtifacts to the init payload table, and make the same correction in stepping.mdx:19.

      direction: "right",
      label: "`init`",
      note: "Builds the simulation, compiles user code, packs frame 0",

libs/@local/petrinaut-arch-docs/content/simulation/protocol.mdx:33

• SimulationFramePayload also contains the ordered newStrings pool delta (simulation/worker/frame-payload.ts:3-24). A protocol consumer implemented from this table would discard that delta, so string token attributes decode against an incomplete pool. Include newStrings? here and in the payload row in memory-model.mdx:79.

| `frame` / `frames` | `{ time, frame }`, single or batch        | Appended to the frame store, which republishes count and latest. |

libs/@local/petrinaut-arch-docs/content/components/byte-map.tsx:46

• When both title and caption are supplied—as in memory-model.mdx—this renders two <figcaption> elements. HTML permits at most one caption per <figure>, so assistive technology may not associate the detailed bottom caption with the diagram. Keep the detailed text as the figure caption and render the short title as a non-caption element.

    {title === undefined ? null : (
      <figcaption className="pnd-title">{title}</figcaption>
    )}

libs/@local/petrinaut-arch-docs/content/components/diagram.css:257

• This media rule collapses the sequence's actor and message grids to one column. On a narrow screen the actor headings stack, while each row becomes label → note or note ← label, so the arrows no longer connect either actor and message direction is unreadable. Keep the sequence and actor grids at three columns; their existing minmax(0, 1fr) columns can shrink and wrap.

  .pnd-msg,
  .pnd-actors {
    grid-template-columns: minmax(0, 1fr);
  }

libs/@local/petrinaut-arch-docs/content/index.mdx:31

• The base PR’s known issues state that lint:arch-docs is not run by CI until #9206, so CI currently does not fail when these pages drift. This promise can lead contributors to rely on a check that never ran; say “the bundle build/check fails” for now or wire the lint task into CI. The same CI-enforcement claim also appears in working-on-the-architecture.mdx:63,118 and AGENTS.md:132.

**Generated pages** — everything under [Architecture](architecture) — are
extracted from annotations in the source on every build, and CI fails if they
drift. Layer sizes and dependency counts all come from the code. If a generated page disagrees with the code, that is a bug in the
annotations, not in the page.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 81e9c30. Configure here.}