v1

.agents/AGENTS.md

@@ -11,3 +11,23 @@ Custom vocabulary mapped to GitHub labels (e.g., `needs triage`, `needs more inf
 ### Domain docs
 
 Single-context layout with `CONTEXT.md` in the `docs/` directory. See `.agent/docs/domain.md`.
+
+### v1 Roadmap package migration rules
+
+For all work transitioning or porting features from the `v0` (dev) branch to the `v1` branch, follow these policies:
+
+1. **Changeset Translation Matrix (Dual-Tracking)**:
+   - When importing changesets from `v0` to `v1`, you must translate the package names in the YAML frontmatter:
+     - If the change is in the CLI/Scaffolding: `@arkenv/cli` (v0) ➔ `arkenv` (v1)
+     - If the change is in the Core Validation engine: `arkenv` (v0) ➔ `@arkenv/core` (v1)
+
+2. **Changelog Identity Swaps**:
+   - `packages/cli/CHANGELOG.md` maps to `packages/arkenv/CHANGELOG.md`.
+   - `packages/arkenv/CHANGELOG.md` (the old core) maps to `packages/core/CHANGELOG.md`.
+
+3. **Changelog Epoch Warnings (Right before v1.0.0 release)**:
+   - In `packages/arkenv/CHANGELOG.md`, prepend a prominent warning alerting users that `arkenv` is now the CLI, not the library.
+   - In `packages/core/CHANGELOG.md`, prepend a welcome header explaining that the core library has moved from `arkenv` to `@arkenv/core`.
+
+4. **CLI Import Restriction**:
+   - The `arkenv` CLI package (`packages/arkenv`) must throw a clear error at runtime if imported or required as a library (using `require.main !== module`) to prevent accidental usage by users upgrading from `v0`.

.agents/docs/CONTEXT.md

@@ -63,8 +63,8 @@ The main goal is to provide a developer-friendly way to validate and type-check
 
 **Naming Conventions:**
 
-- **Files**: kebab-case (`create-env.ts`)
-- **Functions**: camelCase (`createEnv`)
+- **Files**: kebab-case (`arkenv.ts`)
+- **Functions**: camelCase (`arkenvInternal`, `myFunction`)
 - **Types**: PascalCase (`ArkEnvError`)
 - **Constants**: UPPER_SNAKE_CASE for environment variables
 
@@ -83,9 +83,9 @@ The main goal is to provide a developer-friendly way to validate and type-check
 **Monorepo Structure:**
 
 - **Packages** (`packages/`) - Published npm packages
-  - `arkenv` - Core library package
+  - `@arkenv/core` - Core library package
   - `@arkenv/vite-plugin` - Vite plugin package
-  - `@arkenv/cli` - Interactive CLI for scaffolding and project mutation
+  - `arkenv` - Interactive CLI for scaffolding and project mutation
 - **Apps** (`apps/`) - Applications and testing suites (not published)
   - `www` - Next.js documentation site
   - `playgrounds/*` - Test playgrounds for different runtimes
@@ -95,7 +95,7 @@ The main goal is to provide a developer-friendly way to validate and type-check
 **Package Architecture:**
 
 - **Core Package** (`arkenv`):
-  - Main export: `createEnv` function (also exported as default `arkenv`)
+  - Main export: `arkenv` function (also exported as default export)
   - Uses ArkType's `scope` system for type validation
   - Custom types: `string.host`, `number.port`, `boolean`
   - Error handling via `ArkEnvError` class
@@ -200,7 +200,7 @@ pnpm run test:e2e                     # E2E tests
 - **Vite**: Integrated via `@arkenv/vite-plugin`. Validates environment variables at build-time and inlines `import.meta.env` variables for **client-side** (browser) usage.
 - **Next.js**: Integrated via `@arkenv/nextjs`. Provides two layout patterns:
   - **3-File Layout (Strict)**: Uses separate environment files for client, server, and shared scopes (`env/client.ts`, `env/server.ts`, and `env/internal/shared.ts`) for compile-time locking of secrets from browser bundles using package conditional exports (`react-server` vs. `default`) and `server-only`.
-  - **Unified 1-File Layout**: Uses a single `env.ts` schema file. In Next.js, client-side environment variables must be statically destructured in a `runtimeEnv` block to allow static inlining by the Next.js compiler. To automate this, `@arkenv/nextjs/config` exposes a `withArkEnv` wrapper for `next.config.js` that performs static analysis on `env.ts` to locate `client` and `shared` keys, then automatically generates a tailored `createEnv` factory in `generated/env.gen.ts` that pre-fills `runtimeEnv`. It enforces strict client-side prefixing (`NEXT_PUBLIC_`) and prevents server secrets from leaking to client components.
+  - **Unified 1-File Layout**: Uses a single `env.ts` schema file. In Next.js, client-side environment variables must be statically destructured in a `runtimeEnv` block to allow static inlining by the Next.js compiler. To automate this, `@arkenv/nextjs/config` exposes a `withArkEnv` wrapper for `next.config.js` that performs static analysis on `env.ts` to locate `client` and `shared` keys, then automatically generates a tailored `arkenv` factory in `generated/env.gen.ts` that pre-fills `runtimeEnv`. It enforces strict client-side prefixing (`NEXT_PUBLIC_`) and prevents server secrets from leaking to client components.
 - **Bun fullstack dev server**:
   - **Bun.serve**: An HTTP server runtime that integrates with Bun's built-in bundler to scan HTML files, trigger on-demand bundling, and serve resulting assets. It does not perform bundling itself; rather, it coordinates with Bun's bundler (configured via `@arkenv/bun-plugin` in `bunfig.toml`) to inline environment variables (e.g., using a `PUBLIC_` prefix) via static replacement. Primarily used for **client-side** bundling integration.
   - **Bun.build**: Bun's programmatic bundling API. Integrated via `@arkenv/bun-plugin` in the `Bun.build` plugins array. Used for custom build scripts targeting the browser in a fullstack context.
@@ -218,7 +218,7 @@ pnpm run test:e2e                     # E2E tests
 
 - Uses `const` type parameters for better type inference
 - Leverages ArkType's `type.infer` and `type.validate` utilities
-- Typesafe environment object returned from `createEnv`
+- Typesafe environment object returned from `arkenv`
 
 **Error Handling:**
 

.agents/docs/triage-labels.md

@@ -2,14 +2,14 @@
 
 The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
 
-| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
-| -------------------------- | -------------------- | ---------------------------------------- |
-| `needs-triage`             | `needs triage`       | Maintainer needs to evaluate this issue  |
-| `needs-info`               | `needs more info`    | Waiting on reporter for more information |
-| `ready-for-agent`          | `ready for agent`    | Fully specified, ready for an AFK agent  |
-| `ready-for-human`          | `ready for human`    | Requires human implementation            |
-| `wontfix`                  | `wontfix`            | Will not be actioned                     |
-| `meta`                     | `meta`               | Living docs (dashboards, roadmaps)       |
+| Label in mattpocock/skills | Label in our tracker | Meaning                                                        |
+| -------------------------- | -------------------- | ------------------------------------------------------------- |
+| `needs-triage`             | `needs triage`       | Maintainer needs to evaluate this issue                       |
+| `needs-info`               | `needs more info`    | Waiting on reporter for more information                      |
+| `ready-for-agent`          | `ready for agent`    | Fully specified, ready for immediate implementation           |
+| `ready-for-human`          | `ready for human`    | Needs a judgment call or design decision before implementation |
+| `wontfix`                  | `wontfix`            | Will not be actioned                                          |
+| `meta`                     | `meta`               | Living docs (dashboards, roadmaps)                            |
 
 When a skill mentions a role (e.g. "apply the ready for agent triage label"), use the corresponding label string from this table.
 

.agents/platforms/.cursor/rules/arktype.mdc

@@ -22,7 +22,7 @@ Define environment variable schemas using ArkType syntax:
 ```typescript
 import { type } from "arktype";
 
-const env = createEnv({
+const env = arkenv({
   HOST: "string.host", // Custom host type
   PORT: "number.port", // Custom port type
   NODE_ENV: "'development' | 'production' | 'test'", // Union type
@@ -49,7 +49,7 @@ import { $ } from "./scope";
 ## Type Inference
 
 - Use `type.infer` to extract TypeScript types from schemas
-- The return type of `createEnv` is inferred from the schema
+- The return type of `arkenv` is inferred from the schema
 - No manual type definitions needed
 
 ## Error Handling

.agents/platforms/.cursor/rules/coding-guidelines.mdc

@@ -48,8 +48,8 @@ This project uses [Biome](https://biomejs.dev/) for formatting and linting. The
 
 ## Naming Conventions
 
-- **Files**: Use kebab-case for files (`create-env.ts`)
-- **Functions**: Use camelCase (`createEnv`)
+- **Files**: Use kebab-case for files (`arkenv-internal.ts`)
+- **Functions**: Use camelCase (`arkenv`, `myFunction`)
 - **Types**: Use PascalCase (`ArkEnvError`)
 - **Constants**: Use UPPER_SNAKE_CASE for environment variables and constants
 

.agents/platforms/.cursor/rules/test-patterns.mdc

@@ -33,7 +33,7 @@ alwaysApply: true
 - Fast execution (< 100ms per test)
 - Mocked external dependencies (clipboard, network, etc.)
 - Focused on single unit behavior
-- Co-locate with source: `create-env.ts` → `create-env.test.ts`
+- Co-locate with source: `arkenv.ts` → `arkenv.test.ts`
 
 ### Integration Tests (`*.integration.test.ts` or `*.integration.test.tsx`)
 **What:** Test how multiple units (components, hooks, functions) work together without mocking their interactions.
@@ -45,8 +45,8 @@ alwaysApply: true
 - State synchronization across boundaries
 
 **Examples:**
-- `custom-types.integration.test.ts` - Tests `createEnv` + `scope` + custom types working together
-- `error.integration.test.ts` - Tests error propagation through `createEnv` + `formatErrors` + `ArkEnvError`
+- `custom-types.integration.test.ts` - Tests `arkenv` + `scope` + custom types working together
+- `error.integration.test.ts` - Tests error propagation through `arkenv` + `formatErrors` + `ArkEnvError`
 - `copy-button.integration.test.tsx` - Tests `CopyButton` + `useToast` + `Toaster` as a complete flow
 - `heading.integration.test.tsx` - Tests `Heading` + `useIsMobile` responding to viewport changes
 - `toaster.integration.test.tsx` - Tests `useToast` hook + `Toaster` component state synchronization
@@ -98,12 +98,12 @@ alwaysApply: true
 
 ```typescript
 import { describe, expect, it } from "vitest";
-import { createEnv } from "./create-env";
+import arkenv from "./arkenv";
 
-describe("createEnv", () => {
+describe("arkenv", () => {
   it("should validate string env variables", () => {
     process.env.TEST_STRING = "hello";
-    const env = createEnv({
+    const env = arkenv({
       TEST_STRING: "string",
     });
     expect(env.TEST_STRING).toBe("hello");

.agents/platforms/copilot-instructions.md

@@ -56,14 +56,14 @@ The project uses modern tooling:
 
 The core package provides:
 
-1. **`createEnv(schema)`** - Main function to create validated environment objects. Also available as the default export, typically imported as `arkenv`.
+1. **`arkenv(schema)`** - Main function to create validated environment objects. Exposed as default export, and also as named export `arkenv`.
 2. **Built-in validators** - Common validators like `host`, `port`, `url`, etc.
 3. **ArkType integration** - Uses ArkType for schema definition and validation
 4. **Type inference** - Full TypeScript type inference from schemas
 
 ### Key files
 
-- `src/create-env.ts` - Core `createEnv` implementation
+- `src/arkenv.ts` - Core `arkenv` implementation
 - `src/types.ts` - Built-in type validators (host, port, url, etc.)
 - `src/errors.ts` - Error handling and formatting
 - `src/utils.ts` - Utility functions
@@ -113,7 +113,7 @@ The project uses three types of tests:
 
 Tests are located alongside source files with `.test.ts` suffix:
 
-- `create-env.test.ts` - Tests for main `createEnv` functionality
+- `arkenv.test.ts` - Tests for main `arkenv` functionality
 - `types.test.ts` - Tests for built-in validators
 - `errors.test.ts` - Tests for error handling
 - `utils.test.ts` - Tests for utility functions
@@ -131,7 +131,7 @@ Tests are located alongside source files with `.test.ts` suffix:
 
 **Examples:**
 
-- `custom-types.integration.test.ts` - Tests `createEnv` + `scope` + custom types working together
+- `custom-types.integration.test.ts` - Tests `arkenv` + `scope` + custom types working together
 - `error.integration.test.ts` - Tests error propagation through validation pipeline
 - `copy-button.integration.test.tsx` - Tests `CopyButton` + `useToast` + `Toaster` flow
 - `heading.integration.test.tsx` - Tests `Heading` + `useIsMobile` responsive behavior

.all-contributorsrc

@@ -2,7 +2,8 @@
   "projectName": "arkenv",
   "projectOwner": "yamcodes",
   "files": [
-    "packages/arkenv/README.md"
+    "README.md",
+    "packages/core/README.md"
   ],
   "commitType": "docs",
   "commitConvention": "angular",
@@ -22,6 +23,8 @@
         "bug",
         "example",
         "infra",
+        "plugin",
+        "tool",
         "test"
       ]
     },
@@ -52,6 +55,7 @@
       "avatar_url": "https://avatars.githubusercontent.com/u/44430251?v=4",
       "profile": "https://github.com/danciudev",
       "contributions": [
+        "plugin",
         "code"
       ]
     },
@@ -62,6 +66,7 @@
       "profile": "https://joakim.beng.se",
       "contributions": [
         "code",
+        "plugin",
         "doc"
       ]
     },
@@ -71,7 +76,21 @@
       "avatar_url": "https://avatars.githubusercontent.com/u/166608075?v=4",
       "profile": "https://fresh-accordion-06a.notion.site/Jiayi-Du-1817075e92978076b95cf9d90fb5eceb",
       "contributions": [
-        "doc"
+        "doc",
+        "tool"
+      ]
+    },
+    {
+      "login": "abhimanyutiwaribot",
+      "name": "Abhimanyu Tiwari",
+      "avatar_url": "https://avatars.githubusercontent.com/u/181746977?v=4",
+      "profile": "https://abhimanyutiwaribot.vercel.app",
+      "contributions": [
+        "code",
+        "doc",
+        "example",
+        "test",
+        "tool"
       ]
     }
   ]

.changeset/add-host-preset-add-command.md

@@ -0,0 +1,15 @@
+---
+"arkenv": minor
+---
+
+#### Add `add host` command to CLI for adding hosting presets to existing schemas
+
+Support adding a hosting provider preset (Vercel or Netlify) to an existing `env.ts` configuration file:
+
+```bash
+npx arkenv@alpha add host [provider]
+```
+
+- Prompts interactively to select Vercel or Netlify if the provider is omitted.
+- Auto-detects the framework (Next.js, Nuxt, Vite, Bun) and the validator engine (Zod, Valibot, or ArkType) to inject the preset fields with the correct syntax.
+- Fallback to logging the generated variable schemas to stdout with manual configuration instructions if `env.ts` is missing or unparseable.

.changeset/add-host-presets-phase-4.md

@@ -0,0 +1,19 @@
+---
+"arkenv": minor
+---
+
+#### Add hosting presets for Cloudflare, Railway, Render, and Fly.io
+
+Add hosting presets for Cloudflare, Railway, Render, and Fly.io to the interactive prompt selections in both `arkenv init` and `arkenv add host`.
+
+Usage:
+
+```bash
+npx arkenv@latest add host cloudflare
+```
+
+or
+
+```bash
+npx arkenv@latest init --host-preset cloudflare
+```

.changeset/add-host-strict-layouts-forward-port.md

@@ -0,0 +1,13 @@
+---
+"arkenv": minor
+---
+
+#### Support `arkenv add host` for strict multi-file layouts
+
+Support `arkenv add host [provider]` in projects with strict multi-file layouts (`client.ts` and `server.ts`). Automatically partition preset variables into client-prefixed keys for `client.ts` and server-only keys for `server.ts`. Align help text and docs so `add host` is not described as flat-`env.ts`-only.
+
+Usage:
+
+```bash
+npx arkenv@latest add host [provider]
+```

.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-missing-schema-throw.md

@@ -0,0 +1,17 @@
+---
+"@arkenv/nuxt": major
+---
+
+#### Throw when the Nuxt module cannot resolve an env schema
+
+**BREAKING CHANGE**: The `@arkenv/nuxt` module now throws when no schema file is found (auto-discovery or `schemaPath`), instead of warning and skipping setup. Create an `env.ts` (or `src/env.ts`) schema, or set `arkenv.schemaPath` in `nuxt.config.ts`.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["@arkenv/nuxt/module"],
+  arkenv: {
+    schemaPath: "./env.ts", // required if auto-discovery cannot find a schema
+  },
+});
+```

.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/bun-env-module-transform.md

@@ -0,0 +1,46 @@
+---
+"@arkenv/bun-plugin": minor
+---
+
+#### Add `env.ts` transform for Bun fullstack apps
+
+Let the Bun plugin discover your `env.ts` and expose a shared `env` object that works in both client and server code. On the client (`Bun.build` / `[serve.static]`), public (`BUN_PUBLIC_*`) values are inlined at build time and server-only keys throw if read; on the server (`bun run` / `Bun.serve`), `env.ts` still runs normally and validates against the real environment at boot. The plugin does not rewrite your `env.ts` file on disk.
+
+Works with `@arkenv/bun-plugin` and `@arkenv/bun-plugin/standard`.
+
+Usage:
+
+```ts
+// bunfig.toml — zero-config browser transform
+// [serve.static]
+// plugins = ["@arkenv/bun-plugin"]
+
+// or explicitly in Bun.build:
+import arkenv from "@arkenv/bun-plugin";
+
+await Bun.build({
+  entrypoints: ["./src/index.html"],
+  target: "browser",
+  plugins: [arkenv], // finds src/env.ts or env.ts
+  // or: arkenv({ schemaPath: "src/env.ts", clientPrefix: "BUN_PUBLIC_" })
+});
+```
+
+```ts
+// src/env.ts
+import arkenv from "@arkenv/core";
+
+export const env = arkenv({
+  DATABASE_URL: "string",
+  BUN_PUBLIC_API_URL: "string",
+});
+```
+
+```ts
+import { env } from "./env";
+
+env.BUN_PUBLIC_API_URL; // available on client and server
+env.DATABASE_URL; // server only — throws if read in the browser
+```
+
+Passing a schema to `arkenv(schema)` (the previous `process.env` rewrite API) continues to work unchanged as SPA mode.