docs(classes): describe member methods and this semantics

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

4 files changed, 34 insertions, 12 deletions

diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md
index 27bb70a..1178934 100644
--- a/AGENTS/ARCH.md
+++ b/AGENTS/ARCH.md
@@ -289,12 +289,12 @@ do not modify the real release for local verification.
 | `lib/Parser/ParserExpression.cc`, `ParserControlFlow.cc` | Expressions/designators and control-flow statement parsing (including ordered CASE branches) |
 | `lib/Parser/ParserFunction.cc` | FUNCTION/PROCEDURE/CALL/RETURN + parameter-list parsing |
 | `lib/Parser/ParserFile.cc` | OPENFILE/READFILE/WRITEFILE/CLOSEFILE parsing |
-| `lib/Parser/ParserType.cc` | Type names, variable/array/constant declarations, TYPE/ENDTYPE and CLASS/ENDCLASS declarations, shared field parsing, SET/DEFINE reserved stubs |
+| `lib/Parser/ParserType.cc` | Type names, variable/array/constant declarations, TYPE/ENDTYPE and CLASS/ENDCLASS declarations, shared field and method parsing, SET/DEFINE reserved stubs |
 | `lib/CodeGen/CodeGen.cc` | Initialization, symbols, call arguments and main() compilation |
 | `lib/CodeGen/ExpressionGen.cc`, `StatementGen.cc`, `ControlFlowGen.cc` | Expression/statement dispatch and control-flow emission |
 | `lib/CodeGen/ConstantGen.cc` | Literal constants, declaration conflicts and lexical binding restoration |
 | `lib/CodeGen/ValueTypeGen.cc`, `OutputGen.cc`, `Builtins.h` | Expression typing, coercion/declarations, scalar output and the shared builtin table |
-| `lib/CodeGen/Designator.cc`, `TypeCheckGen.cc` | TYPE pre-pass and lvalue access; type admission and user-kind binary operators |
+| `lib/CodeGen/Designator.cc`, `TypeCheckGen.cc` | TYPE pre-pass, member lookup/calls and lvalue access; type admission and user-kind binary operators |
 | `lib/CodeGen/CTypeGen.cc` | CodeGen methods for native C scalar conversions, casts, arithmetic and input/output |
 | `lib/CodeGen/NativeTypeSystem.cc` | Builtin registration, native C type imports/aliases and scalar promotion |
 | `lib/CodeGen/MemoryHandler.cc` | Explicit raw memory allocation, resizing and release with a live-address tracking list |
diff --git a/AGENTS/CONVENTIONS.md b/AGENTS/CONVENTIONS.md
index 8ce9cb2..83e73e2 100644
--- a/AGENTS/CONVENTIONS.md
+++ b/AGENTS/CONVENTIONS.md
@@ -129,7 +129,7 @@ The parser drops a failed statement and resyncs at the
 next token that can start a statement or end a block (`syncToStatementStart`), then
 continues; the failure is always diagnosed and reflected in the exit code.
 
-**Calls share one dispatch path.** `CodeGen::emitCall` handles expression calls, CALL statements and bare `name(args)` statements; statement calls discard results. Explicit casts may bridge C void* and nominal pseudocode pointer types.
+**Calls share argument marshalling.** `CodeGen::emitCall` handles global expression calls, CALL statements and bare `name(args)` statements; `emitMemberCall` resolves member access and adds a hidden receiver address. Both use `marshalCallArgs` and FunctionGen for user calls; statement calls discard results. Explicit casts may bridge C void* and nominal pseudocode pointer types.
 
 **User calls dispatch on the declared signature.** `FunctionGen::emitPrototype` records every
 function's pseudocode signature (`FuncSig`: return type name + per-param `ParamSig`
@@ -140,10 +140,12 @@ arguments through `emitCoercedExpr`, and dispatches whole-array arguments to
 `ArrayHandler::emitArrayArgument`. RETURN values go through `emitCoercedExpr` against
 the declared return type. Top-level prototypes are pre-registered (after the TYPE
 pre-pass) before statement emission, so call-before-definition is fine; a call with
-no registered signature is a compile error. Function names get no mangling, so
+no registered signature is a compile error. Global function names get no mangling, so
 `emitPrototype` rejects names that collide with runtime/libc symbols
 (`isReservedRuntimeName`), builtins, or enum values. Signatures retain the first
-declaration spelling for LLVM lookup, independently of call-site casing.
+declaration spelling for LLVM lookup, independently of call-site casing. Methods use
+`Class.Method` names and a hidden leading receiver address; their FuncSig parameters
+contain only explicit source parameters. Method prototypes are pre-registered too.
 
 **Parameter modes are sticky and BYREF is procedure-only (guide §8.3).** In
 `(BYREF a : T, b : T)` the `b` is BYREF too; unannotated parameters default to
diff --git a/AGENTS/PITFALLS.md b/AGENTS/PITFALLS.md
index 48b1cdb..bae6bd3 100644
--- a/AGENTS/PITFALLS.md
+++ b/AGENTS/PITFALLS.md
@@ -77,11 +77,16 @@ test programs.
   already-invalid programs can hit it).
 
 - **CLASS subset (§10).** `CLASS`/`ENDCLASS`/`PUBLIC`/`PRIVATE` are reserved.
-  CLASS is a top-level record-derived value type with optional per-field access
+  CLASS is a top-level record-derived value type with optional per-member access
   keywords (no DECLARE). Omitting access defaults to public, per the guide.
   TYPE fields cannot specify access and remain public. Private fields
-  cannot be accessed externally; whole-value initialization/copying is allowed.
-  CLASS inherits record limitations, including no array fields or empty bodies.
+  and methods cannot be accessed outside methods of the owning class;
+  whole-value initialization/copying is allowed. Methods modify the receiver;
+  `this` aliases the object itself, not a pointer. `this <- Other` copies a value.
+  Bare fields are supported, but calls to the current object's methods require
+  `this.Method(...)`; unqualified calls remain global. Parameters and local
+  declarations shadowing fields warn without failing compilation. Method-only
+  classes are allowed; empty classes and array fields remain unsupported.
 
 - **Exception extensions.** TRY requires exactly one parameterless CATCH and
   ENDTRY. Bare THROW raises a new anonymous exception even inside CATCH; there is
@@ -109,7 +114,7 @@ SET types (`SET`/`DEFINE` are reserved with dedicated errors),
 random files (OPENFILE...FOR RANDOM/SEEK/GETRECORD/PUTRECORD — TYPE is done, so these
 are unblocked now; the RANDOM keyword is reserved and gives a dedicated parse error),
 DATE, string escape sequences,
-array-typed record fields, whole-array RETURN, class methods/constructors/destructors,
+array-typed record fields, whole-array RETURN, class constructors/destructors,
 NEW and class inheritance. Compiler fixtures now live in `tests/` (see TESTING.md).
 Nightly CI runs the compiler suites, packaged EMBEDDED smoke checks and existing
 plugin tests. The initial standard conflicts and missing diagnostic locations are fixed on
diff --git a/AGENTS/SUBSYSTEMS.md b/AGENTS/SUBSYSTEMS.md
index e564c1f..b21386d 100644
--- a/AGENTS/SUBSYSTEMS.md
+++ b/AGENTS/SUBSYSTEMS.md
@@ -62,9 +62,24 @@ Shared body/field parsing lives in `ParserType.cc`. TYPE fields always have
 `IsPublic = true`; CLASS fields default to public or accept an explicit
 PUBLIC/PRIVATE keyword and carry that flag through `defineRecord` into
 `RecordFieldInfo`. Both the static
-designator type walk and `emitLValue` reject private field access, including
-address-of, array elements and pointer dereferences. There is no class method
-context or language-level inheritance yet.
+designator type walk and `emitLValue` check private field access against the
+current method's owning class, including address-of, array elements and pointer
+dereferences. Other instances of the same class are accessible from its methods.
+
+Class ASTs also own their `FunctionDefAST` methods. PrototypeAST retains the owner
+and access level; `getLinkName()` qualifies method symbols as `Class.Method`, while
+global function names remain unmangled. CodeGen registers methods separately in
+`ClassMethods` and pre-registers their prototypes after the type pre-pass.
+`MemberCallExprAST` keeps an addressable receiver separate from explicit arguments;
+`MemberCallStmtAST` discards its result. `emitMemberCall` checks access and prepends
+the receiver address to arguments marshalled by the existing `marshalCallArgs`.
+The hidden receiver is not part of FuncSig's explicit parameter list.
+FunctionGen binds field aliases and `this` to the incoming receiver storage before
+binding explicit parameters. CodeGen saves/restores `CurrentClass` around each
+function body; unqualified calls still resolve globally. Local declarations and
+parameters may shadow fields with a source-line warning; `this.Field` remains
+explicit. `this` cannot be redeclared within methods. Constructors and language-level
+inheritance remain unsupported.
 
 **Runtime checks** (`RuntimeCheck`): array bounds, file misuse, enum ranges, null
 dereferences and array-parameter bounds contracts are checked at their emit sites.