diff --git a/content/guide/pathways.md b/content/guide/pathways.md
new file mode 100644
index 00000000..b8c945ae
--- /dev/null
+++ b/content/guide/pathways.md
@@ -0,0 +1,37 @@
+---
+title: Two pathways
+description: NativeScript is your development runtime, not your production runtime. Write SwiftUI and develop it live, or write TypeScript and compile the release to native code.
+contributors:
+  - NathanWalker
+---
+
+NativeScript has always run your app on a JavaScript runtime with direct access to every platform API. It now offers
+two pathways that keep that development experience and ship **no JavaScript runtime at all**:
+
+|  | 1. SwiftUI, live | 2. TypeScript, compiled |
+| --- | --- | --- |
+| **You write** | SwiftUI, in an Xcode project | TypeScript with `@nativescript/core` and the framework you like (Angular, Vue, React, Svelte, Solid, plain TypeScript) |
+| **While developing** | NativeScript runs your SwiftUI views live: each save is on screen in about 0.15–0.5 s, state kept | `ns run`: the JavaScript runtime with HMR, Chrome DevTools and the whole npm ecosystem, exactly as today |
+| **What ships** | Your Swift, built by Xcode as usual | Your app compiled to Swift (iOS) and Kotlin (Android) by `ns build --compiled` |
+| **Platforms** | iOS; Android live development, rendered by Jetpack Compose | iOS and Android |
+| **Status** | [Preview](/guide/swiftui-live) | [Preview](/guide/publishing/compiled) |
+
+Both rest on the same idea: **develop live, ship native.** The development runtime gives you instant feedback; the
+release is the native code a platform developer would have shipped.
+
+## Which one fits
+
+- **You know SwiftUI, or you are starting an iOS-first app in Swift**: take [SwiftUI, live](/guide/swiftui-live).
+  You keep Xcode, Swift and your project as they are; NativeScript only shortens the edit-to-screen loop.
+- **You know web development, or you already have a NativeScript app**: take
+  [TypeScript, compiled](/guide/publishing/compiled). Nothing changes while you develop. The release build is
+  compiled instead of bundled.
+
+The two meet at the release: both ship native code with no engine inside, and both are checked the same way,
+pixel by pixel against the build they replace.
+
+## The JavaScript runtime is not going anywhere
+
+A release on the JavaScript runtime (`ns build --release`) remains the default and is fully supported. Compiled
+releases are opt-in, per build or per platform, and you can switch back with `--no-compiled` at any time. See
+[Publishing](/guide/publishing/).
diff --git a/content/guide/publishing/compiled-differences.md b/content/guide/publishing/compiled-differences.md
new file mode 100644
index 00000000..c2d70a09
--- /dev/null
+++ b/content/guide/publishing/compiled-differences.md
@@ -0,0 +1,140 @@
+---
+title: "Compiled releases: supported subset and known differences"
+description: What a compiled release refuses to build, where it still behaves differently from the JavaScript release, and the versions it is tested with.
+contributors:
+  - NathanWalker
+---
+
+<!-- Sourced from the compiler's adversarial review (October 2026) and its preflight rules (packages/compiler/src/preflight.ts). Update an entry when its fix lands. -->
+
+A [compiled release](/guide/publishing/compiled) runs your TypeScript as Swift and Kotlin, against a runtime that
+reproduces JavaScript's semantics. This page lists where that stops: what the build refuses, and the differences
+known today between a compiled release and the JavaScript release of the same app. Each entry names the platform
+it affects. Check every compiled release against its JavaScript release before you ship it
+([Checking a compiled release](/guide/publishing/compiled#checking-a-compiled-release)).
+
+## What the build refuses
+
+Before anything is compiled, the compiler checks the app (and the plugin code the app reaches) and stops on each of
+these with the file, the line and what to write instead. All of them are reported at once.
+
+| Construct | Why | Instead |
+| --- | --- | --- |
+| `new Proxy(…)` | No traps without a JavaScript engine | A class with explicit getters and setters, or a `Map` for dynamic keys |
+| `Reflect.*` | Not provided by the runtime | The operation itself: `obj[key]`, `key in obj`, `Object.keys(obj)`, `new Cls(...args)` |
+| `eval(…)`, `new Function(…)` | There is no engine to evaluate code | A lookup of known functions; or keep this app on the JavaScript release |
+| `FinalizationRegistry` | Finalizers do not run | Release the resource explicitly (`dispose()`, `unloaded`, `disposeNativeView`) |
+| `SharedArrayBuffer`, `Atomics` | No shared memory between workers | An `ArrayBuffer`, with copies posted between workers |
+| `with (obj) { … }` | | Name the object explicitly |
+| `import(expr)`, `require(expr)` with a computed specifier | Every module is linked when the app is built | Import each module by a literal path, and choose among those at run time |
+| `arguments.callee`, `__proto__` | | A named function; `Object.getPrototypeOf` |
+| A bundler constant nothing defines (`declare const __API_URL__`, `process.env.X`) | It would read as undefined at run time | Define it in the bundler config: Vite's `define` and webpack's `DefinePlugin` values are read and compiled in |
+
+The build also stops, before compiling, when:
+
+- **The app's `@nativescript/core` is not the core the compiler's kit was generated from.** The kit is core's own
+  code, compiled; the native widgets it drives come from your installed core, so the two must be the same release.
+  Install the core version the message names, or the `@nativescript/compiler` released with your core.
+  `release: { allowCoreMismatch: true }` builds anyway, with a warning.
+- **A framework package is outside the versions its support is tested with** (table below).
+  `release: { allowUntestedFrameworks: true }` builds anyway, with a warning.
+- **The toolchain is missing or too old:** Xcode 26 or newer for iOS; JDK 17 or newer and the Android SDK for
+  Android.
+
+Other unsupported language and framework constructs are refused by the compiler as it meets them, with the file and
+line; see [What stops a build](/guide/publishing/compiled#what-stops-a-build).
+
+## Tested framework versions
+
+| Framework | Packages and versions |
+| --- | --- |
+| Vue | `nativescript-vue` 3.1 and later 3.x |
+| Angular | `@nativescript/angular` and `@angular/core` 22.x |
+| React | `react-nativescript` 5.x with `react` 18.2 or later 18.x |
+| Solid | `@nativescript-community/solid-js` and `solid-js` 2.0 (from 2.0.0-rc.0) |
+| Svelte | `svelte-native` 1.x with `svelte` 4.2+, or `svelte-native` 5 (from 5.0.0-alpha.0) with `svelte` 5.50+ |
+| Octane | `@nativescript-community/octane` 0.2.4 and later 0.2.x |
+
+Framework features each front end does not support yet stop the build with a message. The main ones:
+
+- **Angular:** pipes other than `async`; a pipe inside `*ngFor`/`@for`; `OnPush` under zone.js; more than one
+  `@Component` in a file. Templates are parsed with the compiler's own `@angular/compiler` 22.
+- **React:** a component body may hold function declarations, variable declarations and the `return`; a bare
+  statement such as `useEffect(() => …, [])` on its own line is refused. JSX spread attributes are refused.
+- **Vue:** `<style module>`, and Options API keys beyond the common ones.
+
+## Known differences at run time
+
+These compile and run, and behave differently from the JavaScript release. They are being fixed; until then,
+avoid relying on them.
+
+### Values and types
+
+- **`null` and `undefined` are one value in a typed optional** (both platforms). With `b?: string | null`, an
+  explicit `null` reads as `undefined`, disappears from `JSON.stringify`, and a destructuring default applies to it.
+  Code that tells `=== null` from `=== undefined` on such a field takes the wrong branch.
+- **Fields of an `Error` subclass read through `any` or `unknown` are undefined** (both): `catch (e: any) { e.code }`.
+  On Android, also after `instanceof`.
+- **A value of the wrong type in a typed slot can stop the app** instead of throwing a `TypeError` (iOS): an
+  untyped value (`any`, parsed JSON) assigned where a class or interface is declared, a downcast to the wrong
+  subclass, a definitely-assigned field (`x!: T`) read before it is set, an out-of-union value in an exhaustive
+  `switch`. Validate parsed data before typing it.
+- **Number to integer conversions of NaN, Infinity or very large values can stop the app** (iOS), where JavaScript
+  gives 0 or wraps.
+- **`valueOf()` is never called**: arithmetic on objects concatenates or gives NaN (both).
+- **`typeof SomeClass` is `"object"`** (both), and `typeof new String('x')` is `"string"`.
+- **Subclass fields are initialized before the base constructor runs** (both), so a base constructor that calls an
+  overridden method sees the subclass's fields already set.
+- **`var` in a `for` loop gets a new binding per iteration** (both), as `let` does.
+
+### Strings and regular expressions
+
+- **`\d`, `\w`, `\b` and `.` follow Unicode rules** (iOS): `\d` matches Arabic-Indic digits, `\w` matches accented
+  letters.
+- **A capture group that did not take part reads `''`**, not `undefined` (iOS).
+- **`replace` with a string pattern ignores `$&`, `` $` ``, `$'` and `$$`** (iOS).
+- **Cutting a string between the two halves of a surrogate pair gives U+FFFD** (iOS), so an emoji split and rejoined
+  is corrupted.
+- **`str[i]` past the end is `''`**, not `undefined` (both).
+- **`===` on strings compares by Unicode canonical equivalence** (iOS): `'é'` precomposed equals `'e'` + accent,
+  while `Map` and `Set` keys keep them apart.
+- **`localeCompare` ignores its locale and options** (both). `lastIndexOf(x, fromIndex)` ignores `fromIndex`.
+
+### Arrays, dates, JSON
+
+- **Holes in a `number[]` read as NaN** (iOS). **`flat(depth)` ignores the depth** (iOS).
+- **`Date.parse` accepts out-of-range ISO fields** and rolls them over (iOS).
+- **`JSON.parse` ignores a reviver** (both).
+
+### Functions, listeners and memory
+
+- **A function read twice is not `===` to itself** (iOS), so `off(handler)` and `removeEventListener` do not remove
+  a listener, and the same handler added twice runs twice. Keep the subscription handle where an API returns one.
+- **Closures stored on an object, and parent and child views, hold each other strongly** (iOS): a page navigated
+  away from may stay in memory.
+- **`WeakMap` and `WeakSet` lack ephemeron semantics** (both): a value that reaches its key keeps both alive.
+- **`WeakRef` timing differs**: on iOS a target can be freed within the job that created it; on Android a
+  `WeakRef` is a soft reference and survives ordinary collections.
+- **Script entered from a native background thread is not serialized** with the main thread (both).
+
+### Errors and crashes
+
+- **Uncaught errors are printed, and `Application.on('uncaughtError')` does not fire** (both); the
+  `uncaughtErrorPolicy` setting is not read.
+- **`error.stack`** lists the native frames the error was made in, not JavaScript frames: on iOS
+  `symbol (App+0xoffset)`, which the archive's dSYM resolves to your TypeScript lines; on Android
+  `class.method(File.kt:line)`, which `ns-native-retrace` maps to your TypeScript lines.
+- **Deep recursion crashes** (iOS) instead of throwing a `RangeError`.
+
+### Android release builds (R8)
+
+Members reached by name at run time (a method called on an `any` value, `typeof x.getFoo`, `'getFoo' in x`) are
+kept from R8's renaming by a scan of the compiled code. A name computed at run time (`x[name]()` with `name` built
+from strings) is not found by the scan; keep such members with a ProGuard rule in
+`App_Resources/Android/app.gradle`, and check the minified release on a device.
+
+By default every class and member of the kit is kept whole, which leaves most of the kit's code to R8 untouched.
+`android: { release: { narrowKitKeeps: true } }` keeps only what the kit's reflection needs (class names,
+constructors, the names of the members that remain) and lets R8 remove the rest: on Recipes (Vue) the kit's dex goes
+from 3.3 to 2.0 MB and the APK from 2.44 to 1.92 MB, with both screens matching the JavaScript release. It is opt-in
+until it has been verified on larger apps; under it, a kit member reached only through a computed name is removed.
diff --git a/content/guide/publishing/compiled.md b/content/guide/publishing/compiled.md
new file mode 100644
index 00000000..e58a94c7
--- /dev/null
+++ b/content/guide/publishing/compiled.md
@@ -0,0 +1,427 @@
+---
+title: Compiled releases
+description: Build a release of your NativeScript app compiled to Swift and Kotlin, with no JavaScript runtime inside, using one flag.
+contributors:
+  - NathanWalker
+---
+
+<!-- Keep in step with the compiler's CLI.md, README.md and STATUS.md in NativeScript/swiftui-live. -->
+
+::: warning Preview
+Compiled releases are in preview. To use, `npm install -g nativescript@beta`. The `--compiled` flag works with the `beta` CLI and the
+`@nativescript/compiler`. This page describes how it works and what it supports.
+:::
+
+A compiled release is the TypeScript pathway's release (see [Two pathways](/guide/pathways)). You develop with
+`ns run|debug` exactly as today: using the JavaScript runtime, HMR, Chrome DevTools. When you build the release, the `--compiled` flag 
+compiles your app to **Swift on iOS and Kotlin on Android**, and the app ships no JavaScript engine, no bundle and no NativeScript runtime.
+
+```bash
+ns build ios --compiled
+```
+
+## The short version
+
+- **One flag.** `--compiled` on `ns build`, `ns run` or `ns deploy`, or `release: { compiled: true }` in
+  `nativescript.config.ts`. It implies `--release`.
+- **Most apps compile without source changes.** The compiler reads the TypeScript you already have, the framework
+  you already use, and your plugins' own TypeScript source. The apps compiled so far (four proof apps and two store
+  apps) changed no source; some added configuration.
+- **What it knows it cannot run, it refuses.** Before compiling, a check reports every construct outside the
+  supported subset (`Proxy`, `eval`, a computed `import()`, an undefined bundler constant…) with the file, the line
+  and what to write instead, and the build stops on a core or framework version it was not built for. This is not a
+  proof that the rest behaves identically: the [known differences](/guide/publishing/compiled-differences) still
+  apply, so check each release against its JavaScript build.
+- **It is checked against the release it replaces.** Proof apps are compared with their JavaScript release builds
+  screen by screen and after the same taps: on iOS the five galleries match pixel for pixel except one HtmlView
+  screen (189 of 191 Vue gallery shots); on Android the galleries and Recipes match at 0 px. The compiler's
+  differential tests hold the runtime to Node's output: every case on iOS, and on Android all but nine known
+  failures, listed with their causes in the compiler's repository. Core's own unit-test app does not pass compiled yet: on iOS, 647 of its tests pass, 115 fail and 957
+  do not run.
+
+What you get, measured on real apps (the dates and methods are below the table):
+
+| App | JavaScript release | Compiled release |
+| --- | --- | --- |
+| Recipes (Vue), first frame, iPhone 16 Pro | 190 ms | 191 ms |
+| Recipes (Vue), memory footprint after launch, iPhone 16 Pro | 47.3 MB | 18.9 MB |
+| Recipes (Vue), `.ipa` | 14 MB | 2.35 MB |
+| ns-duo-guitar (Angular, WebGPU), Play download, arm64 | 28.1 MB | 14.6 MB |
+| openjs-app (Angular, eight plugins), Play download, arm64, 420 dpi | 28.6 MB | 15.2 MB |
+
+iOS: 2026-10-09, iOS 26.6.2, cold launch to first frame from screen recordings, median of 5 runs; memory is the
+physical footprint; the `.ipa` is unsigned, arm64. Android: 2026-10-10, sizes from the App Bundle for one device
+configuration (arm64-v8a, 420 dpi, English). The compiled release launches as fast as the JavaScript one, not
+faster; the gains are memory and size. The scripts that take these measurements, with their method in each one's
+header, are in the compiler's `bench/` folder; they record the compiler commit with every result.
+
+## Using it
+
+### Install
+
+```bash
+npm install --save-dev @nativescript/compiler
+```
+
+`@nativescript/compiler` is released with `@nativescript/core`, at core's version: install the compiler version that
+matches your core (the build checks it). It is not yet published to npm.
+
+Requirements:
+
+- **Node.js 20 or newer**, as for the CLI.
+- **`@nativescript/core` at the compiler's version**, and a framework version from the
+  [tested versions](/guide/publishing/compiled-differences#tested-framework-versions).
+- **iOS:** Xcode 26 or newer. The Xcode project is generated with [XcodeGen](https://github.com/yonaskolb/XcodeGen): yours if it is
+  installed, otherwise a pinned release the compiler downloads once into `~/Library/Caches/nativescript`, checked
+  against its published checksum. The deployment target is at least iOS 17; a lower one in `build.xcconfig` is raised,
+  and the build says so.
+- **Android:** JDK 17 or newer and the Android SDK. The compiler ships its own Gradle wrapper. Windows is not
+  supported yet.
+
+The build checks these before compiling, and names what is missing.
+
+### Build, run, deploy
+
+```bash
+ns build ios --compiled                   # simulator .app
+ns build ios --compiled --for-device      # archive and .ipa; sign with --team-id or --provision
+ns run ios --compiled                     # build, install and launch on a simulator or device
+
+ns build android --compiled --key-store-path release.keystore --key-store-password … \
+  --key-store-alias … --key-store-alias-password …     # signed .apk; add --aab for a bundle
+ns run android --compiled --key-store-path …
+```
+
+Signing works as for any release: on iOS, `--team-id` signs automatically and `--provision` signs with a profile
+(without either, the archive and `.ipa` are unsigned, with a warning); on Android, the `--key-store-*` options sign
+as Android Studio does. The app id is your project's `id`, so a compiled release installs over the JavaScript build
+of the same app, and the [store steps](/guide/publishing/) are the same.
+
+`ns run` without `--compiled`, `ns debug` and every debug build stay on the JavaScript runtime.
+
+### Make it the default
+
+```ts
+// nativescript.config.ts
+export default {
+  id: 'org.example.app',
+  release: {
+    compiled: true, // every release build is compiled
+  },
+  android: {
+    release: { compiled: false }, // except Android's, for now
+  },
+} as NativeScriptConfig
+```
+
+`--compiled` and `--no-compiled` on the command line win over the config, and a platform's `release` wins over the
+top-level one. `--no-compiled` builds one release on the JavaScript runtime whatever the config says.
+
+The output goes to `platforms/compiled/ios` and `platforms/compiled/android`, never `platforms/ios` or
+`platforms/android`: the JavaScript platform projects are left as they are. On iOS the output is an ordinary Xcode
+project you can open, build and run from Xcode.
+
+## How it works
+
+```text
+your app (TypeScript, templates, CSS)            plugins (their TypeScript source)
+                     │                                        │
+                     └──── one TypeScript program, type-checked against @nativescript/core ────┘
+                                                │
+                              compiler: Swift (iOS) / Kotlin (Android)
+                                                │
+                            + NativeScriptKit: @nativescript/core as native code
+                            + plugins' native code (platforms/ios, platforms/android), linked unchanged
+                                                │
+                               Xcode / Gradle ──▶ .app .ipa / .apk .aab
+```
+
+1. **Your framework's own parser reads your templates.** Angular, Vue, React, Svelte, Solid and Octane templates are
+   parsed by each framework's own compiler, so what you write means what it means in the framework.
+2. **Your styles go through your own build.** Your CSS pipeline (Tailwind, PostCSS, Sass) runs as your app's build runs
+   it; the result is applied as core applies CSS. Components' own styles (Vue `<style>`, including `scoped`; Angular
+   `styles` and `styleUrl`, encapsulated as NativeScript Angular encapsulates them; Svelte `<style>` where your Svelte
+   configuration injects component CSS) are scoped as their framework scopes them and added in the same order.
+3. **Everything is type-checked as one program.** The app and its plugins are checked against `@nativescript/core`'s
+   declarations, then translated. JavaScript semantics (numbers, promises and microtasks, closures, `Map`/`Set`,
+   iteration order) are reproduced exactly; the compiler's differential tests run each case under Node and as
+   compiled code and require the same output.
+4. **Core becomes NativeScriptKit.** What `@nativescript/core` does through the JavaScript runtime, the compiled app
+   does through NativeScriptKit: core's views, layouts, styling, property system and platform APIs as Swift and
+   Kotlin. On iOS, NativeScriptKit is generated from core's own TypeScript by the same compiler, so it follows core
+   release by release (see [Under the hood](#under-the-hood)).
+5. **Plugins compile from their own TypeScript.** For each plugin the compiler fetches the exact source its published
+   version was built from, checks it against the published JavaScript, and compiles it with your app. The plugin's
+   native code (`platforms/ios`, `platforms/android`: Swift, Objective-C, `.xcframework`s, CocoaPods, Swift packages,
+   Java/Kotlin, Gradle dependencies) is linked unchanged.
+6. **`App_Resources` carry over** as the CLI carries them: `Info.plist` and entitlements merged with plugins', asset
+   catalogs, the launch screen, `build.xcconfig`, the Android manifest and resources, fonts, and the files your build
+   copies (`assets/`). Native source in `App_Resources/iOS/src` is compiled into the app, and app extensions (widgets,
+   Live Activities) become their own targets.
+
+## What a compiled release supports
+
+### Frameworks
+
+| Framework | Status |
+| --- | --- |
+| Vue 3 (`<script setup>`, Options API) | Supported |
+| Angular (standalone with signals; NgModules with zone.js) | Supported; `ChangeDetectionStrategy.Default` components, the `async` pipe, a subset of RxJS |
+| Svelte 4 and 5 | Supported |
+| React (react-nativescript) | Supported |
+| Solid | Supported |
+| Octane | Supported |
+| Plain TypeScript with XML | Supported: core's own Builder makes the views from your XML, as in the JavaScript build: `{{ }}` bindings, code-behind, custom components (`xmlns:my`) and ListView templates |
+
+Core's own behavior comes with it on iOS, where the kit is core: RTL layout, Dynamic Type through
+`ios-a11y-adjusts-font-size`, `font://` icons, `background-image: url()`, box shadows and the accessibility
+properties render as in the JavaScript build, pixel for pixel. The web globals the NativeScript runtime provides are
+there too: `crypto` (`randomUUID`, `getRandomValues`, and `subtle` with SHA digests, HMAC and RSA-OAEP),
+`TextEncoder`/`TextDecoder`, `atob`/`btoa`, timers, `queueMicrotask` and `console`. `fetch` and `XMLHttpRequest`
+are not yet available in a compiled release.
+
+### Platforms
+
+| | iOS | Android |
+| --- | --- | --- |
+| Compared with the JavaScript release | Galleries in five frameworks, pixel for pixel except one HtmlView screen; xml-ts; openjs-app (store app) | Galleries (Vue 41 screens, XML, Angular, Svelte 5) and Recipes at 0 px, minified and not; openjs-app 49 shots |
+| Verified on | Simulators and an iPhone 16 Pro | Emulators and a Galaxy Z Fold3; ns-duo-guitar is on Google Play |
+| NativeScriptKit | Generated from core | Generated from core (the hand port remains behind `android.release.generatedKit: false`) |
+| Runs on | iOS 17 and later; checked on iOS 26 and 27 | Android 7 (API 24) and later |
+
+### Plugins
+
+| Kind of plugin | In a compiled release |
+| --- | --- |
+| TypeScript over native APIs (most plugins) | Compiled from the plugin's source, as part of your app |
+| Native code in `platforms/ios` / `platforms/android` | Linked unchanged |
+| Installs objects into the JavaScript engine itself (`@nativescript/canvas`) | Needs a native counterpart in the kit. Canvas has one on iOS: 2D, WebGL and WebGPU over the same native library |
+| Only meaningful with a JavaScript runtime (over-the-air JavaScript updates) | Replace it with a module of your own: `release.pluginReplacements` |
+
+### What stops a build
+
+The compiler refuses what it cannot compile faithfully, and says so with the file and line. The full list, with what
+to write instead, is on [Supported subset and known differences](/guide/publishing/compiled-differences).
+
+- **Inherently:** `eval`, `new Function`, `Proxy`, `Reflect`, loading code at run time (a computed `import()`) and
+  over-the-air JavaScript updates. There is no JavaScript to evaluate or replace. Apps that depend on these keep the
+  JavaScript release. These are found before anything is compiled, all at once.
+- **A bundler constant nothing defines**, such as `declare const __API_URL__` without a `define`. The build reads
+  Vite's `define` and webpack's `DefinePlugin` and compiles their values in.
+- **A version mismatch:** a `@nativescript/core` other than the one the compiler's kit was generated from, or a
+  framework version outside the tested ones.
+- **Language constructs not supported yet**, such as a class declared inside a function that reads the function's
+  own variables (one that reads none compiles), a `default` clause before other cases, or `return` in a `finally`
+  block. Each message names the construct.
+- **Framework features not supported yet**, such as Angular `OnPush` under zone.js, Angular pipes other than
+  `async`, more than one Angular `@Component` in a file, Vue `<style module>`, JSX spread attributes, and Vue
+  Options-API keys beyond the common ones.
+- **Plugin native code the build does not carry yet:** a prebuilt `.framework` or `.a` (an `.xcframework` is
+  fine), a resource `.bundle`, a `.podspec`, and Android `jniLibs`/`.so` files.
+
+Your project's hooks run as they do for a JavaScript build: `before-prepare`/`after-prepare` and
+`before-buildIOS`/`after-buildIOS` (`buildAndroid` on Android), with the same arguments. In a compiled build
+`projectRoot` is the compiled project (`platforms/compiled/<platform>`), so a hook that edits the runtime's Xcode or
+Gradle project under `platforms/ios` or `platforms/android` has nothing to change there.
+
+## What your app may need
+
+For most apps: **nothing but the flag.** Of the apps compiled so far, none changed their own source to compile.
+What some needed was configuration, all of it in `release`:
+
+| Situation | What to add |
+| --- | --- |
+| A plugin only meaningful with a JavaScript runtime (OTA updates such as Norrix) | `pluginReplacements: { '@norrix/client-sdk': './release/norrix.ts' }`: a module of your own with the same exports |
+| A plugin whose published source cannot be found or does not match its JavaScript | `pluginSources: { 'some-plugin': '../some-plugin' }`: a checkout of its source |
+| You patch a plugin with patch-package | The same patch against the plugin's TypeScript source, in `native-release/patches/<package>+<version>.patch`. The compiler compiles source, not the published JavaScript your existing patch changes |
+| You patch `@nativescript/core` with patch-package | The compiler recognizes common core patches and applies their effect; a core patch it does not recognize stops the build, so you know to raise it |
+| `@nativescript/core` at another version than the compiler's | Install the matching versions; `allowCoreMismatch: true` builds anyway, with a warning |
+| A framework version outside the tested ones | `allowUntestedFrameworks: true` builds anyway, with a warning |
+| An `Info.plist` that declares no `UIApplicationSceneManifest` (older app templates) | Nothing: the build adds the template's and says so. Apps built with the current iOS SDK must adopt scenes |
+
+```ts
+// nativescript.config.ts: every option
+release: {
+  compiled: true,
+  pluginReplacements: { '@norrix/client-sdk': './release/norrix.ts' },
+  pluginSources: { 'some-plugin': '../some-plugin' },
+  allowCoreMismatch: false,
+  allowUntestedFrameworks: false,
+},
+```
+
+How it went for real apps:
+
+- **openjs-app** (Angular, on the App Store): no source changes. A stand-in for its OTA update plugin, and
+  source-level copies of two plugin patches.
+- **ns-octane** (Octane, six plugins): no source changes. Its input-accessory patch was ported to the plugin's
+  source. One Swift file that called into the JavaScript runtime was left out, with a message.
+- **ns-duo-guitar** (Angular, `@nativescript/canvas` with WebGPU): no source changes needed to compile. Its AI
+  feature was left out of the release by product choice.
+
+## Checking a compiled release
+
+Treat a compiled release like any new build: compare it with the JavaScript release before you ship it.
+
+1. Build both: `ns build ios --release` and `ns build ios --compiled`, on the same version of `@nativescript/core`
+   (the compiler's kit is core at its own version). They use the same app id, so install them on separate
+   simulators, or uninstall between them (installing over a different build keeps stale files).
+2. Walk the same screens and taps in both, focusing and typing in every input, and compare. The proof apps are
+   compared pixel by pixel; differences that come from the platform itself (the clock, animation timing) are
+   expected.
+3. Watch for crashes as well as pixels: a screen can match and still fail on interaction.
+
+`ns compiled verify` does this for you on an iOS Simulator. It builds both releases, runs the same steps on each
+(from the project's `verify.json`: taps, swipes, typing, waits and shots, each screen from a fresh launch), compares
+every shot pixel by pixel once the screen settles, and fails on a difference or on an app that stops running. The
+screenshots and a `report.json` go to `platforms/compiled/verify`.
+
+```json
+{
+  "screens": [
+    { "name": "home", "steps": [["shot", "start"], ["tap", 200, 400], ["wait", 1], ["type", "Ada"], ["shot", "typed"]] }
+  ]
+}
+```
+
+## FAQ
+
+### Do I have to change my app to use `--compiled`?
+
+Usually not. The compiler reads the TypeScript, templates and CSS you already have. None of the apps compiled so
+far changed their own source; some added a few lines of `release` configuration (see
+[What your app may need](#what-your-app-may-need)). What the compiler knows it cannot run stops the build with the
+file and line. Some differences only show at run time; they are listed on
+[Supported subset and known differences](/guide/publishing/compiled-differences), and checking the release against
+its JavaScript build finds the ones that matter to your app.
+
+### How do I map a crash in a compiled release back to my TypeScript?
+
+**iOS, today:** every compiled statement carries the file and line it came from (a Swift `#sourceLocation`
+directive). The archive's dSYM therefore symbolicates crash reports straight to your `.ts`, `.vue`, `.tsx` or
+`.svelte` lines. Upload the dSYM to your crash reporter (Sentry, Crashlytics, App Store Connect) as you would for any
+iOS app, and its frames name your TypeScript. The Xcode debugger shows and steps through the same lines.
+
+**Android, today:** Kotlin has no such directive, so the build writes a line table (`source-lines.json`) beside the
+Gradle project, and the compiler ships one for the kit generated from core. `ns-native-retrace` reads a stack trace
+in source lines: it runs R8's retrace with the build's `mapping.txt` (from the Android SDK's command-line tools),
+then maps your app's frames to your files and the kit's frames to `@nativescript/core` files. Archive `mapping.txt`
+and `source-lines.json` with each release you upload. When a compiled build fails in Kotlin, `ns build` prints each
+error at the TypeScript line it came from as well.
+
+```bash
+adb logcat -d -s AndroidRuntime | npx ns-native-retrace platforms/compiled/android
+npx ns-native-retrace platforms/compiled/android crash.txt    # or a trace saved from your crash reporter
+```
+
+Expressions from templates map to the component's source file, matched by what they share with it; with a separate
+template file (Angular's `templateUrl`) that is the component's `.ts`, not the `.html`. The code that builds a
+component's view tree appears under the component's generated name (for example `GuitarComponent.swift`), which
+still tells you which component it was.
+
+**`error.stack`** in a compiled release lists the native frames the error was made in. On iOS a frame reads
+`symbol (App+0x1a2b3c)`; resolve the offset with the archive's dSYM
+(`atos -o App.app.dSYM/Contents/Resources/DWARF/App -l 0x100000000 0x1001a2b3c`) to get the TypeScript line. On
+Android a frame reads `class.method(File.kt:line)`, which `ns-native-retrace` maps. A crash reporter hooked to
+JavaScript errors receives these frames, not JavaScript ones.
+
+**Planned:**
+
+- One upload for Android crash reporters: the line table composed into `mapping.txt`, or a standard source map, so
+  reporters show TypeScript lines without a manual step.
+- Template-file lines for template expressions and the view-building code.
+
+### Can I debug a compiled release?
+
+With Xcode or Android Studio, as a native app: breakpoints, stepping and variables, on iOS against your TypeScript
+lines. `ns debug` and Chrome DevTools need the JavaScript runtime, so they stay with development builds.
+
+### Will the compiled release behave exactly like the JavaScript one?
+
+That is the goal, and it is checked rather than assumed. JavaScript's semantics (numbers, promises and microtask
+order, closures, iteration order, `Map`/`Set`) are reproduced by a runtime that the compiler's differential tests
+hold to Node's output, and the proof apps match their JavaScript releases pixel for pixel. It is not there yet: the
+differences known today (among them `null` and `undefined` in typed optionals, listener removal on iOS, and some
+regular-expression classes) are listed on [Supported subset and known differences](/guide/publishing/compiled-differences).
+The development runtime and the release are different engines, so check each release before you ship it (see
+[Checking a compiled release](#checking-a-compiled-release)).
+
+### Can I keep over-the-air updates (Norrix, CodePush-style)?
+
+No. Over-the-air updates replace the JavaScript bundle, and a compiled release has none. Ship updates through the
+stores, and replace the update plugin with a no-op module through `release.pluginReplacements`. If over-the-air
+updates are essential to you, keep releasing on the JavaScript runtime.
+
+### Can I use any npm package?
+
+Packages are compiled with your app from their source, like plugins, so what matters is what they do: code that
+uses `eval`, `new Function` or loads code at run time cannot be compiled. Widely used libraries are not yet
+systematically verified; a construct the compiler does not support stops the build with its location.
+
+### Can I still write native code?
+
+Yes. Swift in `App_Resources/iOS/src` is compiled into the app and called from your TypeScript as before. Plugins'
+native code (Swift, Objective-C, `.xcframework`s, CocoaPods, Swift packages, Java, Kotlin, Gradle dependencies)
+links unchanged. App extensions such as widgets and Live Activities become their own targets.
+
+### Is the generated Swift and Kotlin meant to be edited?
+
+No. It is build output in `platforms/compiled/<platform>`, regenerated on every build; your TypeScript stays the
+source of truth. You can open the iOS project in Xcode to run, profile or debug it.
+
+### How long does a compiled build take?
+
+The compile step takes seconds to tens of seconds, depending on the app (an Angular app with 9 components and 27
+modules: about 20 seconds), followed by Xcode's or Gradle's build. Rebuilds after a small change take a few seconds
+of Xcode or Gradle time.
+
+### Which platforms and OS versions?
+
+iOS 17 and later, and Android. visionOS, watchOS and other platforms build on the JavaScript runtime.
+
+### What if a plugin I use does not compile?
+
+The build names the plugin and what stopped it. Depending on the cause: point `release.pluginSources` at its
+source, replace it with `release.pluginReplacements`, or raise it with the plugin's author. Plugins that install
+objects into the JavaScript engine (such as `@nativescript/canvas`) need a native counterpart in the kit, which
+exists for canvas on iOS.
+
+### Can I go back?
+
+Any time: `--no-compiled` builds one release on the JavaScript runtime, and removing `release.compiled` from the
+config makes it the default again. Nothing in your project depends on the compiled build.
+
+## Under the hood
+
+Who touches what:
+
+| Piece | What it is | Who uses it |
+| --- | --- | --- |
+| The CLI (`nativescript`) | `--compiled`, the `release` config, building, signing and installing the compiled project | App developers |
+| `@nativescript/compiler` | The compiler, and NativeScriptKit's sources for Swift and Kotlin | App developers, as a devDependency |
+| NativeScriptKit | `@nativescript/core` as native code, linked by every compiled app | Nobody directly; it comes with the compiler |
+| Core's kit generator (`tools/native-kit` and `packages/compiler` in the NativeScript repo) | Compiles core's TypeScript into NativeScriptKit, once per core release, checked by CI, which builds every file of the kit; the compiler is published at core's version | Core maintainers |
+
+NativeScriptKit started as a hand port of core and matched it wherever it was ported, but a hand port drifts
+everywhere else. It is now generated from core's own TypeScript by the same compiler that compiles apps, on iOS and
+Android, so every core release, fix and platform-version branch reaches compiled releases without a port. The
+published compiler carries both kits, generated from the core release it is published with, and CI builds an app
+from the packed package before publishing.
+
+## What is still open
+
+- Publishing `@nativescript/compiler` and releasing the CLI flag.
+- Core's own apps as compliance: `apps/automated` (core's unit tests) and `apps/toolbox`, compiled, run and
+  compared with their JavaScript builds.
+- Plugins: `.framework` and static libraries, resource bundles, and a way for plugin authors to ship native
+  counterparts of engine-bound code. A corpus of widely used plugins and npm libraries, built in CI.
+- The [known differences](/guide/publishing/compiled-differences) at run time.
+- Android: WinterTC globals; R8 keeps narrowed to what the app reaches by name.
+- `fetch` and `XMLHttpRequest`; localization checked against core.
+- Uploading the compiled code's TypeScript line maps to crash reporters.
+
+## See also
+
+- [Two pathways](/guide/pathways)
+- [SwiftUI, live](/guide/swiftui-live): the other direction: write Swift, develop it live.
+- [Publishing overview](/guide/publishing/)
diff --git a/content/guide/publishing/index.md b/content/guide/publishing/index.md
index 0c1c33ed..cb165858 100644
--- a/content/guide/publishing/index.md
+++ b/content/guide/publishing/index.md
@@ -1,13 +1,37 @@
 ---
 title: Publishing Overview
-description: When building an app, there comes a point where it needs to be published
+description: Build a release of your app, on the JavaScript runtime or compiled to native code, and publish it to the stores.
 contributors:
   - rigor789
+  - NathanWalker
 breadcrumbs:
   - name: 'Publishing'
 ---
 
-## [Publishing to Google Play](/guide/publishing/android-google-play)
-## [Publishing to Apple App Store](/guide/publishing/apple-app-store)
-## [Publishing iOS updated using ns publish ios](/guide/publishing/ns-publish)
-## [Publishing with Fastlane](https://blog.nativescript.org/automatic-nativescript-app-deployments-with-fastlane/)
+Publishing takes two steps: build a release of the app, then submit that build to a store.
+
+## 1. Build a release
+
+NativeScript builds a release in one of two ways.
+
+|  | JavaScript runtime release | Compiled release |
+| --- | --- | --- |
+| **Command** | `ns build ios --release` | `ns build ios --compiled` |
+| **What ships** | Your bundled JavaScript and the NativeScript runtime (V8 on Android and iOS) | Swift (iOS) and Kotlin (Android) compiled from your TypeScript; no JavaScript engine |
+| **Status** | Stable, the default | [Preview](/guide/publishing/compiled) |
+| **Plugins** | Every NativeScript plugin | Plugins compiled from their TypeScript source; see [what a compiled release supports](/guide/publishing/compiled#what-a-compiled-release-supports) |
+
+A compiled release is opt-in. It can be the default for every release build through `nativescript.config.ts`, per
+platform, and `--no-compiled` builds one release on the JavaScript runtime whatever the config says. Read
+[Compiled releases](/guide/publishing/compiled) for how it works, what it supports and how to check that the
+compiled build matches the JavaScript one.
+
+## 2. Publish it
+
+- [Publishing to the Apple App Store](/guide/publishing/apple-app-store)
+- [Publishing to Google Play](/guide/publishing/android-google-play)
+- [Publishing iOS updates with `ns publish ios`](/guide/publishing/ns-publish)
+- [Publishing with Fastlane](https://blog.nativescript.org/automatic-nativescript-app-deployments-with-fastlane/)
+
+The store steps are the same for both kinds of release: a compiled release produces the same signed `.ipa`, `.apk`
+or `.aab`, under the same app id.
diff --git a/content/guide/swiftui-live.md b/content/guide/swiftui-live.md
new file mode 100644
index 00000000..8da4d423
--- /dev/null
+++ b/content/guide/swiftui-live.md
@@ -0,0 +1,115 @@
+---
+title: SwiftUI, live
+description: Edit a SwiftUI app's Swift while it runs and see each save in about a third of a second, with the app's state kept. NativeScript is the development runtime; what ships is your Swift.
+contributors:
+  - NathanWalker
+---
+
+<!-- Keep in step with the swiftui-live repository's README and docs/BRIEF.md. -->
+
+::: warning Preview
+SwiftUI Live is in preview and not yet publicly available. This page describes it as it works today, so the
+pathway is clear before it opens up.
+:::
+
+This is one of NativeScript's [two pathways](/guide/pathways). You write SwiftUI, in an ordinary Xcode project,
+and NativeScript runs it **live** while you develop: save a Swift file and the running app shows the change in
+about 0.15–0.5 seconds, at the screen and state you were on. Nothing of NativeScript ships. The App Store build is
+your Swift, compiled by Xcode as usual.
+
+It is the inverse of the [TypeScript pathway](/guide/publishing/compiled): there, you write TypeScript and the
+release is compiled to Swift and Kotlin. Here, you write Swift and the development session runs it on a JavaScript
+engine for speed.
+
+## What a session is like
+
+In your app's folder:
+
+```bash
+swiftui-live            # reads the .xcodeproj, builds, launches on a simulator, watches
+swiftui-live doctor     # checks the machine; lists which views go live on save, and why the rest do not
+swiftui-live down       # stops the session
+```
+
+There is nothing to add or configure in the project: no `#Preview` blocks, mocks or annotations. The command
+reads the project's targets, packages and build settings and builds a development copy of the app (about 22 s the
+first time, 10 s after that). The development build lives in `~/Library/Caches/swiftui-live`; your project is not
+modified.
+
+Each save reports one line:
+
+```
+[live] ● Backyards/BackyardGridItem.swift: on screen in 368 ms
+[live]   swiftc agrees (0.7 s)
+[live] ✗ Backyards/BackyardGridItem.swift:37:31: value of type 'Backyard' has no member 'nam' (swiftc); the last version it accepted is back on screen
+[live] ○ Donut/TopDonutSalesChart.swift: line 36: modifier `.chartXAxis` is not in the compiled runtime yet; taking the library path (state kept, about a second)
+```
+
+## How it works
+
+```text
+your .swift file ── swift-js ──▶ JavaScript for the view's body ──▶ engine in the running app
+                                                                     │
+                                       the body builds real SwiftUI views; the rest of the app
+                                       is untouched compiled Swift
+          └── swiftc type-checks the same save against the app's module; a rejected save is rolled back
+```
+
+- **Fast path.** Each view's `body` is compiled from Swift to JavaScript and run by an engine inside the app:
+  JavaScriptCore in a plain Xcode project, or NativeScript's V8 in a NativeScript host. The body builds a tree of
+  real SwiftUI views. Swift that the compiler cannot express stays compiled Swift (an _island_) and runs in place.
+- **Library path.** A save that changes code outside view bodies, or uses SwiftUI the fast path does not cover yet,
+  is built as a replacement library, the mechanism Xcode Previews uses: about a second, state kept.
+- **Swift stays the judge.** Every save is also type-checked by `swiftc` against the app's own module. Anything the
+  compiler rejects is taken back off the screen.
+
+## What is measured
+
+- **Real apps, unmodified.** Apple's Food Truck and Backyard Birds (SwiftData, three packages) run live from their
+  own sources.
+- **Pixel conformance.** Views rendered live and compiled in the same process are compared pixel by pixel: the
+  fixture app 16 of 16 (on both JavaScriptCore and V8), Food Truck 6 of 6, Backyard Birds 6 of 6, checked nightly
+  in CI.
+- **Coverage.** Of every SwiftUI view in ten open-source apps (1,684), 1,068 (63%) go live in 0.15–0.5 s; the rest
+  take the library path in about a second, still with state kept.
+
+## Android: the same SwiftUI source, live
+
+The same SwiftUI source also runs live on an Android emulator. View bodies are compiled to JavaScript as on iOS and
+rendered by **Jetpack Compose** (Material 3), and the app's models are compiled for Android by the official Swift
+SDK for Android. One save updates an iOS simulator and an Android emulator at once.
+
+What this proves, and what it does not yet:
+
+| | iOS | Android |
+| --- | --- | --- |
+| Live development of SwiftUI | Yes | Yes, rendered by Compose |
+| The app's non-UI Swift | Compiled Swift | Compiled by the Swift SDK for Android |
+| Views the fast path cannot express | Islands of compiled SwiftUI | A placeholder (there is no SwiftUI on Android to fall back to) |
+| Look | SwiftUI | Material 3: SwiftUI's vocabulary mapped onto Compose components |
+| A release build | Your Xcode project, as always | Not yet: there is no release path for SwiftUI on Android today |
+
+## Limits today
+
+None of these is architectural; each is breadth or polish with a known path.
+
+- **37% of views take the library path** (about a second instead of a third of one). The missing SwiftUI
+  vocabulary is ranked by how often real apps use it (`.onReceive`, `.focused`, gestures, Charts modifiers).
+- **New stored properties, types or model changes need a rebuild**, as with Previews and every hot-reload tool:
+  Swift cannot add stored properties to a running binary. `swiftui-live rebuild` relaunches into the saved state.
+- **Simulator and emulator only.**
+- **Some Swift semantics differ on the fast path**: integer overflow traps, `Dictionary` order, number formatting.
+  `swiftc` still checks every save.
+- **Fidelity is proven on still frames in light mode.** Animation, dark mode, Dynamic Type and right-to-left are not
+  yet in the conformance harness.
+
+## Requirements
+
+- macOS with Xcode 26 or later, and Node 22.
+- For Android: the Android SDK with an arm64 emulator image, NDK r30, and the Swift 6.4 toolchain with the Swift SDK
+  for Android.
+
+## See also
+
+- [Two pathways](/guide/pathways): choosing between SwiftUI and TypeScript.
+- [Compiled releases](/guide/publishing/compiled): the TypeScript pathway's release, with no JavaScript runtime.
diff --git a/content/index.md b/content/index.md
index 9ad08e39..38585d7e 100644
--- a/content/index.md
+++ b/content/index.md
@@ -9,6 +9,15 @@ contributors:
 
 NativeScript provides platform APIs directly to the JavaScript runtime (_with strong types_) for a rich TypeScript development experience. 
 
+### Two pathways: develop live, ship native
+
+NativeScript can now be your development runtime without being your production runtime:
+
+1. **[SwiftUI, live](/guide/swiftui-live)**: write SwiftUI in your Xcode project and see each save in the running app in about a third of a second, state kept. On Android, the same SwiftUI source runs live, rendered by Jetpack Compose. What ships is your Swift. _(Preview)_
+2. **[TypeScript, compiled](/guide/publishing/compiled)**: write TypeScript with the framework you like and the JavaScript ecosystem, develop on the JavaScript runtime as always, and build the release with `--compiled`: Swift and Kotlin, with no JavaScript engine inside. _(Preview)_
+
+[Compare the two pathways](/guide/pathways). Releases on the JavaScript runtime remain the default and fully supported.
+
 Some popular use cases:
 
 - Building Web, iOS, Android and Vision Pro apps with a shared codebase (aka, cross platform apps)
diff --git a/content/sidebar.ts b/content/sidebar.ts
index ac2cd10e..f42f647d 100644
--- a/content/sidebar.ts
+++ b/content/sidebar.ts
@@ -8,6 +8,8 @@ export default [
     text: 'Getting Started',
     items: [
       { text: 'Introduction', link: '/' },
+      { text: 'Two pathways', link: '/guide/pathways' },
+      { text: 'SwiftUI, live', link: '/guide/swiftui-live' },
       {
         text: 'Environment Setup',
         link: '/setup/',
@@ -50,6 +52,13 @@ export default [
       {
         text: 'Publishing',
         link: '/guide/publishing/',
+        items: [
+          { text: 'Compiled releases', link: '/guide/publishing/compiled' },
+          { text: 'Compiled: supported subset', link: '/guide/publishing/compiled-differences' },
+          { text: 'Apple App Store', link: '/guide/publishing/apple-app-store' },
+          { text: 'Google Play', link: '/guide/publishing/android-google-play' },
+          { text: 'ns publish ios', link: '/guide/publishing/ns-publish' },
+        ],
       },
       {
         text: 'Plugins',