Initialize repository with harness code and assets

Initial import of all source code, config, and README assets: the
packages workspace (cli, core, server, web, docs, landing, skills),
build scripts, tooling config, and CI workflows.

Includes the data-layout revision made on this branch: the local data
root defaults to ~/.penguin/data (PENGUIN_HOME still overrides; the
installer keeps its binaries in ~/.penguin), and every Agent lives
under <project>/agents/<agent>/ — path helpers, the three
agent-enumeration scans, the system prompt, built-in Skills, tests
and docs all follow the new layout.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018ihk8iQuo3kv2aPjAYEPuR

packages/docs/src/state/locale.tsx

@@ -0,0 +1,114 @@
+/**
+ * Language context: zh / en / system (tracks navigator.language). On switch it first
+ * synchronously calls setActiveStrings, then remounts the tree keyed on locale so every
+ * `S.x` read reflects the new language; the preference persists to localStorage.
+ * Same pattern as the landing page, under the docs site's own storage key.
+ */
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import type { ReactNode } from "react";
+import { setActiveStrings, zh } from "../lib/strings";
+import { en } from "../lib/strings-en";
+
+export type LangPref = "zh" | "en" | "system";
+export type Locale = "zh" | "en";
+
+const STORAGE_KEY = "penguin-docs.lang";
+
+interface LocaleContextValue {
+  lang: LangPref;
+  locale: Locale;
+  setLang: (lang: LangPref) => void;
+}
+
+const LocaleContext = createContext<LocaleContextValue | null>(null);
+
+/** Device language -> UI language: zh* -> zh, anything else -> en. */
+export function resolveSystemLocale(language: string | undefined): Locale {
+  return language?.toLowerCase().startsWith("zh") ? "zh" : "en";
+}
+
+function systemLocale(): Locale {
+  return resolveSystemLocale(navigator.language);
+}
+
+function resolve(lang: LangPref): Locale {
+  return lang === "system" ? systemLocale() : lang;
+}
+
+function initialLang(): LangPref {
+  const stored = localStorage.getItem(STORAGE_KEY);
+  if (stored === "zh" || stored === "en" || stored === "system") return stored;
+  return "system";
+}
+
+export function LocaleProvider({ children }: { children: ReactNode }) {
+  const [lang, setLangState] = useState<LangPref>(initialLang);
+  const [, setSysTick] = useState(0);
+
+  const locale = resolve(lang);
+  // Switch the active dictionary during render (idempotent): children are keyed on
+  // locale and render after this component, so they read the post-switch dictionary.
+  setActiveStrings(locale === "en" ? en : zh);
+
+  // Keep the document language in sync (static index.html ships lang="en").
+  useEffect(() => {
+    document.documentElement.lang = locale === "zh" ? "zh-CN" : "en";
+  }, [locale]);
+
+  useEffect(() => {
+    if (lang !== "system") return;
+    const onChange = () => setSysTick((t) => t + 1);
+    window.addEventListener("languagechange", onChange);
+    return () => window.removeEventListener("languagechange", onChange);
+  }, [lang]);
+
+  const setLang = useCallback((next: LangPref) => {
+    localStorage.setItem(STORAGE_KEY, next);
+    setLangState(next);
+  }, []);
+
+  return (
+    <LocaleContext.Provider value={{ lang, locale, setLang }}>{children}</LocaleContext.Provider>
+  );
+}
+
+/**
+ * Language scope: a remount boundary keyed on locale. The remount briefly empties the
+ * DOM, which collapses the page height and clamps the scroll position to 0 — so the
+ * scroll offset is captured during the render that switches locale (old DOM still
+ * mounted) and restored right after the new tree lays out.
+ */
+export function LocaleScope({ children }: { children: ReactNode }) {
+  const { locale } = useLocale();
+  const prevLocale = useRef(locale);
+  const savedScroll = useRef<number | null>(null);
+  if (prevLocale.current !== locale) {
+    prevLocale.current = locale;
+    savedScroll.current = window.scrollY;
+  }
+  useLayoutEffect(() => {
+    if (savedScroll.current !== null) {
+      window.scrollTo({ top: savedScroll.current, behavior: "instant" });
+      savedScroll.current = null;
+    }
+  }, [locale]);
+  return (
+    <div key={locale} className="contents">
+      {children}
+    </div>
+  );
+}
+
+export function useLocale(): LocaleContextValue {
+  const ctx = useContext(LocaleContext);
+  if (!ctx) throw new Error("useLocale must be used inside LocaleProvider");
+  return ctx;
+}

packages/docs/src/state/theme.tsx

@@ -0,0 +1,64 @@
+/**
+ * Theme context: light / dark / system (tracks prefers-color-scheme live), toggled
+ * via the html.dark class + Tailwind dark: variant, persisted to localStorage.
+ * Same behavior as the landing page, under the docs site's own storage key
+ * (index.html pre-applies the stored value before first paint).
+ */
+import { createContext, useCallback, useContext, useEffect, useState } from "react";
+import type { ReactNode } from "react";
+
+export type ThemeMode = "light" | "dark" | "system";
+
+const MODE_KEY = "penguin-docs.theme";
+
+interface ThemeContextValue {
+  mode: ThemeMode;
+  /** Resolved effective theme (system mode resolved against the OS preference). */
+  dark: boolean;
+  setMode: (mode: ThemeMode) => void;
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+function initialMode(): ThemeMode {
+  const stored = localStorage.getItem(MODE_KEY);
+  if (stored === "light" || stored === "dark" || stored === "system") return stored;
+  return "system";
+}
+
+function systemDark(): boolean {
+  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [mode, setModeState] = useState<ThemeMode>(initialMode);
+  const [sysDark, setSysDark] = useState(systemDark);
+
+  const dark = mode === "system" ? sysDark : mode === "dark";
+
+  useEffect(() => {
+    document.documentElement.classList.toggle("dark", dark);
+  }, [dark]);
+
+  useEffect(() => {
+    if (mode !== "system") return;
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const onChange = (e: MediaQueryListEvent) => setSysDark(e.matches);
+    setSysDark(mq.matches);
+    mq.addEventListener("change", onChange);
+    return () => mq.removeEventListener("change", onChange);
+  }, [mode]);
+
+  const setMode = useCallback((next: ThemeMode) => {
+    localStorage.setItem(MODE_KEY, next);
+    setModeState(next);
+  }, []);
+
+  return <ThemeContext.Provider value={{ mode, dark, setMode }}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) throw new Error("useTheme must be used inside ThemeProvider");
+  return ctx;
+}