Clean up ArkEnv introduction

[yamcodes]

Summary by CodeRabbit

• Documentation
  • Enhanced ArkEnv documentation with comprehensive code examples and clearer narrative structure.
  • Redesigned documentation navigation for improved discoverability.
  • Updated README with refined guidance on validator options and platform-specific behavior.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: a9aa0b4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Warning

Rate limit exceeded

@yamcodes has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 17 minutes and 7 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between dbb426d and a9aa0b4.

📒 Files selected for processing (3)

• apps/www/content/docs/arkenv/index.mdx
• packages/arkenv/README.md
• tooling/playwright-www/tests/a11y.test.ts

Walkthrough

This pull request updates ArkEnv documentation by replacing external README embeds with inlined content in the main docs page, restructuring the documentation narrative with new Philosophy and examples sections, simplifying README guidance on notation support, and updating navigation metadata to include a titled link.

Changes

Cohort / File(s)	Summary
Documentation Structure apps/www/content/docs/arkenv/index.mdx, apps/www/content/docs/arkenv/meta.json	Replaces README embed with inlined ArkEnv content; adds full code example, Philosophy section, and narrative structure; updates navigation from plain index to titled link.
README Simplification packages/arkenv/README.md	Refines introduction wording, removes code fence language hints, trims example lines, updates notation guidance to clarify ArkType defaults with Standard Schema support, removes cheatsheet reference.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Coercion Documentation #597 — Modifies overlapping ArkEnv documentation content including meta.json and index.mdx with concurrent docs updates.
• Add external link indicators to documentation #645 — Updates index.mdx by removing icon usage and restructuring Card content in the same documentation file.
• Reduce repetitive CTA for reading the docs #679 — Modifies both index.mdx and README.md, directly overlapping with documentation changes across the same files.

Poem

🐰 From README links to pages inline,
Philosophy shines, examples align,
Navigation tidy, content refined—
ArkEnv docs now elegantly signed! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title accurately describes the main change: removing an introduction header from the 'What is ArkEnv?' documentation page, which aligns with the structural updates in the documentation files.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/arkenv@681

npm i https://pkg.pr.new/@arkenv/bun-plugin@681

npm i https://pkg.pr.new/@arkenv/vite-plugin@681

commit: a9aa0b4

[arkenv-bot]

📦 Bundle Size Report

Package	Size	Limit	Diff	Status
arkenv	1.43 kB	2 kB	0.0%	✅

✅ All size limits passed!

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 111f48d and dbb426d.

📒 Files selected for processing (3)

• apps/www/content/docs/arkenv/index.mdx
• apps/www/content/docs/arkenv/meta.json
• packages/arkenv/README.md

🧰 Additional context used

🧠 Learnings (16)

📓 Common learnings

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Document environment requirements in README files for new features or integrations

📚 Learning: 2025-09-09T17:37:19.650Z

Learnt from: yamcodes
Repo: yamcodes/arkenv PR: 132
File: packages/arkenv/README.md:13-14
Timestamp: 2025-09-09T17:37:19.650Z
Learning: For yamcodes/arkenv project: Runtime support documentation should link to specific examples: Node.js (examples/basic), Bun (examples/with-bun), Vite (examples/with-vite-react-ts).

Applied to files:

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

📚 Learning: 2025-11-24T16:03:45.295Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Keep environment variable schemas readable and TypeScript-like using ArkType syntax

Applied to files:

• apps/www/content/docs/arkenv/index.mdx
• packages/arkenv/README.md

📚 Learning: 2025-12-23T07:09:57.130Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use ArkEnvError for environment variable errors instead of generic Error types

Applied to files:

• apps/www/content/docs/arkenv/index.mdx
• packages/arkenv/README.md

📚 Learning: 2025-11-24T16:03:45.295Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Convert ArkType validation errors to `ArkEnvError` for user-friendly error messages that include variable name and expected type

Applied to files:

• apps/www/content/docs/arkenv/index.mdx
• packages/arkenv/README.md

📚 Learning: 2025-11-24T16:04:00.957Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Use `ArkEnvError` for environment variable validation errors

Applied to files:

• apps/www/content/docs/arkenv/index.mdx
• packages/arkenv/README.md

📚 Learning: 2025-12-23T07:09:57.130Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use `createEnv(schema)` function (or default import as `arkenv`) to create validated environment objects in TypeScript

Applied to files:

• apps/www/content/docs/arkenv/index.mdx
• packages/arkenv/README.md

📚 Learning: 2025-11-24T16:03:45.295Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's built-in types (e.g., `string.host`, `number.port`) where possible in environment schemas

Applied to files:

• apps/www/content/docs/arkenv/index.mdx
• packages/arkenv/README.md

📚 Learning: 2025-11-24T16:03:45.295Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use ArkType's `type()` function to define schemas in environment variable definitions

Applied to files:

• apps/www/content/docs/arkenv/index.mdx
• packages/arkenv/README.md

📚 Learning: 2025-11-24T16:03:45.295Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: ArkType validates environment variables at runtime and TypeScript types are inferred from the schema definition

Applied to files:

• apps/www/content/docs/arkenv/index.mdx
• packages/arkenv/README.md

📚 Learning: 2025-12-23T07:09:57.130Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Provide default values for optional environment variables using ArkType syntax (e.g., 'boolean = false')

Applied to files:

• apps/www/content/docs/arkenv/index.mdx
• packages/arkenv/README.md

📚 Learning: 2025-12-23T07:09:57.130Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : For environment schema definition, use ArkType string literal syntax for enumerated values (e.g., "'development' | 'production' | 'test'")

Applied to files:

• apps/www/content/docs/arkenv/index.mdx
• packages/arkenv/README.md

📚 Learning: 2025-12-23T07:09:57.130Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use built-in validators (host, port, url, email) from ArkEnv when available instead of custom ArkType schemas

Applied to files:

• apps/www/content/docs/arkenv/index.mdx
• packages/arkenv/README.md

📚 Learning: 2025-11-24T16:03:45.295Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's type inference for TypeScript types instead of manual type definitions

Applied to files:

• packages/arkenv/README.md

📚 Learning: 2025-11-24T16:03:45.295Z

Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use union types for enums in ArkType schemas (e.g., `"'dev' | 'prod'"`) instead of separate enum definitions

Applied to files:

• packages/arkenv/README.md

📚 Learning: 2025-12-05T20:33:10.676Z

Learnt from: yamcodes
Repo: yamcodes/arkenv PR: 498
File: apps/playgrounds/node/index.ts:2-2
Timestamp: 2025-12-05T20:33:10.676Z
Learning: ArkType 2.1.28+ supports Standard Schema specification, allowing interoperability with other Standard Schema-compliant validation libraries (e.g., Zod, Valibot) within the same schema definition

Applied to files:

• packages/arkenv/README.md

🪛 LanguageTool

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

[grammar] ~28-~28: Use a hyphen to join words.
Context: ...st match to TypeScript syntax for editor to runtime typesafety. You can also use ...

(QB_NEW_EN_HYPHEN)

---

[grammar] ~28-~28: Use a hyphen to join words.
Context: ...match to TypeScript syntax for editor to runtime typesafety. You can also use any...

(QB_NEW_EN_HYPHEN)

packages/arkenv/README.md

[grammar] ~49-~49: Use a hyphen to join words.
Context: ...st match to TypeScript syntax for editor to runtime typesafety. You can also use ...

(QB_NEW_EN_HYPHEN)

---

[grammar] ~49-~49: Use a hyphen to join words.
Context: ...match to TypeScript syntax for editor to runtime typesafety. You can also use any...

(QB_NEW_EN_HYPHEN)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)

• GitHub Check: test-e2e (e2e)
• GitHub Check: test-e2e (a11y)
• GitHub Check: test-build (lts/*)
• GitHub Check: test-build (latest)
• GitHub Check: test-typesafety
• GitHub Check: Deploy-Preview

🔇 Additional comments (7)

apps/www/content/docs/arkenv/meta.json (1)

8-8: LGTM! Enhanced navigation entry.

The navigation entry now includes an icon and explicit title, improving the user experience and making the navigation more descriptive.

apps/www/content/docs/arkenv/index.mdx (4)

2-3: LGTM! Clear and descriptive frontmatter.

The updated title and description effectively introduce ArkEnv while emphasizing its non-intrusive design philosophy.

---

9-26: Excellent code example demonstrating ArkEnv capabilities.

The inline code example effectively showcases:

• ArkType's TypeScript-like syntax for schema definition
• Built-in validators (string.ip, number.integer with range)
• Union types for enumerations
• Default values for optional variables
• Type inference with hover hints

This provides immediate value to users learning ArkEnv.

---

30-50: Excellent lifecycle-based documentation structure.

The progression from Editor → Build time → Runtime effectively demonstrates ArkEnv's comprehensive typesafety guarantees at each stage of development. The concrete error example at runtime reinforces the fail-fast philosophy.

---

54-77: Valuable addition: Philosophy section provides design context.

This section effectively communicates ArkEnv's design principles and helps users understand:

• The core-first, plugin-based architecture
• When and why validation occurs (fail fast)
• Default assumptions and when customization is needed

This transparency improves the developer experience and sets appropriate expectations.

packages/arkenv/README.md (2)

36-38: LGTM! Improved clarity and appropriate code fence.

The wording is now more direct, and using plain ts code fence is appropriate for the README (versus ts twoslash in the documentation site where interactive type hints are valuable).

---

36-59: Documentation updates align well with the broader restructuring.

The README changes maintain consistency with the documentation site while being appropriately scoped for a package README. The notation guidance now clearly communicates both the default (ArkType) and alternatives (Standard Schema validators).