From ac40df755f08616135598d7c548c3661dc7e4123 Mon Sep 17 00:00:00 2001
From: Mauricio Gomes <mauricio@edge14.com>
Date: Fri, 20 Feb 2026 20:54:39 -0500
Subject: [PATCH 1/3] Not needed

---
 docs/pre_1_0_migration.md | 79 ---------------------------------------
 1 file changed, 79 deletions(-)
 delete mode 100644 docs/pre_1_0_migration.md

diff --git a/docs/pre_1_0_migration.md b/docs/pre_1_0_migration.md
deleted file mode 100644
index d8704bf..0000000
--- a/docs/pre_1_0_migration.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# Pre-1.0 Migration Notes
-
-This document tracks known pre-`v1.0.0` breaking changes and how to upgrade.
-
-## Breaking Changes by Version
-
-### v0.4.1: `Time#strftime` renamed to `Time#format`
-
-Before:
-
-```vibe
-Time.now.strftime("%Y-%m-%d")
-```
-
-After:
-
-```vibe
-Time.now.format("2006-01-02")
-```
-
-Action: replace `strftime` calls with `format` and use Go time layouts.
-
-### v0.6.0: Constructors switched from panic-style to error-returning APIs
-
-Before:
-
-```go
-engine := vibes.MustNewEngine(vibes.Config{})
-```
-
-After:
-
-```go
-engine, err := vibes.NewEngine(vibes.Config{})
-if err != nil {
-    return err
-}
-```
-
-Action: update host bootstrap paths to handle constructor errors explicitly.
-
-### v0.12.0: `require` boundary and module isolation tightened
-
-Changes introduced:
-
-- Path normalization and traversal protections.
-- Stricter private helper/module boundary behavior.
-- More explicit cycle diagnostics.
-
-Action: ensure module references stay inside configured roots and review module
-visibility expectations. See `docs/module_require_migration.md`.
-
-### v0.13.0: Capability contracts enforced at call boundaries
-
-Changes introduced:
-
-- Runtime validation of capability args/kwargs/returns.
-- Data-only boundary checks on capability return values.
-
-Action: align adapter payload shapes with declared contracts and add negative
-tests for invalid payloads.
-
-### v0.17.0: Module ergonomics updated (exports/aliasing/conflicts)
-
-Changes introduced:
-
-- Explicit export controls supported (`export def`).
-- Alias collision and namespace conflict behavior enforced.
-- Module allow/deny policy hooks added.
-
-Action: adopt explicit exports and aliases for shared modules, and configure
-policy lists in host setup where needed.
-
-## Upgrade Checklist
-
-1. Review release notes for each skipped version.
-2. Apply module migration updates (`docs/module_require_migration.md`).
-3. Re-run integration tests covering host capabilities and module calls.
-4. Verify script behavior under current quotas and strictness settings.

From 376caf44f46036914ae85b7d30e9e7c2e6bbfafa Mon Sep 17 00:00:00 2001
From: Mauricio Gomes <mauricio@edge14.com>
Date: Fri, 20 Feb 2026 21:10:06 -0500
Subject: [PATCH 2/3] Document classes in Vibescript

---
 docs/classes.md            | 161 +++++++++++++++++++++++++++++++++++++
 docs/introduction.md       |   1 +
 docs/language_reference.md |   5 ++
 3 files changed, 167 insertions(+)
 create mode 100644 docs/classes.md

diff --git a/docs/classes.md b/docs/classes.md
new file mode 100644
index 0000000..13caabc
--- /dev/null
+++ b/docs/classes.md
@@ -0,0 +1,161 @@
+# Classes
+
+VibeScript classes group related state and behavior using instance methods,
+class methods, instance variables, and class variables.
+
+Inheritance is not supported. Class definitions do not support
+subclassing or `super` calls.
+
+## Defining A Class
+
+Use `class ... end` to declare a class and `def ... end` for methods:
+
+```vibe
+class Counter
+  def initialize(start)
+    @count = start
+  end
+
+  def value
+    @count
+  end
+
+  def increment
+    @count = @count + 1
+  end
+end
+```
+
+Construct instances with `.new`:
+
+```vibe
+counter = Counter.new(10)
+counter.increment
+counter.value
+```
+
+If `initialize` is defined, `.new` forwards arguments to it.
+
+## Instance Methods vs Class Methods
+
+Instance methods:
+
+- Are declared with `def name`.
+- Are called on instances (`user.name`).
+
+Class methods:
+
+- Are declared with `def self.name`.
+- Are called on the class (`User.find(1)`).
+
+```vibe
+class Mathy
+  def self.twice(n)
+    n * 2
+  end
+
+  def call_twice(n)
+    self.class.twice(n)
+  end
+end
+```
+
+## Instance Variables (`@name`)
+
+Instance variables are per-object state:
+
+```vibe
+class Person
+  def initialize(name)
+    @name = name
+    @age = 0
+  end
+
+  def birthday
+    @age = @age + 1
+  end
+end
+```
+
+Shorthand parameter assignment is supported in method signatures:
+
+```vibe
+class Point
+  def initialize(@x, @y)
+  end
+end
+```
+
+## Class Variables (`@@name`)
+
+Class variables are shared by all instances of the same class within a script
+invocation:
+
+```vibe
+class Counter
+  @@instances = 0
+
+  def initialize
+    @@instances = @@instances + 1
+  end
+
+  def self.instances
+    @@instances
+  end
+end
+```
+
+## `property`, `getter`, And `setter`
+
+Inside a class body, you can generate accessor methods:
+
+- `property x` creates `x` and `x=`.
+- `getter x` creates `x`.
+- `setter x` creates `x=`.
+
+```vibe
+class Account
+  property balance
+  getter owner
+  setter nickname
+
+  def initialize(owner, balance)
+    @owner = owner
+    @balance = balance
+    @nickname = ""
+  end
+end
+```
+
+When assigning through a member (`obj.name = ...`):
+
+- If `name=` exists, VibeScript calls that setter method.
+- If only `name` exists (getter without setter), assignment raises a read-only
+  property error.
+
+## Privacy
+
+Mark methods private with `private def`:
+
+```vibe
+class Helper
+  private def secret
+    42
+  end
+
+  def call_internal
+    secret
+  end
+end
+```
+
+Private methods are callable only on the current receiver (the same instance or
+class context). Calls like `other.secret` raise a runtime `private method`
+error.
+
+## Common Errors
+
+- Calling a missing method: `unknown member ...` / `unknown class member ...`
+- Calling a private method externally: `private method ...`
+- Assigning to getter-only attributes: `cannot assign to read-only property ...`
+- Calling `.new` with wrong arguments for `initialize`: argument errors
diff --git a/docs/introduction.md b/docs/introduction.md
index 2934c0d..21866ee 100644
--- a/docs/introduction.md
+++ b/docs/introduction.md
@@ -20,6 +20,7 @@ dives on specific topics.
 - `durations.md` – duration literals and time-based helper methods.
 - `time.md` – Time creation, formatting, accessors, and time/duration math.
 - `typing.md` – gradual typing: annotations, nullables, and type-checked calls.
+- `classes.md` – class syntax, class/instance methods, variables, and privacy.
 - `language_reference.md` – consolidated language syntax and semantics reference.
 - `syntax_compatibility.md` – core syntax freeze baseline and compatibility guarantees.
 - `control-flow.md` – conditionals, loops, and ranges.
diff --git a/docs/language_reference.md b/docs/language_reference.md
index 2c0c333..d64bbbb 100644
--- a/docs/language_reference.md
+++ b/docs/language_reference.md
@@ -80,6 +80,11 @@ class Counter
 end
 ```
 
+Inheritance is not supported.
+
+See `docs/classes.md` for class methods, `@`/`@@` variables, accessors, and
+privacy semantics.
+
 ## Method Calls
 
 Calls support positional args and keyword args:

From 075c12beb64c5a143317aad75c1b4ee90c286431 Mon Sep 17 00:00:00 2001
From: Mauricio Gomes <mauricio@edge14.com>
Date: Fri, 20 Feb 2026 21:16:30 -0500
Subject: [PATCH 3/3] Remove stale pre-1.0 migration doc references

---
 README.md            | 1 -
 docs/introduction.md | 1 -
 docs/versioning.md   | 2 +-
 3 files changed, 1 insertion(+), 3 deletions(-)

diff --git a/README.md b/README.md
index d4f92bc..bf9ce14 100644
--- a/README.md
+++ b/README.md
@@ -174,7 +174,6 @@ Long-form guides live in `docs/`:
 - `docs/compatibility.md` – supported Go versions and CI coverage notes.
 - `docs/versioning.md` – semantic versioning policy and compatibility contract.
 - `docs/deprecation_policy.md` – deprecation lifecycle for public Go embedding APIs.
-- `docs/pre_1_0_migration.md` – migration notes for known pre-1.0 breaking changes.
 - `docs/known_issues.md` – tracked P0/P1 correctness bug bar.
 - `ROADMAP.md` – versioned implementation checklist and release roadmap.
 - `templates/` – copy-friendly starter templates for common host integration patterns.
diff --git a/docs/introduction.md b/docs/introduction.md
index 21866ee..f849e3d 100644
--- a/docs/introduction.md
+++ b/docs/introduction.md
@@ -41,5 +41,4 @@ dives on specific topics.
 - `compatibility.md` – supported Go versions and CI coverage expectations.
 - `versioning.md` – semantic versioning policy and compatibility contract.
 - `deprecation_policy.md` – lifecycle policy for public Go embedding APIs.
-- `pre_1_0_migration.md` – migration notes for all known pre-1.0 breaking changes.
 - `known_issues.md` – active P0/P1 correctness bug bar.
diff --git a/docs/versioning.md b/docs/versioning.md
index 7ee7290..55f0fe8 100644
--- a/docs/versioning.md
+++ b/docs/versioning.md
@@ -36,4 +36,4 @@ This contract applies to:
 
 Go toolchain support follows `docs/compatibility.md`.
 Core language syntax guarantees are tracked in `docs/syntax_compatibility.md`.
-Pre-1.0 migration notes are tracked in `docs/pre_1_0_migration.md`.
+Pre-1.0 migration guidance is communicated in release notes and pull request descriptions.