docs: documentation for upstream 1.1.0, one place per fact (#514)

* docs: keep each fact in the doc comment of its declaration

README.md is an overview. Pages that mirrored the API are removed or cut to cross-component material, and each declaration fact lives in its /// doc comment. Doc comments that the code contradicted are corrected. mkdocs navigation drops the removed pages. No code changes.

* fix(docs): repair trimmed documentation checks

* docs: restore event-loop state docs and the _closeBusy parameter reference

* dcm: record the lower calculate-metrics count (12 to 9)

Author: runyaga

.github/workflows/ci.yaml

@@ -125,8 +125,8 @@ jobs:
           test -s out-mk/llms.txt
           test -s out-mk/llms-full.txt
           n=$(find out-mk -name '*.md' | wc -l)
-          echo "raw .md endpoints: $n (floor 24)"
-          [ "$n" -ge 24 ] || { echo "FAIL: expected at least 24 raw .md endpoints, found $n"; exit 1; }
+          echo "raw .md endpoints: $n (floor 19)"
+          [ "$n" -ge 19 ] || { echo "FAIL: expected at least 19 raw .md endpoints, found $n"; exit 1; }
 
       - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
         if: always()

CONTRIBUTING.md

@@ -69,8 +69,14 @@ bash example/web/run.sh
 ```bash
 bash tool/gate.sh                        # Run ALL quality checks
 bash tool/test_python_ladder.sh          # Python ladder (WASM, headless Chrome)
+bash tool/check_core_ref.sh              # Check the shared core Git ref
+bash tool/check_no_core_src_imports.sh   # Keep imports on core's public API
 ```
 
+`tool/check_core_ref.sh` keeps every tracked YAML core reference on the pin in
+`pubspec.yaml`. `tool/check_no_core_src_imports.sh` rejects imports from core
+implementation libraries.
+
 ## Code Quality
 
 Run these checks after every code change:
@@ -298,7 +304,8 @@ After publishing:
 The project has a single `CHANGELOG.md` at the root. During development, add
 entries under `## Unreleased`. Before publishing, rename `## Unreleased` to the
 version heading. pub.dev displays the CHANGELOG entry matching the published
-version as the release notes.
+version as the release notes. Document every breaking change. Pin versions and
+read the changelog before upgrading.
 
 ### pub.dev admin setup (one-time)
 

README.md

@@ -8,148 +8,74 @@
 [![Pages](https://github.com/runyaga/dart_monty/actions/workflows/pages.yaml/badge.svg)](https://runyaga.github.io/dart_monty/)
 [![codecov](https://codecov.io/gh/runyaga/dart_monty/graph/badge.svg)](https://codecov.io/gh/runyaga/dart_monty)
 
-[Live Demo](https://runyaga.github.io/dart_monty/) | [Documentation](https://github.com/runyaga/dart_monty/tree/main/docs) | [GitHub](https://github.com/runyaga/dart_monty)
+`dart_monty` runs restricted Python from Dart and Flutter on native and web
+platforms. It adds stateful runtimes, Dart host functions, extensions, event
+streams, and OS-call policy to the pool and session primitives supplied by
+`dart_monty_core`.
 
-Sandboxed Python interpreter for Dart and Flutter. Run Python from native, web, and mobile — one package, every platform.
+## Installation
 
-## Quick Start
-
-### Install
-
-```sh
-dart pub add dart_monty
-```
-
-The low-level bindings (`dart_monty_core`) are pulled in transitively.
-
-Flutter Web uses the worker assets declared by core's `flutter.assets`
-stanza and core's asset-path probe. Both packages remain pure Dart; no
-Flutter SDK dependency or initialization call is added to core.
-See [installation](docs/user/install.md#flutter-web) for bundling details.
-
-For local development against a worktree, override with `path:`
-deps:
+The package and its core dependency are released from matching Git tags. Add
+the package and override core in the application `pubspec.yaml`:
 
 ```yaml
 dependencies:
   dart_monty:
-    path: /path/to/dart_monty
-  dart_monty_core:
-    path: /path/to/dart_monty_core
-```
+    git:
+      url: https://github.com/runyaga/dart_monty.git
+      ref: v0.110.0-dev.4
 
-Then import the package:
-
-```dart
-import 'package:dart_monty/dart_monty.dart';
+dependency_overrides:
+  dart_monty_core:
+    git:
+      url: https://github.com/runyaga/dart_monty_core.git
+      ref: v0.110.0-dev.4
 ```
 
-Now you can use `dart_monty` in three ways:
+See [Installation](docs/user/install.md) for direct core imports and local
+worktree dependencies.
 
-**1. One-shot execution**
-
-Use a pool and a session for execution:
+## Quick start
 
 ```dart
-final value = await Monty.withPool(
-  (pool) => pool.withSession((session) => session.feedRun('2 + 2')),
-);
-print(value.dartValue); // 4
-```
-
-**2. Stateful session**
+import 'package:dart_monty/dart_monty.dart';
 
-```dart
-await Monty.withPool((pool) async {
-  final session = await pool.checkout(typeCheck: true);
+Future<void> main() async {
+  final runtime = await MontyRuntime.start();
   try {
-    await session.feedRun('x: int = 42');
-    final result = await session.feedRun('x * 2');
-    print(result.dartValue); // 84
+    await runtime.execute('x = 41').result;
+    final value = await runtime.execute('x + 1').result;
+    print(value.dartValue); // 42
   } finally {
-    await session.close();
+    await runtime.dispose();
   }
-});
-```
-
-Type checking happens before each feed runs. A rejected feed throws
-`MontyTypingError`, available from core's public library. See the
-[type-checking example](example/type_check_demo.dart) for `typeCheckStubs`.
-
-**3. Runtime with host functions and extensions**
-
-`MontyRuntime` manages host functions, extensions, and long-lived sessions.
-Register `HostFunction`s to expose Dart callbacks to Python:
-
-```dart
-Future<void> main() async {
-  final runtime = (await MontyRuntime.start())
-    ..register(HostFunction(
-      schema: const HostFunctionSchema(
-        name: 'fetch',
-        description: 'Fetch a URL',
-        params: [HostParam(name: 'url', type: HostParamType.string)],
-      ),
-      // DispatchMode.future lets Python `await fetch(url)` directly.
-      // asyncio.gather over multiple calls runs them concurrently.
-      dispatch: DispatchMode.future,
-      handler: (args, _) async => httpClient.get(args['url']! as String),
-    ));
-
-  final result = await runtime.execute(
-    'await fetch(base_url)',
-    inputs: {'base_url': 'https://example.com/api'},
-  ).result;
-  print(result.dartValue);
-  await runtime.dispose();
 }
 ```
 
-For plugin-style wiring, pass `extensions`:
-
-```dart
-final runtime = await MontyRuntime.start(
-  extensions: [EventLoopExtension()],
-);
-```
-
-## Examples
-
-Runnable end-to-end demos, all platform-agnostic (FFI on the VM, WASM
-in Chrome — `Monty` dispatches to the same Rust ABI on every backend):
+See [Choosing an API](docs/user/api-reference.md) for the runtime and direct
+session tradeoffs.
 
-| File | What it shows |
-|---|---|
-| [`example/example.dart`](example/example.dart) | Minimal pool/session one-shots, including error handling. |
-| [`example/type_check_demo.dart`](example/type_check_demo.dart) | Session type checking with `checkout(typeCheck: true)` and `typeCheckStubs`. |
-| [`example/dataclass_demo.dart`](example/dataclass_demo.dart) | Stateful dataclass round-trip across `MontyRuntime.execute` calls — produce, attribute-access, return, and re-bind a `@dataclass`, hydrating into a typed Dart `User` on the way back. |
+## Platform support
 
-Run any of them with `dart run example/<file>.dart` from the repo root.
-For the native and web runners (with built Rust library and a COOP/COEP
-server), see `example/native/run.sh` and `example/web/run.sh`.
+The Dart VM and Flutter native targets use core's native worker. Browser
+targets use its Web Worker and WASM assets. Web deployments require the
+worker assets and cross-origin isolation headers. Native applications that use
+`MountDir` or self-contained executables must opt in to core's worker build.
+See [Deployment and Bundling](docs/user/deployment.md) for those constraints.
 
 ## Documentation
 
-- [**Installation**](docs/user/install.md) — Add to your project
-- [**Overview**](docs/help.md) — API summary and quick start
-- [**Architecture**](docs/architecture/overview.md) — Module structure and internals
-- [**REPL Guide**](docs/user/repl.md) — Stateful interactive execution
-- [**Extensions**](docs/user/extensions.md) — EventLoop, Sandbox
-- [**Contributing**](CONTRIBUTING.md) — Build, run tests, gate scripts, release process
-- [**Contributor Setup**](docs/contributor/setup.md) — Toolchain install (Rust, Dart, Python)
-
-## Stability and versioning
-
-This package does **not** follow semantic versioning. Breaking changes can
-land in any release. The [CHANGELOG](CHANGELOG.md) is kept up-to-date with
-every breaking change, so pin to a specific version and read the changelog
-before upgrading.
+- [Stateful and concurrent execution](docs/deep-dives/bridge-concurrency.md)
+- [Host functions](docs/tutorials/host-functions-intro.md)
+- [Extensions](docs/deep-dives/extension-system.md)
+- [Sandbox lifecycle and isolation](docs/deep-dives/sandbox-architecture.md)
+- [Filesystem and workspace policy](docs/deep-dives/oscall-vfs.md)
+- [Failure propagation](docs/deep-dives/error-hierarchy.md)
+- [Testing](docs/contributor/testing.md)
 
-We expect to stabilise the API and adopt semver when the package goes into
-production — roughly 1–3 months from now. If you are planning to depend on
-this package, please open an issue so we can factor your use-case into the
-stabilisation work.
+The public declarations are listed in
+[`lib/dart_monty.dart`](lib/dart_monty.dart).
 
 ## License
 
-MIT License. See [LICENSE](LICENSE).
+The package uses the [MIT License](LICENSE).

docs/architecture/core-boundary.md

@@ -1,27 +1,21 @@
 # Core and dart_monty ownership
 
-`dart_monty` pins the complete M6 core at
-`e962659e47d41e7b6bce3f15408f521940a3fcc7`. All five YAML references, browser
-asset links and examples agree on that commit.
+`dart_monty_core` owns sessions, worker transport, Python values, resource
+limits, host mounts, memory files, and OS-call defaults. Applications import
+additional core primitives from its public library. `dart_monty` imports no
+core implementation libraries.
 
-Core owns sessions, worker transport, values, OSAccess memory files, host mounts
-and OS-call defaults. Applications import those primitives from core's public
-library. dm exports nine selected core names and 36 dm names (45 total after
-D4a), and imports no core implementation libraries.
+`dart_monty` owns bridge events, host-function dispatch, extensions, runtime
+state, and private sandbox workspace composition. Workspace code uses core's
+public `OSAccess`, `MemoryFile`, snapshot, and mount operations.
 
-The bridge drives public session feeds and reports host events. Extensions own
-application capabilities. Private workspace composition owns sandbox copy-in,
-collection, read-only protection, caps and disposal leases; it uses public
-`OSAccess` and `MemoryFile` operations. No legacy filesystem implementations or
-conditional filesystem exports remain in dm.
+`OSAccess` is a memory namespace. `MountDir` is native host backing. Native
+backing stays behind conditional imports so browser builds do not load native
+helpers.
 
-`OSAccess` is a memory namespace; `MountDir` is native host backing. They are
-different facilities. D4b supplies owned native backing, a private driver over
-public snapshots, and bounded persistent transfer sessions. Conditional imports
-keep native helpers out of web builds. Child checkout remains the D1-8 stub
-until D5. D5 keeps child state and error implementation details private.
+The facade in `lib/dart_monty.dart` is the supported package surface.
+[dart_monty.dart](https://github.com/runyaga/dart_monty/blob/main/lib/dart_monty.dart)
+exports the core and high-level declarations.
 
-See [workspace policy](../deep-dives/oscall-vfs.md) for the current transfer and
-accounting contract. Surface goldens and compiler fixtures enforce the facade;
-`tool/check_core_ref.sh` and `tool/check_no_core_src_imports.sh` enforce the
-pin and package boundary.
+See [Filesystem and workspace policy](../deep-dives/oscall-vfs.md) for transfer,
+accounting, and disposal guarantees.