(v1) Terminal-forward homepage redesign with nautical motif

.changeset/align-missing-schema-host-hints.md

@@ -0,0 +1,9 @@
+---
+"@arkenv/vite-plugin": patch
+"@arkenv/nextjs": patch
+"@arkenv/nuxt": patch
+---
+
+#### Align missing-schema errors with short, actionable host guidance
+
+Point missing-schema errors at checked paths / `schemaPath` and `arkenv init`, matching the Bun plugin style, without embedding starter `env.ts` modules.

.changeset/align-v1-shared-missing-schema-errors.md

@@ -0,0 +1,17 @@
+---
+"@arkenv/build": patch
+"@arkenv/bun-plugin": patch
+"@arkenv/vite-plugin": patch
+"@arkenv/nextjs": patch
+"@arkenv/nuxt": patch
+---
+
+#### Make missing-schema errors short and actionable across hosts
+
+When a host cannot find an env schema, throw a consistent message that names the expected path / `schemaPath` and points to `npx arkenv@latest init`, without embedding a starter `env.ts` module.
+
+Example:
+
+```text
+[ArkEnv] Could not find schema file at src/env.ts or env.ts. Please specify 'schemaPath' in ArkEnv options (or run `npx arkenv@latest init`).
+```

.changeset/optional-strict-shared-v1.md

@@ -0,0 +1,18 @@
+---
+"@arkenv/build": patch
+"@arkenv/nextjs": patch
+"@arkenv/nuxt": patch
+---
+
+#### Make `env/internal/shared.ts` optional in strict layout
+
+Strict layout now works with just `client.ts` and `server.ts`. Omit `internal/shared.ts` when you have nothing to share — shared keys are treated as empty.
+
+```ts
+// env/client.ts + env/server.ts alone is enough
+export default withArkEnv(nextConfig, {
+  layout: "strict",
+});
+```
+
+The CLI still scaffolds `shared.ts` by default for convenience.

.changeset/pre.json

@@ -1,62 +1,66 @@
 {
-  "mode": "pre",
-  "tag": "alpha",
-  "initialVersions": {
-    "arkenv-cli-playground": "0.0.0",
-    "bun-react-playground": "0.1.0",
-    "vite-playground": "0.0.0",
-    "vite-legacy-playground": "0.0.0",
-    "@repo/playwright-www": "0.0.0",
-    "www": "0.0.0",
-    "arkenv": "0.11.1",
-    "@arkenv/bun-plugin": "0.1.7",
-    "@arkenv/cli": "0.2.10",
-    "@arkenv/fumadocs-ui": "0.0.8",
-    "@repo/scope": "0.1.3",
-    "@repo/types": "0.1.0",
-    "@arkenv/nextjs": "0.0.7",
-    "@arkenv/vite-plugin": "0.1.1",
-    "@arkenv/build": "0.0.1",
-    "@arkenv/nuxt": "0.0.1",
-    "@arkenv/core": "1.0.0-alpha.2",
-    "@repo/utils": "0.1.3",
-    "@arkenv/standard": "1.0.0-alpha.2",
-    "@repo/log": "0.0.1"
-  },
-  "changesets": [
-    "add-host-preset-add-command",
-    "add-host-presets-phase-4",
-    "add-host-strict-layouts-forward-port",
-    "align-missing-schema-throw",
-    "bun-env-module-transform",
-    "drop-example-e-alias",
-    "epg3nspi",
-    "fix-nuxt-proxy-coercion",
-    "forward-port-hosting-presets",
-    "forward-port-keywords-typetable",
-    "host-preset-alias",
-    "improve-npm-keywords",
-    "init-v1",
-    "injectable-logger-api",
-    "machine-actionable-error-codes",
-    "nuxt-augment-config-key",
-    "nuxt-boot-gate-thin-accessors",
-    "nuxt-flat-layout-cli-alignment",
-    "nuxt-module-options-jsdoc-v1",
-    "nuxt-skip-setup-before-boot-gate",
-    "nuxt-strict-auto-extend",
-    "nuxt-strict-client-shared-auto-extend",
-    "reconcile-v0-features",
-    "remove-framework-shared-exports",
-    "rename-create-env-to-arkenv",
-    "standard-isolation-guards",
-    "standard-mode-flat-layout",
-    "standard-mode-packaging",
-    "trim-short-flag-aliases",
-    "unified-error-normalization",
-    "unify-coercion",
-    "valibot-example-registry",
-    "vite-env-module-transform",
-    "walk-back-env-starters"
-  ]
+	"mode": "pre",
+	"tag": "alpha",
+	"initialVersions": {
+		"arkenv-cli-playground": "0.0.0",
+		"bun-react-playground": "0.1.0",
+		"vite-playground": "0.0.0",
+		"vite-legacy-playground": "0.0.0",
+		"@repo/playwright-www": "0.0.0",
+		"www": "0.0.0",
+		"arkenv": "0.11.1",
+		"@arkenv/bun-plugin": "0.1.7",
+		"@arkenv/cli": "0.2.10",
+		"@arkenv/fumadocs-ui": "0.0.8",
+		"@repo/scope": "0.1.3",
+		"@repo/types": "0.1.0",
+		"@arkenv/nextjs": "0.0.7",
+		"@arkenv/vite-plugin": "0.1.1",
+		"@arkenv/build": "0.0.1",
+		"@arkenv/nuxt": "0.0.1",
+		"@arkenv/core": "1.0.0-alpha.2",
+		"@repo/utils": "0.1.3",
+		"@arkenv/standard": "1.0.0-alpha.2",
+		"@repo/log": "0.0.1"
+	},
+	"changesets": [
+		"add-host-preset-add-command",
+		"add-host-presets-phase-4",
+		"add-host-strict-layouts-forward-port",
+		"align-missing-schema-host-hints",
+		"align-missing-schema-throw",
+		"align-v1-shared-missing-schema-errors",
+		"bun-env-module-transform",
+		"drop-example-e-alias",
+		"epg3nspi",
+		"fix-nuxt-proxy-coercion",
+		"forward-port-hosting-presets",
+		"forward-port-keywords-typetable",
+		"host-preset-alias",
+		"improve-npm-keywords",
+		"init-v1",
+		"injectable-logger-api",
+		"machine-actionable-error-codes",
+		"nuxt-augment-config-key",
+		"nuxt-boot-gate-thin-accessors",
+		"nuxt-flat-layout-cli-alignment",
+		"nuxt-module-options-jsdoc-v1",
+		"nuxt-skip-setup-before-boot-gate",
+		"nuxt-strict-auto-extend",
+		"nuxt-strict-client-shared-auto-extend",
+		"optional-strict-shared-v1",
+		"reconcile-v0-features",
+		"remove-framework-shared-exports",
+		"rename-create-env-to-arkenv",
+		"split-help-global-init-options",
+		"standard-isolation-guards",
+		"standard-mode-flat-layout",
+		"standard-mode-packaging",
+		"trim-short-flag-aliases",
+		"unified-error-normalization",
+		"unify-coercion",
+		"valibot-example-registry",
+		"vite-env-module-transform",
+		"walk-back-env-starters"
+	]
 }

.changeset/split-help-global-init-options.md

@@ -0,0 +1,30 @@
+---
+"arkenv": patch
+---
+
+#### Split `--help` options into Global and `init` sections
+
+List shared flags under **Global options** and scaffolding flags under **init options**, matching the multi-command `/docs/cli` taxonomy.
+
+```bash
+npx arkenv@alpha --help
+```
+
+```text
+Usage:
+  arkenv init [project-name]    ...
+  arkenv add host [provider]    ...
+
+Global options:
+  --yes, -y      Skip prompts and use defaults ...
+  --quiet, -q    Quiet mode ...
+  --json, -j     Output structured JSON ...
+  --agent        Enable non-interactive, machine-readable mode ...
+  --help, -h     Show this help message
+
+init options:
+  --example                     Specify an example name ...
+  --force, -f                   Bypass checks and force scaffolding
+  --no-codegen                  Disable automatic env.gen.ts code generation ...
+  --host-preset, -H <preset>    Specify a hosting provider preset ...
+```

.github/workflows/deploy-www-manual.yml

@@ -0,0 +1,111 @@
+name: Deploy www (manual SHA)
+
+# Maintainer escape hatch: deploy any commit to a stable www URL without
+# pushing that commit to the target branch. Requires write access to run.
+on:
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: Full commit SHA to build and deploy
+        required: true
+        type: string
+      target:
+        description: Stable URL to update
+        required: true
+        type: choice
+        options:
+          - arkenv-dev.vercel.app
+          - arkenv-v1.vercel.app
+          - arkenv.js.org
+
+concurrency:
+  group: deploy-www-manual-${{ inputs.target }}
+  cancel-in-progress: true
+
+jobs:
+  Deploy-Manual:
+    runs-on: ubuntu-latest
+    env:
+      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+      VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+      TARGET: ${{ inputs.target }}
+      DEPLOY_SHA: ${{ inputs.sha }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.sha }}
+          fetch-depth: 0
+      - name: Resolve git metadata for the deployed commit
+        id: meta
+        run: |
+          set -euo pipefail
+          case "$TARGET" in
+            arkenv-dev.vercel.app) echo "git_ref=dev" >> "$GITHUB_OUTPUT" ;;
+            arkenv-v1.vercel.app) echo "git_ref=v1" >> "$GITHUB_OUTPUT" ;;
+            arkenv.js.org) echo "git_ref=main" >> "$GITHUB_OUTPUT" ;;
+            *)
+              echo "Unknown target: $TARGET" >&2
+              exit 1
+              ;;
+          esac
+          echo "short_msg=$(git log -1 --format=%s "$DEPLOY_SHA" | head -n1)" >> "$GITHUB_OUTPUT"
+          echo "author_name=$(git log -1 --format=%an "$DEPLOY_SHA")" >> "$GITHUB_OUTPUT"
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: lts/*
+          cache: pnpm
+      - name: Install dependencies
+        run: pnpm install
+      - name: Install Vercel CLI
+        # Pin the CLI to avoid upstream breakage from newly published majors.
+        run: npm install --global vercel@54.7.1
+      - name: Pull Vercel Environment Information
+        run: |
+          if [ "$TARGET" = "arkenv.js.org" ]; then
+            node scripts/vercel-wrapper.cjs pull --yes --environment=production --token="$VERCEL_TOKEN"
+          else
+            node scripts/vercel-wrapper.cjs pull --yes --environment=preview --token="$VERCEL_TOKEN"
+          fi
+      - name: Build Project Artifacts
+        run: |
+          if [ "$TARGET" = "arkenv.js.org" ]; then
+            node scripts/vercel-wrapper.cjs build --prod --token="$VERCEL_TOKEN"
+          else
+            node scripts/vercel-wrapper.cjs build --token="$VERCEL_TOKEN"
+          fi
+      - name: Deploy and attach to stable URL
+        env:
+          GIT_ORG: ${{ github.repository_owner }}
+          GIT_REPO: ${{ github.event.repository.name }}
+          GIT_REF: ${{ steps.meta.outputs.git_ref }}
+          GIT_SHA: ${{ inputs.sha }}
+          GIT_COMMIT_MESSAGE: ${{ steps.meta.outputs.short_msg }}
+          GIT_COMMIT_AUTHOR_NAME: ${{ steps.meta.outputs.author_name }}
+          GIT_COMMIT_AUTHOR_LOGIN: ${{ github.actor }}
+        run: |
+          set -o pipefail
+          META_ARGS=(
+            -m githubDeployment=1
+            -m githubOrg="$GIT_ORG"
+            -m githubRepo="$GIT_REPO"
+            -m githubCommitOrg="$GIT_ORG"
+            -m githubCommitRepo="$GIT_REPO"
+            -m githubCommitRef="$GIT_REF"
+            -m githubCommitSha="$GIT_SHA"
+            -m githubCommitMessage="$GIT_COMMIT_MESSAGE"
+            -m githubCommitAuthorName="$GIT_COMMIT_AUTHOR_NAME"
+            -m githubCommitAuthorLogin="$GIT_COMMIT_AUTHOR_LOGIN"
+          )
+          if [ "$TARGET" = "arkenv.js.org" ]; then
+            node scripts/vercel-wrapper.cjs deploy --prebuilt --prod --archive=tgz --token="$VERCEL_TOKEN" "${META_ARGS[@]}"
+            echo "Deployed $GIT_SHA to production (arkenv.js.org)."
+          else
+            DEPLOYMENT_URL=$(node scripts/vercel-wrapper.cjs deploy --prebuilt --archive=tgz --token="$VERCEL_TOKEN" "${META_ARGS[@]}" | tail -n 1)
+            echo "Deployment URL: $DEPLOYMENT_URL"
+            echo "Aliasing $DEPLOYMENT_URL -> $TARGET"
+            node scripts/vercel-wrapper.cjs alias set "$DEPLOYMENT_URL" "$TARGET" --token="$VERCEL_TOKEN"
+          fi

.github/workflows/deploy-www.yml

@@ -42,4 +42,28 @@ jobs:
       - name: Build Project Artifacts
         run: node scripts/vercel-wrapper.cjs build --prod --token=${{ secrets.VERCEL_TOKEN }}
       - name: Deploy Project Artifacts to Vercel
-        run: node scripts/vercel-wrapper.cjs deploy --prebuilt --prod --archive=tgz --token=${{ secrets.VERCEL_TOKEN }}
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          GIT_ORG: ${{ github.repository_owner }}
+          GIT_REPO: ${{ github.event.repository.name }}
+          GIT_REF: ${{ github.ref_name }}
+          GIT_SHA: ${{ github.sha }}
+          GIT_ACTOR: ${{ github.actor }}
+          GIT_COMMIT_MESSAGE: ${{ github.event.head_commit.message || github.sha }}
+          GIT_COMMIT_AUTHOR_NAME: ${{ github.event.head_commit.author.name || github.actor }}
+        run: |
+          set -o pipefail
+          SHORT_MSG="$(printf '%s\n' "$GIT_COMMIT_MESSAGE" | head -n1)"
+          # --prod already assigns production domains (arkenv.js.org / arkenv.vercel.app).
+          # Git meta keeps the deployment linked to main in the Vercel dashboard.
+          node scripts/vercel-wrapper.cjs deploy --prebuilt --prod --archive=tgz --token="$VERCEL_TOKEN" \
+            -m githubDeployment=1 \
+            -m githubOrg="$GIT_ORG" \
+            -m githubRepo="$GIT_REPO" \
+            -m githubCommitOrg="$GIT_ORG" \
+            -m githubCommitRepo="$GIT_REPO" \
+            -m githubCommitRef="$GIT_REF" \
+            -m githubCommitSha="$GIT_SHA" \
+            -m githubCommitMessage="$SHORT_MSG" \
+            -m githubCommitAuthorName="$GIT_COMMIT_AUTHOR_NAME" \
+            -m githubCommitAuthorLogin="$GIT_ACTOR"

.github/workflows/preview-www-default.yml

@@ -1,7 +1,9 @@
 name: Preview www (Default Events)
 
 on:
-  pull_request:
+  # pull_request_target so fork PRs receive repository secrets (VERCEL_*).
+  # Workflow YAML is taken from the base branch; we checkout PR HEAD in the reusable job.
+  pull_request_target:
     types: [opened, synchronize, ready_for_review]
     branches:
       - dev
@@ -19,6 +21,7 @@ jobs:
   Deploy-Preview:
     # Branch previews (push to dev/v1) always deploy. PR previews are opt-in:
     # they only deploy when the PR carries the `preview` label, regardless of draft state.
+    # Fork authors cannot apply labels (triage+ required), so this is not self-serve spamable.
     if: github.event_name == 'push' || contains(github.event.pull_request.labels.*.name, 'preview')
     uses: ./.github/workflows/preview-www-reusable.yml
     secrets: inherit

.github/workflows/preview-www-labeled.yml

@@ -1,7 +1,8 @@
 name: Preview www (Label Triggered)
 
 on:
-  pull_request:
+  # pull_request_target so fork PRs receive repository secrets when a maintainer applies `preview`.
+  pull_request_target:
     types: [labeled]
     branches:
       - dev