feat: expand documentation, improve SQS implementation details, and add installation-target hook

Author: michasdev

apps/web/www/app/components/shared/footer.tsx

@@ -1,8 +1,10 @@
 import mildstack from '@/assets/logos/mildstack-logo-full-white.png';
 import { Download } from 'lucide-react';
+import { useInstallationTarget } from '@/hooks/use-installation-target';
 
 export function Footer() {
     const year = new Date().getFullYear();
+    const { installationHref } = useInstallationTarget();
 
     const website = [
         {
@@ -63,7 +65,7 @@ export function Footer() {
                             ))}
                             <a
                                 className="hover:bg-accent rounded-md border p-1.5 flex flex-row items-center gap-2 text-sm font-light"
-                                href="/download"
+                                href={installationHref}
                             >
                                 <Download className="size-5" />
                                 Download App

apps/web/www/app/components/shared/navbar.tsx

@@ -3,6 +3,7 @@ import { motion, AnimatePresence, useScroll, useMotionValueEvent } from 'motion/
 import { Star, Download, Menu, X } from 'lucide-react';
 import { useLocation } from 'react-router';
 import { Button } from '@/components/ui/button';
+import { useInstallationTarget } from '@/hooks/use-installation-target';
 import { cn } from '@/lib/utils';
 import logoFullWhite from '../../assets/logos/mildstack-logo-full-white.png'
 
@@ -36,6 +37,7 @@ export const Navbar: React.FC = () => {
   const [activeSection, setActiveSection] = useState<string | null>('home');
   const { scrollY } = useScroll();
   const { pathname } = useLocation();
+  const { installationDocsRoute, installationHref } = useInstallationTarget();
 
   const handleSectionClick = (
     event: React.MouseEvent<HTMLAnchorElement>,
@@ -159,7 +161,8 @@ export const Navbar: React.FC = () => {
     </>
   );
 
-  const isDownloadActive = pathname === '/download';
+  const isDownloadActive =
+    pathname === '/download' || pathname === installationDocsRoute;
 
   const ActionButtons = ({ isMobile = false, closeMenu }: { isMobile?: boolean; closeMenu?: () => void }) => (
     <>
@@ -172,7 +175,7 @@ export const Navbar: React.FC = () => {
           isMobile ? 'px-8 h-12 text-lg w-full max-w-[280px] flex' : 'hidden md:flex h-9 px-4 text-sm hover:text-gray-300'
         )}
       >
-        <a href="/download" onClick={closeMenu}>
+        <a href={installationHref} onClick={closeMenu}>
           <Download className={isMobile ? 'size-5' : 'size-4'} />
           Download
         </a>

apps/web/www/app/features/home/components/call-to-action.tsx

@@ -1,7 +1,10 @@
 import { ArrowRightIcon, PlusIcon } from "lucide-react";
 import { Button } from "@/components/ui/button";
+import { useInstallationTarget } from "@/hooks/use-installation-target";
 
 export function CallToAction() {
+  const { installationHref } = useInstallationTarget();
+
   return (
     <div className="relative mx-auto flex w-full max-w-3xl flex-col justify-between gap-y-6 border-y bg-background bg-[radial-gradient(35%_80%_at_75%_0%,color-mix(in_oklab,var(--color-primary)_35%,var(--color-background)),transparent)] px-4 py-8">
       <PlusIcon
@@ -43,7 +46,7 @@ export function CallToAction() {
           </a>
         </Button>
         <Button asChild>
-          <a href="/download">
+          <a href={installationHref}>
             Download <ArrowRightIcon className="size-4 ml-1" />
           </a>
         </Button>

apps/web/www/app/features/home/sections/hero/hero.tsx

@@ -1,6 +1,7 @@
 import React, { useRef, useEffect, useState } from 'react';
 import { motion, type Variants } from 'motion/react';
 import { ChevronRight, Cpu, Timer, MemoryStick, PlugZap } from 'lucide-react';
+import { useInstallationTarget } from '@/hooks/use-installation-target';
 
 interface LightningProps {
     hue?: number;
@@ -254,6 +255,7 @@ const FeatureItem: React.FC<FeatureItemProps> = ({ name, value, position, icon }
 export const HeroSection: React.FC = () => {
     const lightningHue = 245;
     const [lightningXOffset, setLightningXOffset] = useState(0);
+    const { installationHref } = useInstallationTarget();
 
     useEffect(() => {
         const updateLightningOffset = () => {
@@ -304,7 +306,7 @@ export const HeroSection: React.FC = () => {
                     className="relative z-30 mx-auto flex min-h-[calc(100vh-7rem)] max-w-4xl flex-col items-center justify-center text-center md:min-h-0 md:mt-28"
                 >
                     <motion.a
-                        href="/download"
+                        href={installationHref}
                         variants={itemVariants}
                         whileHover={{ scale: 1.05 }}
                         whileTap={{ scale: 0.95 }}

apps/web/www/app/hooks/use-installation-target.ts

@@ -0,0 +1,39 @@
+import { useEffect, useState } from 'react';
+
+type PlatformFamily = 'macos' | 'windows' | 'linux' | 'unknown';
+
+const DOWNLOAD_ROUTE = '/download';
+const INSTALLATION_DOCS_ROUTE = '/docs/getting-started/installation';
+
+function detectPlatform(): PlatformFamily {
+  if (typeof navigator === 'undefined') return 'unknown';
+
+  const platform = navigator.platform.toLowerCase();
+  const userAgent = navigator.userAgent.toLowerCase();
+
+  if (platform.includes('mac') || userAgent.includes('mac os')) return 'macos';
+  if (platform.includes('win') || userAgent.includes('windows')) return 'windows';
+  if (platform.includes('linux') || userAgent.includes('linux')) return 'linux';
+
+  return 'unknown';
+}
+
+export function useInstallationTarget() {
+  const [platform, setPlatform] = useState<PlatformFamily>('unknown');
+
+  useEffect(() => {
+    setPlatform(detectPlatform());
+  }, []);
+
+  const installationHref =
+    platform === 'macos' ? INSTALLATION_DOCS_ROUTE : DOWNLOAD_ROUTE;
+
+  return {
+    downloadRoute: DOWNLOAD_ROUTE,
+    installationDocsRoute: INSTALLATION_DOCS_ROUTE,
+    installationHref,
+    isMacOS: platform === 'macos',
+    platform,
+  };
+}
+

apps/web/www/content/docs/getting-started/build-from-source.mdx

@@ -0,0 +1,66 @@
+---
+title: Build from Source
+description: |
+  Build MildStack from source for local development, contribution workflows, or custom packaging.
+---
+
+## When to Use This Guide
+
+Use this path when you want to compile MildStack directly from this repository for development, contribution workflows, or custom packaging.
+
+<Callout type="info" title="Standard users">
+  If you only need to run MildStack, use [Installation](/docs/getting-started/installation) instead.
+</Callout>
+
+## Prerequisites
+
+- Go `1.26.2` or later
+- Node.js and npm for the Desktop App build
+- Git
+
+## Clone the Repository
+
+```bash
+git clone https://github.com/michasdev/mildstack.git
+cd mildstack
+```
+
+## Build the CLI Binary
+
+From the repository root:
+
+```bash
+go build -o mildstack ./core/cmd/mildstack/main.go
+```
+
+Optional CLI smoke check:
+
+```bash
+./mildstack start --detach
+./mildstack instances
+./mildstack stop --all
+```
+
+## Build the Desktop App
+
+```bash
+cd apps/desktop
+npm install
+npm run build
+```
+
+## Build Desktop Installers (optional)
+
+From `apps/desktop`:
+
+```bash
+npm run build:mac
+# or
+npm run build:win
+# or
+npm run build:linux
+```
+
+## Back to Installation
+
+For standard installation paths, see [Installation](/docs/getting-started/installation).