plugins and 1pass docs (#175)

* plugin docs, 1pass docs, general cleanup

* mark examples as private

* linting, cleanup

Author: theoephraim

.cursor/rules/varlock.mdc

@@ -28,8 +28,8 @@ actions:
 
       1. File Structure:
          ```
-         .env.schema          # Schema definition with decorators
-         .env                 # Local development values
+         .env.schema          # Schema definition with decorators and default values
+         .env.local           # Local (git-ignored) development overrides
          .env.production      # Production values
          .env.staging         # Staging values
          ```
@@ -41,7 +41,7 @@ actions:
          - Values can be strings, numbers, booleans, or function calls
 
       3. Root Level Decorators:
-         - @envFlag - Sets environment flag key
+         - @currentEnv - Sets current environment env var (e.g., `@currentEnv=$APP_ENV`)
          - @defaultRequired - Sets default required state for all items
          - @defaultSensitive - Sets default sensitive state for all items
 
@@ -52,7 +52,7 @@ actions:
       4. Item Level Decorators:
          - @required - Makes item required (omit if @defaultRequired=true)
          - @sensitive - Marks item as sensitive (omit if @defaultSensitive=true)
-         - @type - Sets value type
+         - @type - Sets value type (omit if basic string with no additional settings)
          - @example - Provides example value
          - @trim - Trims whitespace
          - @deindent - Trims leading whitespace
@@ -112,10 +112,18 @@ examples:
   - input: |
       # Bad: Missing type decorator
       PORT=3000
+      # Bad: Unnecessary type decorator for basic string
+      # @type=string
+      BASIC_STRING
 
-      # Good: With type decorator
+      # Good: With type decorators when necessary
       # @type=port
       PORT=3000
+      # @type=string(startsWith=abc_)
+      STRING_WITH_VALIDATION=
+      # no @type necessary for basic strings
+      BASIC_STRING=
+
     output: "Environment variable with proper type"
 
 metadata:

.gitignore

@@ -10,5 +10,6 @@ changesets-summary.json
 
 .env.local
 .env.*.local
+env.d.ts
 
 

README.md

@@ -16,15 +16,15 @@
 ## Varlock
 > add declarative schema to your .env files using @env-spec decorator comments
 
-- 🛡️ validation, coercion, type safety w/ Intellisense
+- 🛡️ validation, coercion, type safety w/ IntelliSense
 - 🔏 protection for sensitive config values (log redaction, leak prevention)
 - 🌐 flexible multi-environment management
 - 💫 composition of values, functions, load from external sources
 
 Your `.env.schema` is a declarative schema of your environment variables that lives within version control, so it will never be out of sync.
 
 ```bash
-# @defaultSensitive=false @defaultRequired=infer @envFlag=APP_ENV
+# @defaultSensitive=false @defaultRequired=infer @currentEnv=$APP_ENV
 # ---
 # our environment flag, will control automatic loading of `.env.xxx` files
 # @type=enum(development, preview, production, test

eslint.config.mjs

@@ -156,7 +156,7 @@ export default tseslint.config(
   {
     files: [
       'scripts/**',
-      'example-monorepo/**',
+      'examples/**',
       'packages/*.ignore/**',
       'packages/varlock/src/cli/**',
       'packages/varlock/scripts/**',

examples/astro-example/env.d.ts

@@ -2,6 +2,7 @@
   "name": "astro-example",
   "type": "module",
   "version": "0.0.1",
+  "private": true,
   "scripts": {
     "dev": "astro dev",
     "build": "astro build",