some order to outdated and special docs

docs/ai_language_reference.md

@@ -1,5 +1,7 @@
 # Lyng Language Reference for AI Agents (Current Compiler State)
 
+[//]: # (excludeFromIndex)
+
 Purpose: dense, implementation-first reference for generating valid Lyng code.
 
 Primary sources used: `lynglib/src/commonMain/kotlin/net/sergeych/lyng/{Parser,Token,Compiler,Script,TypeDecl}.kt`, `lynglib/stdlib/lyng/root.lyng`, tests in `lynglib/src/commonTest` and `lynglib/src/jvmTest`.

docs/ai_notes_wasm_generation_bug.md

@@ -1,5 +1,7 @@
 # AI notes: avoid Kotlin/Wasm invalid IR with suspend lambdas
 
+[//]: # (excludeFromIndex)
+
 ## Do
 - Prefer explicit `object : Statement()` with `override suspend fun execute(...)` when building compiler statements.
 - Keep `Statement` objects non-lambda, especially in compiler hot paths like parsing/var declarations.

docs/ai_stdlib_reference.md

@@ -1,5 +1,7 @@
 # Lyng Stdlib Reference for AI Agents (Compact)
 
+[//]: # (excludeFromIndex)
+
 Purpose: fast overview of what is available by default and what must be imported.
 
 Sources: `lynglib/src/commonMain/kotlin/net/sergeych/lyng/Script.kt`, `lynglib/stdlib/lyng/root.lyng`, `lynglib/src/commonMain/kotlin/net/sergeych/lyng/stdlib_included/observable_lyng.kt`.

docs/embedding.md

@@ -1,5 +1,7 @@
 # Embedding Lyng in your Kotlin project
 
+[//]: # (topMenu)
+
 Lyng is a tiny, embeddable, Kotlin‑first scripting language. This page shows, step by step, how to:
 
 - add Lyng to your build

docs/fix-scope-parent-cycle.md

@@ -1,34 +0,0 @@
-## Fix: prevent cycles in scope parent chain during pooled frame reuse
-
-### What changed
-- Scope.resetForReuse now fully detaches a reused scope from its previous chain/state before re-parenting:
-  - sets `parent = null` and regenerates `frameId`
-  - clears locals/slots/bindings caches
-  - only after that, validates the new parent with `ensureNoCycle` and assigns it
-- ScopePool.borrow on all targets (JVM, Android, JS, Native, Wasm) now has a defensive fallback:
-  - if `resetForReuse` throws `IllegalStateException` indicating a parent-chain cycle, the pool allocates a fresh `Scope` instead of failing.
-
-### Why
-In some nested call patterns (notably instance method calls where an instance is produced by another function and immediately used), the same pooled `Scope` object can be rebound into a chain that already (transitively) contains it. Reassigning `parent` in that case forms a structural cycle, which `ensureNoCycle` correctly detects and throws. This could surface as:
-
-```
-IllegalStateException: cycle detected in scope parent chain assignment
-  at net.sergeych.lyng.Scope.ensureNoCycle(...)
-  at net.sergeych.lyng.Scope.resetForReuse(...)
-  at net.sergeych.lyng.ScopePool.borrow(...)
-  ... during instance method invocation
-```
-
-The fix removes the failure mode by:
-1) Detaching the reused frame from its prior chain/state before validating and assigning the new parent.
-2) Falling back to a new frame allocation if a cycle is still detected (extremely rare and cheap vs. a crash).
-
-### Expected effects
-- Eliminates sporadic `cycle detected in scope parent chain` crashes during instance method invocation.
-- No change to public API or normal semantics.
-- Pooling remains enabled by default; the fallback only triggers on the detected cycle edge case.
-- Negligible performance impact: fresh allocation is used only when a cycle would have crashed the VM previously.
-
-### Notes
-- The fix is platform-wide (all ScopePool actuals are covered).
-- We recommend adding/keeping a regression test that exercises: a class with a method, a function returning an instance, and an exported function calling the instance method. The test should pass without exceptions.

docs/migrate_time_to_2_2.md

@@ -1,25 +0,0 @@
-# Migration of Instant and Clock
-
-## History
-
-Before kotlin 2.0, there was an excellent library, kotlinx.datetime, which was widely used everywhere, also in Lyng and its dependencies.
-
-When Kotlin 2.0 was released, or soon after, JetBrains made a perplexing decision to remove `Instant` and `Clock` from kotlinx.datetime and replace it with _yet experimental_ analogs in `kotlin.time`.
-
-The problem is, these were not quite the same (these weren't `@Serializable`!), so people didn't migrate with ease. Okay, then JetBrains decided to not only deprecate it but also make them unusable on Apple targets. It sort of split auditories of many published libraries to those who hate JetBrains and Apple and continue to use 1.9-2.0 compatible versions that no longer work with Kotlin 2.2 on Apple targets (but work pretty well with earlier Kotlin or on other platforms). 
-
-Later JetBrains added serializers for their new `Instant` and `Clock` types, but strangely not in the stdlib, but in newer versions of `kotlinx.serialization`. This means that plain upgrade of dependencies to 2.2 is not enough to make them work.
-
-## Solution
-
-We hereby publish a new version of Lyng, 1.0.8-SNAPSHOT, which uses `kotlin.time.Instant` and `kotlin.time.Clock` instead of `kotlinx.datetime.Instant` and `kotlinx.datetime.Clock`. It is in other aspects compatible also with Lynon encoded binaries. You might need to migrate your code to use `kotlin.time` types. (LocalDateTime/TimeZone still come from `kotlinx.datetime`.)
-
-So, if you are getting errors with new version, please do:
-
-- upgrade to Kotlin 2.2
-- upgrade to Lyng 1.0.8-SNAPSHOT
-- replace in your code imports (or other uses) of `kotlinx.datetime.Clock` to `kotlin.time.Clock` and `kotlinx.datetime.Instant` to `kotlin.time.Instant`.
-
-This should solve the problem and hopefully we'll see no more such "brilliant" ideas from IDEA ideologspersons.
-
-Sorry for inconvenience and send a ray of hate to JetBrains ;)

docs/wasm_generation_bug.md

@@ -1,27 +0,0 @@
-# Wasm generation hang in wasmJs browser tests
-
-## Summary
-The wasmJs browser test runner hung after commit 5f819dc. The root cause was invalid WebAssembly generated by the Kotlin/Wasm backend when certain compiler paths emitted suspend lambdas for `Statement` execution. The invalid module failed to instantiate in the browser, and Karma kept the browser connected but never ran tests.
-
-## Symptoms
-- `:lynglib:wasmJsBrowserTest` hangs indefinitely in ChromeHeadless.
-- `:lynglib:wasmJsNodeTest` fails with a WebAssembly compile error similar to:
-  - `struct.set expected type (ref null XXXX), found global.get of type (ref null YYYY)`
-- The failing function name in the wasm name section looks like:
-  - `net.sergeych.lyng.$invokeCOROUTINE$.doResume`
-
-## Root cause
-The delegation/var-declaration changes introduced compiler-generated suspend lambdas inside `Statement` construction (e.g., `statement { ... }` wrappers). Kotlin/Wasm generates extra coroutine state for those suspend lambdas, which in this case produced invalid wasm IR (mismatched GC reference types). The browser loader then waits forever because the module fails to instantiate.
-
-## Fix
-Avoid suspend-lambda `Statement` construction in compiler code paths. Replace `statement { ... }` and other anonymous suspend lambdas with explicit `object : Statement()` implementations and move logic into `override suspend fun execute(...)`. This keeps the resulting wasm IR valid while preserving behavior.
-
-## Where it was fixed
-- `lynglib/src/commonMain/kotlin/net/sergeych/lyng/Compiler.kt`
-- `lynglib/src/commonMain/kotlin/net/sergeych/lyng/Scope.kt`
-
-## Verification
-- `./gradlew :lynglib:wasmJsNodeTest --info`
-- `./gradlew :lynglib:wasmJsBrowserTest --info`
-
-Both tests finish quickly after the change.