A build log of the Syntaxis v0.1.0 scaffold — from identity specification to deployed Astro 5 site with a private KB, written entirely with Claude as the primary engineering tool.

How This Site Was Built in One Session

This is the first journal entry. It documents how Syntaxis v0.1.0 was built — the tools used, the decisions made, the things that nearly went wrong, and what this site is actually for.

What this site is

Syntaxis is a professional identity and knowledge management system for an AI-augmented SRE operating in healthcare interoperability. The public face is a services website. Behind a password is a private knowledge base — runbooks, incident records, integration patterns, architecture decisions.

The KB is the point. The website is the front door.

The philosophy is Forma sequitur functionem — form follows function. Every architectural decision was made because it makes the system more maintainable, more legible to future operators, and more honest about what it is.

The AI tooling

This site was built in a single Claude session. Claude wrote every file — the Astro config, the auth system, the CSS design system, the KB notes, this journal entry. The human operator specified requirements, reviewed output, and made architectural decisions. Claude executed.

This is the governance model in miniature: AI handles implementation (signal amplification), human handles architectural judgment (risk adjudication). It’s the same model used for clinical data operations — and it works for the same reasons.

What Claude contributed:

Read the Shire Door v2 deployment history from Vercel’s API to extract known bugs and patterns
Applied those lessons to prevent the same bugs in this codebase (dynamic import pattern, prerender = false on API routes, CSS import in frontmatter)
Built a complete Astro 5 scaffold from scratch: auth, KB, journal, API routes, design system
Wrote KB-00 with enough detail that a future Claude session can understand the entire system without additional context

What the human contributed:

The identity specification (AI-augmented SRE + healthcare interoperability + Verbos Amicus philosophy)
The decision to model the KB on Obsidian’s digital garden pattern
The decision to use the Shire Door v2 architecture as the template
Review and approval of every significant file

Key lessons from Shire Door v2 (applied here)

The Shire Door v2 deployment history is stored in Vercel. Reading those commit messages like an incident log revealed five recurring bugs. All five were prevented in Syntaxis by applying the lesson directly:

Bug 1 — API route 404: Adding export const prerender = false as the first export in every API route file.

Bug 2 — Middleware crash: Using dynamic import for auth in middleware.ts so the auth module doesn’t run at module initialization time.

Bug 3 — CSS not loading: Importing global.css in the layout’s frontmatter (JavaScript), not inside a <style> tag.

Bug 4 — Secret mismatch: Using process.env everywhere in server-side auth code, never import.meta.env.

Bug 5 — Schema crash: Making order a string in every KB note frontmatter ("00", not 0).

This is what AI-augmented operations looks like in practice. The bugs aren’t novel — they’re patterns. If you can read the pattern from previous incidents, you can prevent the next occurrence. The AI reads faster and retains the pattern more reliably than re-reading commit history manually.

The architecture decisions worth explaining

Why Astro 5 and not Next.js: The overhead of the React runtime isn’t justified for what are mostly content pages. Astro ships zero JavaScript by default. The hybrid output mode lets static pages be prerendered at build time and protected KB pages run as serverless functions — without the full Next.js machinery.

Why individual .md files and not a FILES[] array: The FILES[] array works for Shire Door v1 because it’s a fixed-scope project. Syntaxis’s KB is designed to grow indefinitely. Individual files mean each note has its own git history, Zod validates every note’s frontmatter at build time, and future search (Pagefind) works natively.

Why HMAC password auth now and Better Auth later: Better Auth requires a database, an OAuth app, and 5+ env vars before anything works. Phase 1 launches with 2 env vars. The cookie format is forward-compatible with Phase 2’s role model.

What comes next

The journal stacks. Each entry documents something real — a problem solved, a pattern identified, a decision made and explained. Future AI tools (and future Claude sessions) will read this journal to understand the context of how this system was built.

The KB evolves. Every incident gets a record. Every integration pattern that required debugging gets a note. Every architectural decision gets an ADR.

The site grows. Contact form email integration, Pagefind search, browser editing for KB notes, and eventually Better Auth with GitHub OAuth.

The documentation is the product. The code is just the delivery mechanism.

v0.1.0 · 2026-03-26 · Built with Claude, Astro 5, Vercel