feat: add engineering blog with 4 posts adapted from the system primer

[claude]

Requested by Christian Byrne · Slack thread

Summary

Adds an engineering blog to apps/website, seeded with 4 posts adapted from the internal "Understand This System" Notion primer. Originally these were plain-English explainers of the whole system; per review feedback, they're now rewritten as blog posts — each one leads with the actual engineering problem and how the team arrived at the solution, cuts standard/textbook material and any "this part is still half-built" framing, and gets a diagram.

What changed after review

Christian's feedback was: focus on novel decisions and how they arose, not full system state; cut standard/trivial explanation and temporary/incomplete framing; add diagrams and images, structure like real blog posts; fix the primer title leaking into the blog index; give posts images on the listing page.

• Rewrote all 4 posts around a narrative hook instead of a reference-doc structure:
  • CRDTs From Scratch → "The Stamp That Replaced the Clock" (crdts-from-scratch) — cut the from-scratch tutorial (building a G-Counter, a tombstoned set, from first principles) entirely. Reframed around the actual story: a wall-clock last-write-wins scheme would have let a fast laptop clock win every conflict, and the fix was a self-contained 3-part stamp (base_version/actor/op_id) instead. Also dropped the "logical clocks are the natural next step for a future version" roadmap hedge.
  • Comfy's Agent Architecture, End to End (comfy-agent-architecture-end-to-end) — kept the "one sentence per box" structure (it already read as a real post), but cut the "a future lightweight, locally-persisted engine is planned" line and rewrote the single-writer section to drop the "the door stays open for true multi-writer editing later" roadmap framing, focusing instead on the actual design insight (why single-writer is a routing choice, not a hidden dependency).
  • How a User Complaint Becomes a Permanent Test Case (how-user-feedback-becomes-a-test-case) — moved the strongest material (an agent that polled a job it never submitted, and confidently reported success) from buried mid-post to the opening hook, and tightened the test/eval/benchmark vocabulary section that used to lead.
  • The Agent's Hands: MCP, comfy-cli, and the Tool Surface (the-agents-hands-mcp-and-comfy-cli) — kept mostly as-is (it already led with a hook and a specific technical throughline), trimmed some edge-case detail, added a diagram.
• Added one inline-SVG diagram per post showing the actual mechanism (the write path through ingest/agent-service/doc-host/DB/fan-out; the stamp comparison that makes two replicas converge on the same answer; the intake→triage→eval-gate→fix loop; the two doors into the platform). Built as small Astro components under src/components/engineering-blog/diagrams/, styled with the site's existing color tokens (var(--color-primary-comfy-yellow) etc.) so they match the site's single dark theme (this site doesn't have a light/dark toggle — confirmed via src/styles/global.css, no prefers-color-scheme/data-theme handling exists here, so the diagrams just use the same tokens every other component on the site uses).
• Card images on the listing page: each diagram component renders a compact variant="card" version, shown next to its post's title/description in the /engineering-blog list (previously text-only). Added a heroDiagram frontmatter field (engineering-blog.schema.ts) so the listing and the post body render the same diagram from one source of truth; a small registry (diagrams/registry.ts) maps the field to the component.
• Fixed the index title: /engineering-blog rendered an <h1> of "Understand this system" — leftover from the internal primer's own title, not specific to this blog or any post. Replaced with "Engineering Blog", and updated the eyebrow label and meta description to match.
• No raster hero images: a Comfy Cloud image-generation MCP tool is available in this environment, but generating one spends the connected account's paid credits and the tool's spend gate requires an explicit human confirmation this session couldn't obtain non-interactively, so raster hero art was skipped in favor of the inline-SVG diagrams, which is where the task said priority should go anyway (they show the actual mechanism, not decoration).
• Updated engineeringBlog.ts / engineeringBlog.test.ts for the new heroDiagram field.

Posts

Post	Slug	Author	Diagram
The Stamp That Replaced the Clock	crdts-from-scratch	Kishore	stamp comparison + convergence
Comfy's Agent Architecture, End to End	comfy-agent-architecture-end-to-end	Kishore	write path (truth vs. speed)
How a User Complaint Becomes a Permanent Test Case	how-user-feedback-becomes-a-test-case	Jo Zhang	intake → triage → eval gate → fix loop
The Agent's Hands: MCP, comfy-cli, and the Tool Surface	the-agents-hands-mcp-and-comfy-cli	Matt Miller	two doors into one platform

Review Focus

• Whether the SVG diagrams read clearly at both the card-thumbnail size and full post width.
• Whether the heroDiagram enum / registry approach is the right amount of structure for 4 posts, versus something simpler.
• Still open from the original PR: whether /engineering-blog should get a nav/footer entry, and whether zh-CN translations are wanted.

Verification

• pnpm --filter @comfyorg/website typecheck (astro check) — 0 errors
• pnpm --filter @comfyorg/website build (astro build) — builds cleanly, all 4 posts + listing page render, no duplicate SVG ids across the 4 cards on the index page
• pnpm --filter @comfyorg/website test:unit — 50 test files / 494 tests pass
• pnpm --filter @comfyorg/website validate:jsonld — passes across 617 pages
• pnpm knip — clean
• oxfmt --check / eslint on the new non-MDX files — clean

[github-actions]

🌐 Website E2E

Tip

All tests passed.

Status	✅ Passed
Report	View Report

🔗 Website Preview

Website Preview: https://comfy-website-preview-pr-15640.vercel.app

_{This commit: https://website-frontend-jsefmfofs-comfyui.vercel.app}

_{Last updated: 2026-08-22T10:04:52Z for 7a8f7ca}

[codecov]

Codecov Report

❌ Patch coverage is 83.33333% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...c/components/engineering-blog/diagrams/registry.ts	0.00%	1 Missing ⚠️

@@           Coverage Diff           @@
##             main   #15640   +/-   ##
=======================================
  Coverage   79.39%   79.39%           
=======================================
  Files        2217     2219    +2     
  Lines      112188   112194    +6     
  Branches    35091    35092    +1     
=======================================
+ Hits        89069    89074    +5     
- Misses      22640    22641    +1     
  Partials      479      479           

Flag	Coverage Δ
website-unit	26.39% <83.33%> (+0.06%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
apps/website/src/utils/engineeringBlog.ts	100.00% <100.00%> (ø)
...c/components/engineering-blog/diagrams/registry.ts	0.00% <0.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.