Migrate docs to Starlight and ship Phase 1.1 hardening/polish

.env.example

@@ -0,0 +1,5 @@
+# Free tools frontend API target
+PUBLIC_FREE_TOOLS_API_BASE_URL=http://127.0.0.1:5000
+
+# Cloudflare Turnstile site key (optional in local)
+PUBLIC_TURNSTILE_SITE_KEY=

.github/workflows/check.yml

@@ -1,4 +1,4 @@
-name: fern-check
+name: docs-check
 
 on:
   pull_request:
@@ -7,14 +7,23 @@ on:
       - main
 
 jobs:
-  run:
+  verify:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Install Fern CLI tool
-        run: npm install -g fern-api
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
 
-      - name: Check API is valid
-        run: fern check
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run docs checks
+        run: npm run check
+
+      - name: Run smoke tests
+        run: npm run test:smoke

.gitignore

@@ -3,10 +3,12 @@
 
 # Production
 /build
+/dist
 
 # Generated files
 .docusaurus
 .cache-loader
+.astro
 
 # Misc
 .DS_Store

README.md

@@ -12,18 +12,43 @@ This documentation is written and maintained by [Promptless](https://promptless.
 
 ### Prerequisites
 
-- Node.js 18 or higher
-- Fern CLI installed globally:
-  ```bash
-  npm install -g fern-api
-  ```
+- Node.js 20 or higher
+- npm 10 or higher
 
 ### Local Development
 
 From the repository root, run:
 
 ```bash
-fern docs dev
+npm install
+npm run migrate
+npm run dev
 ```
 
-This starts a local server at `http://localhost:3000` with hot-reloading as you edit markdown and configuration files.
+This starts Astro/Starlight at `http://localhost:4321` with hot-reloading.
+
+### Useful Commands
+
+```bash
+npm run migrate:dry      # route/content migration dry run
+npm run migrate          # regenerate manifests, redirects, and content
+npm run validate:links   # internal link validation against route + redirect manifests
+npm run check:route-parity
+npm run check            # typecheck + build + link validation + parity check
+```
+
+### Free Tools Local Env
+
+The Broken Link Report form reads these optional public env vars at build/dev time:
+
+```bash
+PUBLIC_FREE_TOOLS_API_BASE_URL=http://127.0.0.1:5000
+PUBLIC_TURNSTILE_SITE_KEY=your_turnstile_site_key
+```
+
+If `PUBLIC_FREE_TOOLS_API_BASE_URL` is unset, local dev defaults to `http://127.0.0.1:5000` and production defaults to `https://api.gopromptless.ai`.
+
+### Deployment
+
+- Production and preview deployments are handled by Vercel Git integration.
+- Redirects are generated into `vercel.json` by the migration script.

astro.config.mjs

@@ -0,0 +1,71 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import react from '@astrojs/react';
+
+import generatedSidebar from './src/lib/generated/sidebar.json' with { type: 'json' };
+import redirectsManifest from './migration/redirects.generated.json' with { type: 'json' };
+
+const redirectEntries = (redirectsManifest.redirects || []).map((rule) => [rule.source, rule.destination]);
+
+const redirects = {
+  '/home': '/',
+  '/docs': '/docs/getting-started/welcome',
+  '/site': '/demo',
+  '/site/demo': '/demo',
+  '/video-demo': '/demo',
+  '/use-cases': '/',
+  '/faq': '/',
+  '/api-reference': '/',
+  '/blog/all': '/blog',
+  '/changelog/all': '/changelog',
+  ...Object.fromEntries(redirectEntries),
+};
+
+export default defineConfig({
+  site: process.env.SITE_URL || 'https://docs.gopromptless.ai',
+  redirects,
+  image: {
+    service: {
+      entrypoint: 'astro/assets/services/noop',
+    },
+  },
+  integrations: [
+    react(),
+    starlight({
+      title: 'Promptless | Documentation',
+      description: 'Automated docs that eliminate manual overhead and keep your docs current with your codebase',
+      logo: {
+        src: './fern/docs/assets/logo.svg',
+        dark: './fern/docs/assets/logo_darkbg.svg',
+        alt: 'Promptless',
+        replacesTitle: true,
+      },
+      favicon: '/favicon.ico',
+      customCss: ['./src/styles/custom.css', './src/styles/site.css'],
+      sidebar: generatedSidebar,
+      components: {
+        Header: './src/components/starlight/Header.astro',
+        SiteTitle: './src/components/starlight/SiteTitle.astro',
+        PageTitle: './src/components/starlight/PageTitle.astro',
+        Footer: './src/components/starlight/Footer.astro',
+        ThemeProvider: './src/components/starlight/ThemeProviderLightOnly.astro',
+        MobileMenuFooter: './src/components/starlight/MobileMenuFooter.astro',
+      },
+      titleDelimiter: '|',
+      markdown: {
+        processedDirs: ['./src/content/blog', './src/content/changelog', './src/content/website'],
+      },
+      editLink: {
+        baseUrl: 'https://github.com/Promptless/docs/tree/main',
+      },
+    }),
+  ],
+  vite: {
+    resolve: {
+      alias: {
+        '@components': '/src/components',
+        '@lib': '/src/lib',
+      },
+    },
+  },
+});