From f84e2792836c7c72ccaf7ede6d7d774b0f25c77e Mon Sep 17 00:00:00 2001
From: Nathan Flurry <git@nathanflurry.com>
Date: Sat, 18 Jul 2026 17:15:31 -0700
Subject: [PATCH] chore(website): add dev-website justfile recipes for the docs
 site

---
 justfile | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 76 insertions(+), 4 deletions(-)

diff --git a/justfile b/justfile
index f8ecd22034..f75cf6a8b9 100644
--- a/justfile
+++ b/justfile
@@ -144,12 +144,84 @@ shell *args:
 		NODE_OPTIONS="--no-deprecation ${NODE_OPTIONS:-}" \
 		pnpm --filter @rivet-dev/agentos-shell exec tsx src/main.ts "$@"
 
-# Run the agentos-sdk.dev site (landing + /docs) locally with hot reload
-docs:
+# --- agentos-sdk.dev docs site (landing + /docs) ---
+# The site (packages under website/) depends on the private @rivet-dev/docs-theme
+# and @rivet-gg/icons, which are NOT committed here. `dev-website-setup` vendors
+# the theme from a sibling workspace, builds it, and links the site into the
+# pnpm workspace. Then `dev-website` (or `dev-website-start`) serves it with hot
+# reload. Building the icon set needs a Font Awesome Pro token exported as
+# FONTAWESOME_PACKAGE_TOKEN (e.g. `source ~/misc/env.txt` first).
+
+# Vendor + build the docs theme and link the site into the workspace (idempotent).
+dev-website-setup:
+	#!/usr/bin/env bash
+	set -euo pipefail
+	theme="website/vendor/theme"
+	icons="$theme/vendor/icons"
+	built=0
+
+	# 1. Vendor the private docs theme from a sibling workspace if absent.
+	if [ ! -f "$theme/package.json" ]; then
+		src=""
+		for d in ../*/website/vendor/theme; do
+			[ -f "$d/package.json" ] || continue
+			v="$(node -p "require('$d/package.json').version" 2>/dev/null)" || continue
+			case "$v" in *stub*) continue;; esac
+			src="$d"; break
+		done
+		[ -n "$src" ] || { echo "error: no sibling docs-theme found under ../*/website/vendor/theme" >&2; exit 1; }
+		echo "vendoring docs-theme from $src"
+		mkdir -p website/vendor
+		cp -R "$src" "$theme"
+	fi
+
+	# 2. Include the site + theme in the pnpm workspace (local-only; do not commit).
+	if grep -qE '^[[:space:]]*# - website(/|$)' pnpm-workspace.yaml; then
+		sed -i '/^[[:space:]]*# - website\(\/\|$\)/ s/# - /- /' pnpm-workspace.yaml
+		echo "enabled website workspace globs in pnpm-workspace.yaml (local-only)"
+	fi
+
+	# 3. Install so workspace links + build deps (esbuild) exist.
+	pnpm install --lockfile=false
+
+	# 4. Build the theme's config-time modules (dist/) if missing.
+	if [ ! -f "$theme/dist/mdx/remark.js" ]; then
+		pnpm --filter @rivet-dev/docs-theme build
+		built=1
+	fi
+
+	# 5. Build the icon set (dist/). Requires a Font Awesome Pro token.
+	if [ ! -f "$icons/dist/index.js" ]; then
+		if [ -z "${FONTAWESOME_PACKAGE_TOKEN:-}" ]; then
+			echo "error: FONTAWESOME_PACKAGE_TOKEN is required to build @rivet-gg/icons." >&2
+			echo "       export it (e.g. 'source ~/misc/env.txt') and re-run." >&2
+			exit 1
+		fi
+		pnpm --filter @rivet-gg/icons generate
+		built=1
+	fi
+
+	# 6. Re-sync the pnpm store with freshly built dist/ (file: deps are copied in).
+	if [ "$built" = 1 ]; then
+		pnpm install --lockfile=false
+	fi
+
+	# A workspace-wide install can leave website/node_modules partially linked
+	# after generated theme packages are rebuilt. Refresh the site package last
+	# so Astro renderers and the newly generated icon files resolve immediately.
+	pnpm --dir website install --lockfile=false
+
+	echo "dev-website-setup: ready"
+
+# Start the docs site dev server with hot reload (run dev-website-setup first).
+dev-website-start:
 	pnpm --filter @rivet-dev/agentos-website dev
 
-# Build the agentos-sdk.dev site to website/dist
-docs-build:
+# Set up (if needed) and start the docs site dev server.
+dev-website: dev-website-setup dev-website-start
+
+# Set up (if needed) and build the agentos-sdk.dev site to website/dist.
+dev-website-build: dev-website-setup
 	pnpm --filter @rivet-dev/agentos-website build
 
 test-bounded cmd='pnpm test':