Update CLAUDE.md and NOTEBOOK.md for 1.2.3 release

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: respencer-ncl

CLAUDE.md

@@ -301,6 +301,32 @@ When implementing new code:
 **Cause**: sbt-ossuminc 1.0.0 API change
 **Fix**: Use `With.ScalaJS` instead
 
+### Error: "No given instance of PlatformContext for default parameter"
+**Cause**: Scala 3.7.4 limitation — default parameter values in a case
+class's first parameter list cannot resolve `given` instances from a
+subsequent `using` clause in the generated companion `apply` method.
+**Fix**: Remove the default value. May be fixed in 3.9.x LTS.
+**Example**:
+```scala
+// This fails in 3.7.4:
+case class Foo(x: Bar = Bar())(using PlatformContext)
+// Fix: remove default (or provide explicit given)
+case class Foo(x: Bar)(using PlatformContext)
+```
+
+### Error: "parameters with defaults must be at the end" (Scala.js)
+**Cause**: `@JSExportTopLevel` on a case class with `(using
+PlatformContext)` in a second parameter list. The JS export sees the
+context parameter as a non-default parameter after defaulted params.
+**Fix**: Remove `@JSExportTopLevel` from internal data structures that
+don't need to be constructed from JS code.
+
+### System.lineSeparator() returns null in Scala.js
+**Cause**: `System.lineSeparator()` returns `\0` in Scala.js
+**Fix**: Use `PlatformContext.newline` instead. Never use
+`System.lineSeparator()` in shared code. The `FileBuilder` trait
+and its entire hierarchy use `(using PlatformContext)` for this.
+
 ## File Organization
 
 ### Creating New Modules
@@ -622,3 +648,7 @@ Then add to root aggregation: `.aggregate(..., mymodule, mymoduleJS, mymoduleNat
 14. **BAST location comparisons use offsets** - Compare offset/endOffset, not line/col
 15. **Scala version changes require workflow updates** - Update `scala-X.Y.Z` paths in workflows
 16. **All RIDDL documentation goes to ossum.tech** - Don't add docs to this repo's `doc/` directory
+17. **Never use System.lineSeparator() in shared code** - Use `PlatformContext.newline` instead; returns `\0` in Scala.js
+18. **FileBuilder requires PlatformContext** - `trait FileBuilder(using PlatformContext)` — all subclasses must propagate the using clause
+19. **Scala 3.7.4 default param limitation** - Case class defaults can't resolve givens from a subsequent using clause in generated apply; remove defaults or provide explicit givens
+20. **@JSExportTopLevel incompatible with using clauses** - Don't use on case classes that have `(using PlatformContext)` in a second parameter list

NOTEBOOK.md

@@ -12,8 +12,11 @@ This is the central engineering notebook for the RIDDL project. It tracks curren
 compiler infinite loop bug with opaque types/intersection types in 3.3.x).
 All workflow paths updated to `scala-3.7.4`.
 
-**Release 1.2.2 Published**: Fixed Scala.js null newline bug that was causing error
-message truncation in synapify. All 715 tests pass. Published to GitHub Packages.
+**Release 1.2.3 Published**: Comprehensive fix for all
+`System.lineSeparator()` calls in shared code that returned `\0` in
+Scala.js. Added `(using PlatformContext)` to `FileBuilder` trait and
+propagated through entire hierarchy. All tests pass. Published to
+GitHub Packages. Merged to main.
 
 **Packaging Infrastructure**: Docker, npm, and TypeScript support added:
 - `Dockerfile` — Multi-stage build with custom JRE via jlink (~80-100MB image)
@@ -153,6 +156,76 @@ The `pseudoCodeBlock` parser now allows comments before and/or after `???`:
 
 ## Session Log
 
+### February 3, 2026 (Release 1.2.3 - System.lineSeparator Fix)
+
+**Focus**: Comprehensive fix for `System.lineSeparator()` returning
+`\0` null bytes in Scala.js shared code
+
+**Root Cause**: `System.lineSeparator()` returns `\0` in Scala.js,
+not just in `Messages.scala` (fixed in 1.2.2) but throughout all
+shared code including `FileBuilder`, `StringHelpers`, and command
+files.
+
+**Approach**: The architecturally correct fix — added
+`(using PlatformContext)` trait parameter to `FileBuilder` and
+propagated through the entire class hierarchy. This ensures all
+code uses `pc.newline` which returns the correct value per platform.
+
+**Work Completed**:
+1. ✅ **Fixed JVM/Native PlatformContext** — Changed hardcoded
+   `"\n"` to `System.lineSeparator()` (correct on these platforms)
+2. ✅ **Fixed Messages.scala** — Changed `System.lineSeparator()`
+   to existing `nl` constant
+3. ✅ **Fixed StringHelpers.toPrettyString** — Added
+   `(using PlatformContext)`, uses `pc.newline`
+4. ✅ **Fixed FileBuilder hierarchy** — Added
+   `(using PlatformContext)` trait parameter, propagated through:
+   `OutputFile`, `TextFileWriter`, `RiddlFileEmitter`,
+   `PrettifyState`, `PrettifyVisitor`, `PrettifyOutput`
+5. ✅ **Fixed Command files** — Replaced `System.lineSeparator()`
+   with `io.newline`/`pc.newline` in `Command.scala`,
+   `HelpCommand.scala`, `AboutCommand.scala`
+6. ✅ **Fixed JS export issues** — Removed `@JSExportTopLevel`
+   from `PrettifyState` and `PrettifyOutput` (incompatible with
+   `using` parameter lists in Scala.js exports)
+7. ✅ **All tests pass** — 715+ JVM tests, JS and Native compile
+8. ✅ **Released 1.2.3** — Tagged, published to GitHub Packages,
+   merged to main, GitHub release created
+
+**Scala 3.7.4 Compiler Limitation Discovered**:
+Default parameter values in a case class's first parameter list
+cannot resolve `given` instances from a subsequent `using` clause
+in the generated companion `apply` method. Worked around by
+removing the default value for `PrettifyOutput.state` (only call
+site provides it explicitly anyway). Documented with comment noting
+potential fix in 3.9.x LTS.
+
+**Commits** (on development, merged to main):
+- `5bcfbc68` - Fix System.lineSeparator() returning null bytes in
+  Scala.js
+
+**Files Modified** (18 files):
+- `utils/shared/.../FileBuilder.scala` — trait parameter
+- `utils/shared/.../StringHelpers.scala` — using clause
+- `utils/shared/test/.../StringHelpersTest.scala`
+- `utils/jvm/.../JVMPlatformContext.scala`
+- `utils/native/.../NativePlatformContext.scala`
+- `utils/jvm-native/.../OutputFile.scala`
+- `utils/jvm-native/.../TextFileWriter.scala`
+- `utils/jvm/test/.../FileBuilderTest.scala`
+- `utils/jvm/test/.../TextFileWriterTest.scala`
+- `language/shared/.../Messages.scala`
+- `passes/shared/.../PrettifyPass.scala`
+- `passes/shared/.../PrettifyState.scala`
+- `passes/shared/.../PrettifyVisitor.scala`
+- `passes/shared/.../RiddlFileEmitter.scala`
+- `passes/jvm-native/test/.../RiddlFileEmitterTest.scala`
+- `commands/shared/.../Command.scala`
+- `commands/shared/.../AboutCommand.scala`
+- `commands/shared/.../HelpCommand.scala`
+
+---
+
 ### February 3, 2026 (Packaging Infrastructure)
 
 **Focus**: Packaging infrastructure for Docker, npm, TypeScript, and
@@ -995,4 +1068,4 @@ Tool(
 ## Git Information
 
 **Branch**: `main`
-**Latest release**: 1.2.2 (February 3, 2026)
+**Latest release**: 1.2.3 (February 3, 2026)