Clean up ArkEnv introduction

apps/www/content/docs/arkenv/index.mdx

@@ -1,24 +1,79 @@
 ---
-title: What is ArkEnv
-icon: CircleQuestionMark
+title: What is ArkEnv?
+description: Introducing ArkEnv, an environment variable validator that stays out of your way.
 ---
 
 import { BookOpen, Rocket, Globe } from "lucide-react";
 import { SiGithub as GitHub } from "@icons-pack/react-simple-icons";
 
-<include cwd>../../packages/arkenv/README.md#introduction</include>
+At its core, ArkEnv is a single export that creates a ready-to-use, typesafe environment variable object:
+
+```ts twoslash
+import arkenv from "arkenv";
+
+const env = arkenv({
+  HOST: "string.ip | 'localhost'",
+  PORT: "0 <= number.integer <= 65535",
+  NODE_ENV: "'development' | 'production' | 'test' = 'development'",
+  DEBUGGING: "boolean = false",
+});
+
+// Hover to see ✨exact✨ types
+const host = env.HOST;
+const port = env.PORT;
+const nodeEnv = env.NODE_ENV;
+const debugging = env.DEBUGGING;
+```
+
+> ArkEnv defaults to [ArkType](https://arktype.io/) notation, the closest match to TypeScript syntax for editor-to-runtime typesafety. You can also use any [Standard Schema](https://standardschema.dev/schema) validator, including Zod, Valibot, and Typia.
+
+We consider the resulting `env` object "typesafe from editor to runtime": at every step in the app's lifecycle, you are getting a guarantee about your environment variables.
+
+### Editor
+
+ArkEnv tells TypeScript about the shape of your environment variables, so you can use the types your schema defines without additional checks or manual type-casts. Your editor will also autocomplete your schema and provide type hints, whether you're using [ArkType](https://arktype.io/), Zod, Valibot, or any other Standard Schema validator. If you're using [ArkType](https://arktype.io/), you can take this a step further with [syntax highlighting and inline errors](docs/arkenv/integrations/vscode). This way, writing your schema feels like writing TypeScript.
+
+### Build time
+
+Wherever possible, ArkEnv is designed to run during your build process. We provide a toolkit for doing so with [Bun's bundler](http://arkenv.js.org/docs/bun-plugin) and [Vite](http://arkenv.js.org/docs/vite-plugin). This way, your app will fail fast if any environment variables are incorrect or missing.
+
+### Runtime
+
+With ArkEnv, your environment variables are **guaranteed to match your schema** at runtime. If any variable is incorrect or missing, the app won't start and a clear error will be thrown:
+
+```bash title="Terminal"
+❯ PORT=hello npm start
+
+ArkEnvError: Errors found while validating environment variables
+  HOST must be a string or "localhost" (was missing)
+  PORT must be a number (was a string)
+```
+
 <include cwd>../../packages/arkenv/README.md#features</include>
 
-## The ArkEnv icon 
+## Philosophy
+
+### Build from the core up
+
+Some environment variable validators were built around a specific framework and its conventions.
+ArkEnv, instead, is designed to "just work" even within a simple Node.js server, with no configuration required. This core is where ArkEnv started, and it's what we continue to test and optimize today.
+
+We layer framework integrations as optional modules (which we call "plugins") on top of this core to provide a convenient experience for your app's development. Using these integrations in modern JavaScript toolkits should feel just as simple as using the core library within a simple Node.js server.
+
+### Fail fast
+
+ArkEnv is built to protect your app from runtime errors as early as possible. This means that as soon as we know what the actual values are, we'll fail your app if they don't match your schema. When environment variables eventually reach runtime, you can be sure they're valid.
 
-<img src="/assets/icon.svg" alt="ArkEnv icon" width="128" height="128"/>
+### Sane defaults
 
-The ArkEnv icon tells the story of what we're building. It weaves together three distinct symbols:
+ArkEnv makes a few opinionated assumptions about your workflow: 
 
-- **A gear**: At first glance, it's a settings gear, representing the core mechanical purpose of the library: precise environment configuration.
-- **A ship's wheel**: Look closer, and it's a ship's wheel. This honors the Ark motif, symbolizing the freedom to explore and build, steered by reliable technology.
-- **A lighthouse**: It is also the Japanese map symbol for a lighthouse. Just as a lighthouse warns sailors of danger, ArkEnv's typesafety guides your apps away from the rocky shores of runtime errors.
+* Environment variables come from `process.env` (or `import.meta.env` in Vite)
+* They start as strings but should become the types defined in your schema
+* Your framework already loads `.env` files
+* You're using a modern, Standard Schema-compliant validator
 
+These defaults keep ArkEnv dead simple. If your workflow is different, you can opt out of features like type coercion, customize the env source, or extend behavior with plugins.
 
 ## Next steps
 

apps/www/content/docs/arkenv/meta.json

@@ -5,7 +5,7 @@
 	"icon": "Box",
 	"pages": [
 		"---Introduction---",
-		"index",
+		"[CircleQuestionMark][What is ArkEnv](/docs/arkenv)",
 		"comparison",
 		"quickstart",
 		"examples",

packages/arkenv/README.md

@@ -33,10 +33,9 @@
 
 ## Introduction
 
-ArkEnv is an environment variable validator for modern JavaScript runtimes. 
-It lets you create a ready-to-use, typesafe environment variable object:
+ArkEnv is an environment variable validator for modern JavaScript runtimes. It creates a ready-to-use, typesafe environment variable object:
 
-```ts twoslash
+```ts
 import arkenv from "arkenv";
 
 const env = arkenv({
@@ -45,15 +44,9 @@ const env = arkenv({
   NODE_ENV: "'development' | 'production' | 'test' = 'development'",
   DEBUGGING: "boolean = false",
 });
-
-// Hover to see ✨exact✨ types
-const host = env.HOST;
-const port = env.PORT;
-const nodeEnv = env.NODE_ENV;
-const debugging = env.DEBUGGING;
 ```
 
-> ArkEnv supports native [ArkType](https://arktype.io/) notation and any [Standard Schema](https://standardschema.dev/schema) validator: Zod, Valibot, Typia, etc.
+> ArkEnv defaults to [ArkType](https://arktype.io/) notation, the closest match to TypeScript syntax for editor-to-runtime typesafety. You can also use any [Standard Schema](https://standardschema.dev/schema) validator, including Zod, Valibot, and Typia.
 
 With ArkEnv, your environment variables are **guaranteed to match your schema**. If any variable is incorrect or missing, the app won't start and a clear error will be thrown:
 
@@ -77,7 +70,6 @@ ArkEnvError: Errors found while validating environment variables
 * Compatible with any Standard Schema validator (Zod, Valibot, etc.)
 * Native support for ArkType, TypeScript’s 1:1 validator
 
-
 > See how ArkEnv compares to alternatives like T3 Env, znv, and envalid in the [comparison cheatsheet](https://arkenv.js.org/docs/arkenv/comparison#comparison-cheatsheet).
 
 ## Installation

tooling/playwright-www/tests/a11y.test.ts

@@ -71,7 +71,7 @@ test.describe("A11y Smoke Tests", () => {
 	test("should have proper page titles on all top routes", async ({ page }) => {
 		const expectedTitles: Record<string, string> = {
 			"/": "ArkEnv",
-			"/docs/arkenv": "What is ArkEnv · ArkEnv",
+			"/docs/arkenv": "What is ArkEnv? · ArkEnv",
 			"/docs/arkenv/quickstart": "Quickstart · ArkEnv",
 		};