feat: add Astro docs site and GitHub Pages deployment

Author: code5717

.github/workflows/deploy-docs.yml

@@ -0,0 +1,60 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [master, main]
+    paths:
+      - 'site/**'
+      - '.github/workflows/deploy-docs.yml'
+      - 'README.md'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: site/package-lock.json
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Install dependencies
+        working-directory: site
+        run: npm ci
+
+      - name: Build docs
+        working-directory: site
+        run: npm run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -58,6 +58,7 @@ PYTHONPATH=. uv run pytest                         # All tests
 PYTHONPATH=. uv run pytest test/test_tokenizer.py  # Specific test file
 PYTHONPATH=. uv run pytest -k "generic" -v         # Targeted tests
 uv run python scripts/verify_examples_e2e.py       # Compile/build/run + output checks for all examples
+uv run python scripts/verify_error_stages.py       # Error-stage audit across modes and formats
 ```
 
 ## Compilation Pipeline
@@ -96,12 +97,21 @@ All AST traversals are iterative (no recursion) — the pipeline works with Pyth
 
 ## Learn More
 
+- Documentation website: `https://airbus5717.github.io/a7-py/`
 - `docs/SPEC.md` - Language specification
 - `examples/` - 36 sample programs
 - `CLAUDE.md` - Development guide
 - `MISSING_FEATURES.md` - Feature status and roadmap
 - `CHANGELOG.md` - Change history
 
+## Docs Development
+
+```bash
+cd site
+npm install
+npm run dev
+```
+
 ---
 
 Work in progress. Contributions welcome!

site/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

site/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

site/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

site/README.md

@@ -0,0 +1,33 @@
+# A7 Documentation Site
+
+Astro + Starlight documentation site for the A7 compiler project.
+
+## Local development
+
+```bash
+cd site
+npm install
+npm run dev
+```
+
+## Build
+
+```bash
+cd site
+npm run build
+```
+
+## Check
+
+```bash
+cd site
+npm run check
+```
+
+## Deployment
+
+Deployment is handled by GitHub Actions workflow `.github/workflows/deploy-docs.yml`.
+
+Production URL:
+
+- `https://airbus5717.github.io/a7-py/`

site/astro.config.mjs

@@ -0,0 +1,74 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+// https://astro.build/config
+export default defineConfig({
+	site: 'https://airbus5717.github.io',
+	base: '/a7-py',
+	integrations: [
+		starlight({
+			title: 'A7 Compiler Docs',
+			description: 'Documentation for the A7 language and the a7-py compiler.',
+			favicon: '/favicon.svg',
+			customCss: ['./src/styles/docs.css'],
+			pagefind: false,
+			social: [
+				{
+					icon: 'github',
+					label: 'GitHub',
+					href: 'https://github.com/airbus5717/a7-py',
+				},
+			],
+			sidebar: [
+				{
+					label: 'Get Started',
+					items: [
+						{ label: 'Installation', slug: 'getting-started/installation' },
+						{ label: 'Quickstart', slug: 'getting-started/quickstart' },
+					],
+				},
+				{
+					label: 'Compiler Usage',
+					items: [
+						{ label: 'CLI Reference', slug: 'compiler/cli-reference' },
+						{ label: 'Modes and Output', slug: 'compiler/modes-and-output' },
+						{ label: 'Pipeline Overview', slug: 'compiler/pipeline-overview' },
+					],
+				},
+				{
+					label: 'Language Guide',
+					items: [
+						{ label: 'Types', slug: 'language/types' },
+						{
+							label: 'Declarations and Expressions',
+							slug: 'language/declarations-and-expressions',
+						},
+						{ label: 'Control Flow', slug: 'language/control-flow' },
+						{ label: 'Functions', slug: 'language/functions' },
+						{ label: 'Generics', slug: 'language/generics' },
+						{ label: 'Memory Management', slug: 'language/memory-management' },
+						{ label: 'Modules and Visibility', slug: 'language/modules-and-visibility' },
+						{ label: 'Builtins and Operators', slug: 'language/builtins-and-operators' },
+						{ label: 'Grammar Summary', slug: 'language/grammar-summary' },
+						{ label: 'Diagnostics and Limits', slug: 'language/diagnostics-and-limits' },
+					],
+				},
+				{
+					label: 'Examples',
+					items: [
+						{ label: 'Examples Index', slug: 'examples/examples-index' },
+						{ label: 'By Topic', slug: 'examples/by-topic' },
+					],
+				},
+				{
+					label: 'Project Status',
+					items: [
+						{ label: 'Changelog', slug: 'project/changelog' },
+						{ label: 'Missing Features', slug: 'project/missing-features' },
+					],
+				},
+			],
+		}),
+	],
+});