From e495e875ac2e20d9bdb2f9dff7f0319f2106df16 Mon Sep 17 00:00:00 2001
From: Loyyd <konradkunkel@gmx.de>
Date: Thu, 11 Jun 2026 09:14:40 +0200
Subject: [PATCH] astro only

---
 AGENTS.md              |  6 ++++++
 README.md              | 19 +++++++++++++++++++
 docs/SITE-STRUCTURE.md | 13 +++++++++++++
 package.json           |  4 +++-
 4 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index d6b40905..bbd49db8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -55,6 +55,12 @@ npm run build
 npm run preview
 ```
 
+For a build health check:
+
+```bash
+npm run check
+```
+
 Then open:
 
 ```text
diff --git a/README.md b/README.md
index 0d7230cd..dd564ce5 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,12 @@ Run Astro locally while editing:
 npm run dev
 ```
 
+Check that the generated site builds successfully:
+
+```bash
+npm run check
+```
+
 Regenerate Markdown content from the exported post HTML:
 
 ```bash
@@ -85,3 +91,16 @@ Then open:
 ```text
 http://localhost:4321/
 ```
+
+## Deployment
+
+This project deploys as a static Astro build. A deployment job should install
+dependencies, run the build, and publish the generated `dist/` directory:
+
+```bash
+npm ci
+npm run build
+```
+
+Use `npm run start` only when you intentionally want Astro to serve the built
+output in an environment such as a local or Nomad preview job.
diff --git a/docs/SITE-STRUCTURE.md b/docs/SITE-STRUCTURE.md
index 6618bcb1..72731a46 100644
--- a/docs/SITE-STRUCTURE.md
+++ b/docs/SITE-STRUCTURE.md
@@ -79,6 +79,12 @@ Then open Astro's local URL, usually:
 http://localhost:4321
 ```
 
+Run the build health check:
+
+```bash
+npm run check
+```
+
 For a production-style Astro preview, build first:
 
 ```bash
@@ -91,3 +97,10 @@ Then open:
 ```text
 http://localhost:4321
 ```
+
+## Deployment
+
+Astro emits a static site into `dist/`. Deployment should run `npm ci` and
+`npm run build`, then publish or serve the generated `dist/` directory. Use
+`npm run start` only for Astro-based preview jobs that need to serve the built
+output directly.
diff --git a/package.json b/package.json
index 72945a80..51ef1b00 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,9 @@
     "prepare:source": "npm run organize && npm run render:layout",
     "dev": "npm run prepare:source && astro dev --host 0.0.0.0",
     "build": "npm run prepare:source && astro build && node scripts/copy-static-assets.mjs",
-    "preview": "astro preview --host 0.0.0.0"
+    "preview": "astro preview --host 0.0.0.0",
+    "start": "npm run preview",
+    "check": "npm run build"
   },
   "devDependencies": {
     "astro": "^6.4.6"