Update CLAUDE.md

CLAUDE.md

@@ -1,64 +1,113 @@
-# diachron overview for Claude
+# CLAUDE.md
 
-## Overview
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository.
 
-diachron is an attempt at a web framework that attempts to solve various pain
+## Project Overview
-points I've dealt with when using other frameworks.
 
-## Goals
+Diachron is an opinionated TypeScript/Node.js web framework with a Go-based
+master process. Key design principles:
+- No development/production distinction - single mode of operation everywhere
+- Everything loggable and inspectable for debuggability
+- Minimal magic, explicit behavior
+- PostgreSQL-only (no database abstraction)
+- Inspired by "Taking PHP Seriously" essay
 
-- Programs are increasingly complicated; therefore:
+## Commands
-  - We want to have everything loggable available for inspection
-  - At any given point in execution execution, we want to know "what the
-    framework thinks"
-  - Easy debuggability is very important
-- We don't want extreme flexibility; for example, by design we only support
-  Postgres
-- We don't aim to be fast (it's nice when we can get good performance, but it
-  should be sacrificed to other goals most of the time)
-- Application Diachron code uses Typescript; however, it draws a lot of ideas
-  from the essay titled "Taking PHP Seriously"
-- We want as little magic as possible
-- When it comes to behavior or architecture, there must be no
-  development/production distinction.  Just one mode of operation.
 
+### General
 
-## architecture
+**Install dependencies:**
+```bash
+./sync.sh
+```
 
-Note: for now, this document only describes the part of the framework that is
+**Run an app:**
-involved with processing requests and creating responses.
+```bash
-
+./master
-### master process
+```
-
-The master process is written in golang.  It has the following
-responsabilities:
-
-- Listen on one or more ports and proxy web requests to the correct backend
-  worker
-- Watch the typescript source directory for changes; when it changes, attempt
-  to rebuild the typescript source
-  - Keep numerous copies of the transpiled system available
-  - If transpiliation fails, execution should not stop
-- Keep track of child processes, ensuring that a sufficient number of them are
-  available at a given time.
-
-Note that the master process behaves exactly the same in production
-environments as it does on a developer's desktop system.  There is no
-development/production distinction.
 
 
 
-## Project structure
+### Development
+
+**Check shell scripts (shellcheck + shfmt) (eventually go fmt and prettier or similar):**
+```bash
+./check.sh
+```
+
+**Format TypeScript code:**
+```bash
+cd express && ../cmd pnpm prettier --write .
+```
+
+**Build Go master process:**
+```bash
+cd master && go build
+```
+
+### Operational
+
+(to be written)
+
+## Architecture
+
+### Components
+
+- **express/** - TypeScript/Express.js backend application
+- **master/** - Go-based master process for file watching and process management
+- **framework/** - Managed binaries (Node.js, pnpm), command wrappers, and
+  framework-specific library code
+- **monitor/** - Go file watcher that triggers rebuilds (experimental)
+
+### Master Process (Go)
+
+Responsibilities:
+- Watch TypeScript source for changes and trigger rebuilds
+- Manage worker processes
+- Proxy web requests to backend workers
+- Behaves identically in all environments (no dev/prod distinction)
+
+### Express App Structure
+
+- `app.ts` - Main Express application setup with route matching
+- `routes.ts` - Route definitions
+- `handlers.ts` - Route handlers
+- `services.ts` - Service layer (database, logging, misc)
+- `types.ts` - TypeScript type definitions (Route, Call, Handler, Result, Method)
+
+### Framework Command System
+
+Commands flow through: `./cmd` → `framework/cmd.d/*` → `framework/shims/*` → managed binaries in `framework/binaries/`
+
+This ensures consistent tooling versions across the team without system-wide installations.
+
+## Tech Stack
+
+- TypeScript 5.9+ / Node.js 22.15
+- Express.js 5.1
+- Go 1.23.3+ (master process)
+- pnpm 10.12.4 (package manager)
+- Zod (runtime validation)
+- Nunjucks (templating)
+- @vercel/ncc (bundling)
+
+## Platform Requirements
+
+Linux x86_64 only (currently). Requires:
+- Modern libc for Go binaries
+- docker compose (for full stack)
+- fd, shellcheck, shfmt (for development)
+
+## Current Status
+
+Early stage - most implementations are stubs:
+- Database service is placeholder
+- Logging functions marked WRITEME
+- No test framework configured yet
 
 # meta
 
-## plans
-
-- This document includes many statements that should be taken as statements of
-  intent and not necessarily of current fact.  In other words, when diachron
-  reaches a certain stage of maturity, the entire document should be true, but
-  initially it is not yet entirely true.
-
 ## guidelines for this document
 
 - Try to keep lines below 80 characters in length, especially prose.  But if