astro only

AGENTS.md

@@ -55,6 +55,12 @@ npm run build
 npm run preview
 ```
 
+For a build health check:
+
+```bash
+npm run check
+```
+
 Then open:
 
 ```text

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.

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.

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"